Interfejs API dla programistów, MCP, GitHub oraz symulacja wyzwalaczy

Mogą Państwo przeglądać swoje wyzwalacze, włączać je lub wyłączać, przeglądać historię zdarzeń oraz symulować działanie wyzwalacza z poziomu własnego kodu lub za pośrednictwem asystenta AI. Rozszerzenia wyzwalaczy przepływu pracy (Workflow Trigger Extensions) udostępniają interfejs API REST oraz serwer MCP, a także umożliwiają połączenie z repozytorium GitHub, dzięki czemu Państwa niestandardowy kod wyzwalacza podlega kontroli wersji. Wszystkimi tymi elementami można zarządzać na stronie Dla programistów.

Symulacja wyzwalacza

Testowanie przepływu pracy w Shopify Flow zazwyczaj wiąże się z przeprowadzeniem rzeczywistych czynności w Państwa sklepie - edycją produktu, złożeniem zamówienia, oczekiwaniem na wynik ankiety. Symulacja eliminuje to oczekiwanie: wystarczy wybrać wyzwalacz, przypisać go do zasobu, a zostanie on uruchomiony tak, jakby rzeczywiste zdarzenie właśnie miało miejsce.

Dwa sposoby na uruchomienie jednego:

• W aplikacji. Otwórz dowolne zdarzenie w historii zdarzeń i ponownie wybierz opcję Symuluj. Spowoduje to ponowne wywołanie dokładnie tego samego zdarzenia.
• Za pośrednictwem interfejsu API lub MCP, na podstawie identyfikatora zasobu lub wydarzenia z przeszłości.

Symulacja jest celowo wierna rzeczywistości. Nie tworzy ona skróconej treści - przechodzi przez ten sam proces, co prawdziwy webhook Shopify, więc to, co otrzymuje Państwa system, jest dokładnie tym, co otrzymałby w środowisku produkcyjnym.

curl -X POST https://shopify.workflow-trigger-extensions.app/api/v1/triggers/product-update-trigger/simulate \
  -H "Authorization: Bearer ftk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"resourceId":"gid://shopify/Product/123456789","dryRun":true}'

Przebieg próbny weryfikuje wyzwalacz, rozwiązuje temat i wyświetla ładunek - nie powodując jednak uruchomienia żadnego działania. Aby uruchomić zdarzenie na poważnie, należy usunąć dryRun. Można również przekazać {"fromHistoryId":"456"}, aby ponownie uruchomić zdarzenie z przeszłości zamiast tworzyć nowe.

Wyzwalaczy obsługiwanych na zasadzie odpytywania, a nie za pomocą webhooka, nie można symulować; w wykazie wyzwalaczy wyświetlają one wartość simulatable: false.

Klucze API

Proszę utworzyć klucz na stronie Dla programistów i wybrać jego poziom dostępu:

• Tylko do odczytu - wyświetlanie listy wyzwalaczy i ich stanu, przeglądanie historii zdarzeń, statystyk oraz uprawnień.
• Odczyt i zapis - a także włączanie i wyłączanie wyzwalaczy.
• Odczyt, zapis i wykonanie - a także symulacja wyzwalaczy oraz testowanie niestandardowego kodu wyzwalaczy.

Pełny klucz jest wyświetlany jednokrotnie, w momencie utworzenia. Klucze są przechowywane w postaci zaszyfrowanej i można je w każdej chwili unieważnić. Proszę przesłać go jako token typu „Bearer”:

Authorization: Bearer ftk_your_key_here

Funkcja „Simulation” znajduje się na odrębnym poziomie z powyższego powodu: uruchamia ona Państwa automatyzacje w trybie rzeczywistym, więc klucz używany do codziennego odczytu nie może ich uruchomić.

Interfejs API REST

Metoda	Ścieżka	Poziom	Cel
POBRAĆ	/api/v1	brak	Wskaźnik API - potwierdza, że API działa
POBRAĆ	/api/v1/me	przeczytaj	Sprawdź uprawnienia i poziom swojego klucza
POBRAĆ	/api/v1/triggers	przeczytaj	Każdy wyzwalacz wraz ze stanem dla Państwa sklepu
POBRAĆ	/api/v1/triggers/:handle	przeczytaj	Szczegółowy opis jednego wyzwalacza
PUT	/api/v1/triggers/:handle	napisać	Włączenie lub wyłączenie jednego wyzwalacza
PUT	/api/v1/triggers	napisać	Włączanie lub wyłączanie wielu urządzeń w ramach jednego wywołania
POST	/api/v1/triggers/:handle/simulate	wykonaj	Symulacja wyzwalacza
POBRAĆ	/api/v1/triggers/custom	przeczytaj	Państwa własne, niestandardowe wyzwalacze wraz z ich kodem
POBRAĆ	/api/v1/triggers/custom/:handle/test	przeczytaj	Zdarzenie przechwyconej próbki dla wyzwalacza niestandardowego
POST	/api/v1/triggers/custom/:handle/test	wykonać	Uruchomienie niestandardowego kodu wyzwalacza bez zapisywania ani uruchamiania
POBRAĆ	/api/v1/history	przeczytaj	Wymień zdarzenia wyzwalające
POBRAĆ	/api/v1/history/:id	przeczytaj	Pobierz jedno zdarzenie wraz z jego danymi
POBRAĆ	/api/v1/stats	przeczytaj	Wyniki ogólne, wskaźnik skuteczności, podział według statusu
POBRAĆ	/api/v1/permissions	przeczytaj	Jakie uprawnienia dotyczące danych Państwo przyznali oraz jakie możliwości zapewnia każde z nich

