Slik kobler du sporingsdata for forsendelser til Oms: Ordrekartlegging og synkroniseringsregler
For å koble data om forsendelsessporing til et ordrebehandlingssystem (OMS), må du knytte hver sporede pakke til en intern forsendelsespost og deretter koble denne forsendelsen til ordren og ordrelinjene som skal oppfylles. Motta sporingsoppdateringer gjennom leverandørens støttede grensesnitt, bevar de opprinnelige hendelsene og bruk tydelige regler for duplikater, sene oppdateringer, forsendelsesstatus og ordreavslutning. Ikke bruk et sporingsnummer alene som ordreidentifikator, og la ikke én enkelt leveringshendelse automatisk lukke en ordre med flere pakker.
Denne veiledningen er for integrasjonsingeniører og team som arbeider med netthandelsdrift og implementerer denne koblingen. Den anbefalte utformingen skiller transportørens observasjoner fra forretningsbeslutninger: Sporingsdata beskriver pakkens reise, mens OMS avgjør hva denne reisen betyr for oppfyllelse, kundekommunikasjon og lukking av ordren.
Definer hvilket system som eier hver post
Før du bygger en API-kobling, må du avklare eierskapet med OMS-administratoren, oppfyllelsesteamet og kundeserviceteamet. Ellers kan en teknisk vellykket integrasjon likevel overskrive gyldige forretningsdata.
- OMS: Eier ordrer, ordrelinjer, nødvendige mengder, kanselleringer og reglene for når en ordre er fullført.
- Oppfyllelsessystem: Eier forsendelses- eller pakkepostene det oppretter, inkludert pakkeallokeringer og tildeling av etiketter. Dette kan være selve OMS-et eller et separat lagersystem.
- Sporingsleverandør: Leverer sporingsobservasjoner og eventuelle statusklassifiseringer som er definert av leverandøren.
- Integrasjonslag: Eier kryssreferanser mellom identifikatorer, hendelsesbehandling, normalisering, håndtering av nye forsøk og revisjonsposter for synkronisering.
Betrakt disse som anbefalte grenser, ikke som antakelser om programvaren din. Dokumenter unntak. Hvis lageret for eksempel kan erstatte en fraktetikett, trenger integrasjonen en uttrykkelig oppdatering fra dette systemet i stedet for å anta at et nylig observert nummer erstatter et gammelt.
Bygg koblingen mellom ordre og pakke før du synkroniserer statuser
En praktisk relasjon er ordre → oppfyllelse → pakke → sporingstildeling. OMS-et ditt kan bruke andre navn eller kombinere noen av disse postene. Bevar relasjonene selv om databasestrukturen er annerledes.
En ordre kan ha flere oppfyllelser, og en oppfyllelse kan inneholde flere pakker. En pakke kan også få en erstatningstildeling av sporingsnummer eller en tilknyttet sisteleddsidentifikator. Disse identifikatorene skal ikke opprette ytterligere bestilte mengder.
| Post | Anbefalte felt | Formål |
|---|---|---|
| Ordre | Leietaker- eller butikk-ID, uforanderlig OMS-ordre-ID | Skiller mellom forhandlere og unngår avhengighet av viste ordrenumre. |
| Oppfyllelse | Oppfyllelses-ID, ordre-ID, tildelte ordrelinje-ID-er og mengder | Identifiserer hvilke kjøpte varer som oppfylles. |
| Pakke | Intern pakke-ID, oppfyllelses-ID, pakkeallokeringer der de finnes | Gir en stabil identitet som er uavhengig av sporingsetiketter. |
| Sporingstildeling | Tildelings-ID, pakke-ID, leverandørkonto, transportøridentifikator, sporingsnummer, aktiv periode | Kobler innkommende sporingsobservasjoner til riktig pakke og livssyklusen for tildelingen. |
Match oppdateringer gjennom en lagret kryssreferanse
Når en forsendelse opprettes, må du lagre de interne ID-ene før du registrerer den for sporing. Lagre eventuell leverandørutstedt ID for sporingsposten som returneres av den dokumenterte registreringsprosessen. Hvis leverandøren støtter en referanse fra forhandleren, bruker du en ugjennomsiktig intern referanse og beholder koblingen lokalt.
For innkommende oppdateringer må du først finne den lagrede leverandørpost-ID-en i riktig leverandørkonto og leietakerkontekst. Hvis denne identifikatoren ikke er tilgjengelig, bruker du den dokumenterte kombinasjonen av sporingsnummer, transportøridentitet, kontokontekst og historikk for tildelinger. Behandle dette som en oppslagsstrategi, ikke som en garanti for at kombinasjonen er globalt unik.
Ikke match etter kundenavn, e-postadresse eller et uavgrenset vist ordrenummer. Bevar sporingsnumre som strenger slik at innledende nuller beholdes. Unngå å fjerne tegn eller endre store og små bokstaver med mindre den relevante transportør- eller leverandøravtalen tillater slik normalisering.
Hvis et oppslag ikke gir noen treff eller gir flere mulige treff, må du sette oppdateringen i karantene for undersøkelse. En uavklart hendelse er tryggere enn en sikker oppdatering av feil kundes ordre.
Håndter delte ordrer uten å finne på pakkeallokeringer
Se for deg en ordre med tre enheter. Pakke A inneholder to enheter, og pakke B inneholder én. Levering av pakke A betyr at det finnes leveringsbevis for to enheter; det betyr ikke at hele ordren er levert.
Hvis oppfyllelsessystemet bare registrerer at begge pakkene tilhører samme oppfyllelse, må du ikke finne på allokeringer på enhetsnivå. Du kan fortsatt beregne om alle nødvendige pakker er levert, men rapportering av levering på varenivå bør forbli utilgjengelig eller uttrykkelig usikker til det finnes allokeringsdata.
Koble sporings-API-et gjennom et robust inntakslag
Bruk en pipeline som holder leverandørkommunikasjon adskilt fra OMS-skrivinger:
Opprettelse av forsendelse → sporingsregistrering → innkommende oppdatering eller planlagt henting → varig lagring av hendelse → kartlegging og normalisering → OMS-oppdatering → avstemming
For en 17TRACK-implementering er produktsiden for Tracking API og den offisielle API-dokumentasjonen relevante startpunkter. Bekreft det aktuelle registreringsgrensesnittet, transportøridentifikatorene, alternativene for levering av oppdateringer, autentiseringskravene, statusdefinisjonene og kontogrensene før du implementerer adapteren. Datamodellen i denne veiledningen er en integrasjonsanbefaling, ikke en påstand om at 17TRACK bruker disse feltnavnene eller tilbyr en innebygd kobling til OMS-et ditt.
Hvis den valgte leverandøren støtter webhooks, må du autentisere innkommende forespørsler ved hjelp av den dokumenterte mekanismen og lagre aksepterte meldinger varig før du bekrefter mottaket. Hold langsomt OMS-arbeid utenfor forespørselsbanen. Følg leverandørens faktiske kontrakt for bekreftelser og nye forsøk i stedet for å anta et bestemt svar eller tidsavbrudd.
Hvis polling er nødvendig, må du lagre fremdriften for hentingen der API-et støtter det, kontrollere samtidighet og følge de dokumenterte hastighetsgrensene. Verken mottak av en webhook eller en vellykket pollingforespørsel beviser at OMS-et ble oppdatert; registrer disse resultatene separat.
Definer synkroniseringsregler som tåler nye forsøk og sene hendelser
1. Gjør behandlingen idempotent
Behandling av den samme observasjonen to ganger skal ikke duplisere en forsendelse, øke mengder to ganger eller sende den samme kundemeldingen på nytt. HTTP gjør ikke en vilkårlig POST-operasjon idempotent; integrasjonen må implementere beskyttelse mot duplikater. RFC 9110 forklarer idempotens for HTTP-metoder.
Bruk en stabil leverandør-ID for hendelsen når en slik er dokumentert og tilgjengelig. Ellers definerer du et fingeravtrykk basert på tildelings-ID-en og relevante hendelsesfelt, for eksempel hendelsestidspunkt, kildestatus og plassering. Dokumenter muligheten for kollisjoner eller endrede hendelsesbeskrivelser. Behold den rå observasjonen selv når den ikke fører til en ny OMS-handling.
Beskytt hver bivirkning separat. En OMS-statusskriving og en e-postvarsling trenger for eksempel egne kontroller mot duplikater. Bruk en transaksjonell outbox eller en tilsvarende varig arbeidspost slik at et prosesskrasj ikke kan etterlate en akseptert hendelse uten en planlagt oppdatering.
2. Lagre hendelsestidspunkt og mottakstidspunkt separat
Tidspunktet en hendelse oppsto og tidspunktet integrasjonen mottok den, svarer på ulike spørsmål. Lagre begge, sammen med den opprinnelige representasjonen av tidsstempelet og eventuell oppgitt tidssoneforskyvning. Ikke tildel lagerets tidssone i stillhet til en hendelse der tidssonen er ukjent.
En sent ankommet skanning under transport bør normalt berike historikken uten å erstatte en nyere levert-status. Tidsstempler alene er imidlertid utilstrekkelige: En leverandør kan utstede en korrigering, og hendelser kan ha ufullstendige tidsopplysninger. Bruk dokumenterte sekvens- eller revisjonsfelt når de finnes, sammen med en uttrykkelig korrigeringspolicy.
3. Normaliser statuser uten å slette kildedetaljer
Opprett et lite internt vokabular som OMS-et forstår, for eksempel venter på transportørens aksept, under transport, ute for levering, levert, avvik og returneres. Kartlegg leverandørens dokumenterte statuser til dette. Dette er foreslåtte interne kategorier, ikke universelle transportørdefinisjoner.
Lagre den opprinnelige statuskoden, beskrivelsen, hendelsesstedet, referansen til leverandørposten og versjonen av kartleggingsregelen. En ukartlagt verdi bør opprette en tilstand som kan gjennomgås, i stedet for å bli satt til levert eller mislykket som standard. Opprettelse av en etikett skal ikke behandles som bevis på fysisk aksept hos transportøren med mindre kildehendelsen uttrykkelig støtter denne tolkningen.
4. Bruk overgangsregler, ikke en enkel numerisk rangering
Forsendelsestilstander følger ikke alltid en rett linje. Et avvik kan etterfølges av normal transport, og et leveringsforsøk er ikke det samme som levering. Returtransport kan begynne etter en tidligere leveringshendelse.
- Tillat at et avvik fjernes når påfølgende bevis støtter gjenopptatt transport.
- Hindre at en vanlig historisk skanning i stillhet erstatter en levert-status.
- Tillat en dokumentert korrigering gjennom en kontrollert revisjonsbane.
- Følg returtransport separat fra fullføring av utgående levering der OMS-et støtter dette.
- Send tvetydige eller motstridende bevis til en operasjonell kø.
Versjoner disse reglene. Når en kartlegging endres, må du avgjøre om den bare gjelder nye hendelser, eller om historiske poster krever en kontrollert ny beregning.
Beregn ordrestatus ut fra nødvendige oppfyllelsesforpliktelser
Pakkestatus og ordrestatus bør være separate felt. En pakke som er merket levert, gir bevis for denne pakken; fullføring av ordren avhenger av de gjenværende nødvendige mengdene og forretningspolicyen din.
En nyttig standard er å merke en ordre som fullstendig levert først når alle leveringspliktige mengder har gyldige leveringsbevis på pakkenivå, og ingen nødvendige allokeringer gjenstår som uavklarte. Trekk fra kansellerte mengder i henhold til OMS-ets kanselleringsregler. Håndter digitale varer, henteordrer og andre ikke-fraktrelaterte forpliktelser gjennom egne fullføringsbetingelser.
Erstatningsforsendelser krever uttrykkelige relasjoner. Hvis en tapt pakke erstattes, må du avgjøre om erstatningen erstatter den opprinnelige leveringsforpliktelsen. Ellers kan den opprinnelige pakken blokkere fullføringen på ubestemt tid, eller begge pakkene kan telle mot oppfyllelsen. Registrer beslutningen i stedet for å utlede den bare fra sporingsstatusen.
Hold leveringsfullføring adskilt fra økonomisk avslutning, refusjonsberettigelse og tvisteløsning. En leveringshendelse fra transportøren skal ikke automatisk godkjenne en refusjon eller avgjøre et kundekrav.
Gjenopprett etter feil uten å miste revisjonssporet
Prøv igjen ved midlertidige feil ved hjelp av begrenset backoff og eventuell dokumentert veiledning om nye forsøk. Skill midlertidige tilkoblingsfeil fra ugyldige identifikatorer, utløpte legitimasjonsopplysninger, tilgangsfeil og inkompatibilitet i skjemaet. De sistnevnte krever korrigerende tiltak, ikke endeløse nye forsøk.
Vedlikehold en kø for mislykket arbeid som inneholder berørt leietaker, pakke, hendelsesreferanse, forsøkt operasjon, feilkategorisering og neste tiltak. Logg nok kontekst til å undersøke saken uten å kopiere unødvendige kundedata eller legitimasjonsopplysninger til loggene.
Kjør avstemming i tillegg til den normale oppdateringsbanen. Gå gjennom aktive forsendelser med foreldet sporingsinformasjon, aksepterte hendelser der OMS-skrivingen mislyktes, uavstemte observasjoner og forskjeller mellom integrasjonens beregnede tilstand og OMS-et. Velg gjennomgangsfrekvens ut fra leveringsforpliktelser, API-begrensninger og operasjonell risiko, i stedet for å bruke en vilkårlig universell tidsplan.
Fordel eierskap: Teknikk håndterer inntaks- og skrivefeil; oppfyllelsesdriften løser manglende pakkerelasjoner; kundeservice gjennomgår avvik som krever kundekommunikasjon. En kø uten en ansvarlig eier er bare et lagringssted.
Test kartleggingen og forretningsreglene før lansering
Bruk kontrollerte testdata og en begrenset utrulling i produksjon. Test følgende tilfeller mot både hendelseshistorikken og den resulterende OMS-posten:
- En ordre med én pakke går normalt frem til levering.
- En delt ordre har én levert pakke og én pakke som fortsatt er under transport.
- Den samme hendelsen mottas flere ganger uten dupliserte bivirkninger.
- En eldre transports skanning ankommer etter levering.
- En ukjent transportør eller status havner i gjennomgangskøen.
- En etikett erstattes uten å opprette en ny oppfyllelsesforpliktelse.
- En erstatningsforsendelse erstatter en opprinnelig pakke i henhold til en godkjent regel.
- OMS-et er utilgjengelig etter at en hendelse er akseptert.
- En prosess starter på nytt mellom en OMS-skriving og bekreftelsen av den.
- Det samme viste ordrenummeret finnes i to butikker uten matching på tvers av leietakere.
Lanser når hver aksepterte hendelse har et sporbart behandlingsresultat, tvetydige treff ikke kan oppdatere ordrer automatisk, og operatører kan spille av mislykket arbeid på nytt på en trygg måte. Dette er mer nyttige godkjenningskriterier enn bare å vise at en API-forespørsel lykkes.
Vanlige spørsmål
Kan jeg koble sporingsnumre direkte til ordrer?
For en strengt enkeltpakke-basert arbeidsflyt kan en direkte relasjon være tilstrekkelig i starten. Bruk likevel en intern forsendelsesidentitet mellom ordren og sporingstildelingen. Den gir en migreringsvei for delte forsendelser, ommerking og erstatninger uten å endre betydningen av ordreposten.
Bør integrasjonen bruke webhooks eller polling?
Bruk leveringsmekanismen som leverandøren støtter og som er kompatibel med infrastrukturen din. Webhooks kan redusere gjentatte hentinger, mens polling kan støtte hentingsbaserte arbeidsflyter og avstemming der dette er tilgjengelig. Ingen av metodene fjerner behovet for varig lagring, håndtering av duplikater og gjenoppretting.
Hva skal skje når en sporingshendelse ikke har noen matchende ordre?
Lagre den i en kø for uavstemte hendelser og undersøk registreringsposten, leietakerkonteksten, transportøridentiteten og tidspunktet for opprettelsen av forsendelsen. Ikke opprett en ordre eller knytt hendelsen automatisk til en sannsynlig kunde. Spill den av på nytt etter at kartleggingen er korrigert.
Bør leveringsvarsler komme fra OMS-et eller sporingssystemet?
Velg én eier for hver varslingstype og utløser. Hvis to systemer kan sende den samme meldingen, må du deaktivere én bane eller dele en varig varslingslogg. Avgjør også om en melding gjelder én pakke eller hele ordren, særlig ved delt oppfyllelse.
Betyr en avviksstatus at ordren har mislyktes?
Nei. Et avvik er en observasjon som krever tolkning, ikke nødvendigvis et permanent resultat. Bevar årsaken, overvåk påfølgende hendelser og bruk eskaleringspolicyen din til å avgjøre når driften bør gripe inn.
Kilder
- 17TRACK Tracking API — offisiell produktreferanse og utgangspunkt for API-integrasjonen.
- 17TRACK API documentation — implementasjonsreferanse for leverandørens spesifikke kontrakt; bekreft aktuelle grensesnitt og kontokrav før utrulling.
- RFC 9110, Section 9.2.2: Idempotent Methods — HTTP-semantikk som understøtter skillet mellom metodeidempotens og beskyttelse mot duplikater på applikasjonsnivå.


