API i webhooki nie są alternatywą, którą się wybiera raz na zawsze, lecz dwoma uzupełniającymi się kierunkami wymiany danych. API służy do sytuacji, w których Twój system pyta o dane lub zleca operację — pobiera listę awizacji na dany dzień, zakłada rezerwację na podstawie zamówienia z ERP. Webhooki działają odwrotnie: to system awizacji informuje Twoje środowisko, że coś się stało, na przykład zmienił się status awizacji. Praktyczna integracja z WMS lub ERP korzysta zwykle z obu. W AwizoSlot API i webhooki są dostępne w planach Standard, Sieć i Enterprise.
Czym się różnią te dwa mechanizmy
| Cecha | API | Webhooki |
|---|---|---|
| Kto inicjuje | Twój system | System awizacji |
| Typowe zastosowanie | Pobranie danych, założenie lub zmiana awizacji | Reakcja na zdarzenie, na przykład zmianę statusu |
| Opóźnienie | Zależy od częstotliwości odpytywania | Zbliżone do momentu zdarzenia |
| Obciążenie | Rośnie z częstotliwością zapytań | Proporcjonalne do liczby zdarzeń |
| Wymaga po Twojej stronie | Klienta wykonującego zapytania | Publicznie dostępnego adresu odbiorczego |
| Zachowanie przy awarii | Ponowne zapytanie przy kolejnym cyklu | Wymaga obsługi powtórzeń i kolejki |
Najprostsza reguła wyboru: jeśli pytanie brzmi „jaki jest stan rzeczy”, użyj API. Jeśli brzmi „powiedz mi, gdy coś się zmieni”, użyj webhooka.
Typowe scenariusze integracji
Awizacja zakładana na podstawie zamówienia z ERP
Zamówienie zakupu z potwierdzoną datą dostawy może automatycznie tworzyć awizację. Numer zamówienia trafia wtedy do rezerwacji, co ma bezpośrednie znaczenie operacyjne, bo harmonogram pozwala filtrować właśnie po numerze zamówienia i przewoźniku.
To scenariusz dla API — inicjatywa jest po stronie ERP, w momencie, gdy dokument osiąga odpowiedni status.
Status awizacji zasilający system magazynowy
Gdy kierowca zgłosi się na miejscu i awizacja dostanie status „Oczekujący”, WMS może rozpocząć przygotowanie zadań przyjęcia albo zwolnić kompletację do wydania. Tu naturalnym mechanizmem jest webhook, bo reakcja ma nastąpić blisko zdarzenia, a nie przy kolejnym cyklu odpytywania. Webhooki AwizoSlot wysyłają żądanie POST podpisane HMAC i ponawiają dostarczenie, gdy odbiorca chwilowo nie odpowiada.
Raportowanie i hurtownia danych
Do analiz obłożenia bram i czasów obsługi nie potrzeba reakcji natychmiastowej. Wystarczy nocne pobranie danych przez API albo raporty KPI za wybrany zakres dat (obłożenie bram, spóźnienia, anulowania, rozbicie na dni i statusy) z eksportem do CSV.
Synchronizacja słowników
Przewoźnicy, kontrahenci i typy towarów zwykle istnieją już w ERP. Utrzymywanie ich w dwóch miejscach ręcznie prowadzi do rozjazdu nazw, co psuje potem raporty. Jednokierunkowa synchronizacja przez API, z ERP jako źródłem prawdy, jest tu prostsza niż próba uzgadniania obu stron.
Jak zaplanować integrację, żeby nie przepisywać jej dwa razy
- Zacznij od procesu, nie od pól. Ustal, jakie zdarzenie w jednym systemie ma wywołać jaką akcję w drugim. Mapowanie pól jest łatwe, gdy przebieg jest jasny.
- Wskaż system nadrzędny dla każdej danej. Data dostawy, przewoźnik, numer zamówienia — dla każdej z nich jedno miejsce musi być źródłem prawdy.
- Ustal, co robi integracja przy konflikcie. Jeśli dyspozytor przesunął okno w harmonogramie, a ERP przysyła starą datę, kto wygrywa.
- Zadbaj o idempotencję. Powtórzone zdarzenie nie może utworzyć drugiej awizacji na to samo zamówienie.
- Loguj obie strony wymiany. Bez tego diagnoza rozbieżności sprowadza się do zgadywania.
- Zrób to po ustabilizowaniu reguł. Integracja budowana w trakcie zmian siatki okien będzie przepisywana.
Ostatni punkt wynika z doświadczenia typowego dla wdrożeń: reguły czasowe i zasady pierwszeństwa zmieniają się w pierwszych tygodniach. Kolejność etapów opisaliśmy w tekście o wdrożeniu systemu awizacji.
Kwestie bezpieczeństwa wymiany danych
Integracja oznacza, że dane opuszczają interfejs użytkownika i płyną kanałem technicznym, więc kilka rzeczy trzeba ustalić zawczasu:
- Zakres uprawnień. Klucz API dostaje tylko wybrane zakresy, na przykład odczyt awizacji bez prawa ich tworzenia. Utworzenie klucza wymaga ponownego potwierdzenia hasłem albo kodem MFA.
- Ślad w historii. Operacje wykonywane przez integrację powinny być rozpoznawalne w dzienniku audytu.
- Limity zapytań. Rate limiting chroni system przed nadmiarowym odpytywaniem, więc częstotliwość cyklu lepiej dobrać z zapasem.
- Dane osobowe. Imię kierowcy, telefon i podobne dane chroni izolacja bazy firmy i kontrola dostępu. Integracja nie powinna ich kopiować tam, gdzie nie są potrzebne. Numerów PESEL i dokumentów tożsamości system nie przyjmuje.
- Odrębność danych firm. Każda firma ma osobną bazę danych, co ma znaczenie przy środowiskach wielospółkowych.
Zakres wymiany danych warto uwzględnić w umowie powierzenia przetwarzania. AwizoSlot udostępnia jej wzór.
Kiedy integracja nie jest potrzebna
Nie każdy magazyn musi łączyć awizacje z ERP. Jeśli liczba dostaw dziennie jest niewielka, a numer zamówienia i tak wpisuje przewoźnik podczas rezerwacji, wartość automatyzacji bywa mniejsza niż koszt jej utrzymania.
Część potrzeb, które na pierwszy rzut oka wyglądają na zadanie dla integracji, rozwiązują mechanizmy wbudowane. Powiadomienia e-mail i SMS o utworzeniu awizacji, zmianie statusu i anulowaniu, ustawiane w macierzy zdarzeń i odbiorców, zastępują wysyłkę realizowaną z zewnątrz. Raporty KPI z eksportem CSV, dostępne w każdym planie, pokrywają większość zapotrzebowania raportowego.
Pytania do zadania przed startem
Przed rozpoczęciem prac uzgodnij odpowiedzi na cztery pytania: które zdarzenia mają przekraczać granicę systemów, kto utrzymuje kod integracji po uruchomieniu, jak wygląda procedura przy niedostępności jednej ze stron oraz czy plan obejmuje API i webhooki. W AwizoSlot obejmują je plany Standard, Sieć i Enterprise, a nie ma ich w planach Test i Start (aktualne warunki są w cenniku). Zestaw szerszych pytań do dostawcy zebraliśmy w tekście o wyborze systemu awizacji.
Najczęstsze pytania
Czy do integracji z ERP wystarczy samo API?
Do zakładania awizacji z zamówień i nocnego pobierania danych tak. Jeśli WMS ma reagować na zgłoszenie pojazdu albo zakończenie rozładunku w ciągu sekund, potrzebny jest webhook, bo odpytywanie co kilka minut daje opóźnienie i niepotrzebny ruch.
Co się stanie, gdy mój serwer nie odbierze webhooka?
AwizoSlot ponawia dostarczenie według własnej polityki, ale po serii nieudanych prób zdarzenie może zostać uznane za niedostarczone. Dlatego odbiornik powinien być idempotentny, a stan po awarii warto uzgodnić przez API.