Skip to main content
HomeBlogGidsenVerzendtrackinggegevens verbinden met een Oms: ordertoewijzing en synchronisatieregels

Verzendtrackinggegevens verbinden met een Oms: ordertoewijzing en synchronisatieregels

17TRACK

Om verzendtrackinggegevens te koppelen aan een orderbeheersysteem (OMS), wijs je elk gevolgd pakket toe aan een intern verzendrecord en koppel je die zending vervolgens aan de order en de fulfilmentregels. Ontvang trackingupdates via de door de provider ondersteunde interface, bewaar de oorspronkelijke gebeurtenissen en pas expliciete regels toe voor duplicaten, late updates, de verzendstatus en het voltooien van orders. Gebruik niet alleen een trackingnummer als order-ID en laat één bezorgingsgebeurtenis niet automatisch een order met meerdere pakketten sluiten.

Hoe je verzendtrackinggegevens koppelt aan een OMS-order

Deze handleiding is bedoeld voor integratie-engineers en ecommerce-operations teams die deze koppeling implementeren. Het aanbevolen ontwerp scheidt waarnemingen van vervoerders van zakelijke beslissingen: trackinggegevens beschrijven de reis van een pakket, terwijl het OMS bepaalt wat die reis betekent voor fulfilment, klantcommunicatie en het sluiten van de order.

Bepaal welk systeem eigenaar is van elk record

Spreek voordat je een API-koppeling bouwt met de OMS-beheerder, het fulfilmentteam en de klantenserviceteam af welk systeem eigenaar is van welke gegevens. Anders kan een technisch geslaagde integratie nog steeds geldige bedrijfsgegevens overschrijven.

  • OMS: Beheert orders, orderregels, vereiste aantallen, annuleringen en de regels voor het voltooien van orders.
  • Fulfilmentsysteem: Beheert de verzend- of pakketrecords die het aanmaakt, inclusief verpakkingsverdelingen en labeltoewijzingen. Dit kan het OMS zelf zijn of een afzonderlijk magazijnsysteem.
  • Trackingprovider: Levert trackingwaarnemingen en eventuele door de provider gedefinieerde statusclassificaties.
  • Integratielaag: Beheert kruisverwijzingen naar identificatoren, gebeurtenisverwerking, normalisatie, retry-afhandeling en synchronisatie-auditrecords.

Beschouw dit als aanbevolen grenzen, niet als aannames over je software. Documenteer uitzonderingen. Als het magazijn bijvoorbeeld een verzendlabel kan vervangen, heeft de integratie een expliciete update van dat systeem nodig in plaats van te veronderstellen dat een nieuw waargenomen nummer een oud nummer vervangt.

Bouw de koppeling tussen order en pakket voordat je statussen synchroniseert

Een praktische relatie is order → fulfilment → pakket → trackingtoewijzing. Je OMS kan andere namen gebruiken of sommige van deze records combineren. Behoud de relaties ook als de databasestructuur anders is.

Een order kan meerdere fulfilments hebben en een fulfilment kan meerdere pakketten bevatten. Een pakket kan ook een vervangende trackingtoewijzing of een gekoppelde last-mile-identificator krijgen. Deze identificatoren mogen geen extra bestelde aantallen creëren.

RecordAanbevolen veldenDoel
OrderTenant- of winkel-ID, onveranderlijke OMS-order-IDScheidt verkopers en voorkomt afhankelijkheid van zichtbare ordernummers.
FulfilmentFulfilment-ID, order-ID, toegewezen regel-ID's en aantallenIdentificeert welke gekochte artikelen worden uitgevoerd.
PakketInterne pakket-ID, fulfilment-ID, pakketverdelingen indien beschikbaarLevert een stabiele identiteit die onafhankelijk is van trackinglabels.
TrackingtoewijzingToewijzings-ID, pakket-ID, provideraccount, vervoerdersidentificator, trackingnummer, actieve periodeKoppelt binnenkomende trackingwaarnemingen aan het juiste pakket en de juiste levenscyclus van de toewijzing.

Match updates via een opgeslagen kruisverwijzing

Wanneer een zending wordt aangemaakt, sla je de interne ID's op voordat je deze voor tracking registreert. Bewaar elke door de provider uitgegeven trackingrecord-ID die door het gedocumenteerde registratieproces wordt teruggegeven. Als de provider een referentie van de verkoper ondersteunt, gebruik dan een ondoorzichtige interne referentie en bewaar de koppeling lokaal.

Los voor binnenkomende updates eerst de opgeslagen providerrecord-ID op binnen het juiste provideraccount en de juiste tenant. Als die identificator niet beschikbaar is, gebruik je de gedocumenteerde combinatie van trackingnummer, vervoerdersidentiteit, accountcontext en toewijzingsgeschiedenis. Beschouw dit als een zoekstrategie, niet als een garantie dat de combinatie wereldwijd uniek is.

