Interfejs API dla programistów i MCP
Zarządzaj webhookami Shopify Flow przez REST API lub asystenta AI przez MCP. Klucze API z poziomami dostępu: odczyt, zapis i wykonanie.
Wszystkimi funkcjami, którymi zarządzają Państwo w aplikacji, mogą Państwo również zarządzać za pomocą własnego kodu lub asystenta AI. Usługa Workflow Webhooks udostępnia dwa interfejsy: interfejs API REST oraz serwer MCP. Oba znajdują się na stronie dla programistów.
Klucze API
Obie platformy uwierzytelniają się za pomocą klucza API. Na stronie Dla programistów, w sekcji Klucze API, należy utworzyć klucz i wybrać jego poziom dostępu:
- Tylko do odczytu - wyświetlanie listy webhooków, historia wywołań oraz statystyki.
- Odczyt i zapis - a także tworzenie, aktualizowanie i usuwanie webhooków.
- Odczyt, zapis i wykonanie - można również uruchomić wywołanie testowe lub odtworzyć wcześniejsze wywołanie.
Pełny klucz jest wyświetlany tylko raz, w momencie utworzenia. Proszę go wówczas skopiować i przechowywać w bezpiecznym miejscu; nie będzie już Pana/Pani można go ponownie wyświetlić. Klucze są przechowywane w postaci zaszyfrowanej, nigdy w postaci zwykłego tekstu, a klucz można unieważnić w dowolnym momencie.
Proszę przesyłać klucz jako token typu „Bearer” w każdym żądaniu:
Authorization: Bearer fwk_your_key_hereDlaczego „wykonanie” stanowi odrębny poziom
Wywołanie webhooka faktycznie uruchamia Państwa przepływy pracy w Shopify Flow, a przepływy te mogą wprowadzać zmiany w Państwa sklepie - np. oznaczanie zamówień, wysyłanie wiadomości e-mail czy aktualizowanie stanów magazynowych. Oddzielenie tego procesu na osobnym poziomie oznacza, że klucz, który przekazują Państwo skryptowi lub asystentowi AI do codziennej pracy, nie może przypadkowo uruchomić Państwa automatyzacji. Domyślnie należy przyznawać klucze do odczytu, a klucz wykonawczy należy tworzyć wyłącznie wtedy, gdy jest on rzeczywiście potrzebny.
Adres URL bazowy
Interfejs API oraz serwer MCP są udostępniane pod dedykowaną nazwą hosta:
https://shopify.workflow-webhooks.appZatem interfejs API REST znajduje się pod adresem https://shopify.workflow-webhooks.app/api/v1, a serwer MCP pod adresem https://shopify.workflow-webhooks.app/api/mcp. Na stronie dla programistów wyświetlane są oba adresy wraz z przyciskiem „Kopiuj”.
Ta nazwa hosta obsługuje wyłącznie /api - wbudowany interfejs administracyjny pozostaje pod własnym adresem URL zarejestrowanym w Shopify. Rozdzielenie tych elementów oznacza, że adres, który wkleja Pan/Pani do skryptu, zadania CI lub klienta AI, jest stały i niezależny od sposobu osadzenia aplikacji.
Interfejs API REST
Podstawowy adres URL jest podany na stronie dla programistów. Główne punkty końcowe:
| Metoda | Ścieżka | Poziom | Cel |
|---|---|---|---|
| POBRAĆ | /api/v1 |
brak | Indeks API - potwierdza, że API działa |
| POBRAĆ | /api/v1/me |
przeczytaj | Sprawdź uprawnienia i poziom swojego klucza |
| POBRAĆ | /api/v1/webhooks |
przeczytaj | Wyświetl listę webhooków |
| POST | /api/v1/webhooks |
napisać | Utwórz webhook |
| POBRAĆ | /api/v1/webhooks/:id |
przeczytaj | Utwórz jeden webhook |
| PUT / PATCH | /api/v1/webhooks/:id |
napisać | Zaktualizowanie webhooka |
| USUŃ | /api/v1/webhooks/:id |
napisać | Usuń webhook |
| POST | /api/v1/webhooks/:id/test |
wykonać | Wykonaj wywołanie testowe |
| POBRAĆ | /api/v1/history |
przeczytaj | Wywołania list |
| POBRAĆ | /api/v1/history/:id |
przeczytaj | Pobierz jedno wywołanie wraz z jego danymi |
| POST | /api/v1/history/:id/replay |
wykonaj | Odtworzenie poprzedniego wywołania |
| POBRAĆ | /api/v1/stats |
przeczytaj | Wyniki ogólne, wskaźnik skuteczności, serie dzienne |
| POBRAĆ | /api/v1/templates |
przeczytaj | Wbudowane szablony webhooków |
Szybkie sprawdzenie, czy Państwa klucz działa:
curl https://shopify.workflow-webhooks.app/api/v1/me \
-H "Authorization: Bearer fwk_your_key_here"{ "authenticated": true, "shop": "your-store.myshopify.com", "level": "READ" }Serwer MCP
Serwer MCP umożliwia asystentom AI (takim jak Claude, Cursor, VS Code, Gemini CLI i innym) korzystanie z Państwa webhooków w trakcie rozmowy. Na stronie „Dla programistów” w zakładce MCP wyświetlany jest adres URL serwera oraz gotowe do skopiowania polecenie połączenia dla każdego klienta, z już wstawionym Państwa kluczem.
Narzędzia te odzwierciedlają punkty końcowe REST, a zestaw narzędzi zależy od poziomu uprawnień Państwa klucza: klucz z uprawnieniami wyłącznie do odczytu nie ma nawet dostępu do narzędzi służących do tworzenia, usuwania ani uruchamiania webhooków. Cały proces uwierzytelniania oraz przetwarzania danych odbywa się po stronie serwera.
W jaki sposób chronione są Państwa dane
Zanim wykorzystają Państwo to API w ramach automatyzacji lub z pomocą asystenta opartego na sztucznej inteligencji, warto zapoznać się z dwiema kwestiami.
Token uwierzytelniający Państwa webhooka nigdy nie jest dostępny do odczytu. Token ani klucz podpisujący ustawiony w webhooku nie mogą zostać odczytane za pośrednictwem API ani MCP na żadnym poziomie. Odpowiedzi informują jedynie o tym, czy token jest ustawiony (hasToken), ale nigdy nie podają jego wartości. Mogą Państwo ustawić nowy token; starego nie da się nigdy odzyskać.
Dane osobowe w treściach żądań są zamaskowane. Treści żądań webhooków pochodzą z systemów zewnętrznych i często zawierają dane klientów. Zanim ładunek wywołania opuści serwer, wartości przypominające dane osobowe są zastępowane znakami ***: adresy e-mail, numery telefonów, numery kart oraz pola nazwane na cześć osoby (customerName, shippingAddress i podobne). Nagłówki żądań są oczyszczane w taki sam sposób, jak ma to miejsce na ekranie historii aplikacji.
Takie maskowanie jest starannie przeprowadzone, ale nie stanowi gwarancji. Działa ono w odniesieniu do nazw pól i wzorców wartości, więc dane osobowe zawarte w polu tekstowym - notatka, komentarz, treść wiadomości - mogą nadal zostać ujawnione. Prosimy traktować odpowiedzi API jako potencjalnie zawierające dane klientów i przechowywać je odpowiednio.
Funkcje testowania i odtwarzania nie wykorzystują Państwa limitu. Wywołania wysyłane za pośrednictwem interfejsu API są rejestrowane jako testy, więc nie są wliczane do miesięcznego limitu przewidzianego w Państwa planie. Odtwarzania również nie są wliczane, ponieważ zostały już uwzględnione w ramach pierwotnego wywołania.
Kolejne kroki
- Wprowadzenie do Workflow Webhooks - jak działają webhooki i mapowanie danych.
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ę. Oba limity są wykorzystywane, więc seria wywołań wykonawczych również zużywa wspólny limit. W przypadku tej aplikacji oznacza to testowe wywołanie webhooka oraz odtworzenie wpisu z historii - obie te operacje faktycznie uruchamiają Państwa przepływy pracy w Shopify Flow.
- W każdym planie jest tak samo. Państwa plan uwzględnia liczbę wywołań, a nie liczbę żądań 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ę.
Przychodzące webhooki nie podlegają ograniczeniom szybkości
Warto to jasno podkreślić, ponieważ jest to pytanie, które słyszymy najczęściej: nie ograniczamy przepustowości przychodzących powiadomień webhook. Przesyłamy je tak szybko, jak tylko napływają, niezależnie od tego, w jakich seriach generuje je Państwa system źródłowy - z naszej strony nie ma żadnych limitów na sekundę ani na minutę.
Jedynym ograniczeniem jest **30-dniowy limit wywołań **przewidziany w Państwa planie. Po wyczerpaniu tego limitu dalsze wywołania nie będą przetwarzane do momentu rozpoczęcia nowego okresu rozliczeniowego lub przejścia na wyższy plan. Poza tym obowiązują ograniczenia ustalone przez Shopify: Shopify Flow ma własne limity wykonania, a rozmiar danych wyzwalacza jest ograniczony do 50 KB.
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