Przewodnik po integracji z Shopify

Tajo łączy Shopify z Brevo w dwóch miejscach. Aplikacja Shopify Tajo zamienia webhooki Shopify w zapisy w Brevo, gdy tylko nadejdą. Reguły synchronizacji, które buduje agent, a zatwierdza człowiek, przenoszą rekordy do Brevo według harmonogramu. Ta strona opisuje oba mechanizmy, a potem narzędzia Shopify, które Tajo udostępnia przez MCP.

Wymagania wstępne

Zanim zaczniesz integrację, upewnij się, że masz:

• Sklep Shopify w dowolnym planie (Basic, Shopify, Advanced lub Plus)
• Konto Tajo (Tajo jest we wczesnym dostępie)
• Konto Brevo, czyli miejsce docelowe synchronizacji
• Dostęp administratora do Twojego sklepu Shopify

Krok 1: Połącz swój sklep Shopify

Tajo jest we wczesnym dostępie. Aplikacji Shopify nie ma w Shopify App Store i nie ma linku do samodzielnej instalacji. Skontaktuj się z zespołem, żeby wszystko skonfigurować. Gdy Twój obszar roboczy Tajo będzie gotowy:

1. W Tajo otwórz Connections.
2. Wpisz domenę myshopify.com swojego sklepu i wybierz Connect Shopify. Shopify pokaże zakresy uprawnień, o które prosi Tajo, i po ich zatwierdzeniu przekieruje Cię z powrotem do Tajo.
3. Sprawdź, do czego służy każdy zakres i co Tajo zapisuje z powrotem w Shopify, w artykule Wyjaśnienie uprawnień Shopify.

Krok 2: Co aplikacja Shopify Tajo wysyła do Brevo

Aplikacja weryfikuje każdy webhook Shopify, zapisuje go, umieszcza w kolejce i od razu przetwarza. Tematy klientów i produktów najpierw czekają około czterech sekund. Nie ma okna wsadowego. Nieudane zadanie jest ponawiane z narastającym odstępem (backoff).

Tematy webhooków

Aplikacja Shopify Tajo subskrybuje te tematy webhooków Shopify:

