Dokumentacja interfejsu API REST
Dokumentacja API REST Workflow Transactional Email dla Shopify Flow: punkty końcowe szablonów, żądań HTTP, historii i statystyk oraz poziomy dostępu.
Wszystkie ścieżki są podawane względem https://shopify.workflow-transactional-email.app. Każdy punkt końcowy, z wyjątkiem strony głównej, wymaga nagłówka Authorization: Bearer fak_... - zob. Uwierzytelnianie i klucze API.
Odpowiedzi mają format JSON. Komunikaty o błędach mają zawsze tę samą strukturę:
{ "error": "Invalid or missing API key" }Indeks i tożsamość
| Metoda | Ścieżka | Poziom | Cel |
|---|---|---|---|
| POBRAĆ | /api/v1 |
brak | Indeks API. Potwierdza, że API działa, oraz podaje informacje o aktualnej wersji |
| POBRAĆ | /api/v1/me |
przeczytaj | Proszę sprawdzić, czy klucz działa, oraz zweryfikować jego poziom dostępu |
Indeks nie wymaga klucza, dlatego stanowi bezpieczny element do monitorowania w ramach kontroli stanu systemu.
Układy wiadomości e-mail
| Metoda | Ścieżka | Poziom | Cel |
|---|---|---|---|
| POBRAĆ | /api/v1/email-templates |
przeczytaj | Wyświetlenie szablonów wiadomości e-mail. Opcja q umożliwia wyszukiwanie według nazwy, tematu i opisu; opcja category=transactional lub category=marketing pozwala wyświetlić jeden typ wiadomości e-mail |
| POST | /api/v1/email-templates |
napisać | Utwórz układ |
| POBRAĆ | /api/v1/email-templates/:id |
przeczytaj | Jeden układ wraz z projektem graficznym lub załącznikami, tekstami w stopce oraz wykazem języków |
| PUT / PATCH | /api/v1/email-templates/:id |
napisać | Zmiana układu. Zmianie ulegają wyłącznie pola, które Państwo przesyłają |
| USUŃ | /api/v1/email-templates/:id |
napisać | Usunięcie szablonu wraz z jego tłumaczeniami i wersjami |
| POBRAĆ | /api/v1/layout-schema |
przeczytaj | Jak stworzyć układ strony: format projektu, domyślne ustawienia poszczególnych bloków, dostępne elementy Liquid, ograniczenia oraz przykład |
Lista akceptuje parametry page (domyślnie 1), limit (domyślnie 25, maksymalnie 100) oraz q, który umożliwia wyszukiwanie według nazwy, tematu i opisu. W interfejsie API nie ma możliwości filtrowania według typu; zamiast tego prosimy o sprawdzenie parametru category w każdym układzie.
Układ zawiera następujące pola:
| Dziedzina | Uwagi |
|---|---|
name, description |
Wymagana nazwa, maksymalnie 200 znaków; opis - maksymalnie 2000 znaków |
bodyType |
visual (domyślnie) lub text. Po utworzeniu wartość ta jest stała |
defaultLocale |
Język treści samego szablonu, domyślnie en, o ile nie określono inaczej |
category |
transactional (domyślnie) lub marketing. Zobacz poniżej |
subject, previewText |
Dopuszczalne jest spożywanie napojów. Przedmiot obowiązkowy |
bodyDesign |
Układy wizualne: { blocks, global?, header?, footer?, testVariables? }. W przypadku wprowadzania zmian prosimy o przesłanie kompletnego projektu; na jego podstawie renderowany jest element HTML body |
body |
Układ tekstu: element body w HTML |
attachments |
Układ tekstu: [{ filename, fileKey, sendAsLink? }] w przypadku plików przesłanych (patrz pliki poniżej) lub [{ filename, url }] w przypadku pliku pobranego przez protokół HTTPS w momencie wysłania wiadomości e-mail |
marketingTexts |
Teksty stopki w szablonie marketingowym lub null. Zobacz poniżej |
Płynne rozmieszczenie elementów w temacie, tekście podglądu, treści głównej oraz każdym bloku tekstowym musi zostać poprawnie przetworzone, a każdy fileKey musi należeć do Państwa sklepu; w przeciwnym razie operacja zapisu zostanie odrzucona z kodem błędu 400, w którym podane zostanie nazwa danego pola. Przed przystąpieniem do tworzenia projektu wizualnego prosimy zapoznać się z GET /api/v1/layout-schema: jest on generowany przez sam kreator, więc nie może ulec zmianie.
Każda operacja zapisu wykonana za pośrednictwem tego interfejsu API jest zapisywana w historii wersji układu, dokładnie tak samo jak zapis w aplikacji.
Szablony transakcyjne i marketingowe
category określa przeznaczenie danego szablonu. Szablon transakcyjny jest wysyłany do każdego odbiorcy w niezmienionej postaci. Szablon marketingowy pomija odbiorców, którzy zrezygnowali z subskrypcji (w ramach tego etapu wiadomość nie jest wysyłana do odbiorców z pola „Do”, którzy zrezygnowali, a w historii pojawia się oznaczenie SKIPPED), jest wysyłany jako jedna wiadomość do każdego odbiorcy z pola „Do” wraz z własnym linkiem rezygnacji z subskrypcji (maksymalnie 20 na etap) i kończy się zdaniem dotyczącym rezygnacji z subskrypcji oraz danymi Państwa firmy. {{ unsubscribe_url }} oraz {{ unsubscribe_link }} - prosimy o samodzielne umieszczenie linków; w szablonach transakcyjnych oba pola pozostają puste. Informacje dotyczące strony sprzedawcy znajdują się w sekcji E-maile marketingowe i rezygnacje z subskrypcji.
marketingTexts to treść stopki stosowana w układzie marketingowym zamiast tekstów obowiązujących w całym sklepie, określonych w sekcji „Ustawienia”:
{
"marketingTexts": {
"unsubscribeText": "You get this because you shop with us. {{ unsubscribe_link }}",
"unsubscribeLinkLabel": "Unsubscribe",
"companyDetails": "Example GmbH, Musterstrasse 1, 10115 Berlin"
}
}Wszystkie pola są opcjonalne. Wypełnienie danego pola powoduje zastąpienie tekstu z sekcji „Ustawienia” dla tego pola; pozostałe pola pozostają bez zmian. null (wartość domyślna) oznacza teksty ustawień w języku wiadomości e-mail. Ograniczenia: unsubscribeText i companyDetails - 2000 znaków, unsubscribeLinkLabel - 100 znaków. Pole unsubscribeText musi zawierać {{ unsubscribe_link }} lub {{ unsubscribe_url }}, w przeciwnym razie zapis zostanie odrzucony. Pole to jest zapisywane dla wszystkich układów, ale wysyłane jest wyłącznie wraz z układami marketingowymi.
Usunięcie układu nigdy nie jest blokowane. Jeśli kroki w Shopify Flow nadal odwołują się do tego układu, w odpowiedzi pojawia się warning z informacją o liczbie takich kroków; kroki te zakończą się niepowodzeniem, dopóki nie zostanie zastosowany inny układ.
Tłumaczenia
| Metoda | Ścieżka | Poziom | Cel |
|---|---|---|---|
| POBRAĆ | /api/v1/email-templates/:id/translations |
przeczytaj | Każdy język układu wraz z jego treścią |
| POBRAĆ | /api/v1/email-templates/:id/translations/:locale |
przeczytaj | Jeden język |
| PUT | /api/v1/email-templates/:id/translations/:locale |
napisać | Utwórz lub zastąp jeden język |
| USUŃ | /api/v1/email-templates/:id/translations/:locale |
napisać | Należy usunąć jeden język. W takim przypadku system powróci do domyślnego układu |
| POST | /api/v1/email-templates/:id/translations/:locale/promote |
napisać | Proszę ustawić ten język jako główny język układu |
:locale to kod języka, np. de, fr lub pt-br; wielkość liter i znak oddzielający nie mają znaczenia. Maksymalnie 30 języków na układ. Pole Język w kroku Shopify Flow wybiera jeden z nich w momencie wysyłania: dokładnie ten sam kod języka, następnie język podstawowy, następnie wariant regionalny, a w przypadku braku innych opcji - sam układ.
Operacja PUT przyjmuje pełną treść przetłumczoną: subject (pole obowiązkowe), previewText oraz bodyDesign (element wizualny) lub body (tekst). Prosimy o pozostawienie tagów Liquid i adresów URL bez zmian. Dwa pola dotyczą konkretnie tłumaczenia:
| Dziedzina | Układ tekstu | Znaczenie |
|---|---|---|
attachments |
tak | Lista (o tym samym kształcie co układ) = załączniki właściwe dla tego języka, [] = brak załączników w tym języku. null = wysyłanie załączników z układu. Pominięcie = zachowanie bieżącego wyboru; nowy język korzysta z załączników z układu. Układy wizualne przenoszą swoje załączniki jako bloki w polu bodyDesign każdego języka i odrzucają to pole |
marketingTexts |
dowolny | Teksty stopki dla tego języka są umieszczane nad tekstami stopki układu, pole po polu. null = teksty stopki układu. Pominięcie = zachowanie bieżącego wyboru |
Zwracane tłumaczenie zawiera te same dwa pola: attachments ma wartość null, mimo że wykorzystuje układ, a marketingTexts ma wartość null, mimo że korzysta z układu.
promote zamienia układ i tłumaczenie: układ przejmuje treść i ustawienia regionalne tłumaczenia, a treść, którą dotychczas zawierał, staje się tłumaczeniem dla języka, w którym był dotychczas wyświetlany. Załączniki i teksty stopki również zamieniają się miejscami, dzięki czemu każdy język nadal wysyła to, co wysyłał wcześniej. Odpowiedź zawiera informacje o promoted, previousMainLanguage oraz układzie. Jest to jedna wersja, więc można ją cofnąć.
Wersje
| Metoda | Ścieżka | Poziom | Cel |
|---|---|---|---|
| POBRAĆ | /api/v1/email-templates/:id/versions |
przeczytaj | Zapisane wersje, najnowsze na początku. Aplikacja przechowuje 25 najnowszych |
| POBRAĆ | /api/v1/email-templates/:id/versions/:version |
przeczytaj | Pełna kopia jednej wersji: układ oraz wszystkie tłumaczenia |
| POST | /api/v1/email-templates/:id/versions/:version/restore |
napisać | Proszę przywrócić tę wersję. Została zapisana jako nowa wersja |
| POBRAĆ | /api/v1/email-templates/:id/versions/github?page= |
przeczytaj | Każda wersja przechowywana w powiązanym repozytorium GitHub, po 20 na stronę |
| POBRAĆ | /api/v1/email-templates/:id/versions/github/:sha |
przeczytaj | Układ w stanie z jednego zatwierdzenia |
| POST | /api/v1/email-templates/:id/versions/github/:sha/restore |
napisać | Przywróć poprzednią wersję z serwisu GitHub - działa to podobnie jak zapisywanie zmian |
Punkty końcowe serwisu GitHub zwracają kod błędu 409, gdy na stronie „Developer” nie jest podłączone żadne repozytorium. Proszę zapoznać się z Historia wersji układu oraz Przechowuj nieograniczoną historię układów na GitHubie.
Nadawcy wiadomości e-mail
| Metoda | Ścieżka | Poziom | Cel |
|---|---|---|---|
| POBRAĆ | /api/v1/smtp-configs |
przeczytaj | Lista nadawców SMTP |
| POBRAĆ | /api/v1/senders |
przeczytaj | Wyświetlenie listy połączonych skrzynek pocztowych (Microsoft 365, Google) |
Nadawcy korzystający z protokołu SMTP przekazują informacje hasUsername oraz hasPassword zamiast samych danych uwierzytelniających - obie części są ukrywane, ponieważ nazwa użytkownika stanowi tak samo integralną część danych uwierzytelniających jak hasło. Nadawcę można zidentyfikować na podstawie jego nazwy, hosta oraz adresu nadawcy. Podłączone skrzynki pocztowe przekazują częściowo zamaskowany adres, np. so***@example.com, i nigdy nie ujawniają swoich tokenów logowania.
Tylko do odczytu. Proszę połączyć się z aplikacją i edytować dane nadawców.
Sekrety
| Metoda | Ścieżka | Poziom | Cel |
|---|---|---|---|
| POBRAĆ | /api/v1/secrets |
przeczytaj | Proszę podać tajne nazwy i opisy |
Zwraca hasValue, nigdy samą wartość. Nie ma punktu końcowego umożliwiającego odczytanie sekretu. Prosimy o tworzenie i aktualizowanie sekretów w aplikacji.
Przesłane pliki
| Metoda | Ścieżka | Poziom | Cel |
|---|---|---|---|
| POBRAĆ | /api/v1/files |
przeczytaj | Lista przesłanych logo, obrazów i załączników |
| USUŃ | /api/v1/files |
napisać | Usuń jeden element na podstawie key’a w treści |
Funkcja list akceptuje parametry page, limit (maks. 100) oraz q, umożliwiające wyszukiwanie według nazwy pliku.
Proszę dodać parametr ?usage=true, a każdy plik wyświetli również wartość inUse oraz tablicę usedBy zawierającą nazwy układów i ustawień wstępnych, które odwołują się do tego pliku. W ten sposób można w ramach jednego żądania zidentyfikować wszystkie elementy, które można bezpiecznie usunąć. Funkcja ta skanuje Państwa układy i ustawienia wstępne, dlatego jest to opcja, którą należy włączyć, a nie ustawienie domyślne.
Funkcja przesyłania plików nie jest tutaj dostępna - prosimy o dodawanie plików za pomocą selektora multimediów w aplikacji.
Żądania HTTP
| Metoda | Ścieżka | Poziom | Cel |
|---|---|---|---|
| POBRAĆ | /api/v1/http-requests |
przeczytaj | Wykaz żądań HTTP |
| POST | /api/v1/http-requests |
napisać | Utwórz jeden |
| POBRAĆ | /api/v1/http-requests/:id |
przeczytaj | Proszę to zamówić |
| PUT / PATCH | /api/v1/http-requests/:id |
napisać | Aktualizacja nr 1 |
| USUŃ | /api/v1/http-requests/:id |
napisać | Usuń jeden |
| POST | /api/v1/http-requests/:id/test |
wykonaj | Proszę uruchomić to na rzeczywistym obiekcie docelowym |
Funkcja list przyjmuje te same parametry page, limit i q, co szablony wiadomości e-mail.
Adres docelowy url musi mieć postać http:// lub https://. Inne schematy są odrzucane podczas zapisywania.
Dane uwierzytelniające wpisane bezpośrednio w nagłówku lub treści są maskowane w każdej odpowiedzi. Wartości, do których odwołuje się za pomocą {{ secrets.KEY }}, są zwracane w niezmienionej postaci, ponieważ samo odwołanie nie stanowi informacji wrażliwej.
Historia i statystyki
Obejmuje zarówno wysyłanie wiadomości e-mail, jak i żądania HTTP.
| Metoda | Ścieżka | Poziom | Cel |
|---|---|---|---|
| POBRAĆ | /api/v1/history |
przeczytaj | Wykonanie list |
| POBRAĆ | /api/v1/history/:id |
przeczytaj | Pobierz jedno wykonanie wraz z danymi żądania i odpowiedzi |
| POBRAĆ | /api/v1/stats |
przeczytaj | Wyniki ogółem i wskaźnik skuteczności |
Funkcja „History” akceptuje parametry page, limit (maks. 100), actionType, status (PENDING, SUCCESS, FAILED, SKIPPED) oraz actionConfigId w celu filtrowania wyników według pojedynczego układu lub żądania.
SKIPPED to wiadomość e-mailowa o charakterze marketingowym, której wszyscy odbiorcy zrezygnowali z subskrypcji: nie wysłano żadnej wiadomości, nie wykorzystano limitu, a wiadomość ta nie jest uwzględniana przy obliczaniu wskaźnika skuteczności.
actionType musi przyjmować wyłącznie wartość EMAIL lub HTTP_REQUEST. Nieznana wartość jest ignorowana, a nie odrzucana, więc literówka spowoduje zwrócenie wszystkich danych zamiast wygenerowania błędu.
W parametrze „stats” można podać liczbę days (wartość domyślna to 30, maksymalna to 365).
Kody statusu
| Kod | Znaczenie |
|---|---|
| 200 | Sukces |
| 201 | Utworzono |
| 400 | Nieprawidłowe żądanie lub nieudana walidacja. W polu error podano nazwę pola, na przykład subject: required |
| 401 | Brakujący, nieprawidłowy lub unieważniony klucz API |
| 403 | Klucz jest prawidłowy, ale jego poziom jest zbyt niski dla tego punktu końcowego |
| 404 | Nie znaleziono lub produkt należy do innego sklepu |
| 405 | Niewłaściwa metoda dla tej ścieżki |
| 409 | Odmowa z powodu faktu, że rekord jest nadal w użyciu (usuwanie plików) lub brak połączenia z serwisem GitHub (wersje GitHub) |
| 429 | Ograniczenie częstotliwości - patrz poniżej |
| 502 | Żądanie zostało wykonane, ale operacja na obiekcie zewnętrznym zakończyła się niepowodzeniem |
Rekord należący do innego sklepu zwraca kod 404 zamiast 403, w związku z czym interfejs API nigdy nie potwierdza, że dany identyfikator istnieje gdzie indziej.
Limity częstotliwości
Dwa niezależne budżety, oba w przeliczeniu na klucz:
- 300 żądań na 60 sekund we wszystkich punktach końcowych.
- Ponadto należy wykonać 60 wywołań na godzinę, obejmujących żądanie typu
POST /api/v1/http-requests/:id/test.
Przekroczenie którejkolwiek z tych wartości powoduje zwrot kodu błędu 429 wraz z opisowym komunikatem error. Limit wykonania został celowo ustalony na niskim poziomie: pętla, która wymyka się spod kontroli i wysyła na bieżąco żądania do dostawcy usług płatniczych, stanowi znacznie poważniejszą awarię niż wolno działający skrypt.
Budżety są przypisane do poszczególnych kluczy, a nie do poszczególnych sklepów, więc jedna integracja nie może wyczerpać limitu przeznaczonego dla innej.