Match niet op klantnaam, e-mailadres of een niet-afgebakend zichtbaar ordernummer. Bewaar trackingnummers als tekenreeksen zodat voorloopnullen behouden blijven. Vermijd het verwijderen van tekens of het wijzigen van hoofdletters, tenzij het relevante vervoerders- of providercontract die normalisatie toestaat.

Als een zoekopdracht geen match of meerdere mogelijke matches oplevert, plaats je de update in quarantaine voor onderzoek. Een onopgeloste gebeurtenis is veiliger dan een zelfverzekerde update van de order van de verkeerde klant.

Behandel gesplitste orders zonder pakketverdelingen te verzinnen

Neem een voorbeeldorder met drie eenheden. Pakket A bevat twee eenheden en pakket B één. De bezorging van pakket A betekent dat er bezorgingsbewijs is voor twee eenheden; het betekent niet dat de volledige order is bezorgd.

Als het fulfilmentsysteem alleen registreert dat beide pakketten bij hetzelfde fulfilment horen, verzin dan geen toewijzingen op eenheidsniveau. Je kunt nog steeds berekenen of alle vereiste pakketten zijn bezorgd, maar rapportage van bezorging per artikel moet niet beschikbaar blijven of expliciet als onzeker worden gemarkeerd totdat toewijzingsgegevens bestaan.

Verbind de tracking-API via een duurzame opnamelaag

Gebruik een pipeline die communicatie met de provider gescheiden houdt van OMS-schrijfbewerkingen:

Verzending aanmaken → trackingregistratie → binnenkomende update of geplande ophaling → duurzame gebeurtenisopslag → mapping en normalisatie → OMS-update → reconciliatie

Voor een 17TRACK-implementatie zijn de productpagina van de Tracking API en de officiële API-documentatie de relevante startpunten. Controleer de toepasselijke registratie-interface, vervoerdersidentificatoren, opties voor het afleveren van updates, authenticatievereisten, statusdefinities en accountlimieten voordat je de adapter implementeert. Het datamodel in deze handleiding is een integratieadvies en geen bewering dat 17TRACK deze veldnamen gebruikt of een native connector voor je OMS levert.

Als je geselecteerde provider webhooks ondersteunt, authenticeer je binnenkomende verzoeken met het gedocumenteerde mechanisme en sla je geaccepteerde berichten duurzaam op voordat je ze bevestigt. Houd trage OMS-bewerkingen buiten het aanvraagpad. Volg het werkelijke bevestigings- en retrycontract van de provider in plaats van uit te gaan van een bepaalde response body of time-out.

Als polling vereist is, sla dan de voortgang van het ophalen op waar de API dit ondersteunt, beheer gelijktijdigheid en volg de gedocumenteerde snelheidslimieten. Noch webhookontvangst noch een geslaagde pollingaanvraag bewijst dat het OMS is bijgewerkt; registreer die resultaten afzonderlijk.

Definieer synchronisatieregels die bestand zijn tegen retries en late gebeurtenissen

1. Maak verwerking idempotent

Het twee keer verwerken van dezelfde waarneming mag geen dubbele zending creëren, aantallen twee keer verhogen of dezelfde klantmelding opnieuw versturen. HTTP maakt een willekeurige POST-bewerking niet idempotent; de integratie moet bescherming tegen duplicaten implementeren. RFC 9110 legt idempotentie van HTTP-methoden uit.

Gebruik een stabiele providergebeurtenis-ID wanneer die gedocumenteerd en beschikbaar is. Definieer anders een fingerprint op basis van de toewijzings-ID en relevante gebeurtenisvelden, zoals het tijdstip van de gebeurtenis, de bronstatus en de locatie. Documenteer de mogelijkheid van botsingen of gewijzigde gebeurtenisbeschrijvingen. Bewaar de onbewerkte waarneming ook wanneer deze geen nieuwe OMS-actie veroorzaakt.

Bescherm elk neveneffect afzonderlijk. Een OMS-statusschrijfactie en een e-mailmelding hebben bijvoorbeeld elk hun eigen deduplicatiecontroles nodig. Gebruik een transactionele outbox of een gelijkwaardig duurzaam werkrecord zodat een procescrash geen geaccepteerde gebeurtenis zonder geplande update achterlaat.

2. Sla gebeurtenistijd en ontvangsttijd afzonderlijk op

Het tijdstip waarop een gebeurtenis plaatsvond en het tijdstip waarop je integratie deze ontving beantwoorden verschillende vragen. Sla beide op, samen met de oorspronkelijke tijdstempelweergave en eventuele meegeleverde timezone-offset. Wijs niet stilzwijgend de magazijntijdzone toe aan een gebeurtenis waarvan de tijdzone onbekend is.

