Czasem ktoś chce coś podłączyć do Stippa. Twórca strony, który chce odtworzyć formularz rezerwacji w Twojej identyfikacji wizualnej, księgowy ze skryptem pobierającym obrót albo usługa taka jak Zapier, która wysyła wiadomość, gdy przyjdzie nowa rezerwacja. Taka osoba poprosi Cię o klucz API.
Ta strona jest dla Ciebie, nie dla programisty. Nie musisz wiedzieć, jak to działa technicznie, żeby podjąć dobrą decyzję. To, czego potrzebuje programista, jest w dokumentacji dla programistów, po angielsku.
Czym jest klucz API?
Długi, tajny tekst zaczynający się od stp_live_. Kto go ma, może w imieniu Twojej firmy robić
dokładnie to, co zostało zaznaczone przy tworzeniu klucza, i nic poza tym.
Trzy rzeczy są ważniejsze niż technika:
- Klucz należy do Twojej firmy. Nigdy nie dosięgnie danych innej firmy, nawet przez przypadek.
- Klucz to nie logowanie. Nie ma przy nim hasła i nikt nie wejdzie z nim do aplikacji. Działa tylko dla samej integracji.
- Klucz to tajemnica, jak klucz do lokalu. Kto go ma, może go użyć. Dokładnie dlatego istnieje reszta tej strony.
Kiedy jest potrzebny?
Tylko wtedy, gdy ktoś o niego poprosi. Do zwykłego korzystania ze Stippa klucz API nigdy nie jest potrzebny: widget rezerwacji, kalendarz, e-maile i profil publiczny działają bez niego.
Typowe sytuacje, w których jednak wchodzi w grę:
- Twórca Twojej strony chce wpleść rezerwację w całości w Twoją witrynę, zamiast używać standardowego widgetu.
- Ktoś chce automatycznie przenosić Twoje wizyty do arkusza albo programu księgowego.
- Chcesz powiadomienia w Slacku, Teams albo Zapierze, gdy ktoś zarezerwuje.
Jakiej subskrypcji potrzebuję?
| Czego chcesz | Od |
|---|---|
| Odczytu danych (wizyty, klienci, usługi, dostępność) | Groei |
| Tworzenia i zmieniania danych oraz webhooków | Pro |
Gdy zejdziesz na niższą subskrypcję, klucz zostaje. Przestają działać tylko te uprawnienia, których Twoja subskrypcja już nie daje. Gdy później wrócisz wyżej, integracja od razu znowu działa i nikt nic nie musi ustawiać.
Utworzenie klucza
Klucze znajdziesz w aplikacji Dev, która pojawia się w przełączniku aplikacji w lewym górnym rogu, gdy włączysz moduł API access.
Włącz moduł
Przejdź do Zarządzanie > Moduły i włącz API access. Aplikacja Dev pojawi się wtedy w przełączniku aplikacji.
Przejdź do Dev > Klucze
Kliknij Nowy klucz.
Nadaj nazwę, którą zrozumiesz za rok
Nie „test” ani „klucz 2”, tylko „Strona Jansen Webdesign” albo „Integracja księgowa”. Gdy kiedyś trzeba będzie coś unieważnić, nazwa jest jedynym śladem, po którym poznasz, czyj jest który klucz.
Zaznacz tylko to, co potrzebne
Są gotowe zestawy. Gdy masz wątpliwości, wybierz Tylko odczyt: taki klucz niczego nie zmieni. Uprawnień nie da się później dodać, ale da się utworzyć drugi klucz, i to jest bezpieczna kolejność.
Skopiuj klucz od razu
Pełny klucz zobaczysz jeden raz, zaraz po utworzeniu. Potem Stippa trzyma już tylko jego zaszyfrowaną postać i my też go nie pokażemy. Gdy go zgubisz, unieważnij go i utwórz nowy.
Bezpieczne przekazanie klucza
Wysłanie klucza raz e-mailem i zapomnienie o tym to najczęstszy sposób, w jaki sprawy idą źle: skrzynka pozostaje przeszukiwalna latami, bywa współdzielona i wędruje do następnego pracodawcy.
- Przekaż go kanałem, który kasuje wiadomości, albo przez menedżer haseł, z którego programista i tak korzysta.
- Nigdy nie wstawiaj go do publicznej wiadomości, zgłoszenia ani współdzielonego dokumentu.
- Twórz osobny klucz dla każdej firmy. Dwa podmioty z tym samym kluczem oznaczają, że przy unieważnianiu jednego psujesz integrację obu.
- Poproś o datę wygaśnięcia, gdy zlecenie jest tymczasowe. Klucz może wygasnąć sam i nikt nie musi o tym później pamiętać.
Unieważnienie klucza
Przejdź do Dev > Klucze i wybierz Unieważnij przy danym kluczu. Działa to natychmiast: najbliższe zapytanie z tym kluczem zostanie odrzucone. Unieważnienia nie da się cofnąć, więc integracja musi potem dostać nowy klucz.
Unieważnij w każdym razie:
- gdy kończy się współpraca z twórcą strony albo agencją;
- gdy klucz trafił tam, gdzie nie powinien;
- gdy nie wiesz już, do czego dany klucz służy. Klucz, którego nikt nie umie przypisać, nie powinien być aktywny.
Nie masz pewności, czy klucz jest jeszcze używany? Zajrzyj najpierw do Dev > Dziennik. Zobaczysz tam przy każdym zapytaniu, kiedy przyszło i czy się udało. Klucz, którego od miesięcy tam nie ma, możesz spokojnie unieważnić.
Webhooki: w drugą stronę
Klucz pozwala komuś pobierać dane od Ciebie. Webhook robi odwrotnie: Stippa wysyła wiadomość pod wskazany adres internetowy, gdy coś się wydarzy, na przykład gdy ktoś zarezerwuje albo anuluje wizytę. Tego właśnie potrzebuje integracja ze Slackiem albo Zapierem. Webhooki są w subskrypcji Pro i znajdziesz je w Dev > Webhooki.
Adres webhooka zasługuje na taką samą ostrożność jak klucz. Przy każdym zdarzeniu Stippa wysyła pod ten adres powiązane dane, w tym nazwiska, adresy e-mail i numery telefonów Twoich klientów. Kto może ustawić adres, może więc przekierować ten strumień gdzie indziej. Przyjmuj adres tylko od kogoś, komu ufasz, i przejrzyj listę, gdy nie wiesz już, kto co ustawił.
Gdy adres pozostaje nieosiągalny, Stippa próbuje jeszcze kilka razy, a potem sama wyłącza endpoint, żeby nie wysyłać w nieskończoność pod martwy adres. Widać to jako komunikat nad listą, z przyciskiem do ponownego włączenia, gdy odbiorca znowu działa.
Częste pytania
Czy ktoś z moim kluczem zaloguje się do Stippa? Nie. Klucz działa tylko dla integracji i nie daje dostępu do aplikacji, Twojego konta ani subskrypcji.
Czy klucz dosięgnie danych innej firmy? Nie. Klucz sam wyznacza, o którą firmę chodzi; nie ma ustawienia, którym dałoby się wskazać inną.
Nie widzę aplikacji Dev. Moduł API access jest wyłączony, Twoja subskrypcja to Starter albo masz rolę pracownika. Aplikacja jest widoczna dla właścicieli i administratorów.
Mój programista prosi o dokumentację. Wyślij go do dokumentacji dla programistów. Jest po angielsku i zawiera wszystko, czego potrzebuje, razem z przykładami.