Shoper i Meta Conversions API: jak wysyłać zamówienia jako serwerowe zdarzenia Purchase

Zamówienie ze Shopera jako serwerowe zdarzenie Purchase to zakup, który do Meta wysyła serwer, a nie przeglądarka klienta. Taki zakup nie znika, gdy klient ma blokadę reklam, nie kliknie zgody albo zamknie kartę przed stroną podziękowania. Poniżej: jakie pola Meta wymaga, jak Basketly czyta zamówienia prosto z API Shopera, jak nie policzyć zamówienia dwa razy i gdzie sprawdzić, czy zakupy dochodzą. Na końcu uczciwie: czego to połączenie nie robi.

Dlaczego Pixel w sklepie to za mało?

Pixel to skrypt w przeglądarce. Wysyła Purchase tylko wtedy, gdy strona podziękowania się załaduje, skrypt nie jest zablokowany, a klient zgodził się na pliki cookies marketingowe. Każdy z tych warunków czasem zawodzi, a Ty nie wiesz, ile zakupów w ten sposób przepada.

Meta sama zaleca, żeby Conversions API działało obok Pixela, a nie zamiast niego. Serwer widzi każde opłacone zamówienie, więc może wysłać Purchase niezależnie od tego, co stało się w przeglądarce.

Ważne zastrzeżenie: lepsze dane to nie gwarancja lepszych wyników. Conversions API daje Mecie pełniejszy obraz zakupów, ale nie dowodzi, że kampania jest optymalizowana pod te zdarzenia, ani nie rozstrzyga atrybucji. Więcej o tym w artykule Meta Conversions API: co to jest.

Jakie pola musi mieć serwerowy Purchase?

Serwerowy Purchase musi mieć nazwę, czas, źródło akcji, wartość i walutę oraz dane, po których Meta rozpozna klienta. Bez nich zdarzenie zostanie odrzucone albo słabo dopasowane do osoby, która kliknęła reklamę.

Dwie rzeczy łatwo przeoczyć. Po pierwsze, client_user_agent to przeglądarka klienta, a nie Twojego serwera. Po drugie, czas ma znaczenie: Meta w przewodniku wdrożenia zaleca wysyłkę w czasie rzeczywistym albo w ciągu godziny od zdarzenia. Jakie dane klienta najbardziej pomagają w dopasowaniu, opisujemy w tekście o Event Match Quality.

Jak Basketly czyta zamówienia ze Shopera?

Basketly łączy się z API Twojego sklepu jako osobny użytkownik API, zakłada w sklepie webhook i dociąga zamówienia co 15 minut. Każde opłacone zamówienie staje się jednym zdarzeniem Purchase w kolejce do Mety, bez kodu po Twojej stronie.

Co wpisujesz przy połączeniu

W panelu sklepu zakładasz administratora z typem „Dostęp do API” i prawem odczytu zamówień, produktów, kategorii, producentów i walut oraz webhooków (webhooki także z prawem dodawania i usuwania). W źródle Shoper w Basketly wybierasz „Połączenie z API Shopera” i podajesz:

• login i hasło tego użytkownika; hasło jest przechowywane zaszyfrowane,
• statusy liczone jako zakup poza flagą „opłacone” Shopera, np. status za pobraniem (numery statusów po przecinku),
• identyfikator produktu w katalogu Mety: ID produktu w Shoperze (domyślnie), ID wariantu (stock_id), kod (SKU) albo EAN; musi być taki sam jak w katalogu, inaczej reklamy katalogowe nie połączą zakupu z produktem,
• potwierdzenie podstawy prawnej przekazywania danych zamówień (e-mail, telefon) do Mety.

Webhook i dociąganie co 15 minut