Een laat binnengekomen scan tijdens transport moet de geschiedenis normaal gesproken aanvullen zonder een nieuwere bezorgstatus te vervangen. Tijdstempels alleen zijn echter onvoldoende: een provider kan een correctie uitgeven en gebeurtenissen kunnen onvolledige tijdinformatie bevatten. Gebruik beschikbare gedocumenteerde sequentie- of revisievelden, samen met een expliciet correctiebeleid.

3. Normaliseer statussen zonder details uit de bron te wissen

Maak een kleine interne woordenschat die het OMS begrijpt, zoals wachten op acceptatie door de vervoerder, onderweg, uit voor bezorging, bezorgd, uitzondering en retour. Breng de gedocumenteerde statussen van de provider hierop in kaart. Dit zijn voorgestelde interne categorieën, geen universele definities van vervoerders.

Bewaar de oorspronkelijke statuscode, beschrijving, gebeurtenislocatie, providerrecordreferentie en versie van de mappingregel. Een niet-gemapte waarde moet een controleerbare situatie creëren in plaats van standaard op bezorgd of mislukt te worden gezet. Het aanmaken van een label mag niet worden behandeld als bewijs van fysieke acceptatie door de vervoerder, tenzij de brongebeurtenis die interpretatie expliciet ondersteunt.

4. Gebruik overgangsregels, geen eenvoudige numerieke rangorde

Verzendstatussen vormen niet altijd een rechte lijn. Een uitzondering kan worden gevolgd door normaal transport en een bezorgpoging is geen bezorging. Retourtransport kan beginnen na een eerdere bezorggebeurtenis.

  • Sta toe dat een uitzondering wordt opgeheven wanneer latere informatie hervat transport ondersteunt.
  • Voorkom dat een gewone historische scan stilzwijgend een bezorgstatus vervangt.
  • Sta een gedocumenteerde correctie toe via een gecontroleerd revisiepad.
  • Volg retourtransport afzonderlijk van voltooiing van de heenzending wanneer het OMS dit ondersteunt.
  • Stuur dubbelzinnige of tegenstrijdige informatie naar een operationele wachtrij.

Versioneer deze regels. Wanneer een mapping verandert, bepaal je of die alleen voor nieuwe gebeurtenissen geldt of dat historische records gecontroleerd opnieuw moeten worden berekend.

Bereken de orderstatus op basis van vereiste fulfilmentverplichtingen

Pakketstatus en orderstatus moeten afzonderlijke velden zijn. Een pakket met de status bezorgd levert bewijs voor dat pakket; het voltooien van de order hangt af van de resterende vereiste aantallen en je bedrijfsbeleid.

Een nuttige standaard is om een order pas als volledig bezorgd te markeren wanneer alle bezorgingsplichtige aantallen geldig bezorgingsbewijs op pakketniveau hebben en er geen vereiste toewijzingen onopgelost blijven. Sluit geannuleerde aantallen uit volgens de annuleringsregels van het OMS. Behandel digitale artikelen, afhaalorders en andere niet-verzendverplichtingen volgens hun eigen voltooiingsvoorwaarden.

Vervangende zendingen vereisen expliciete relaties. Als een verloren pakket wordt vervangen, bepaal je of de vervanging de oorspronkelijke bezorgingsverplichting overneemt. Anders kan het oorspronkelijke pakket de voltooiing onbeperkt blokkeren of kunnen beide pakketten meetellen voor fulfilment. Leg de beslissing vast in plaats van deze uitsluitend uit de trackingstatus af te leiden.

Houd voltooiing van de bezorging gescheiden van financiële afsluiting, geschiktheid voor terugbetaling en geschiloplossing. Een bezorgingsgebeurtenis van een vervoerder mag niet automatisch een terugbetaling goedkeuren of een klantclaim afhandelen.

Herstel van fouten zonder de audittrail te verliezen

Herhaal tijdelijke fouten met begrensde backoff en eventuele gedocumenteerde retry-richtlijnen. Scheid tijdelijke verbindingsfouten van ongeldige identificatoren, verlopen inloggegevens, toestemmingsfouten en incompatibiliteiten in het schema. Voor deze laatste categorieën is corrigerende actie nodig, geen eindeloze retries.

Onderhoud een wachtrij voor mislukt werk met de betrokken tenant, het pakket, de gebeurtenisreferentie, de uitgevoerde bewerking, de foutclassificatie en de volgende actie. Log voldoende context om onderzoek mogelijk te maken zonder onnodige klantgegevens of inloggegevens in logs te kopiëren.