Obsługiwane są także obowiązkowe webhooki prywatności Shopify (żądanie danych klienta, usunięcie danych klienta, usunięcie danych sklepu). Aplikacja nie subskrybuje carts/*. Porzucone koszyki pochodzą z tematów checkouts/*.

Co trafia do Brevo:

Aplikacja nie dodaje przycisku „Powiadom mnie” do Twojego motywu. Prośba o powiadomienie o dostępności musi pochodzić z Twojego sklepu, na przykład z przycisku, który sam dodasz.

Istniejące dane

Przy instalacji aplikacja importuje Twoich istniejących klientów jako kontakty Brevo. Pełną synchronizację historyczną uruchamiasz ze strony synchronizacji w aplikacji. W płatnych planach importuje ona również produkty, kolekcje, firmy i zamówienia.

Krok 3: Zbuduj regułę synchronizacji z agentem

Reguła synchronizacji to deklaratywna definicja jednej synchronizacji: zasób źródłowy, akcja w Brevo, mapowanie pól i filtr. Nie piszesz jej ręcznie. Opisujesz ją, agent ją buduje, a człowiek ją zatwierdza.

1. W Tajo otwórz Agents i poproś Brevo Integration Architect o synchronizację zwykłym językiem. Na przykład: „Wysyłaj do Brevo jako kontakty tych klientów Shopify, którzy zgodzili się na email marketing”.
2. Agent sprawdza konektor Shopify. Jego próbka zwraca nazwy i typy pól, nigdy wartości dotyczące klientów.
3. Proponuje regułę z mapowaniem pól i filtrem, następnie waliduje mapowanie pól względem akcji Brevo i wykonuje próbne uruchomienie (dry run) szkicu. Żaden z tych kroków nie odczytuje rekordów klientów.
4. Zapisuje regułę jako szkic. Możesz też zacząć od szablonu w Connections > Syncs and mappings > New sync from template.
5. Request publish approval uruchamia podgląd na Twoim sklepie. Odczytuje najwyżej 10 rekordów, niczego nie zapisuje w Brevo i nie przesuwa kursora. Zapisuje wyłącznie liczby: rekordy pobrane, kwalifikujące się, zmapowane i odrzucone przez filtr, a także błędy mapowania. Jeśli podgląd się nie powiedzie, prośba o zatwierdzenie nie powstaje.
6. Człowiek zatwierdza prośbę na stronie Approvals, podając pisemne uzasadnienie. Zatwierdzenie jest powiązane ze skrótem SHA-256 reguły i wygasa po 30 minutach. Na stronie reguły pojawia się wtedy Publish approved version.

Edycja opublikowanej reguły przywraca ją do stanu szkicu. Zanim znów zostanie uruchomiona, ponownie przechodzi przez podgląd i zatwierdzenie.

Prawdziwa reguła

Tak wygląda szablon Shopify customers -> Brevo contacts w definicji Tajo:

sourceSlug: "shopify",
sourceResource: "customers",
destinationSlug: "brevo",
destinationAction: "upsert_contact",
fieldMap: [
  { source: "email", destination: "email", transform: "toLowerCase" },
  { source: "first_name", destination: "attributes.FIRSTNAME" },
  { source: "last_name", destination: "attributes.LASTNAME" },
  { source: "phone", destination: "attributes.PHONE" },
  { source: "total_spent", destination: "attributes.TOTAL_SPENT", transform: "toNumber" },
  { source: "orders_count", destination: "attributes.ORDERS_COUNT", transform: "toNumber" },
  { source: "tajo_email_marketing_consent", destination: "attributes.OPT_IN", transform: "toBoolean" },
  { source: "tags", destination: "attributes.SHOPIFY_TAGS" },
  { source: "id", destination: "attributes.SHOPIFY_ID", transform: "toString" },
  { source: "created_at", destination: "attributes.SHOPIFY_CREATED_AT" },
  { source: "updated_at", destination: "attributes.SHOPIFY_UPDATED_AT" },
],
filterExpression:
  "($json.tajo_email_marketing_consent === true) && ($json.tajo_email_suppressed === false)",

Filtr jest sprawdzeniem zgody. Tajo wyprowadza obie wartości z pola Shopify email_marketing_consent.state lub ze starszej flagi accepts_marketing. Reguły, która zapisuje kontakty w Brevo, nie da się bez niego opublikować. Drugi szablon Shopify, Shopify orders → Brevo orders, rejestruje w Brevo zamówienia kupujących, którzy zgodzili się na marketing przy składaniu zamówienia.

Kiedy reguła działa

• Reguły synchronizacji kontaktów działają domyślnie co 15 minut. Każde uruchomienie zaczyna się od kursora reguły.
• Strona aktywnej reguły ma przycisk Test run (1 batch).
• Aktywna, opublikowana reguła Shopify orders → Brevo orders również działa co 15 minut. Jej pierwsze zaplanowane uruchomienie zaczyna się kilka minut przed tym momentem i nie wysyła starszych zamówień. Każde kolejne uruchomienie wysyła zamówienia zaktualizowane od poprzedniego.
• Wcześniejsze zamówienia trafiają do Brevo tylko wtedy, gdy uruchomisz regułę samodzielnie: przyciskiem Test run (1 batch) albo prosząc agenta Sync Operator o jej uruchomienie.
• Reguła zamówień działa według harmonogramu tylko z filtrem zgody kupującego na marketing (opt-in) z szablonu. Reguła z edytowanym filtrem działa tylko wtedy, gdy uruchomisz ją samodzielnie.
• Po pięciu kolejnych nieudanych uruchomieniach reguła sama się wstrzymuje, a jej strona pokazuje ostatni błąd. Usuń przyczynę, a potem opublikuj regułę ponownie.

Każde uruchomienie widnieje w historii uruchomień reguły z liczbą rekordów odczytanych, zapisanych i nieudanych oraz czasem trwania.

Co konektor Shopify odczytuje i zapisuje

Reguły synchronizacji zapisują tylko w miejscu docelowym, tutaj w Brevo. Nigdy nie zapisują niczego w Shopify.

Aplikacja Shopify Tajo prosi o 12 zakresów uprawnień i wykonuje w Shopify krótką listę zapisów, takich jak rezygnacje ze zgody i tagi lojalnościowe. Artykuł Wyjaśnienie uprawnień Shopify wymienia każdy zakres i każdy zapis wraz z tym, co go wywołuje.

Agenci i hosty MCP docierają do sklepu przez konektor Shopify:

Konektor deklaruje też korektę stanów magazynowych. Wymaga ona zakresu write_inventory, o który aplikacja Shopify Tajo nie prosi.

Krok 4: Korzystaj z narzędzi Shopify przez MCP

Tajo udostępnia konektor Shopify jako serwer MCP pod adresem https://alto.tajo.io/mcp/connectors/shopify. Dodaj go do Claude Code:

claude mcp add --transport http tajo-shopify https://alto.tajo.io/mcp/connectors/shopify

Host wykrywa serwer OAuth Tajo i otwiera logowanie do Tajo. Dostęp mają tylko konta z wczesnym dostępem. Serwer udostępnia 12 narzędzi:

Rozwiązywanie problemów

• Kontakty nie pojawiają się w Brevo: zobacz brakujące kontakty w Brevo.
• Reguła się nie uruchamia albo sama się wstrzymała: zobacz dane się nie synchronizują.

Kolejne kroki

• Zrozumienie synchronizacji danych, czyli jak działają reguły synchronizacji
• Wyjaśnienie uprawnień Shopify, każdy zakres i każdy zapis
• Shopify + Brevo, przewodnik po integracji
• Skontaktuj się z zespołem, żeby wszystko skonfigurować