Po połączeniu Basketly loguje się do sklepu i zakłada webhook na zdarzenia order.create, order.paid, order.status oraz zmiany produktów. Każde powiadomienie jest sprawdzane podpisem Shopera. Shoper doręcza webhook tylko raz, bez ponowień, więc niezależnie od niego co 15 minut Basketly czyta zamówienia, których status zmienił się od ostatniego odczytu. Przy pierwszym połączeniu czyta zamówienia z 7 dni wstecz i wszystkie produkty. Przycisk „Pobierz teraz” uruchamia odczyt zamówień i produktów od razu, a „Odłącz” usuwa webhook ze sklepu i zapomina login.

Co trafia do Mety

Zamówienie oznaczone w Shoperze jako opłacone albo z wybranym statusem zakupu idzie jako Purchase:

1. external_id to numer zamówienia, a event_id ma postać shoper-order-<numer>, więc to samo zamówienie nigdy nie trafi do kolejki dwa razy.
2. Wartość i waluta z zamówienia, identyfikatory produktów z pozycji (do 100) według wybranego pola.
3. E-mail i telefon klienta, znormalizowane i zahashowane SHA-256; sam 9-cyfrowy numer traktujemy jako polski.
4. Adres IP klienta zapisany przez sklep, bez hashowania.
5. Zamówienie odczytane z API nie ma danych przeglądarki, więc bez User-Agenta idzie jako system_generated, a nie website.

Zamówienia, także nieopłacone i anulowane, zostają w panelu na stronie Zamówienia, a kupujący trafia do Klientów. Raz na połączenie Basketly czyta też zamówienia z ostatnich 24 miesięcy, ale z historii niczego nie wysyła do Mety. Więcej na stronie Zamówienia i kupujący.

Do czego służy skrypt w sklepie?

Skrypt kolektora instalujesz w sklepie i wywołujesz z banera zgód. Przed zgodą niczego nie zapisuje i nie wysyła. Zakupu sam nie potwierdza: robi to wyłącznie serwer, bo publiczny klucz skryptu zna każdy, kto otworzy stronę.

Po zgodzie (setConsent(true)) skrypt:

• korzysta z istniejącego ciasteczka _fbp albo tworzy własny identyfikator, więc działa także bez Pixela,
• zapisuje _fbc i prawdziwy parametr fbclid z linku reklamy; nigdy nie tworzy fbc bez rzeczywistego kliknięcia,
• trzyma identyfikator w przeglądarce do 30 dni,
• może liczyć oglądania produktów, dodania do koszyka i rozpoczęte zamówienia (track('view_item' | 'add_to_cart' | 'begin_checkout', [id produktów])) do statystyk produktów; to dzienne liczniki bez żadnej osoby.

Wycofanie zgody (setConsent(false)) usuwa stan w przeglądarce i dane przypisania po stronie serwera. Nie cofa konwersji, które już trafiły do Meta.

A jeśli mój sklep to nie Shoper?

Inne sklepy i własne systemy wysyłają potwierdzone zamówienia na bezpieczny adres źródła z prywatnym tokenem. To wymaga kodu po stronie sklepu, ale reguły są te same: tylko status purchase, obowiązkowy event_id, wartość i waluta.

POST /api/ingest/SOURCE_ID
Authorization: Bearer PRYWATNY_TOKEN_ŹRÓDŁA
Content-Type: application/json

Taki adapter przekazuje identyfikator zamówienia, event_id, czas, e-mail lub telefon, wartość, walutę i zgodę. Może też dołączyć tracking_id ze skryptu (wtedy zakup dostaje fbp i fbc klienta) albo sam podać IP i User-Agent prawdziwego klienta. Adres strony musi należeć do domeny sklepu, a zdarzenie website bez User-Agenta klienta jest odrzucane. Nigdy nie wysyłaj IP ani User-Agenta własnego serwera. Pole consent: true oznacza, że Twój proces potwierdza podstawę prawną przekazania danych; szerzej w tekście RODO i Conversions API (to nie jest porada prawna).

Jak nie policzyć zamówienia dwa razy?

Jeśli w sklepie działa Pixel wysyłający Purchase, Meta dostanie ten sam zakup z przeglądarki i z serwera. Zliczy go raz tylko wtedy, gdy oba zdarzenia mają tę samą nazwę i ten sam identyfikator: eventID w Pixelu i event_id w Conversions API.

