Dokumentacja dla programistów

Dokumentacja JS API

Tracker udostępnia jedną funkcję, paczesny.track(), do wszystkiego poza automatycznymi odsłonami. Ta strona opisuje jej sygnaturę oraz pięć zdarzeń e-commerce, które endpoint zbierający dane waliduje i zapisuje: view_item, add_to_cart, begin_checkout, purchase i refund.

Wywołanie track()

Wywołaj paczesny.track() z nazwą zdarzenia i zwykłym obiektem właściwości, po załadowaniu skryptu trackera. Nie potrzeba konfiguracji, plików cookie ani banera zgody. Nieznane nazwy właściwości są usuwane po stronie serwera, więc wysyłanie dodatkowych kluczy jest bezpieczne, ale nic nie daje.

paczesny.track(name, props);

view_item

Wyślij je, gdy klient otwiera stronę produktu. Korzysta ze standardowego kanału zdarzeń niestandardowych, więc nie powstaje rekord zamówienia: to sygnał lejka, a nie przychód.

Pole	Typ	Wymagane	Opis
itemId	string	Tak	Twój identyfikator produktu lub SKU. Przycinany, od 1 do 128 znaków.
itemName	string	Nie	Czytelna nazwa produktu, do 256 znaków.
priceMinor	integer, minor units	Nie	Cena jednostkowa jako liczba całkowita w najmniejszej jednostce waluty, na przykład 4999 dla 49,99.
quantity	integer	Nie	Liczba sztuk jako liczba całkowita. Musi być dodatnia.

paczesny.track("view_item", {
  itemId: "sku_123",
  itemName: "Wireless Mouse",
  priceMinor: 4999,
  quantity: 1,
});

add_to_cart

Wyślij je, gdy klient dodaje produkt do koszyka. Ten sam zestaw pól co view_item i tak samo nie powstaje rekord zamówienia.

Pole	Typ	Wymagane	Opis
itemId	string	Tak	Twój identyfikator produktu lub SKU. Przycinany, od 1 do 128 znaków.
itemName	string	Nie	Czytelna nazwa produktu, do 256 znaków.
priceMinor	integer, minor units	Nie	Cena jednostkowa jako liczba całkowita w najmniejszej jednostce waluty, na przykład 4999 dla 49,99.
quantity	integer	Nie	Liczba sztuk jako liczba całkowita. Musi być dodatnia.

paczesny.track("add_to_cart", {
  itemId: "sku_123",
  itemName: "Wireless Mouse",
  priceMinor: 4999,
  quantity: 2,
});

begin_checkout

Wyślij je, gdy klient wchodzi do kasy. Oba pola są opcjonalne, więc pusty obiekt właściwości również jest poprawny.

Pole	Typ	Wymagane	Opis
valueMinor	integer, minor units	Nie	Wartość koszyka jako liczba całkowita w najmniejszej jednostce waluty, na przykład 9998 dla 99,98.
itemCount	integer	Nie	Liczba pozycji w koszyku przy wejściu do kasy. Zero lub więcej.

paczesny.track("begin_checkout", {
  valueMinor: 9998,
  itemCount: 2,
});

purchase

Wyślij je po potwierdzeniu zamówienia, zwykle na stronie z podziękowaniem. To jedyne zdarzenie, które zapisuje trwały rekord zamówienia, dlatego jego pola są walidowane rygorystycznie, a przychód zmiennoprzecinkowy jest odrzucany, nie zaokrąglany.

Pole	Typ	Wymagane	Opis
orderId	string, max 128 chars	Tak	Twój identyfikator zamówienia. Pełni też rolę klucza idempotencji, więc musi być stabilny mimo przeładowań strony i ponowionych płatności.
revenue	integer, minor units	Tak	Wartość zamówienia jako liczba całkowita w najmniejszej jednostce waluty. Liczby zmiennoprzecinkowe są odrzucane, nigdy zaokrąglane.
currency	ISO 4217 string	Tak	Kod ISO 4217 wielkimi literami, na przykład PLN lub EUR. Kody zapisane małymi literami są odrzucane.
items	array, max 20 items	Nie	Pozycje koszyka, każda z polem id oraz opcjonalnie name, priceMinor, quantity i category. Zapisujemy pierwsze 20 pozycji, a prawdziwa liczba pozycji jest zawsze zachowana.

paczesny.track("purchase", {
  orderId: "ORDER-1042",
  revenue: 9998,
  currency: "PLN",
  items: [
    {
      id: "sku_123",
      name: "Wireless Mouse",
      priceMinor: 4999,
      quantity: 2,
    },
  ],
});

refund

Wyślij je, aby zgłosić pełny lub częściowy zwrot dla istniejącego zamówienia. Odejmujemy go od przychodu w pierwotnym dniu zamówienia, nigdy w dniu, w którym dotarł zwrot, więc korygujemy sumy z przeszłego dnia, zamiast zaniżać dzień późniejszy.

Pole	Typ	Wymagane	Opis
orderId	string, max 128 chars	Tak	Ten sam identyfikator zamówienia, który wysłałeś w zdarzeniu purchase. Nieznane orderId jest odrzucane i logowane, nigdy po cichu przyjmowane i nigdy nie tworzy nowego zamówienia.
amountMinor	integer, minor units	Nie	Zwracana kwota jako liczba całkowita w najmniejszej jednostce waluty. Pomiń to pole w całości, aby zwrócić całe pozostałe saldo. Zwroty częściowe sumują się, a kwota przekraczająca pozostałe saldo jest odrzucana i logowana, nigdy przycinana.

paczesny.track("refund", {
  orderId: "ORDER-1042",
  amountMinor: 4999,
});

Idempotencja zamówień

Każdy zakup zapisujemy pod kluczem wyliczonym z Twojej witryny i orderId, dodatkowo zabezpieczonym unikalnym indeksem. Ponowne wysłanie tego samego zakupu po przeładowaniu strony, ponowieniu płatności lub podwójnym kliknięciu nigdy nie zliczy przychodu dwa razy: wygrywa pierwszy zapis, a kolejny trafia do logu jako konflikt i niczego nie nadpisuje. Wysyłaj to samo orderId dla tego samego zamówienia, a inne wyłącznie dla faktycznie innego zamówienia.

Czego nigdy nie zapisujemy

Nazwy pól to lista dozwolonych, a nie lista zabronionych. Zapisujemy wyłącznie właściwości wymienione w tabelach powyżej; wszystko inne, w tym adres e-mail, imię i nazwisko, adres, numer telefonu klienta czy dowolny Twój własny klucz, jest usuwane podczas walidacji i nigdy nie trafia do bazy. Dopasowanie jest dokładne i rozróżnia wielkość liter, więc EMAIL i Email są usuwane tak samo jak email. Nie ukrywaj też danych osobowych w dozwolonych polach: nigdy nie używaj adresu e-mail klienta jako orderId.

Liczby całkowite w najmniejszej jednostce waluty

Pola revenue, priceMinor i valueMinor to zawsze liczby całkowite w najmniejszej jednostce waluty. 12999 oznacza 129,99 w walucie z dwoma miejscami po przecinku, takiej jak PLN czy EUR, a liczba miejsc dziesiętnych wynika z waluty, więc waluta bez części ułamkowej, taka jak JPY, przyjmuje kwotę wprost. Liczba zmiennoprzecinkowa, na przykład 129,99, jest odrzucana i logowana, nigdy zaokrąglana, dzięki czemu zapisana wartość jest dokładnie tą, którą wysłałeś.