Klucz w nagłówku i sześć zasobów: klienci, szanse, etapy, oferty, zadania, zgłoszenia.
Webhooki mówią Twojemu systemowi, że coś się stało. API działa w drugą stronę: Twój system sam pyta o dane i sam je dopisuje. Razem załatwiają synchronizację, na przykład ze stroną firmową, magazynem albo programem księgowym.
Klucz
Klucz tworzysz w Ustawieniach firmy, w zakładce Integracje. Wygląda tak: ins_a7Kd2Xtp_9fRq… i pokazujemy go RAZ, w chwili utworzenia. Zgubiony klucz wymienia się nowym, bo trzymanie go do wglądu przez cały czas byłoby wygodne dokładnie tak samo dla Ciebie i dla kogoś, kto zajrzy Ci w ekran.
- Przy tworzeniu wybierasz zakres: tylko odczyt albo odczyt z zapisem. Domyślnie sam odczyt, bo większość integracji tylko czyta.
- Osobny klucz na każdą integrację. Wtedy wyciek albo błąd w jednym skrypcie odcina się bez zrywania pozostałych.
- Odwołanie działa natychmiast, nie po godzinie ani do końca dnia.
- Na liście widać datę ostatniego użycia i licznik żądań, więc od razu wiadomo, czy dana integracja w ogóle chodzi.
Jak pytać
Klucz idzie w nagłówku Authorization jako Bearer. Adres bazowy to https://instero.pl/api/v1/zewnetrzne, a pierwsze wywołanie, które warto zrobić, to sam ten adres: odpowiada nazwą Twojej firmy, zakresem klucza i limitem żądań, więc od razu wiadomo, czy klucz działa.
- GET /zewnetrzne/klienci, /szanse, /etapy, /oferty, /zadania, /zgloszenia.
- POST i PATCH wszędzie poza ofertami. Oferty są tylko do odczytu, bo powstają z koszyka i liczą się z cennika.
- Kasowania nie ma wcale. Klucz w cudzym skrypcie ma nie umieć usunąć kartoteki.
- Każda lista odpowiada tak samo: dane, razem, limit, offset. Do stu rekordów na stronę, najwyżej pięćset.
Nazwy pól
Pola są po polsku i są własne: nazwa, nip, miasto, telefon, a przy szansie tytul, etap, wartosc. Nie są przepisane z tabel bazy danych i to jest celowe. Dzięki temu przebudowa aplikacji u nas nie psuje połączeń zbudowanych po Twojej stronie.
Limity i błędy
- Sto dwadzieścia żądań na minutę z jednego klucza. Po przekroczeniu dostajesz kod 429 i nagłówek Retry-After z liczbą sekund do ponowienia.
- Kod 401 znaczy zły albo odwołany klucz, 403 próbę zapisu kluczem tylko do odczytu, 402 brak funkcji w planie firmy.
- Kod 404 dostajesz też wtedy, gdy numer należy do innej firmy. Numery z cudzej kartoteki mają nie istnieć, a nie być zabronione.
- Kod 422 to dane nie do przyjęcia, na przykład status zgłoszenia spoza słownika Twojej firmy. Treść odpowiedzi mówi wtedy, które wartości są dopuszczalne.