Korzystanie z API Passtastic | Passtastic Help
Passtastic
Explore
Product
Loyalty app
Pricing
Use Cases
Customer Stories
Help
No account yet? Sign up free

Korzystanie z API Passtastic

Co umożliwia Ci API

API Passtastic łączy Twoje własne systemy — niestandardowy POS, CRM, wewnętrzną aplikację — bezpośrednio z Twoim programem lojalnościowym. Dzięki niemu możesz:

  • Rejestrować klientów i wydawać karty wallet z własnego procesu rejestracji
  • Dodawać pieczątki lub punkty oraz sprawdzać saldo klienta z własnej kasy lub systemu back office
  • Otrzymywać powiadomienia w czasie rzeczywistym dzięki webhookom — zamiast ciągle odpytywać API, Passtastic wysyła zdarzenie do Twojego systemu w momencie, gdy coś się dzieje (klient się rejestruje, nagroda zostaje zrealizowana i inne)
  • Wykorzystywać klientów, których już masz — jeśli ktoś, kogo rejestruje Twój system, zapisał się już przez Twoją stronę rejestracji, Passtastic rozpoznaje go po e-mailu lub telefonie i dodaje Twoją referencję do karty, którą już ma, zamiast wydawać drugą

To rozwiązanie dla firm, które budują niestandardową integrację. Jeśli chcesz po prostu gotowe połączenie, zobacz Połącz Square POS lub Systemy POS i integracje — bez pisania kodu.

Dostęp do API zależy od Twojego planu. Jeśli nie jest w nim zawarty, po otwarciu API i webhooki w Ustawieniach zobaczysz propozycję ulepszenia planu.

Utwórz klucz API

1. Otwórz Ustawienia, a potem API i webhooki (w sekcji Firma).

2. Na karcie Klucze API kliknij Utwórz klucz testowy, aby wypróbować bez ryzyka, albo Utwórz klucz na żywo, gdy będziesz gotowy połączyć prawdziwych klientów.

