Do czego służy API w systemie awizacji
Najczęstszy przypadek: zamówienia i dostawy są w ERP, a dział logistyki przepisuje je ręcznie do harmonogramu. Przez API system klienta sam zakłada awizację z numerem zamówienia, liczbą palet i przewoźnikiem, a potem sprawdza jej status. Drugi typowy przypadek to WMS, który po zakończeniu rozładunku zmienia status awizacji. Planista widzi to od razu na planszy i nie musi dzwonić na rampę.
API (interfejs programistyczny) to zestaw adresów, pod które system klienta wysyła zapytania i dostaje odpowiedzi w formacie JSON, czyli w prostym formacie tekstowym, który odczyta każdy język programowania. Szerzej o scenariuszach integracji piszemy w artykule integracja systemu awizacji z WMS i ERP.
Co można zrobić przez API
| Zapytanie | Co robi |
|---|---|
| GET /appointments | lista awizacji z filtrami: lokalizacja, dzień lub zakres dat, status; do 100 wyników na stronę |
| GET /appointments/{id} | szczegóły jednej awizacji |
| POST /appointments | utworzenie awizacji |
| PATCH /appointments/{id} | zmiana danych awizacji |
| POST /appointments/{id}/status | zmiana statusu awizacji |
| DELETE /appointments/{id} | anulowanie awizacji |
| GET /locations, GET /gates | lista lokalizacji i bram, czyli identyfikatory potrzebne przy zakładaniu awizacji |
Każdy adres zaczyna się od ścieżki Twojej firmy, np. /nazwa-firmy/api/v1/appointments. Awizacja założona albo zmieniona przez API przechodzi przez te same reguły co w panelu i wysyła te same powiadomienia e-mail i SMS.
Przy zmianie awizacji możesz podać numer wersji (pole expected_revision), który dostałeś przy jej odczycie. Jeśli w międzyczasie planista zmienił awizację w panelu, API zwróci błąd 409 z aktualnymi danymi, zamiast nadpisać jego zmianę.
Klucze API i zakresy uprawnień
Klucz API to długi, tajny ciąg znaków, który system klienta dołącza do każdego zapytania w nagłówku Authorization: Bearer albo X-API-Key. Klucz generujesz w panelu w zakładce API i integracje i wybierasz jeden z trzech typów:
- Odczyt: lista i szczegóły awizacji, bez żadnych zmian,
- Tylko statusy: odczyt i zmiana statusu, bez zakładania, edycji i anulowania,
- Operacyjny: pełny odczyt i zapis awizacji.
Dawaj integracji najwęższy klucz, jaki wystarczy. Arkusz z raportem potrzebuje tylko odczytu, a WMS, który zgłasza koniec rozładunku, klucza „Tylko statusy”. Gdy klucz nie ma potrzebnego uprawnienia, API odpowiada błędem 403.
Pełny klucz pokazuje się tylko raz, zaraz po wygenerowaniu, więc od razu przenieś go do konfiguracji integracji. Na liście widać potem tylko jego początek, datę utworzenia i ostatniego użycia. Wygenerowanie i unieważnienie klucza trzeba potwierdzić hasłem, a jeśli masz włączone logowanie dwuskładnikowe, także kodem z aplikacji.
API ma limit zapytań: do 300 na minutę na jeden klucz i do 120 na minutę z jednego adresu IP. Przy synchronizacji co kilka minut to duży zapas.
W których planach jest API
API REST jest w planach Standard, Sieć i Enterprise. W planach Test i Start zakładka API i integracje pokazuje informację o zmianie planu i nie pozwala wygenerować klucza. Plan jest sprawdzany przy każdym zapytaniu, więc po przejściu na plan bez API istniejące klucze przestają działać. Ceny są w cenniku, a zasady korzystania z API, w tym odpowiedzialność za integrację, w regulaminie API.
Najczęstsze pytania
Czy API jest dostępne w okresie próbnym?
Nie. W planie Test, tak jak w planie Start, nie ma API. Klucz wygenerujesz po przejściu na plan Standard, Sieć lub Enterprise.
Czy przez API można zmienić status awizacji?
Tak, zapytaniem POST /appointments/{id}/status. Wystarczy klucz typu „Tylko statusy” albo „Operacyjny”.
Gdzie znajdę dokumentację API?
W panelu, w zakładce API i integracje, są przykłady zapytań i link do pełnej specyfikacji OpenAPI. Plik specyfikacji zaimportujesz do Postmana albo Insomnii i od razu sprawdzisz zapytania.
Czym API różni się od webhooków?
Przez API Twój system sam pyta AwizoSlot o dane. Webhooki działają odwrotnie: AwizoSlot wysyła informację na Twój adres, gdy awizacja się zmieni.
Skąd te zrzuty ekranu
Zrzuty pochodzą z działającej instalacji AwizoSlot, z firmy demonstracyjnej „Firma testowa AwizoSlot”. Nazwy kluczy i firm są fikcyjne.