API i webhooki

Zlecenia wraz ze statusami i danymi przewozu, kartoteka kontrahentów, rejestr pojazdów i kierowców, dokumenty przypięte do przewozów oraz dane rozliczeniowe. Odczyt i, w wybranym zakresie, zapis — bo część firm chce nie tylko czytać, ale i zakładać zlecenia z własnego systemu.

Zakres zapisu jest celowo węższy niż odczytu. Zlecenie utworzone przez interfejs przechodzi te same reguły walidacji co wprowadzone ręcznie, bo dane wpuszczone „na skróty” mszczą się przy rozliczeniu.

Zewnętrzne narzędzie może dowiadywać się o zmianach na dwa sposoby: pytając cyklicznie albo dostając powiadomienie. Pierwszy jest prostszy do napisania, drugi znacznie tańszy w utrzymaniu i szybszy.

Zdarzenia takie jak zmiana statusu przewozu, podpięcie dokumentu czy wystawienie faktury mogą trafiać na wskazany adres w momencie, w którym zachodzą. Portal klienta zbudowany na powiadomieniach pokazuje aktualny stan bez odpytywania systemu co minutę przez całą dobę.

Klucz dostępowy ma określony zakres. Narzędzie zbudowane przez zewnętrznego dostawcę może widzieć statusy przewozów bez dostępu do stawek, marż i danych kadrowych — i to jest zwykle dokładnie ten podział, którego firma potrzebuje.

Klucze są odwoływalne pojedynczo. Zakończenie współpracy z dostawcą nie wymaga wtedy zmiany niczego poza wyłączeniem jego dostępu.

Najpopularniejszy przypadek użycia nie jest ambitny: chodzi o to, żeby klient sam sprawdził, gdzie jest jego towar, zamiast dzwonić. Wystarczą do tego statusy przewozu i dokumenty, czyli wycinek danych, który da się udostępnić bez ryzyka.

Firmy budują to na dwa sposoby — jako część własnej strony albo jako osobne narzędzie. Oba działają na tym samym interfejsie, a wybór zależy od tego, kto to utrzymuje.

Część organizacji ma zbudowaną analitykę i chce w niej widzieć także dane transportowe, obok sprzedaży i finansów. Zamiast eksportować pliki, podłącza się je do interfejsu.

Warto przy tym pamiętać o czymś, co bywa pomijane: raport zbudowany na zewnątrz nie zna reguł biznesowych systemu. Marża policzona własnym wzorem z surowych danych potrafi różnić się od tej w systemie i wywołać kilkugodzinną dyskusję, w której obie strony mają rację, bo liczyły co innego.

Interfejs jest ogólny i nie zna specyfiki systemu po drugiej stronie. Jeżeli kontrahent oczekuje danych w konkretnym formacie wymiany, jeżeli trzeba uzgodnić znaczenie pól albo obsłużyć niestandardowy przebieg procesu — to jest już praca integracyjna, a nie korzystanie z gotowego interfejsu.

Granica przebiega mniej więcej tak: jeśli Wasz zespół albo Wasz dostawca potrafi to napisać na podstawie dokumentacji, to jest API. Jeśli potrzebne są ustalenia z obiema stronami i mapowanie danych — to jest projekt integracyjny.

Każdy interfejs ma ograniczenia liczby zapytań i warto poznać je przed zaprojektowaniem narzędzia, a nie po jego uruchomieniu. Portal, który przy każdym odświeżeniu strony odpytuje o pełną listę zleceń, wyczerpie limit szybciej, niż ktokolwiek zakładał, i przestanie działać w najgorszym momencie — czyli wtedy, gdy zacznie z niego korzystać więcej klientów.

Dobrze zaprojektowane narzędzie pobiera zmiany, a nie całość, i korzysta z powiadomień zamiast odpytywania. Ta różnica nie ma znaczenia przy dziesięciu przewozach dziennie i decyduje o wszystkim przy tysiącu, dlatego warto ją uwzględnić od początku, choćby wolumen na razie tego nie wymuszał.

Rzecz, o której warto powiedzieć przed rozpoczęciem: narzędzie zbudowane na interfejsie staje się Waszym oprogramowaniem i wymaga opieki. Zmiana w procesie, nowy typ danych albo rozwój interfejsu wymagają czyjejś uwagi.

Nie oznacza to, że nie warto — oznacza, że przy planowaniu takiego przedsięwzięcia trzeba uwzględnić kilka dni pracy rocznie. Portale klienckie umierają najczęściej nie dlatego, że przestały działać, tylko dlatego, że nikt nie miał ich w zakresie obowiązków.