GET /api/v1/triggers to przydatny interfejs do konfiguracji: dla każdego wyzwalacza podaje on wymagane uprawnienia, informację, czy uprawnienie zostało przyznane, czy wyzwalacz jest włączony oraz gdzie w aplikacji można nim zarządzać.

Włączanie i wyłączanie wyzwalaczy

Zastosowano metodę PUT zamiast PATCH, ponieważ wywołanie to jest idempotentne - ponowne wykonanie go po upływie limitu czasu nie spowoduje podwójnego zastosowania żadnej operacji, co ma znaczenie w sytuacji, gdy interfejs API jest obsługiwany przez asystenta.

curl -X PUT https://shopify.workflow-trigger-extensions.app/api/v1/triggers/order-tags-added-trigger \
  -H "Authorization: Bearer ftk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'

Funkcja „Enabling” nigdy nie przyznaje uprawnień. Jeśli wyzwalacz wymaga uprawnienia, którego Państwo nie przyznali, wywołanie i tak zakończy się powodzeniem, a system poinformuje Państwa dokładnie, czego brakuje i gdzie należy je przyznać:

{
  "enabled": true,
  "scopeGranted": false,
  "missingScopeLabels": ["Order Data Access"],
  "permissionsUrl": "https://admin.shopify.com/store/.../app/permissions?permission=read_orders",
  "warning": "Enabled, but this trigger cannot fire until Order Data Access is granted."
}

Ten link otwiera stronę „Uprawnienia”, na której kursor jest już przesunięty bezpośrednio do potrzebnej Państwu karty.

Proszę dodać "sync": true, aby uruchomić również synchronizację danych, dzięki czemu wyzwalacz będzie działał na już istniejących rekordach, a nie tylko na tych tworzonych od tej pory.

Aby zmienić ustawienia kilku elementów jednocześnie, polecenie PUT /api/v1/triggers akceptuje zarówno wyraźną listę, jak i całą kategorię:

{ "enabled": true, "handles": ["order-tags-added-trigger", "order-note-changed-trigger"] }
{ "enabled": true, "category": "orders" }

Połącz z serwisem GitHub

Na stronie Programista w zakładce Połączenia można podłączyć repozytorium GitHub dla kodu Wyzwalacze niestandardowe. Zmiany stają się dostępne do przeglądu w pull requestie; można sprawdzić, kto wprowadził jakie zmiany, a także cofnąć transformację, która przestała działać.

Po kliknięciu przycisku „Połącz” aplikacja GitHub zostanie zainstalowana na wybranym przez Państwa koncie. To Państwo decydują, do których repozytoriów aplikacja ma dostęp, a dostęp ten można w dowolnym momencie cofnąć w serwisie GitHub. Wybranie repozytorium powoduje natychmiastowe zapisanie w nim wszystkich posiadanych już niestandardowych wyzwalaczy, dzięki czemu repozytorium od samego początku jest dostosowane do aplikacji, a nie uzupełniane stopniowo z upływem czasu.

Czym się Państwo zajmują	Co się dzieje
Proszę utworzyć, edytować lub powielić wyzwalacz w aplikacji	Plik został zapisany w Państwa repozytorium
Usunięcie wyzwalacza w aplikacji	Plik został usunięty z Państwa repozytorium
Proszę zatwierdzić zmianę w podłączonej gałęzi	Kod wyzwalacza został zaktualizowany w aplikacji

Każdy wyzwalacz to pojedynczy plik o nazwie odpowiadającej jego identyfikatorowi, zawierający dokładnie ten sam moduł, który widzą Państwo w edytorze - bez żadnych dodatkowych elementów. Mogą Państwo zatem otworzyć go w swoim edytorze, uruchomić i sprawdzić pod kątem poprawności tak jak każdy inny plik JavaScript, a następnie skorzystać z powyższego punktu końcowego /test, aby przetestować go na prawdziwym zarejestrowanym zdarzeniu przed zatwierdzeniem zmian.

