Egy adapter pattern, hat carrier. Igy hangzik a marketing pitch, es a marketing pitch hazudik, mert a 'egy' adapter pattern valojaban hat sajat implementacio egy kozos interface mogott. Itt van, mit tanultunk meg amikor a Foxpost, MPL, GLS, DPD, DHL es UPS integraciot egyenkent osszerakttuk.
Label generation: PDF vs. ZPL
Ket formatum a vilagon. A PDF a kis cegek alapertelmezett (A4 lap, otthoni printer). A ZPL a profi (Zebra GK420 vagy hasonlo cimkenyomtato, 100x150mm). A Logistics modul mindketto formatumot generalja, es a partner valassza ki, hogy mit kuld ki: a kisebb raktarak (1-2 polnak) PDF-et nyomtatnak, a nagyobbak (5+ pickeres) ZPL-t a cimkenyomtatora kuldik a JetDirect protokollon.
A Foxpost egyedi: a label-juket PNG-ben kuldik (?), ami egyik printerrel sem mukodik nativ jol. A megoldas: a Logistics oldalon konvertaljuk a PNG-t ZPL-be a ZebraPicture library-vel, es a partner mar nem latja a kulonbseget.
Webhook ingestion
Minden carrier kuld webhookokat (delivered, failed, in_transit, returned), de mind masok. A CarrierWebhookController-unk egy endpoint per carrier (/api/v1/carriers/foxpost/webhook, /api/v1/carriers/mpl/webhook...), es minden adapter sajat parseWebhook metodusa egy zod-schema validacion at futtatja a payloadot. Sikeres parse utan a carrier_event rekord landol egy normalt formaban a carrier_events tablaban.
A legmegrazoabb tapasztalat: az X carrier (nem nevezzuk meg) 200-as HTTP valaszt kuld a webhook-bevitelre meg akkor is, ha a payload semantikailag hibas (pl. hianyzik a tracking szam). Ez azt jelenti, hogy nem tudjuk megkulonboztetni a sikeres ingestiont a csendes hibatol. A megoldas: a parse-error landol a webhook_parse_errors tablaban, es egy alacsony-frekvenciaju Slack-ertesites szol, ha a parse-error arany >1%/ora egy adott carrierre. 2026 marciusaban igy talaltunk meg egy DPD szema-valtozast 38 percen belul.
Idempotency keys per carrier
A DHL es UPS kuld idempotency kulcsot (X-Idempotency-Key header). A GLS nem. A Foxpost szandekosan dupla-tuzeli a delivered esemenyt. Igy a Logistics platform sajat carrier_event_hash dedup-tablat tart, amibe minden webhook payload SHA-256 hash-et taroljuk. Ha 24 oran belul ugyanaz a hash jon megint, eldobjuk. 2026 januar ota 1.4 millio duplazasit allitott meg ez a tabla.
A bookShipment hivasoknal mi adjunk idempotency kulcsot (order_42_attempt_2), es a carrier validalja vagy nem - ha nem, a sajat server-side dedup-unk kapja el a duplazst. Az elso valtozat naiv exponential backoff volt (1s, 2s, 4s, 8s), es a GLS-nel ket bookolt csomagot eredmenyezett, mert a foglalas siker volt, csak a valasz veszett el. Ma minden booking idempotency-kulccsal megy.
COD reconciliation
A carrierek hetente kuldnek COD beszedett osszegeket (CSV vagy SFTP feedek). A Logistics modul a cod_collections tablaban regisztralja, es a Finance modul ezt visszahasonlitja a feladott COD-megrendelesek listajaval. A mismatchek (carrier kevesebbet utalt at mint amit a webhook szerint beszedettek) egy review-queue-be esnek, ahol a penzugyi munkatars egyenkent szembesul a carrier-rel. A GLS COD-szamlazas atvitlagosan 8.4 napos kesest mutat (havi vegen rosszul). Ezt mar a teljesitmenymeresnel hasznaljuk.
Az egy dolog, amit a Foxpost jol csinal
A Foxpost parcel-locker (automata) elerheto kapacitas API-ja. Real-time, megmutatja melyik csomagautomatahoz fer be a kuldemenyem (méret + jelenlegi telitettsegtenek figyelembe vetelvel). Mi a webshopok checkout-jaba kotjuk be, igy a vasarlo csak elerheto automatakkal valaszthat. Ezt csak a Foxpost csinalja a 6 carrierbol; a tobbi nem tudom, varjuk meg. Ez egy olyan API-feature, ami egyedul lehetne a Foxpost lefoglalo-eronyi predikcioja, es valoszinuleg ez tartja oket a magyar parcel-locker piacon az elen.
A megerzes
A carrier integraciok kozott nincs gyozelmi: van olcso (MPL), van precis (DHL), van rugalmas (GLS), van automata-fokuszu (Foxpost). A Logistics modul feladata, hogy mindettol fuggetlen reteget adjon, es a partner ne erezze a kulonbseget a webshop oldalan. Hat ev integraciofelujitas tapasztalata: nem letezik 'final' adapter-implementacio. A carrierek havonta valtoztatnak.