Meta deduplikuje pary, które dotrą w ciągu 48 godzin. Serwer wysyła identyfikator shoper-order-<numer zamówienia>, więc Pixel na stronie podziękowania powinien używać dokładnie takiego eventID. Jeśli Twoja instalacja Pixela nie pozwala go ustawić, podwójnej wysyłki nie da się uczciwie uznać za rozwiązaną. Szczegóły i typowe błędy opisuje artykuł o deduplikacji zdarzeń Pixela i CAPI.

Po stronie Basketly działa druga warstwa ochrony: ta sama kombinacja zbioru danych, nazwy zdarzenia, event_id i trybu (test lub produkcja) nie trafi do kolejki dwa razy.

Gdzie sprawdzić, czy zakupy dochodzą?

Zamówienie trafia do trwałej kolejki. Przy błędzie sieci, limicie zapytań (429) albo błędzie serwera Meta Basketly ponawia wysyłkę do 6 razy z rosnącymi odstępami i respektuje nagłówek Retry-After. Inne błędy czekają na ręczne ponowienie po naprawie przyczyny.

Wynik widać w kilku miejscach:

• Konwersje (bilans zakupów z 7, 14 lub 30 dni): zamówienia ze sklepu, zakupy przyjęte przez Basketly i dla każdego odbiorcy przyjęte, błędy i oczekujące, dzień po dniu, z najczęstszymi przyczynami błędów.
• Zdarzenia: każda wysyłka do Mety ze statusem, liczbą prób i ostatnim błędem.
• Kampanie: zakupy, ich wartość i ROAS tak, jak raportuje je Meta (jej atrybucja), obok przychodu sklepu.
• Raporty: przychód sklepu obok wydatków wszystkich kanałów reklamowych (MER łącznie), zamówienia według źródła i odsetek zamówień przyjętych do wysyłki.

Status „przyjęte przez Meta” oznacza odpowiedź, w której Meta policzyła zdarzenie. To potwierdzenie odbioru, a nie dowód jakości dopasowania, celu kampanii ani atrybucji. Jeśli chcesz, te same zakupy mogą iść z serwera także do GA4, TikToka, Pinteresta, Klaviyo (zakupy z e-mailem), Google Ads i Microsoft Ads (zakupy z kliknięć ich reklam): włączasz to przełącznikiem „Wysyłaj zakupy” przy połączeniu na stronie Konwersje. Więcej o źródłach na stronie Integracje.

Ograniczenia

Zanim zaczniesz, sprawdź, czy te ograniczenia Ci nie przeszkadzają:

• Gotowe połączenie jest tylko dla Shopera. IdoSell, WooCommerce, Shopify i BaseLinker są w planach; inne sklepy wysyłają zamówienia własnym kodem na adres źródła.
• Zamówienie z API nie ma danych przeglądarki. Idzie jako system_generated z e-mailem, telefonem i IP, bez fbp i fbc, więc dopasowanie zależy głównie od danych kontaktowych klienta.
• Tylko opłacone zakupy. Koszyki, rozpoczęte płatności i zwroty nie idą do Mety jako zdarzenia.
• Limit 7 dni. Zamówień starszych niż 7 dni Meta nie przyjmie; historia z 24 miesięcy zostaje tylko w panelu.
• Limity Shopera. Basketly czeka, gdy sklep każe zwolnić (Retry-After), i czyta do 40 stron zamówień na jeden odczyt, więc przy bardzo dużym ruchu zaległości nadrabia w kolejnych przebiegach.
• Lokalny adres serwera nie dostanie webhooków; wtedy działa tylko dociąganie co 15 minut.
• Zakupy w Kampaniach to raport Mety; przychodu sklepu nie przypisujemy pojedynczym kampaniom.

Następny krok

Załóż organizację, dodaj testowego odbiorcę Meta i źródło Shoper, połącz je z API sklepu i złóż zamówienie testowe. Plany i limity zamówień miesięcznie znajdziesz w cenniku.