Voer naast het normale updatepad ook reconciliatie uit. Controleer actieve zendingen met verouderde trackinginformatie, geaccepteerde gebeurtenissen waarvan de OMS-schrijfbewerking is mislukt, niet-gematchte waarnemingen en verschillen tussen de door de integratie berekende status en het OMS. Kies de controlefrequentie op basis van bezorgingsverplichtingen, API-limieten en operationeel risico in plaats van een willekeurig universeel schema toe te passen.

Wijs eigenaarschap toe: engineering behandelt opname- en schrijffouten; fulfilment operations lost ontbrekende pakketrelaties op; klantenservice beoordeelt uitzonderingen waarvoor klantcommunicatie nodig is. Een wachtrij zonder verantwoordelijke eigenaar is slechts een opslaglocatie.

Test de mapping en bedrijfsregels vóór de lancering

Gebruik gecontroleerde fixtures en een beperkte productierol-out. Test de volgende gevallen aan de hand van zowel de gebeurtenisgeschiedenis als het resulterende OMS-record:

  • Een order met één pakket verloopt normaal tot bezorging.
  • Een gesplitste order heeft één bezorgd pakket en één pakket dat nog onderweg is.
  • Dezelfde gebeurtenis wordt herhaaldelijk ontvangen zonder dubbele neveneffecten.
  • Een oudere transportsan komt na de bezorging binnen.
  • Een onbekende vervoerder of status komt in de controlewachtrij terecht.
  • Een label wordt vervangen zonder een extra fulfilmentverplichting te creëren.
  • Een vervangende zending neemt volgens een goedgekeurde regel de plaats in van een oorspronkelijk pakket.
  • Het OMS is niet beschikbaar nadat een gebeurtenis is geaccepteerd.
  • Een proces start opnieuw tussen een OMS-schrijfbewerking en de bevestiging daarvan.
  • Hetzelfde zichtbare ordernummer bestaat in twee winkels zonder matching tussen tenants.

Lanceer wanneer elke geaccepteerde gebeurtenis een traceerbaar verwerkingsresultaat heeft, dubbelzinnige matches orders niet automatisch kunnen bijwerken en operators mislukt werk veilig opnieuw kunnen afspelen. Dit zijn nuttigere acceptatiecriteria dan alleen aantonen dat een API-aanvraag slaagt.

Veelgestelde vragen

Kan ik trackingnummers rechtstreeks aan orders koppelen?

Voor een strikt proces met één pakket kan een directe relatie aanvankelijk voldoende zijn. Gebruik toch een interne verzendidentiteit tussen de order en de trackingtoewijzing. Dit biedt een migratiepad voor gesplitste zendingen, herlabeling en vervangingen zonder de betekenis van het orderrecord te wijzigen.

Moet de integratie webhooks of polling gebruiken?

Gebruik het aflevermechanisme dat door de provider wordt ondersteund en compatibel is met je infrastructuur. Webhooks kunnen herhaald ophalen verminderen, terwijl polling op ophalen gebaseerde workflows en reconciliatie kan ondersteunen waar dit beschikbaar is. Geen van beide benaderingen neemt de noodzaak weg van duurzame opslag, duplicaatverwerking en herstel.

Wat moet er gebeuren wanneer een trackinggebeurtenis geen overeenkomende order heeft?

Sla deze op in een wachtrij voor niet-gematchte gebeurtenissen en onderzoek het registratierecord, de tenantcontext, de identiteit van de vervoerder en het tijdstip waarop de zending is aangemaakt. Maak niet automatisch een order aan en koppel de gebeurtenis niet automatisch aan een aannemelijke klant. Speel de gebeurtenis opnieuw af nadat de mapping is gecorrigeerd.

Moeten bezorgingsmeldingen vanuit het OMS of het trackingsysteem komen?

Kies één eigenaar voor elk meldingstype en elke trigger. Als twee systemen hetzelfde bericht kunnen versturen, schakel dan één pad uit of deel een duurzaam meldingenregister. Bepaal ook of een bericht betrekking heeft op één pakket of op de volledige order, vooral bij gesplitste fulfilment.

Betekent een uitzonderingsstatus dat de order is mislukt?

Nee. Een uitzondering is een waarneming die interpretatie vereist en niet noodzakelijk een permanente uitkomst. Bewaar de reden, volg latere gebeurtenissen en gebruik je escalatiebeleid om te bepalen wanneer operations moet ingrijpen.

Bronnen

  • 17TRACK Tracking API — officiële productreferentie voor het startpunt van de API-integratie.
  • 17TRACK API-documentatie — implementatiereferentie voor het providerspecifieke contract; controleer vóór implementatie de toepasselijke interfaces en accountvereisten.
  • RFC 9110, Section 9.2.2: Idempotent Methods — HTTP-semantiek ter ondersteuning van het onderscheid tussen idempotentie van methoden en duplicaatbescherming op applicatieniveau.