Powrót do wcześniejszej wersji

Nie muszą Państwo znać systemu Git, aby cofnąć zmianę. Po podłączeniu repozytorium w edytorze wyzwalaczy wyświetla się lista rozwijana Wersja, zawierająca wszystkie poprzednie wersje danego pliku wraz z datą i autorem. Wystarczy wybrać jedną z nich, a zostanie ona załadowana do edytora jako niezapisana zmiana, dzięki czemu mogą Państwo najpierw ją przejrzeć - dopiero zapisanie powoduje przywrócenie tej wersji jako nowego zatwierdzenia.

Wymiana lub odłączenie

Opcja Zmień repozytorium powoduje powrót do listy wyboru bez wprowadzania zmian w instalacji. Opcja Odłącz cofa instalację na GitHubie, a także usuwa ją tutaj, więc jej działanie jest zgodne z nazwą. Opcja Zarządzaj uprawnieniami otwiera ustawienia instalacji na GitHubie, gdzie można dodawać lub usuwać repozytoria.

Testowanie niestandardowego kodu wyzwalacza

Jeśli przechowują Państwo kod niestandardowego wyzwalacza w repozytorium i edytują go we własnym edytorze, mogą Państwo uruchomić go na przechwyconej próbce zdarzenia bez konieczności uprzedniego zapisywania go w aplikacji.

curl -X POST https://shopify.workflow-trigger-extensions.app/api/v1/triggers/custom/my-trigger/test \
  -H "Authorization: Bearer ftk_your_key_here" \
  -H "Content-Type: application/json" \
  -d "$(jq -Rn --rawfile c flow-triggers/my-trigger.js '{code:$c}')"

Otrzymują Państwo informacje wyświetlane po naciśnięciu przycisku „Test” w aplikacji: czy akcja zostałaby wykonana, obiekt wyjściowy, wpisy z pliku ctx.log oraz czas wykonania.

Nic nie jest uruchamiane i nic nie jest zapisywane - żaden przepływ pracy nie jest uruchamiany, żadne zdarzenie nie jest rejestrowane, żadne limity nie są wykorzystywane, a zapisany kod pozostaje nienaruszony. Można to bezpiecznie uruchamiać przy każdym zapisaniu z poziomu modułu monitorującego pliki. Pełny opis przepływu pracy znajduje się w sekcji Wyzwalacze niestandardowe.

Serwer MCP

Zakładka MCP na stronie „Developer” zawiera adres URL serwera oraz gotowe do skopiowania polecenie połączenia dla aplikacji Claude, Cursor, VS Code, Gemini CLI i innych. Narzędzia odzwierciedlają punkty końcowe REST, a zestaw narzędzi zależy od poziomu uprawnień klucza - w przypadku klucza z uprawnieniami wyłącznie do odczytu narzędzia do zapisu lub wykonywania nie są w ogóle widoczne.

Narzędzie	Poziom	Jak to działa
list_triggers	przeczytaj	Każdy wyzwalacz i jego stan
list_custom_triggers	przeczytaj	Państwa własne, niestandardowe wyzwalacze wraz z ich kodem
get_custom_trigger_sample	przeczytaj	Zdarzenie przechwycone przez niestandardowy wyzwalacz, pod kątem którego przeprowadzana jest weryfikacja
list_history	przeczytaj	Ostatnie zdarzenia wyzwalające
get_event	przeczytaj	Jedno zdarzenie wraz z jego ładunkiem
get_stats	przeczytaj	Statystyki zbiorcze
get_permissions	przeczytaj	Przyznane uprawnienia i związane z nimi możliwości
get_trigger	napisać	Szczegółowy opis jednego wyzwalacza
set_trigger	napisać	Włączenie lub wyłączenie jednego wyzwalacza
set_triggers_bulk	napisać	Włączcie lub wyłączcie kilka urządzeń jednocześnie
simulate_trigger	wykonaj	Wywołanie zdarzenia na żądanie
test_custom_trigger	wykonać	Uruchomienie niestandardowego kodu wyzwalacza bez zapisywania ani uruchamiania

Właśnie to sprawia, że asystent jest naprawdę przydatny: potrafi wyświetlić listę istniejących elementów, wyjaśnić, czego wymaga dany wyzwalacz, włączyć go, uruchomić zdarzenie testowe, odczytać wynik - a w przypadku wyzwalaczy niestandardowych - przerobić kod i przetestować go - a wszystko to bez konieczności opuszczania rozmowy.

W jaki sposób chronione są Państwa dane

