KB

Czas wysyłki w Allegro API: dozwolone wartości handlingTime i pułapka z SKU

Ten tekst powstał, bo szukałem go sam i nie znalazłem. Kiedy budowałem automat, który przestawia czas wysyłki na ofertach Allegro w zależności od stanu magazynowego, najwięcej czasu zjadły mi nie rzeczy trudne, tylko dwie rzeczy nieopisane: jakie wartości czasu wysyłki Allegro w ogóle przyjmuje i dlaczego część ofert cicho nie dopasowywała się po SKU. Poniżej wszystko, co bym chciał przeczytać wtedy.

Gdzie w ogóle siedzi czas wysyłki

W nowym API czas wysyłki to pole delivery.handlingTime w zasobie oferty. Zmienia się je przez częściową aktualizację oferty:

PATCH /sale/product-offers/{offerId}
Content-Type: application/vnd.allegro.public.v1+json

{
  "delivery": {
    "handlingTime": "P3D"
  }
}

Odpowiedź 200 oznacza zmianę natychmiastową, 202 oznacza, że zmiana została przyjęta i przetwarza się w tle. Obie traktuj jako sukces. Wszystko inne, zwłaszcza 422, oznacza, że wysłałeś coś, czego Allegro nie przyjmuje, i tu zaczyna się pierwszy temat.

Dozwolone wartości handlingTime

Pole używa formatu czasu trwania ISO 8601, ale nie przyjmuje dowolnej liczby dni. Lista jest zamknięta i odpowiada opcjom, które widzisz w formularzu oferty:

Wartość	Znaczenie
PT0S	natychmiast
PT24H	24 godziny
P2D, P3D, P4D, P5D	2, 3, 4, 5 dni
P7D, P10D, P14D	7, 10, 14 dni
P21D, P30D, P60D	21, 30, 60 dni

Konsekwencja praktyczna: jeżeli Twoja logika policzy „sześć dni", nie możesz wysłać P6D. Trzeba zaokrąglić w górę do najbliższej dozwolonej wartości, czyli do P7D. W dół nie, bo obiecałbyś klientowi szybciej, niż wyślesz, a Allegro rozlicza z obietnicy. U mnie wygląda to tak:

const DOZWOLONE = [1, 2, 3, 4, 5, 7, 10, 14, 21, 30, 60];

function handlingTimeZDni(dni) {
  if (dni <= 0) return "PT0S";
  const d = DOZWOLONE.find(x => x >= dni) ?? 60;
  return d === 1 ? "PT24H" : `P${d}D`;
}

Jedna uwaga do PT24H: to jest „jeden dzień" i tak trzeba go zapisać. P1D nie przejdzie, mimo że logicznie znaczy to samo.

Skąd wiedzieć, którą ofertę zmienić: pułapka z SKU

Automat dostaje sygnał ze świata magazynu: „SKU dS_58225 spadło do zera". Musi znaleźć ofertę na Allegro, która odpowiada temu SKU. Właściwe miejsce to pole external.id oferty, czyli sygnatura, którą sprzedawca nadaje sam.

I tu przejechałem się porządnie. external.id rozróżnia wielkość liter. dS_58225 i ds_58225 to dla Allegro dwa różne identyfikatory. Tymczasem sporo źródeł danych po drodze zamienia wszystko na małe litery: eksporty CSV, niektóre arkusze, ręczne przeklejanie, a bywa, że własny kod, który „normalizuje" klucze. Efekt jest paskudny, bo cichy: automat nie znajduje oferty, nie zgłasza błędu, tylko nic nie robi, a Ty jesteś przekonany, że działa.

Dwie zasady, które to załatwiają:

• Przechowuj SKU w oryginalnej pisowni od pierwszego kroku do ostatniego. Jeżeli potrzebujesz klucza do porównań, trzymaj go obok, nie zamiast.
• Brak dopasowania traktuj jak błąd, nie jak „nic do zrobienia". Wpis w dzienniku „brak aktywnej oferty dla SKU X" po tygodniu powie Ci więcej niż jakikolwiek test.

Masowe zmiany: nie po jednej ofercie

Przy kilkudziesięciu ofertach PATCH po jednej wystarczy. Przy setkach lepiej użyć poleceń modyfikacji, które zmieniają jedno pole na liście ofert w jednym żądaniu i przetwarzają się asynchronicznie:

PUT /sale/offer-modification-commands/{commandId}

{
  "modification": { "delivery": { "handlingTime": "PT24H" } },
  "offerCriteria": [
    { "type": "CONTAINS_OFFERS", "offers": [ { "id": "1234567890" }, { "id": "1234567891" } ] }
  ]
}

Potem sprawdzasz status polecenia i dopiero on mówi, ile ofert zmieniło się naprawdę. Przy zmianach hurtowych to jedyny sposób, żeby nie dostać limitu zapytań i nie zgadywać, co się udało.

Trzy rzeczy, które robię w każdym takim automacie

1. Tryb podglądu. Przez pierwszy tydzień automat tylko zapisuje, co by zrobił. Dwie z moich pierwszych reguł okazały się głupie i klient dostałby wysyłkę w 30 dni na towar, który wracał za dwa.
2. Zmiana w obie strony. Wydłużanie jest łatwe. Sztuka polega na tym, żeby czas wrócił do normy, kiedy towar wraca na stan, bo inaczej po miesiącu wszystkie oferty stoją na siedmiu dniach.
3. Alert ciszy. Jeżeli automat przez kilka godzin nie zapisał ani jednej decyzji, dostaję maila. Zepsuty automat, który milczy, jest gorszy niż brak automatu.

Szerszy kontekst, po co w ogóle to robić i co się dzieje z ofertą, kiedy zamiast wydłużyć czas wysyłki po prostu ją zdejmiesz, opisałem w tekście o automatycznych czasach wysyłki na Allegro.