Jak podłączyć swoją stronę przez API

Ten artykuł jest dla właściciela konta, którego informatyk albo agencja chce wpiąć rezerwacje Rezeri we własną stronę lub system: pokazać wolne terminy bez widgetu, przyjmować rezerwacje przez API albo dostawać informacje o nowych rezerwacjach i płatnościach (webhooki). Pokazuje, co zrobić w panelu i co przekazać developerowi. Techniczną dokumentację developer znajdzie w portalu developers.rezeri.com. Jeśli wystarczy Ci gotowy formularz rezerwacji na stronie, bez pracy developera, użyj widgetu na Twoją stronę — instrukcję znajdziesz w artykule jak osadzić widget rezerwacji.

Zanim zaczniesz

• API i webhooki są dostępne w planach Team i Business (porównanie w artykule Plany i limity). W okresie próbnym konto działa jak plan Team, więc integrację możesz sprawdzić przed zakupem.
• Klucze i webhooki ustawia wyłącznie właściciel konta organizacji. Inni członkowie zespołu nie widzą tej sekcji ustawień.
• Sekcję znajdziesz w panelu: Ustawienia → API i webhooki (grupa „Produkt”).

Krok 1 — utwórz klucz API

Klucz identyfikuje Twoją stronę lub system w zapytaniach do api.rezeri.com. Daje dostęp tylko do danych Twojej organizacji, które zaznaczysz.

1. W API i webhooki, w karcie Klucze API, kliknij Utwórz klucz.
2. W polu Nazwa wpisz, do czego służy klucz, np. „Strona www”. Dzięki temu później rozpoznasz go na liście.
3. W sekcji Uprawnienia zostaw zaznaczone tylko to, czego developer potrzebuje (lista uprawnień niżej).
4. Jeśli przyjmujesz płatności online, uzupełnij Dozwolone domeny powrotu po płatności (krok 2).
5. Kliknij Utwórz klucz.

Uprawnienia, które możesz nadać kluczowi:

• Usługi — odczyt listy usług, cen i czasu trwania;
• Specjaliści — odczyt profili osób, które przyjmują rezerwacje;
• Dostępność — odczyt wolnych terminów w kalendarzu;
• Rezerwacje — odczyt — podgląd rezerwacji i ich statusów;
• Rezerwacje — zapis — tworzenie i anulowanie rezerwacji;
• Webhooki — zarządzanie webhookami przez API (domyślnie odznaczone; zaznacz, jeśli developer ma sam dodawać adresy webhooków).

Pełny klucz zobaczysz tylko raz, zaraz po utworzeniu. Skopiuj go albo zaznacz Zapisałem klucz i przekaż developerowi bezpiecznym kanałem, np. przez menedżer haseł. Nie wysyłaj klucza w otwartej wiadomości i nie wklejaj go do kodu strony widocznego w przeglądarce. Jeśli zgubisz klucz, odwołaj go i utwórz nowy — Rezeri nie pokaże go ponownie.

Nazwy, uprawnień i domen istniejącego klucza nie zmienisz. Gdy developer potrzebuje innych uprawnień, utwórz nowy klucz i odwołaj stary.

Krok 2 — domeny powrotu po płatności

Gdy klient płaci online (zobacz jak włączyć płatność online) za rezerwację złożoną na Twojej stronie, po płatności wraca na adres, który poda developer. Rezeri przyjmie ten adres tylko wtedy, gdy jego domena jest na liście Dozwolone domeny powrotu po płatności w kluczu.

• Wpisz samą domenę, np. twojastrona.pl, i zatwierdź klawiszem Enter albo przecinkiem. Możesz dodać kilka domen.
• Adres powrotu musi zaczynać się od https://.
• Wpis twojastrona.pl pasuje tylko do tej dokładnej domeny. Subdomeny (np. rezerwacje.twojastrona.pl) dopuścisz wpisem *.twojastrona.pl. Taki wpis nie obejmuje samego twojastrona.pl, więc jeśli potrzebujesz obu, dodaj oba.

Klient wraca na Twoją stronę z informacją, czy płatność się udała, nie udała, czy jeszcze czeka na potwierdzenie. O tym, czy wizyta jest opłacona, rozstrzyga status rezerwacji w Rezeri (i webhook o płatności), a nie sam powrót klienta.

Jeśli nie przyjmujesz płatności online, zostaw to pole puste.

Krok 3 — przekaż developerowi

Developer potrzebuje od Ciebie tylko dwóch rzeczy (a jeśli dodasz webhook — także jego sekretu, krok 4):

• klucza API z kroku 1;
• linku do dokumentacji: developers.rezeri.com — jest tam szybki start, opis rezerwacji, płatności, webhooków i strona Testowanie.

Rezeri ma jedno środowisko API — produkcyjne. Developer sprawdza integrację na Twoim koncie: rezerwacja testowa to prawdziwa rezerwacja: zajmuje termin, dopóki developer jej nie anuluje, i wysyła te same powiadomienia co każda inna — także przy anulowaniu. Dlatego przy testach powinien podawać własne dane kontaktowe, nie cudze.

Krok 4 — dodaj webhook (opcjonalnie)

