Så ansluter du leveransspårningsdata till ett Oms: ordermappning och synkroniseringsregler
För att ansluta data om försändelsespårning till ett orderhanteringssystem (OMS), koppla varje spårat paket till en intern försändelsepost och länka sedan försändelsen till dess order- och leveransrader. Ta emot spårningsuppdateringar via leverantörens gränssnitt som stöds, bevara de ursprungliga händelserna och tillämpa uttryckliga regler för dubbletter, sena uppdateringar, försändelsestatus och orderfärdigställande. Använd inte ett spårningsnummer ensamt som orderidentifierare och låt inte en enda leveranshändelse automatiskt stänga en order med flera paket.
Den här guiden är avsedd för integrationsingenjörer och team för e-handelsdrift som implementerar denna anslutning. Den rekommenderade designen separerar transportörernas observationer från affärsbesluten: spårningsdata beskriver ett pakets resa, medan OMS avgör vad denna resa innebär för leverans, kundkommunikation och stängning av ordern.
Definiera vilket system som äger varje post
Innan du bygger en API-anslutning bör du komma överens om ägarskapet med OMS-administratören, leveransteamet och kundtjänstteamet. Annars kan en tekniskt framgångsrik integration fortfarande skriva över giltiga affärsdata.
- OMS: Äger order, orderrader, erforderliga kvantiteter, annulleringar och reglerna för färdigställande av order.
- Leveranssystem: Äger de försändelse- eller paketposter som systemet skapar, inklusive packningsallokeringar och etiketttilldelningar. Detta kan vara själva OMS eller ett separat lagersystem.
- Spårningsleverantör: Tillhandahåller spårningsobservationer och eventuella leverantörsdefinierade statusklassificeringar.
- Integrationslager: Äger korsreferenser för identifierare, händelsebearbetning, normalisering, hantering av nya försök och synkroniseringsloggar.
Se dessa som rekommenderade gränser, inte som antaganden om din programvara. Dokumentera undantag. Om lagret exempelvis kan byta en fraktetikett behöver integrationen en uttrycklig uppdatering från det systemet i stället för att gissa att ett nyupptäckt nummer ersätter ett gammalt.
Bygg kopplingen mellan order och paket innan statusar synkroniseras
En praktisk relation är order → leverans → paket → spårningstilldelning. Ditt OMS kan använda andra namn eller kombinera vissa av dessa poster. Bevara relationerna även om databasstrukturen skiljer sig.
En order kan ha flera leveranser och en leverans kan innehålla flera paket. Ett paket kan också få en ersättande spårningstilldelning eller en länkad identifierare för sista ledet. Dessa identifierare ska inte skapa ytterligare beställda kvantiteter.
| Post | Rekommenderade fält | Syfte |
|---|---|---|
| Order | Klient- eller butiks-ID, oföränderligt OMS-order-ID | Separera handlare och undvik beroende av ordernummer som endast visas för användaren. |
| Leverans | Leverans-ID, order-ID, tilldelade rad-ID:n och kvantiteter | Identifierar vilka köpta artiklar som levereras. |
| Paket | Internt paket-ID, leverans-ID, pakettilldelningar när sådana finns | Tillhandahåller en stabil identitet som är oberoende av spårningsetiketter. |
| Spårningstilldelning | Tilldelnings-ID, paket-ID, leverantörskonto, transportörsidentifierare, spårningsnummer, aktiv period | Länkar inkommande spårningsobservationer till rätt paket och tilldelningens livscykel. |
Matcha uppdateringar via en lagrad korsreferens
När en försändelse skapas ska du spara dess interna ID:n innan du registrerar den för spårning. Spara alla leverantörsutfärdade ID:n för spårningsposter som returneras av den dokumenterade registreringsprocessen. Om leverantören stöder en handlarreferens ska du använda en ogenomskinlig intern referens och bevara mappningen lokalt.
För inkommande uppdateringar ska du först hitta det lagrade leverantörspost-ID:t inom rätt leverantörskonto och klient. Om identifieraren saknas använder du den dokumenterade kombinationen av spårningsnummer, transportörsidentitet, kontokontext och tilldelningshistorik. Se detta som en uppslagsstrategi, inte som en garanti för att kombinationen är globalt unik.
Matcha inte via kundens namn, e-postadress eller ett ordernummer som visas för användaren utan klientavgränsning. Bevara spårningsnummer som strängar så att inledande nollor finns kvar. Undvik att ta bort tecken eller ändra skiftläge om inte den berörda transportörens eller leverantörens avtal tillåter sådan normalisering.
Om en sökning inte ger någon träff eller ger flera möjliga träffar ska du placera uppdateringen i karantän för utredning. En olöst händelse är säkrare än en säker uppdatering av fel kunds order.
Hantera delade order utan att hitta på pakettilldelningar
Tänk på en exempelorder som innehåller tre enheter. Paket A innehåller två enheter och Paket B en. Leverans av Paket A innebär att det finns leveransbevis för två enheter; det innebär inte att hela ordern är levererad.
Om leveranssystemet endast registrerar att båda paketen tillhör samma leverans ska du inte hitta på tilldelningar på enhetsnivå. Du kan fortfarande beräkna om alla obligatoriska paket är levererade, men rapportering av leverans på artikelnivå bör förbli otillgänglig eller uttryckligen osäker tills tilldelningsdata finns.
Anslut spårnings-API:t via ett hållbart inmatningslager
Använd en pipeline som håller leverantörskommunikationen åtskild från OMS-skrivningar:
Skapande av försändelse → spårningsregistrering → inkommande uppdatering eller schemalagd hämtning → varaktig händelselagring → mappning och normalisering → OMS-uppdatering → avstämning
För en 17TRACK-implementation är produktsidan för Tracking API och den officiella API-dokumentationen relevanta utgångspunkter. Bekräfta tillämpligt registreringsgränssnitt, transportörsidentifierare, alternativ för leverans av uppdateringar, autentiseringskrav, statusdefinitioner och kontobegränsningar innan adaptern implementeras. Datamodellen i den här guiden är en integrationsrekommendation, inte ett påstående om att 17TRACK använder dessa fältnamn eller tillhandahåller en inbyggd anslutning till ditt OMS.
Om den valda leverantören stöder webhooks ska du autentisera inkommande förfrågningar med den dokumenterade mekanismen och varaktigt lagra accepterade meddelanden innan du bekräftar dem. Håll långsamt OMS-arbete utanför begärans väg. Följ leverantörens faktiska bekräftelse- och omförsöksavtal i stället för att anta en viss svarskropp eller tidsgräns.
Om polling krävs ska du lagra hämtningsförloppet där API:t stöder det, kontrollera samtidighet och följa dokumenterade hastighetsgränser. Varken mottagande av en webhook eller en lyckad pollingförfrågan bevisar att OMS uppdaterades; registrera dessa resultat separat.
Definiera synkroniseringsregler som klarar nya försök och sena händelser
1. Gör bearbetningen idempotent
Att bearbeta samma observation två gånger ska inte duplicera en försändelse, öka kvantiteter två gånger eller skicka samma kundmeddelande igen. HTTP gör inte en godtycklig POST-operation idempotent; integrationen måste implementera dubblettskydd. RFC 9110 förklarar idempotens för HTTP-metoder.
Använd ett stabilt leverantörs-händelse-ID när ett sådant är dokumenterat och tillgängligt. Annars definierar du ett fingeravtryck från tilldelnings-ID:t och relevanta händelsefält, exempelvis händelsens tidsstämpel, källstatus och plats. Dokumentera möjligheten till kollisioner eller ändrade händelsebeskrivningar. Behåll den råa observationen även när den inte leder till någon ytterligare OMS-åtgärd.
Skydda varje sidoeffekt separat. En OMS-statusskrivning och en e-postavisering behöver till exempel egna kontroller för deduplicering. Använd en transaktionell outbox eller motsvarande varaktig arbetsregistrering så att en processkrasch inte kan lämna en accepterad händelse utan en schemalagd uppdatering.
2. Lagra händelsetid och mottagningstid separat
Tiden då en händelse inträffade och tiden då integrationen tog emot den besvarar olika frågor. Lagra båda, tillsammans med den ursprungliga tidsstämpelrepresentationen och eventuell angiven tidszonsförskjutning. Tilldela inte i tysthet lagrets tidszon till en händelse vars tidszon är okänd.
En sent anländande transportskanning bör normalt berika historiken utan att ersätta en nyare levererad status. Tidsstämplar ensamma är dock otillräckliga: en leverantör kan utfärda en korrigering och händelser kan ha ofullständig tidsinformation. Använd dokumenterade sekvens- eller revisionsfält när sådana finns, tillsammans med en uttrycklig korrigeringspolicy.
3. Normalisera statusar utan att radera källdetaljer
Skapa ett litet internt vokabulär som OMS förstår, till exempel väntar på transportörens mottagande, under transport, ute för leverans, levererad, undantag och returneras. Mappa leverantörens dokumenterade statusar till detta. Detta är föreslagna interna kategorier, inte universella transportörsdefinitioner.
Lagra den ursprungliga statuskoden, beskrivningen, händelseplatsen, referensen till leverantörsposten och versionen av mappningsregeln. Ett omappat värde bör skapa ett granskningsbart tillstånd i stället för att som standard markeras som levererat eller misslyckat. Etikettskapande ska inte betraktas som bevis på att transportören fysiskt har tagit emot försändelsen om inte källhändelsen uttryckligen stöder den tolkningen.
4. Använd övergångsregler, inte en enkel numerisk rangordning
Försändelsestatusar bildar inte alltid en rak linje. Ett undantag kan följas av normal transport och ett leveransförsök är inte samma sak som leverans. Returtransport kan börja efter en tidigare leveranshändelse.
- Tillåt att ett undantag upphör när efterföljande bevis stöder återupptagen transport.
- Förhindra att en vanlig historisk skanning i tysthet ersätter en levererad status.
- Tillåt en dokumenterad korrigering via en kontrollerad revisionsväg.
- Spåra returtransport separat från utgående färdigställande när OMS stöder det.
- Dirigera tvetydiga eller motsägelsefulla bevis till en operativ kö.
Versionshantera dessa regler. När en mappning ändras ska du besluta om den endast gäller nya händelser eller om historiska poster kräver en kontrollerad omberäkning.
Beräkna orderstatus utifrån obligatoriska leveransåtaganden
Paketstatus och orderstatus bör vara separata fält. Ett paket som markerats som levererat ger bevis för det paketet; färdigställande av ordern beror på återstående obligatoriska kvantiteter och din affärspolicy.
En användbar standard är att markera en order som helt levererad endast när alla leveranspliktiga kvantiteter har giltiga leveransbevis på paketnivå och inga obligatoriska tilldelningar återstår att lösa. Exkludera annullerade kvantiteter enligt OMS:s annulleringsregler. Hantera digitala artiklar, upphämtningsorder och andra icke-leveransrelaterade åtaganden genom egna villkor för färdigställande.
Ersättningsförsändelser kräver uttryckliga relationer. Om ett förlorat paket ersätts ska du besluta om ersättningen ersätter det ursprungliga leveransåtagandet. Annars kan originalpaketet blockera färdigställandet på obestämd tid, eller så kan båda paketen räknas mot leveransen. Registrera beslutet i stället för att härleda det enbart från spårningsstatus.
Håll leveransfärdigställande åtskilt från ekonomisk stängning, återbetalningsberättigande och tvistlösning. En leveranshändelse från transportören ska inte automatiskt godkänna en återbetalning eller avgöra ett kundanspråk.
Återställ efter fel utan att förlora granskningsspåret
Försök igen vid tillfälliga fel med begränsad backoff och eventuell dokumenterad vägledning om nya försök. Separera tillfälliga anslutningsfel från ogiltiga identifierare, utgångna autentiseringsuppgifter, behörighetsfel och inkompatibilitet i scheman. De senare kräver korrigerande åtgärder, inte oändliga nya försök.
Underhåll en kö för misslyckat arbete som innehåller berörd klient, paket, händelsereferens, försökt åtgärd, felklassificering och nästa åtgärd. Logga tillräckligt med kontext för att kunna utreda utan att kopiera onödiga kunduppgifter eller autentiseringsuppgifter till loggarna.
Kör avstämning utöver den normala uppdateringssökvägen. Granska aktiva försändelser med inaktuell spårningsinformation, accepterade händelser vars OMS-skrivningar misslyckades, omatchade observationer och skillnader mellan integrationens beräknade tillstånd och OMS. Välj granskningsfrekvens utifrån leveransåtaganden, API-begränsningar och operativ risk i stället för att tillämpa ett godtyckligt universellt schema.
Fördela ägarskapet: teknikteamet hanterar inmatning och skrivfel; leveransverksamheten löser saknade paketrelationer; kundtjänsten granskar undantag som kräver kundkommunikation. En kö utan ansvarig ägare är endast en lagringsplats.
Testa mappningen och affärsreglerna före lansering
Använd kontrollerade testdata och en begränsad utrullning i produktion. Testa följande fall mot både händelsehistoriken och den resulterande OMS-posten:
- En order med ett paket går normalt vidare till leverans.
- En delad order har ett levererat paket och ett paket som fortfarande transporteras.
- Samma händelse tas emot upprepade gånger utan duplicerade sidoeffekter.
- En äldre transportskanning anländer efter leveransen.
- En okänd transportör eller status hamnar i granskningskön.
- En etikett ersätts utan att skapa ytterligare ett leveransåtagande.
- En ersättningsförsändelse ersätter ett originalpaket enligt en godkänd regel.
- OMS är otillgängligt efter att en händelse har accepterats.
- En process startar om mellan en OMS-skrivning och dess bekräftelse.
- Samma ordernummer som visas för användaren finns i två butiker utan matchning över klientgränser.
Lansera när varje accepterad händelse har ett spårbart behandlingsresultat, tvetydiga matchningar inte kan uppdatera order automatiskt och operatörer säkert kan spela upp misslyckat arbete igen. Detta är mer användbara acceptanskriterier än att bara visa att en API-förfrågan lyckas.
Vanliga frågor
Kan jag koppla spårningsnummer direkt till order?
För ett strikt arbetsflöde med ett enda paket kan en direkt relation vara tillräcklig inledningsvis. Använd ändå en intern försändelseidentitet mellan ordern och spårningstilldelningen. Den ger en migreringsväg för delade försändelser, ometikettering och ersättningar utan att ändra orderpostens innebörd.
Bör integrationen använda webhooks eller polling?
Använd den leveransmekanism som leverantören stöder och som är kompatibel med din infrastruktur. Webhooks kan minska upprepade hämtningar, medan polling kan stödja hämtningsbaserade arbetsflöden och avstämning där det är tillgängligt. Inget av alternativen eliminerar behovet av varaktig lagring, dubbletthantering och återställning.
Vad ska hända när en spårningshändelse inte har någon matchande order?
Lagra den i en kö för omatchade händelser och undersök registreringsposten, klientkontexten, transportörsidentiteten och tidpunkten för skapandet av försändelsen. Skapa inte en order och koppla inte automatiskt händelsen till en sannolik kund. Spela upp den igen efter att mappningen har korrigerats.
Bör leveransaviseringar komma från OMS eller spårningssystemet?
Välj en ägare för varje typ av avisering och utlösare. Om två system kan skicka samma meddelande ska du inaktivera en sökväg eller dela en varaktig aviseringslogg. Bestäm också om ett meddelande gäller ett paket eller hela ordern, särskilt vid delad leverans.
Betyder en undantagsstatus att ordern har misslyckats?
Nej. Ett undantag är en observation som kräver tolkning, inte nödvändigtvis ett permanent resultat. Bevara orsaken, övervaka efterföljande händelser och använd eskaleringspolicyn för att avgöra när verksamheten ska ingripa.
Källor
- 17TRACK Tracking API — officiell produktreferens och utgångspunkt för API-integrationen.
- 17TRACK API documentation — implementeringsreferens för det leverantörsspecifika avtalet; verifiera tillämpliga gränssnitt och kontokrav före driftsättning.
- RFC 9110, Section 9.2.2: Idempotent Methods — HTTP-semantik som stöder åtskillnaden mellan metodidempotens och dubblettskydd på applikationsnivå.