3. Nadaj kluczowi nazwę, żebyś później wiedział, do czego służy (np. „CRM produkcyjny").

4. Twój nowy klucz zostanie pokazany jednorazowo, w oknie Twój nowy klucz API (dla klucza testowego: Twój nowy klucz testowy). Skopiuj go teraz — nie będziesz mógł zobaczyć go ponownie. Kliknij Kopiuj albo Pokaż, żeby najpierw go zobaczyć.

Traktuj ten klucz jak hasło. Każdy, kto go ma, może działać na Twoim koncie przez API.

5. Przechowuj klucz bezpiecznie we własnym systemie (zmienna środowiskowa, menedżer sekretów) i wysyłaj go jako nagłówek uwierzytelniający przy każdym zapytaniu — dokładny format znajdziesz w dokumentacji technicznej poniżej.

Klucze API mogą tworzyć i unieważniać wyłącznie administratorzy.

Wypróbuj najpierw z kluczem testowym

Klucze testowe działają w każdym planie, także podczas okresu próbnego — bez potrzeby ulepszania planu. Klienci testowi otrzymują prawdziwą kartę wallet, oznaczoną TEST, i są automatycznie usuwani po 30 dniach — nie musisz nic sprzątać ręcznie.

Skorzystaj z przewodnika Quickstart w dokumentacji technicznej razem z kluczem testowym — pokazuje on krok po kroku, jak zarejestrować klienta testowego i dodać kartę na własny telefon, zanim zaangażujesz jakiegokolwiek prawdziwego klienta.

Gdy Twoja integracja zadziała od początku do końca, wróć do API i webhooki i kliknij Utwórz klucz na żywo, aby przejść na prawdziwych klientów. Klucze na żywo są dostępne od planu Wiele Lokalizacji i wyższych.

Zgubiłeś klucz lub podejrzewasz wyciek?

Klucze nie są ponownie pokazywane po utworzeniu. Jeśli zgubiłeś klucz lub podejrzewasz, że wyciekł, otwórz Klucze API i kliknij przy nim Unieważnij — to natychmiast go zablokuje — a potem utwórz nowy i zaktualizuj swoją integrację.

Skonfiguruj webhook

Webhooki sprawiają, że Twój system reaguje w momencie, gdy coś dzieje się w Passtastic, bez konieczności ciągłego odpytywania API.

1. Na karcie Webhooki kliknij Dodaj endpoint.

2. Wpisz URL endpointu — adres w Twoim systemie, który odbierze zdarzenie (np. `https://twoj-system.com/hook`).

3. W sekcji Zdarzenia wybierz, które chcesz otrzymywać:

  • Klient zarejestrowany
  • Saldo zaktualizowane
  • Poziom zmieniony
  • Nagroda zrealizowana
  • Karta wygasła
  • Karta odnowiona

4. Zapisz. Twój sekret podpisujący zostanie pokazany jednorazowo, w oknie Sekret podpisujący — skopiuj go teraz. Użyj go, żeby sprawdzić, czy zapytanie webhook naprawdę pochodzi z Passtastic (dokumentacja techniczna wyjaśnia, jak zweryfikować podpis).

Webhooki mogą tworzyć i edytować wyłącznie administratorzy.

Każdy endpoint webhooka pokazuje swoje ostatnie dostawy, dzięki czemu możesz sprawdzić, czy wywołanie się powiodło, czy nie, oraz wysłać ponownie nieudaną dostawę, gdy tylko Twój system znów zadziała — bez czekania na kolejne zdarzenie.

Edycja lub wyłączanie webhooka

Otwórz endpoint i kliknij Edytuj, żeby zmienić jego URL lub zdarzenia, albo ustaw status na Wyłączony, żeby wstrzymać dostawy bez jego usuwania. Kliknij Usuń, żeby usunąć go na stałe.

Gdzie znaleźć pełną dokumentację techniczną

Ten przewodnik obejmuje część dotyczącą panelu — tworzenie kluczy i webhooków. Endpointy, formaty żądań/odpowiedzi, nagłówki uwierzytelniające, kody błędów i przykłady kodu znajdziesz w pełnej dokumentacji API, albo przejdź od razu do dokumentacji referencyjnej API, by zobaczyć schemat żądania/odpowiedzi każdego endpointu. Możesz też wejść do obu w każdej chwili z linków Przeczytaj dokumentację API i Dokumentacja referencyjna API na górze strony API i webhooki — dokumentacja referencyjna API otwiera się w nowej karcie.

Najczęstsze pytania

Czy potrzebuję systemu POS, żeby korzystać z API?
Nie. API służy do łączenia własnych systemów — niestandardowego POS-a, CRM-u lub aplikacji. Jeśli wolisz gotowe połączenie, zobacz Połącz Square POS lub Systemy POS i integracje.
Czy moja integracja utworzy zduplikowanych klientów?
Nie. Gdy Twój system rejestruje kogoś, Passtastic najpierw sprawdza, czy ten klient już istnieje na Twoim koncie — po referencji wysyłanej przez Twój system, potem po e-mailu, potem po telefonie. Jeśli tak, łączy Twoją referencję z jego istniejącą kartą zamiast wydawać drugą, dzięki czemu jego pieczątki i punkty pozostają tam, gdzie były. Jeśli dwóch klientów ma ten sam e-mail lub telefon, Passtastic nie zgaduje między nimi — zwraca błąd, który wskazuje obu, żeby Twój deweloper mógł wybrać właściwego.
Czy mój system może wiedzieć, kiedy karta klienta wygasa?
Tak. Jeśli Twoja karta ma okres ważności (Ważność karty w sekcji Szczegóły karty na karcie Konfiguracja programu), zaznacz w webhooku Karta wygasła i Karta odnowiona: Twój system dowie się, kiedy karta wygasa i kiedy zostaje odnowiona, także gdy odnawiasz ją w Passtastic. Twój programista może też odczytać datę końca karty każdego klienta i odnowić kartę z Twojego systemu. Aby to wypróbować, zanim wygaśnie prawdziwa karta, klucz testowy może od razu zakończyć ważność karty klienta testowego. Szczegóły znajdziesz w dokumentacji API.
Czy dostęp do API jest zawarty w moim planie?
API jest dostępne w planach Wiele Lokalizacji i Grupy i Marki. W planie Pojedyncza Lokalizacja API i webhooki w Ustawieniach pokazują propozycję ulepszenia planu zamiast Twoich kluczy.
Gdzie znajdę ID karty?
Otwórz zakładkę Udostępnij programu. W sekcji Udostępnij w Mediach Społecznościowych lub na Stronie zobaczysz jej link: część po `/get-pass/` to ID karty. Nie kopiuj ID z adresu strony programu, bo może to być inne ID. Twój programista może też pobrać listę wszystkich Twoich kart i ich ID przez API (`GET /api/v1/cards`).
Mój programista dostaje błąd "Missing scope(s): cards:read". Co mam zrobić?
Klucz został utworzony, zanim API umożliwiało pobieranie listy kart. Utwórz nowy klucz (Klucze API → Utwórz klucz), przekaż go programiście, a potem Unieważnij stary.
Kto może zarządzać kluczami API i webhookami?
Tylko administratorzy. Edytorzy i widzowie nie zobaczą opcji tworzenia, edycji ani unieważniania klucza lub webhooka.
Czy mogę mieć więcej niż jeden klucz API?
Tak — utwórz osobny klucz dla każdego systemu lub środowiska (np. jeden dla CRM-u, jeden dla środowiska testowego), żeby móc unieważnić jeden bez wpływu na pozostałe.
Webhook przestał otrzymywać zdarzenia — co się stało?
Otwórz endpoint i sprawdź ostatnie dostawy, żeby zobaczyć powód niepowodzenia (np. Twój serwer zwrócił błąd albo przekroczono limit czasu). Napraw problem po swojej stronie, a potem kliknij Wyślij ponownie przy nieudanej dostawie, żeby wysłać ją jeszcze raz.