Mikor egy webshop a MPL-rol DPD-re vagy GLS-re valt, az atallas hetekig tart. Mikor parhuzamosan kell mind a hattal dolgozni (MPL, GLS, Foxpost, DPD, DHL, UPS), az nem egy hosszabb projekt, hanem egy kulonbozo termek. Az elmult evben hat partnerunknel epitettunk multi-carrier dashboard-ot a Netorigo platformon, es itt van, amit megtanultunk.
A 'kuldetes' adapter
A dashboard maganak nincs sok kodja. A magvalo munka az adapter-retegben tortenik, ami minden szallitora kulonbozo, es minden szallito ugy gondolja, hogy az ovék lesz a standard. A CarrierAdapter interfaceunk negy muveletet ker:
interface CarrierAdapter {
bookShipment(intent: ShipmentIntent): Promise<CarrierShipmentRef>;
getStatus(ref: CarrierShipmentRef): Promise<CarrierStatus>;
generateLabel(ref: CarrierShipmentRef): Promise<LabelArtifact>;
parseWebhook(raw: unknown): CarrierEvent | null;
}
A hat szallitora a hat adapter masok merete: a GLS implementacio 340 sor, a Foxpost 180 sor (az automatakod-lekerdezes miatt), az UPS 720 sor (mert az autentikacios flow OAuth 2.0 hardware key-alappal mukodik, ami egy 6 honapja elinditott valtozas). A DPD adapter 290 sor, de mar ket valtozaton vagyunk tul, mert a DPD 2025 novemberben megvaltoztatta a webhook payload sememat figyelmeztetes nelkul.
A webhook-format bukfenc
A legreszletesebb fejvonas, ami megtort minket: a webhook-formatumok inkonzisztencia. A MPL XML-t kuld (UTF-8 szel), a DPD JSON-t (camelCase mezok), a Foxpost JSON-t (snake_case mezok), a GLS JSON-t (PascalCase mezok), a DHL JSON-t (camelCase plus event_data wrapper), az UPS XML-t SOAP envelope-pal. Ez nem csak munka, ez bug-magnet. A mi parseWebhook-unk minden adapterben sajat sema validaciot vegez (zod-dal), es a hibakat a webhook_parse_errors tablaba taroljuk visszaszamlalashoz.
A tipikus webhook-event-ek (shipment.delivered, shipment.failed_delivery, shipment.in_transit) idoponti pontossaga is masok. A DHL pontosan azt jelzi, amikor az autosofor a pod (proof of delivery) gombot megnyomja a kezi keszuleken. A MPL este 22:00-kor szakaszosan kuldi a napi osszes deliveryt egy nagy posztban, ami azt jelenti, hogy a deliveredAt mezo szinkronra varohat 8 oraig.
Idempotencia kulcsok per carrier
A legnagyobb pofa: nem minden carrier kuld idempotencia kulcsot. A DHL es az UPS kuld (X-Idempotency-Key), a GLS nem. A Foxpost szandékkal ketszer fire-olja a delivered esemenyt, hogy a partner biztosan megkapja. A megoldas: a Netorigo platformon egy carrier_event_hash redundancia-tablat tartunk, amibe a webhook payload SHA-256-ait taroljuk, es 24 oran belul ugyanazt a hash-t nem fogadjuk el ujra. Ez 2026 januar ota 1.4 millio dupla esemenyt allitott meg.
A retry policy buktatoja
A bookShipment muvelet a legkritikusabb, mert ez kuldemenyt foglal le. Az elso retry-policiankban exponencialis backoffot allitottunk be (1s, 2s, 4s, 8s), de a GLS-nel ez a duplazaast eredmenyezte: a foglalas sikerült, csak a valasz veszett el a halozati hibatol, es a kovetkezo proba egy uj foglalast hozott letre. Ma az osszes booking muvelet idempotencia kulccsal megy (X-Idempotency-Key: order_42_attempt_2), es a server-side dedup-ot mi vegezzuk, ha a carrier nem.
Az egy feature, amit kikapcsolnank
A dashboard ket dolgot mutat: a kuldemenyek statuszat carrierenkent, es a teljesitmenymetrikakat (atlagos kezbesitesi ido, sikertelen kezbesitesi arany, kuldemenyek koltsegei). A teljesitmenymetrikakat irjak. Senki nem nezi. A partnerek 90%-a a statusz-listat hasznalja a napi munkajaban, es ha a metrikak nem lennenek, nem hianyozna. Ha most kezdenenk, a metrikak feletti munkat (320 sor controller, 480 sor service, kulonbozo charting library integracio) nem csinalnak.