Dane zdarzeń są zwracane z zamaskowanymi danymi osobowymi: adresy e-mail, numery telefonów, numery kart oraz pola zawierające imiona i nazwiska są zastępowane znakami ***. Identyfikatory zasobów Shopify oraz pola dotyczące działalności pozostają niezmienione, dzięki czemu dane te zachowują swoją użyteczność.

Maskowanie dotyczy nazw pól i wzorców wartości, dlatego jest skuteczne, ale nie stanowi gwarancji - dane osobowe zawarte w polu tekstowym mogą nadal zostać ujawnione. Komunikaty o błędach są również pozbawiane wewnętrznych szczegółów diagnostycznych przed opuszczeniem serwera.

Połączenie z serwisem GitHub nie przechowuje żadnych danych uwierzytelniających, które mogłyby zostać ujawnione: zachowywany jest jedynie identyfikator instalacji, a dostęp do repozytorium odbywa się za pomocą tokenu generowanego na żądanie, którego ważność wygasa w ciągu godziny.

Kolejne kroki

• Wyzwalacze niestandardowe - stwórz własny wyzwalacz za pomocą kilku wierszy kodu JavaScript.
• Plany i sposób użytkowania - co uznaje się za zdarzenie i na jakich zasadach działa limit.
• Wprowadzenie do Workflow Trigger Extensions - jak działają wyzwalacze i jak je włączyć.

Limity częstotliwości

Interfejs API REST i serwer MCP korzystają z jednego limitu na klucz API.

• 300 żądań na 60 sekund na klucz, w ramach stałego okna czasowego.
• Wywołania na poziomie wykonania mają przydzielony drugi, bardziej restrykcyjny limit wynoszący 60 na godzinę. Wykorzystują one oba limity, więc seria wywołań na poziomie wykonania również uszczupla wspólny limit. W przypadku tej aplikacji oznacza to symulację wyzwalacza oraz uruchomienie niestandardowego kodu wyzwalacza - obie te czynności faktycznie uruchamiają Państwa przepływy pracy.
• W każdym planie jest tak samo. To liczniki Państwa planu wyzwalają zdarzenia, a nie wywołania API, więc przejście na wyższy plan nie powoduje wzrostu tych wartości.
• W wyniku przetwarzania zwracany jest kod HTTP 429. Należy odczekać i spróbować ponownie, najlepiej stosując algorytm wykładniczego opóźniania.
• W przypadku krótkotrwałej niedostępności naszej pamięci podręcznej mechanizm ograniczający działa w trybie fail-open, zamiast blokować Państwa integrację.

Webhooki przychodzące w Shopify nie podlegają ograniczeniom częstotliwości

Nie ograniczamy liczby webhooków przesyłanych nam przez Shopify - są one przyjmowane w miarę ich napływania i umieszczane w kolejce. Ograniczeniem jest **30-dniowy limit zdarzeń **przewidziany w Państwa planie.

Warto pamiętać o jednej rzeczy, jeśli tworzą Państwo własne wyzwalacze: Państwa kod jest uruchamiany przy każdym zdarzeniu w temacie, którego dotyczy, a każde uruchomienie liczy się jako jedno zdarzenie - w tym również te, które odfiltrowują Państwo poprzez zwracanie wartości null. Koszt tego działania jest taki sam, jak w przypadku wbudowanego wyzwalacza dla tego samego zdarzenia.

Shopify

Są to ograniczenia nałożone przez Shopify na interfejsy API tej platformy, a nie nasze. Mają one wpływ na to, jakie działania może wykonywać ta aplikacja (oraz Państwa procesy robocze) po stronie Shopify, i mogą Państwo napotkać je w przypadku dużych sklepów, nawet jeśli pozostają Państwo znacznie w granicach naszych limitów.

• W przypadku wszystkich interfejsów API Shopify maksymalna liczba elementów w tablicach wejściowych wynosi 250. Żądanie zawierające tablicę o większej liczbie elementów zostanie odrzucone.
• Paginacja kończy się po 25 000 obiektów. Liczby są dokładne do 25 000; powyżej tej liczby Shopify zwraca wartość 25001, co oznacza „ponad 25 000”. Jeśli chcą Państwo uzyskać więcej wyników, proszę najpierw zastosować filtr.
• Korzystanie z interfejsu API GraphQL Admin jest rozliczane na podstawie obliczonego kosztu zapytania, wyrażonego w punktach na sekundę, a limit zależy od planu Shopify, z którego korzysta sklep:

Plan Shopify	Punkty na sekundę
Standard	100
Zaawansowane	200
Ponadto	1000
Enterprise (komponenty handlowe)	2000

Interfejs API serwisu Storefront nie podlega ograniczeniom częstotliwości.

Szczegółowe informacje: Limity częstotliwości wywołań API Shopify