Webhook to adres na serwerze Twojej strony lub systemu, na który Rezeri wysyła zdarzenia o rezerwacjach i płatnościach. Adres dostaniesz od developera.

1. W API i webhooki, w karcie Webhooki, kliknij Dodaj endpoint.
2. W polu Adres URL wklej adres od developera. Musi zaczynać się od https:// i wskazywać publiczny serwer.
3. W sekcji Zdarzenia zaznacz, o czym Rezeri ma informować: Utworzona, Zaakceptowana, Przełożona, Anulowana, Opłacona, Płatność nieudana.
4. W sekcji Zakres danych wybierz jedną z dwóch opcji (opis niżej).
5. Kliknij Dodaj endpoint.

Zakres danych decyduje, co trafia do Twojego systemu:

• Pełne dane rezerwacji — klient, usługa, termin i status; do synchronizacji z Twoim systemem;
• Bez danych klienta — tylko identyfikator rezerwacji, status i czas zdarzenia, np. do mierzenia konwersji z reklam.

Po dodaniu zobaczysz Sekret podpisu. Tak jak klucz, jest widoczny tylko raz — przekaż go developerowi tym samym bezpiecznym kanałem. Developer używa go, żeby sprawdzić, że zdarzenie naprawdę przyszło z Rezeri. Gdy sekret zginie albo wycieknie, otwórz szczegóły endpointu i kliknij Rotuj sekret. Stary sekret działa jeszcze 24 h, więc developer zdąży podmienić go w systemie.

Organizacja może mieć najwyżej 16 endpointów.

Krok 5 — sprawdź, czy integracja działa

Na liście webhooków kliknij endpoint, żeby otworzyć Szczegóły endpointu.

• Wyślij zdarzenie testowe wysyła na adres przykładowe zdarzenie, podpisane tak samo jak prawdziwe. Test połączenia sprawdza tylko, czy adres odpowiada, i nie zawiera danych rezerwacji. Możesz też wysłać przykład jednego z zaznaczonych zdarzeń — z danymi najnowszej rezerwacji Twojej organizacji. Sama rezerwacja się nie zmienia.
• Ostatnie dostawy pokazują, które zdarzenia dotarły, a które nie. Nieudaną dostawę możesz wysłać jeszcze raz przyciskiem Ponów.

Jeśli adres przez 24 h nie przyjmie żadnego zdarzenia, Rezeri wyłączy endpoint i wyśle Ci e-mail. Gdy developer naprawi serwer, popraw adres w szczegółach endpointu i włącz go ponownie przełącznikiem Włączony. Pełną listę kontrolną, łącznie z rezerwacją testową i płatnością bez prawdziwych pieniędzy, do przekazania informatykowi, znajdziesz we wpisie na blogu jak sprawdzić, że integracja z Rezeri działa.

Jak odwołać klucz

Gdy klucz wyciekł, developer przestał z Tobą współpracować albo integracja nie jest już potrzebna, odwołaj klucz: w karcie Klucze API otwórz menu przy kluczu, wybierz Odwołaj i potwierdź Odwołaj klucz. Integracje używające tego klucza przestaną działać natychmiast. Odwołania nie da się cofnąć — w razie potrzeby utworzysz nowy klucz.

Co się dzieje po zmianie planu na niższy niż Team

Na planach Free i Starter (także po zakończeniu okresu próbnego bez zakupu planu) klucze przestają działać, a webhooki nie są wysyłane. Klucze i endpointy nie są usuwane: w API i webhooki nadal widzisz ich listę i możesz odwołać klucze oraz usunąć endpointy, których już nie potrzebujesz. Nowych kluczy i endpointów nie dodasz. Po powrocie na plan Team lub Business klucze zaczną działać ponownie, a włączone endpointy znów będą dostawać nowe zdarzenia. Zdarzenia z okresu na niższym planie nie zostaną wysłane same — nieudane dostawy możesz ponowić ręcznie przyciskiem Ponów w szczegółach endpointu.

Najczęstsze pytania

Czy muszę umieć programować, żeby skorzystać z API?

Nie. Ty tworzysz klucz i ustawiasz webhooki w panelu. Integrację po stronie Twojej strony lub systemu buduje developer na podstawie dokumentacji w developers.rezeri.com.

Czy API działa w okresie próbnym?

Tak. W okresie próbnym konto działa jak plan Team, więc możesz utworzyć klucz i sprawdzić integrację. Po zakończeniu okresu próbnego klucze działają dalej tylko na planie Team lub Business.

Czy pracownik może utworzyć klucz?

Nie. Klucze API i webhooki ustawia wyłącznie właściciel konta organizacji.

Zgubiłem klucz. Czy mogę go zobaczyć jeszcze raz?

Nie. Rezeri pokazuje pełny klucz tylko raz, zaraz po utworzeniu. Odwołaj zgubiony klucz i utwórz nowy.

Czy przez API można przełożyć rezerwację albo zarządzać bazą klientów?

Nie. Przez API developer odczyta usługi, specjalistów, wolne terminy i rezerwacje oraz utworzy i anuluje rezerwację (także z płatnością online). Zmianę terminu i kartoteki klientów obsługujesz w panelu. O przełożeniu wizyty Twój system dowie się z webhooka „Przełożona”.