Testowanie integracji

API ma jedno środowisko: produkcję (https://api.rezeri.com/v1, klucze rez_live_…). Integrację sprawdzasz na własnej organizacji z planem obejmującym dostęp do API — tymi samymi wywołaniami, których potem użyje Twój system.

Rezerwacja testowa

Przejdź Szybki start na własnej organizacji:

1. utwórz klucz w Ustawienia → API i webhooki;
2. zarezerwuj wolny termin, podając własne dane jako dane klienta — swój e-mail i, jeśli usługa go wymaga, swój telefon;
3. na koniec anuluj rezerwację przez POST /v1/bookings/{id}/cancel.

To prawdziwa rezerwacja. Zajmuje termin w kalendarzu, dopóki jej nie anulujesz, i wysyła te same wiadomości co każda inna:

• przy utworzeniu klient dostaje potwierdzenie e-mailem (i SMS-em, jeśli organizacja wysyła SMS-y), a pracownik — powiadomienie o nowej rezerwacji;
• przy anulowaniu przez API klient dostaje e-mail (i SMS) o odwołaniu wizyty, a pracownik — powiadomienie o anulowaniu. Zwolniony termin może też trafić do osób z listy oczekujących.

Dlatego nie wpisuj cudzych ani wymyślonych adresów. Wiadomości dla klienta trafią na Twoją skrzynkę i Twój telefon, więc przy okazji sprawdzisz, co zobaczy klient.

Rezerwację testową zakładaj na usługę bez płatności online (payment równe none albo optional). Usługę płatną sprawdzisz w trybie testowym bramki — patrz niżej.

Webhooki

Rezerwacja testowa i jej anulowanie dają prawdziwe zdarzenia (booking.created, booking.accepted, booking.cancelled) na każdy endpoint, który je subskrybuje. To najpełniejszy test odbiornika. Zobacz Webhooki.

Odbiornik na własnym komputerze

Na localhost dostawa nie dotrze — zobacz Wymagania wobec adresu. Odbiornik, który piszesz na swoim komputerze, wystaw więc przez tunel, na przykład:

cloudflared tunnel --url http://localhost:3000

ngrok http 3000

Zamiast 3000 podaj port swojego serwera. Narzędzie wypisze publiczny adres https. Pod tym adresem dostępny jest cały serwer na tym porcie, nie tylko odbiornik — nie uruchamiaj na nim niczego, czego nie chcesz pokazać w internecie. Zarejestruj ten adres razem ze ścieżką odbiornika (np. https://<adres-tunelu>/webhooks/rezeri) przez POST /v1/webhook-endpoints i zapisz zwrócony secret — patrz Rejestracja endpointu. Podpis weryfikuj na surowym body żądania, tak jak opisuje Weryfikacja podpisu.

Adres tunelu może się zmienić po ponownym uruchomieniu narzędzia. Wtedy podmień go w istniejącym endpoincie przez PATCH /v1/webhook-endpoints/{id} z nowym url, zamiast rejestrować kolejny — organizacja może mieć najwyżej 16 endpointów.

Żeby zobaczyć surowe żądanie — nagłówki, body i Rezeri-Signature — zanim napiszesz odbiornik, zarejestruj jako endpoint adres z webhook.site z payload_format: minimal (patrz ostrzeżenie niżej). Pełny kształt data.object opisuje Format dostawy.

Dane klienta

webhook.site i tunel to usługi firm trzecich — widzą całą dostawę. Endpoint dostaje subskrybowane zdarzenia ze wszystkich rezerwacji organizacji, także tych, które Twoi klienci składają w widgecie albo Ty w panelu. Przy payload_format: full dostawa niesie dane klienta. Dlatego na czas testu ustaw w endpoincie payload_format: minimal albo testuj na osobnej organizacji bez prawdziwych klientów (ona też potrzebuje planu z dostępem do API) — wtedy dane niesie tylko Twoja rezerwacja testowa na własne dane.

Gdy tunel nie działa, dostawy się nie udają i czekają na kolejne próby. Jeśli dostawa wyczerpie wszystkie próby, a endpoint od jej powstania nie przyjął z sukcesem żadnej innej dostawy, wyłączamy go — patrz Wyłączenie endpointu. Włączysz go ponownie przez PATCH z "enabled": true. Zdarzeń z okresu wyłączenia nie wysyłamy ponownie.

Po teście usuń endpoint przez DELETE /v1/webhook-endpoints/{id} albo wyłącz go przez PATCH z "enabled": false.

Historia dostaw

Dostawy endpointu zobaczysz w panelu: Ustawienia → API i webhooki → karta „Webhooki” → endpoint → sekcja „Ostatnie dostawy”. Historię i „Ponów” obsługuje właściciel organizacji w panelu — kluczem API ich nie wywołasz. Zdarzenie testowe wyślesz też kluczem API — patrz Przez API.

Lista pokazuje 50 najnowszych dostaw endpointu. Przy każdej:

• Czas — chwila zdarzenia.
• Zdarzenie — nazwa zdarzenia (przy nieznanym typie — jego type).
• Kod odpowiedzi — kod HTTP, którym Twój serwer odpowiedział na ostatnią próbę. „brak odpowiedzi” znaczy, że nie dostaliśmy kodu HTTP (np. błąd połączenia, przekroczone 10 sekund albo próba w toku), a „w kolejce” — że pierwszej próby jeszcze nie było.
• Próba — n/8: ile z 8 automatycznych prób już wykorzystaliśmy. Zobacz Ponowienia.

Zdarzeń testowych tu nie ma — ich wynik panel pokazuje od razu po wysłaniu.

Przy dostawie, która się nie udała — ostatecznie albo tylko w ostatniej próbie (wtedy czeka na kolejną) — jest przycisk „Ponów”. Po naprawie serwera nie musisz czekać na następną próbę:

• „Ponów” wysyła dostawę raz, od razu, i nie zużywa automatycznych prób — licznik n/8 się nie zmienia.
• Ponowiona dostawa ma to samo id, type i created_at, a data.object budujemy od nowa, z aktualnym stanem rezerwacji — tak jak przy każdej próbie (zobacz Jak odbierać zdarzenia). Deduplikacja po id działa więc także dla ponowień.
• Gdy ponowienie się uda, dostawa jest dostarczona i kolejnych prób nie będzie. Gdy się nie uda, panel pokaże nowy kod odpowiedzi, a dostawa, która czekała na automatyczną próbę, czeka na nią dalej.
• Wyłączony endpoint najpierw włącz. Dostawy rezerwacji, która została usunięta, ponowić się nie da.

Zdarzenie testowe

Bez tworzenia nowej rezerwacji wyślesz na endpoint zdarzenie testowe: w sekcji „Ostatnie dostawy” kliknij „Wyślij zdarzenie testowe” i wybierz rodzaj zdarzenia:

• Test połączenia (domyślnie) — zdarzenie webhook.test bez danych rezerwacji. Sprawdza sam odbiór i weryfikację podpisu.
• Jeden z typów, które endpoint subskrybuje, np. booking.payment_succeeded albo booking.payment_failed — przykładowe zdarzenie z danymi rezerwacji. Tak sprawdzisz obsługę płatności bez prawdziwej płatności (przy payload_format: full — przy minimal przykład nie niesie payment).

Zdarzenie testowe ma tę samą kopertę, nagłówki i podpis co każda dostawa:

{
  "id": "evt_test_9f2c41d07a6e4b1c8d3e5f60718293a4",
  "type": "webhook.test",
  "created_at": "2026-10-20T10:15:04.118230+02:00",
  "api_version": "v1",
  "test": true,
  "data": {}
}

• id zaczyna się od evt_test_ i jest nowe przy każdym wysłaniu.
• test jest true — po tym odróżnisz zdarzenie testowe od prawdziwej dostawy.
• data w webhook.test jest puste — zdarzenie nie dotyczy żadnej rezerwacji.
• Podpisujemy je aktywnymi sekretami endpointu, tak jak inne dostawy. Zobacz Weryfikacja podpisu.

Zdarzenie testowe niczego nie zmienia: rezerwacja zostaje bez zmian, zdarzenie nie trafia do historii dostaw i nie przybliża endpointu do wyłączenia. Wysyłamy je raz, bez ponowień. Wynik — kod odpowiedzi Twojego serwera albo brak odpowiedzi — panel pokazuje od razu.

Odbiornik powinien zweryfikować podpis i odpowiedzieć 2xx. Po zdarzeniu z test: true nie zmieniaj stanu u siebie: nie oznaczaj rezerwacji jako opłaconej i nie wysyłaj klientowi wiadomości. webhook.test zignoruj, tak jak każdy nieznany typ zdarzenia.

Przez API

Zdarzenie testowe wyślesz też bez panelu, kluczem ze scope webhooks:manage: POST /v1/webhook-endpoints/{id}/test. Robi to samo co przycisk w panelu — ta sama koperta, podpis i "test": true, także na wyłączony endpoint. Body jest opcjonalne: bez niego idzie webhook.test, z event_type — przykład typu rezerwacji, który endpoint subskrybuje. booking_id wskazuje rezerwację organizacji; bez niego przykład niesie najnowszą (przy webhook.test jest ignorowane).

curl -X POST https://api.rezeri.com/v1/webhook-endpoints/$ENDPOINT_ID/test \
  -H "Authorization: Bearer $REZERI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_type": "booking.payment_succeeded", "booking_id": "'"$BOOKING_ID"'"}'

Odpowiedź niesie wynik wysyłki na Twój serwer:

{
  "ok": true,
  "response_code": 200,
  "error": null
}

Gdy wysyłka się nie uda, ok jest false, a error ma kod: http_<kod> (Twój serwer odpowiedział kodem spoza 2xx), timeout, blocked_address i inne kody błędów połączenia; response_code jest wtedy kodem HTTP albo null.

• Rezeri czeka na Twój serwer do 10 sekund, więc odpowiedź może przyjść po tylu sekundach. Ustaw w kliencie HTTP timeout dłuższy niż 10 s. Testy jednej organizacji idą na serwerze po kolei, jeden naraz, więc kilka testów wysłanych jednocześnie odpowiada jeden po drugim.
• Limit to 10 wysyłek na minutę na klucz. Liczą się tylko żądania, które doszły do wysyłki; odrzucone (401, 403, 404, 409, 422) limitu nie zużywają. Po przekroczeniu dostajesz 429 rate_limited z Retry-After.
• Typ, którego endpoint nie subskrybuje, kończy się 422 webhook_event_not_subscribed, a organizacja bez rezerwacji i bez booking_id — 422 webhook_test_booking_missing. Endpoint albo rezerwacja spoza organizacji to 404 not_found. W tych przypadkach nic nie jest wysyłane.
• Organizacja, dla której Rezeri nie dostarcza dostaw (np. plan bez dostępu do API), dostaje 403 z kodem blokady już przy uwierzytelnianiu, jak każde wywołanie API. Gdy blokada pojawi się między uwierzytelnieniem a wysyłką, odpowiedź to 409 z tym samym kodem i nic nie jest wysyłane.

Przykładowe zdarzenie rezerwacji

Przykład typu rezerwacji niesie w data.object najnowszą rezerwację Twojej organizacji, w formacie endpointu — full albo minimal, tak jak prawdziwa dostawa. Udawany jest tylko type:

• data.object pokazuje bieżący stan rezerwacji i nie jest dopasowany do typu. booking.payment_succeeded przy rezerwacji bez płatności online przyjdzie (przy full) z jej prawdziwym payment.status (np. "not_required"), a booking.cancelled przy aktywnej rezerwacji — ze status: "accepted". Jeśli odbiornik porównuje type z data.object, przy test: true pomiń to sprawdzenie.
• Przykład wysłany zaraz po rezerwacji testowej złożonej w widgecie niesie jej identyfikator — ten sam, co bookingId w zdarzeniu rezeri:bookingSuccessful widgetu. Sprawdzisz tak np. dopasowanie konwersji. Jeśli w międzyczasie zarezerwuje ktoś inny, przykład poniesie jego rezerwację (przy full — z jego danymi, zobacz ostrzeżenie wyżej).
• Organizacja bez żadnej rezerwacji przykładu nie wyśle — panel pokaże komunikat „Żeby wysłać zdarzenie rezerwacji, najpierw utwórz rezerwację testową.” Utwórz ją tak, jak opisuje Rezerwacja testowa.

Płatności online

Płatność online sprawdzisz w trybie testowym bramki. Bramkę organizacji podłączasz w panelu w Integracje → Płatności. Przelewy24, PayU, Paynow, Tpay i Stripe mają przy podłączaniu przełącznik „Tryb testowy”:

1. odłącz bramkę i podłącz ją ponownie z danymi konta testowego operatora oraz włączonym „Trybem testowym”;
2. utwórz rezerwację na usługę płatną online i zapłać danymi testowymi operatora. Żadne pieniądze nie są pobierane;
3. odłącz bramkę i podłącz ją z powrotem z danymi produkcyjnymi i wyłączonym trybem testowym.

Tryb testowy dotyczy całej organizacji, nie tylko API. Dopóki jest włączony, także klienci z widgetu płacą w środowisku testowym operatora — nie zostawiaj go włączonego.

HotPay nie ma środowiska testowego. Z HotPay płatność sprawdzisz tylko prawdziwą transakcją.

Przepływ płatności opisuje Płatności online.