Integracja Allegro z BaseLinkerem, programem do faktur i magazynem

Jak działa API Allegro

Allegro ma publiczne API typu REST z dokumentacją na portalu dla programistów. Każde żądanie niesie token OAuth 2.0 w nagłówku Authorization. Dokumentacja opisuje cztery sposoby uzyskania dostępu: najczęściej używany kod autoryzacyjny, w którym sprzedawca zgadza się na dostęp w przeglądarce, przepływ urządzenia dla aplikacji bez okna logowania, przepływ client credentials dla danych publicznych oraz dynamiczną rejestrację klienta dla aplikacji instalowanych u wielu użytkowników. Do obsługi własnego konta sprzedawcy zwykle służy kod autoryzacyjny. Token dostępu wygasa po dwunastu godzinach, a token odświeżania działa przez trzy miesiące, więc integracja musi go odnawiać i zapisywać nowy. Jeśli odnowienie się nie uda, sprzedawca musi zalogować się ponownie, a zamówienia przestają spływać.

Nowe zamówienia integracja wykrywa przez dziennik zdarzeń, czyli zasób order/events. Zdarzenia mają typy, takie jak BOUGHT, FILLED_IN, READY_FOR_PROCESSING, BUYER_CANCELLED, FULFILLMENT_STATUS_CHANGED i AUTO_CANCELLED, a zamówienie gotowe do realizacji oznacza READY_FOR_PROCESSING, czyli takie z wypełnionymi danymi dostawy i opłacone albo wybrane za pobraniem lub z odbiorem osobistym. Kolejne partie pobiera się parametrem from z identyfikatorem ostatniego widzianego zdarzenia, a limit wynosi do tysiąca zdarzeń na zapytanie. Zdarzenia można pobrać z ostatnich sześćdziesięciu dni, więc po dłuższej awarii trzeba nadrobić zaległości, zanim znikną z dziennika. Szczegóły zamówienia, w tym dane kupującego, płatność, dostawę i informację, czy kupujący prosi o fakturę, daje zasób order/checkout-forms.

W drugą stronę API pozwala dołączyć do zamówienia fakturę jako plik albo odnośniki do dokumentów, dodać numer przesyłki z przewoźnikiem, a także zmienić status realizacji. Grupowe zmiany ceny i stanu ofert idą przez polecenia z własnym identyfikatorem UUID, co sprawia, że ponowione żądanie nie robi szkody. Limit dla jednego klienta aplikacji to dziewięć tysięcy zapytań na minutę, a po jego przekroczeniu API odpowiada kodem 429. Do testów służy osobne środowisko sandbox, które trzeba jednak sprawdzać ostrożnie, bo raz na kwartał jest czyszczone z ofert. Dobry wykonawca zaczyna właśnie tam, a potem przechodzi na prawdziwe konto z jednym zamówieniem testowym.

Typowy przepływ danych

1. Kupujący składa zamówienie na Allegro, a integracja wykrywa zdarzenie gotowości do realizacji w dzienniku zamówień.
2. Integracja pobiera szczegóły zamówienia: produkty, adres dostawy, płatność i informację, czy kupujący chce fakturę.
3. Dane trafiają do BaseLinkera, magazynu albo programu do faktur, gdzie powstaje dokument sprzedaży i rezerwacja towaru.
4. Po wysyłce do Allegro wraca numer przesyłki i nowy status realizacji, a kupujący widzi aktualne informacje w swoim koncie.
5. Błędy, takie jak nieznany produkt albo wygasły token, trafiają na listę do sprawdzenia, zamiast ginąć po cichu.