Integracja z platformą Shopify

Koszyk.pro integruje się ze sklepami na platformie Shopify przez OAuth 2.0 oraz opcjonalny widget JavaScript. Shopify oferuje pełne wsparcie webhooków, co pozwala na powiadomienia w czasie rzeczywistym. Poniżej znajdziesz szczegółową instrukcję konfiguracji.

Jak połączyć sklep

Połączenie sklepu Shopify z Koszyk.pro zajmuje kilka minut. Wykonaj poniższe kroki:

Zaloguj się do swojego konta w Koszyk.pro.
Przejdź do sekcji „Sklepy" i kliknij przycisk „Dodaj sklep".
Wybierz platformę Shopify z listy dostępnych integracji.
Podaj adres URL swojego sklepu — w formacie twojsklep.myshopify.com (np. https://mójsklep.myshopify.com).
Kliknij „Autoryzuj" — zostaniesz przekierowany na stronę Shopify, gdzie musisz zaakceptować uprawnienia aplikacji. Koszyk.pro wymaga następujących uprawnień:
- read_checkouts — odczyt porzuconych koszyków
- read_orders — odczyt zamówień (do detekcji odzyskanych koszyków)
- read_customers — odczyt danych klientów
- read_products — odczyt informacji o produktach
Koszyk.pro nie modyfikuje żadnych danych w Twoim sklepie — wymaga wyłącznie uprawnień do odczytu.
Gotowe! Po pomyślnej autoryzacji zostaniesz przekierowany z powrotem do Koszyk.pro. Sklep pojawi się na liście ze statusem „Aktywny", a pierwsza synchronizacja koszyków rozpocznie się automatycznie.

Ważne: Tokeny dostępu Shopify nie wygasają. Autoryzacja jest jednorazowa — nie musisz jej ponawiać, chyba że samodzielnie odłączysz aplikację w panelu Shopify.

Synchronizacja koszyków

Koszyk.pro automatycznie pobiera porzucone koszyki (checkouts) z Twojego sklepu Shopify i wykrywa te, które zostały porzucone.

Jak działa polling

Co 15 minut nasz system odpytuje API Shopify (/admin/api/2024-01/checkouts.json) i pobiera aktualne porzucone koszyki. Każdy koszyk identyfikowany jest przez pole token z checkoutu Shopify (nie przez numer zamówienia), które zapisywane jest jako platform_cart_id w naszym systemie.

Webhooki (real-time)

Shopify wspiera webhooki, dzięki czemu Koszyk.pro może otrzymywać powiadomienia o nowych koszykach i zamówieniach w czasie rzeczywistym — bez czekania na polling. Webhooki konfigurowane są automatycznie podczas łączenia sklepu.

Przeliczanie cen

Shopify przechowuje ceny w centach (np. 1999 oznacza 19.99). Koszyk.pro automatycznie przelicza te wartości na format dziesiętny — nie musisz się tym martwić.

Detekcja porzucenia

Koszyk uznawany jest za porzucony, gdy:

Upłynął skonfigurowany czas od utworzenia lub ostatniej aktualizacji koszyka.
Klient nie złożył zamówienia — Koszyk.pro sprawdza to, dopasowując zamówienia po adresie email klienta.

Widget JavaScript zbiera zdarzenia po stronie przeglądarki klienta i przesyła je do Koszyk.pro w czasie rzeczywistym. Dzięki temu możesz identyfikować klientów nawet zanim zakończą zamówienie.

Instalacja

W panelu Shopify przejdź do Online Store → Themes → Edit code, otwórz plik theme.liquid i wklej poniższy snippet tuż przed zamykającym tagiem </body>:

      <script>
    window.koszyk = window.koszyk || { q: [] };
    window.koszyk.q = window.koszyk.q || [];
    window.koszyk.q.push(['init', 'TWOJ_TOKEN', { platform: 'shopify' }]);
  </script>
  <script async src="https://app.koszyk.pro/widget/koszyk-widget.min.js"></script>

Wartość TWOJ_TOKEN znajdziesz w panelu Koszyk.pro, w ustawieniach sklepu.

Co zbiera widget

Dane koszyka — widget pobiera aktualny stan koszyka przez Shopify AJAX API (/cart.js) i przesyła produkty, ceny oraz ilości do Koszyk.pro. Ceny w centach są automatycznie przeliczane na format dziesiętny.
Zdarzenia koszyka — widget przechwytuje wywołania fetch() do endpointów /cart/add i /cart/change. Po każdej zmianie koszyka pobiera aktualny stan i wysyła go do Koszyk.pro.
Adres email — na stronach checkout widget automatycznie przechwytuje email wpisany przez klienta w polach formularza (np. input[name="checkout[email]"]) i identyfikuje sesję.
Sesja klienta — widget generuje unikalny identyfikator sesji (cookie kp_sid, ważny 30 dni) i przypisuje do niego wszystkie zdarzenia. Pozwala to powiązać koszyk z klientem nawet bez podania emaila.
Zakończenie zamówienia — widget wykrywa strony /thank_you oraz /orders/ i wysyła event order_completed, co pozwala automatycznie oznaczyć koszyk jako odzyskany.

Popup do zbierania emaili

Widget może wyświetlać popup z prośbą o podanie adresu email. Popup można skonfigurować w panelu Koszyk.pro i ustawić wyzwalacze:

Exit intent — popup pojawia się, gdy kursor myszy opuści obszar strony (próba zamknięcia karty).
Dodanie do koszyka — popup wyświetla się po dodaniu produktu do koszyka.

Wygląd popupu (kolory, nagłówek, treść przycisku) można dostosować w konfiguracji widgetu. Popup wyświetla się maksymalnie raz na sesję.

FAQ

Czy tokeny dostępu wygasają?

Nie. Tokeny Shopify są permanentne — po jednorazowej autoryzacji połączenie działa bezterminowo. Nie musisz ponawiać autoryzacji, chyba że samodzielnie odłączysz aplikację w panelu Shopify (Apps → Manage apps).

Koszyki nie synchronizują się

Sprawdź kolejno:

Status sklepu — synchronizacja działa tylko dla sklepów ze statusem „Aktywny".
Uprawnienia — upewnij się, że aplikacja Koszyk.pro ma uprawnienie read_checkouts w panelu Shopify. Bez tego uprawnienia API zwraca błąd 403.
Adres URL sklepu — upewnij się, że adres sklepu jest poprawny i w formacie twojsklep.myshopify.com.

Identyfikator koszyka wygląda jak losowy ciąg znaków

To normalne zachowanie. Shopify identyfikuje porzucone koszyki (checkouty) przez pole token, które jest losowym ciągiem znaków (np. abc123def456...). Nie jest to numer zamówienia — Shopify tak właśnie identyfikuje checkouty w swoim API.

Widget nie działa