Skip to main content
HemBloggGuiderArbetsflöde för Shipment Tracking API: från registrering av en försändelse till hämtning av spårningsuppgifter

Arbetsflöde för Shipment Tracking API: från registrering av en försändelse till hämtning av spårningsuppgifter

17TRACK

Ett arbetsflöde för ett API för försändelsespårning börjar med att skicka in ett spårningsnummer och eventuell obligatorisk transportörsinformation, kontrollera om registreringen lyckades, låta spårningsdata bli tillgänglig och hämta försändelsens status och händelsehistorik. För en produktionsintegration behöver utvecklare dessutom koppla varje spårningspost till en order, hantera partiella fel, bearbeta uppdateringar säkert och skilja mellan en accepterad registrering och en faktisk skanning hos transportören.

Arbetsflöde för Shipment Tracking API från registrering av en försändelse till hämtning

Den här guiden förklarar arbetsflödet för utvecklare som ansluter en e-handelsplattform, ett orderhanteringssystem, en lagerapplikation eller ett kundtjänstverktyg. Den skiljer rekommendationer för applikationsdesign från leverantörsspecifika API-krav. För en 17TRACK-integration använder du den officiella API-dokumentationen för att bekräfta begäransschema, autentisering, funktioner som stöds och svarsdata innan du implementerar exemplen nedan.

Förstå vad registrering gör – och inte gör

Att registrera en försändelse hos en spårningstjänst innebär att skicka in en identifierare så att tjänsten kan spåra eller hantera försändelsen enligt sitt API-avtal. Det är inte samma sak som att köpa porto, skapa en fraktsedel, boka en upphämtning eller lämna över ett paket till en transportör.

Håll isär tre resultat i din applikation:

  • Begäran mottagen: API:t returnerade ett svar på din HTTP-begäran.
  • Registrering accepterad: Tjänsten accepterade den enskilda spårningsposten för behandling.
  • Spårningsinformation tillgänglig: Tjänsten har försändelseinformation som din applikation kan hämta eller ta emot.

Dessa resultat bör inte slås ihop till en enda flagga för ”lyckades”. Ett accepterat spårningsnummer kan ännu sakna händelser från transportören. På samma sätt innebär ett lyckat HTTP-svar för en batchbegäran inte att varje post i batchen accepterades; kontrollera resultatstrukturen på applikationsnivå som definieras av leverantören.

1. Förbered försändelsens identitet och API-konfiguration

Innan du gör en registreringsbegäran bör du bestämma hur en försändelse ska identifieras i ditt eget system. Ett order-ID är vanligtvis otillräckligt eftersom en order kan delas upp i flera paket. Ge varje försändelse eller paket en egen intern post och koppla posten till den relevanta ordern.

En användbar intern post innehåller följande information. Detta är föreslagna applikationsfält, inte ett 17TRACK-begäransschema.

  • Internt försändelse-ID: Din stabila identifierare för paketet.
  • Orderreferens: Den order eller leveranspost som försändelsen tillhör.
  • Spårningsnummer: Den identifierare som utfärdats av transportören, lagrad som text för att bevara inledande nollor.
  • Transportörsinformation: Transportörens identitet från ditt leveranssystem, om den är känd.
  • Leverantörsreferens: Alla identifierare som spårningstjänsten returnerar och som behövs för senare åtgärder.
  • Registreringsstatus: Din registrering av om inskickningen väntar, har accepterats, avvisats eller väntar på avstämning.
  • Spårningsstatus: Den senaste försändelsestatusen, separat från registreringsstatusen.

Validera indata före inskickning. Ta bort oavsiktliga inledande och avslutande blanksteg, men skriv inte om spårningsnumret utifrån antaganden om transportörens format. Bevara originalvärdet för felsökning. Om transportören är känd ska du mappa den till leverantörens dokumenterade transportörsidentifierare i stället för att skicka ett informellt visningsnamn.

Konfigurera autentisering på serversidan. Förvara autentiseringsuppgifter utanför källkodshanteringen, separera utvecklings- och produktionskonfiguration och maskera hemligheter i loggar. Bekräfta den dokumenterade API-versionen, begärandegränserna, batchgränserna och kontokraven i stället för att låna värden från en orelaterad integration.

2. Registrera försändelsen och spara resultatet för varje post

Skicka spårningsposten med den registreringsfunktion som beskrivs i leverantörens dokumentation. Inkludera endast obligatoriska fält och valfri information som har ett definierat syfte. Undvik att skicka kundnamn, adresser eller andra personuppgifter bara för att de finns i din orderdatabas.

Följande pseudokod illustrerar applikationssekvensen. Funktionsnamnen är exempel; de är inte API-slutpunkter eller SDK-metoder.

shipment = load_internal_shipment(shipment_id)
validate_tracking_input(shipment)

result = tracking_adapter.register(shipment)

if result.item_accepted:
    save_registration_result(shipment_id, result)
elif result.outcome_unknown:
    schedule_registration_reconciliation(shipment_id)
else:
    save_registration_error(shipment_id, result)
    route_for_retry_or_correction(result)

Spara tillräckligt med information för att förklara vad som hände: internt försändelse-ID, inskickningstid, försöksnummer, resultat för den enskilda posten och eventuell begäransreferens från leverantören. Förlita dig inte enbart på en tillfällig arbetarlogg. Kundtjänst- och driftteamen behöver ett beständigt svar på om en försändelse registrerades korrekt.

Hantera batchinskickningar individuellt

Om API:t stöder batchregistrering ska du koppla varje returnerad post till den ursprungliga försändelsen. Markera inte hela batchen som accepterad bara för att HTTP-begäran slutfördes. Spara accepterade poster, isolera avvisade poster och undersök oklara resultat separat.

Detta förhindrar att ett felaktigt spårningsnummer tvingar fram onödiga nya försök för poster som redan lyckats. Det ger också driftpersonalen en användbar lista över poster som behöver korrigeras.

Behandla tidsgränsöverskridanden som ett okänt resultat

Ett tidsgränsöverskridande bevisar inte att registreringen misslyckades. Leverantören kan ha accepterat begäran innan anslutningen avbröts. Använd dokumenterat idempotensbeteende, hantering av dubbletter eller uppslagsfunktioner för att stämma av resultatet innan du skickar om begäran på måfå.

Om leverantörens beteende vid dubbletter är oklart bör du testa det med kontrollerade poster och bekräfta avtalet innan automatiska nya försök aktiveras. Intern deduplicering av registreringsjobb är fortfarande användbar, men den ersätter inte förståelsen av hur fjärrtjänsten hanterar upprepade begäranden.

3. Ge den första spårningsinformationen tid att komma in

Efter att registreringen har accepterats kanske spårningsdetaljerna inte blir tillgängliga omedelbart. En etikett kan finnas innan transportören har registrerat en fysisk hanteringshändelse. Saknad information kan också innebära att spårningsnumret, transportörsvalet eller försändelsespecifika uppslagskrav måste kontrolleras.

Representera detta tillstånd uttryckligen. ”Registrerad; väntar på spårningsinformation” är mer korrekt än antingen ”Under transport” eller ”Registreringen misslyckades”. Hitta inte på en leveransprognos eller en rörelsehändelse för att fylla ett tomt gränssnitt.

När en post fortfarande är tom bör du undersöka följande i praktisk ordning:

  1. Bekräfta att den enskilda registreringen accepterades.
  2. Jämför det inskickade spårningsnumret med leveransposten.
  3. Kontrollera transportörsmappningen och eventuella dokumenterade ytterligare uppslagskrav.
  4. Kontrollera transportörens egen spårningssida för samma försändelse.
  5. Om transportören har händelser men din integration inte har det, granska hämtningssvaren och kontakta API-leverantören med maskerad diagnostisk information.

Undvik att införa en universell väntetid utan belägg. Eskaleringsreglerna bör återspegla transporttjänsten, den förväntade överlämningsprocessen och dina egna operativa åtaganden.

4. Hämta spårningsdetaljer och tolka dem korrekt

När posten är tillgänglig ska du anropa den dokumenterade funktionen för spårningsdetaljer med de identifierare som krävs. Anta inte att registrering och hämtning accepterar identiska fält. Vissa API-avtal skiljer mellan spårningsnummer, transportörsidentifierare och postreferenser som genererats av leverantören.

Din applikation bör skilja mellan tre informationsnivåer:

  • Försändelsesammanfattning: Det övergripande tillståndet som används i instrumentpaneler, ordersidor och operativa filter.
  • Händelsehistorik: De enskilda observationerna, inklusive händelsebeskrivningar, tidsstämplar och platser när de anges.
  • Metadata för hämtning: När applikationen tog emot eller hämtade informationen och om begäran slutfördes korrekt.

Ett lyckat uppslag innebär att hämtningsåtgärden lyckades. Det betyder inte att paketet har rört sig sedan föregående uppslag. Jämför den returnerade spårningsinformationen med den lagrade posten innan du skapar en avisering eller ett efterföljande arbetsflöde.

Håll händelsetid och hämtningstid åtskilda

Lagra tiden som hör till en transportörshändelse separat från tiden då ditt system tog emot den. En händelse som hämtas i eftermiddag kan beskriva en tidigare skanning. Om händelsetiden ersätts med hämtningstiden ser en gammal uppdatering ut som en ny fysisk förflyttning.

Bevara den ursprungliga tidsstämpeln och eventuell angiven förskjutning. Normalisera tidsstämplar för jämförelser endast när tidszonen är känd. Om en händelse saknar tidszonsinformation ska du behålla osäkerheten i stället för att tyst tilldela serverns tidszon.

Bevara den råa betydelsen tillsammans med normaliserad status

En normaliserad status är användbar för att gruppera försändelser över transportörer, men den ursprungliga händelsebeskrivningen kan förklara ett operativt problem mer exakt. Behåll båda när de finns tillgängliga. En bred undantagskategori ensam kanske inte berättar för en supportagent om nästa åtgärd är att kontrollera en adress, kontakta mottagaren eller vänta på en ny uppdatering.

Härled inte en leveransgaranti, en bekräftad förlust eller ett visst tullutfall från en vag status. Eskalera utifrån den underliggande informationen och din verksamhetspolicy.

5. Håll posterna uppdaterade genom polling eller webhooks

Att hämta detaljer en gång räcker för att testa anslutningen, men inte för att upprätthålla insyn i försändelser. Din produktionsdesign behöver en mekanism för uppdateringar. Bekräfta vilka mekanismer din valda leverantör stöder och vilka villkor som gäller för dem.

Med polling begär applikationen spårningsdetaljer enligt ett schema. Schemalägg begäranden inom de dokumenterade gränserna, undvik att upprepade gånger fråga efter oförändrade poster utan anledning och använd backoff för fel som kan åtgärdas genom nya försök. När en kund öppnar en ordersida bör det inte automatiskt utlösa en obegränsad begäran uppströms; en lagrad spårningsvy kan visa sidan medan en kontrollerad bakgrundsprocess uppdaterar den.

Om du använder webhooks ska inkommande begäranden valideras med leverantörens dokumenterade verifieringsmekanism. Spara eller köa accepterade meddelanden på ett beständigt sätt innan du bekräftar mottagandet enligt webhook-avtalet, och bearbeta sedan händelserna asynkront.

Bygg mottagaren så att den tål dubbletter och oväntad ankomstordning, om inte det dokumenterade leveransavtalet garanterar något annat. Använd en händelseidentifierare från leverantören för deduplicering när den finns tillgänglig. Annars definierar och testar du ett fingeravtryck baserat på lämpliga händelsefält, med insikten att ett sådant fingeravtryck kan behöva justeras för dina data.

En webhook-styrd integration kan också använda kontrollerad hämtning för avstämning. Exempelvis kan ett återställningsjobb kontrollera poster som påverkats av ett avbrott hos mottagaren. Detta är ett motståndskraftsmönster, inte ett tillstånd att ignorera hastighetsgränser eller leverantörsspecifik vägledning.

6. Omvandla spårningsinformation till säkra affärsåtgärder

Uppdatera din interna försändelsepost innan kundåtgärder utlöses. Spara en beständig historik över aviseringar och arbetsflödesövergångar så att en upprepad händelse inte skapar upprepade meddelanden.

Koppla affärsåtgärder till meningsfulla förändringar i stället för till varje API-svar. En nyupptäckt leveranshändelse kan motivera en leveransavisering. Ett upprepat svar som innehåller samma händelse bör inte göra det. Ett undantag kan motivera en intern granskning, men kundmeddelandet bör återspegla vad händelsen faktiskt säger.

Definiera hur du hanterar händelser som tas emot efter att en försändelse har ansetts vara slutförd. Ta inte bort händelsehistoriken eller blockera permanent alla senare uppdateringar bara för att en sammanfattning nått ett slutligt tillstånd. Dina regler för lagring, avstämning och avisering bör ta hänsyn till legitima korrigeringar utan att upprepade gånger öppna slutförda arbetsflöden igen.

Tillämpa arbetsflödet på en 17TRACK-integration

För en anpassad spårningsintegration är relevanta utgångspunkter sidan för 17TRACK Tracking API och dess utvecklardokumentation. Använd produktsidan för att bedöma erbjudandet och dokumentationen för att fastställa det faktiska integrationsavtalet. Spårningssidor för konsumenter ersätter inte API-specifikationer.

Innan du skriver din adapter ska du bekräfta autentiseringsformatet, registrerings- och hämtningsfunktionerna, reglerna för identifiering av transportörer, hanteringen av svar på postnivå och tillämpliga begärandegränser. För webhook-baserad behandling ska du även bekräfta nyttolastens schema, verifieringsprocessen, kraven på bekräftelse och beteendet vid nya försök.

Håll dessa leverantörsspecifika detaljer inne i en adapter i stället för att sprida antaganden om svarsfält genom hela ordersystemet. Resten av applikationen kan då arbeta med interna begrepp som registreringsresultat, försändelsestatus, händelsehistorik och senaste lyckade synkronisering.

Kontroller före lansering som upptäcker kostsamma misstag

  • Accepterad men tom post: Gränssnittet visar att spårningsinformation väntar, inte att paketet är i rörelse.
  • Blandat batchresultat: Varje försändelse får sitt eget sparade resultat.
  • Tidsgränsöverskridande efter inskickning: Arbetaren stämmer av det osäkra resultatet i stället för att anta att det misslyckades.
  • Upprepad händelse: Försändelsens tidslinje och kundavisering förblir deduplicerade.
  • Äldre händelse mottagen senare: Händelsen bevaras utan att en nyare sammanfattning ersätts blint.
  • Otillgänglig tjänst uppströms: Kundsidan kan visa det senast lagrade resultatet med en lämplig uppgift om aktualitet.
  • Felaktig transportörsmappning: Posten kan korrigeras genom en dokumenterad återställningsväg.
  • Delad order: Varje paket behåller sin egen spårningsstatus och händelsehistorik.
  • Exponering av autentiseringsuppgifter eller nyttolast: Loggar innehåller diagnostiska referenser utan att läcka hemligheter eller onödig personlig information.

Det praktiska kriteriet för att vara klar är inte bara att ta emot ett lyckat registreringssvar. Det är att kunna följa ett paket från inskickning genom uppdateringar, förklara ett tomt eller misslyckat resultat och återhämta sig från avbruten behandling utan att förlora händelser eller duplicera kundåtgärder.

Vanliga frågor

Skapar registrering av ett spårningsnummer en försändelse?

Inte i det arbetsflöde som beskrivs här. Spårningsregistrering skickar en befintlig identifierare till en spårningstjänst. Skapande av etikett, köp av porto och bokning hos transportör är separata åtgärder, om inte ett visst API uttryckligen kombinerar dem.

Varför är spårningsdetaljerna tomma efter att registreringen lyckats?

Registreringsacceptans och tillgänglighet för spårningsdata är olika tillstånd. Transportören kanske ännu inte har registrerat en händelse, eller så kan spårningsnumret, transportörsmappningen eller ytterligare uppslagsinformation behöva kontrolleras. Granska resultatet på postnivå innan du betraktar posten som korrekt registrerad.

Bör jag registrera försändelsen varje gång jag hämtar dess status?

Använd inte upprepad registrering som standardmekanism för uppdatering. Spara den accepterade registreringsstatusen och använd den dokumenterade hämtnings- eller uppdateringsmekanismen. Följ leverantörens uttryckliga regler för korrigeringar, återaktivering eller dubbla inskickningar.

Bör jag använda polling eller webhooks?

Använd den mekanism som passar det dokumenterade API-avtalet och dina operativa krav. Polling kräver ett kontrollerat begärandeschema. Webhooks kräver en säker, beständig mottagare och behandling som tål dubbletter. När det stöds kan webhook-uppdateringar med riktad avstämning ge en praktisk återställningsväg.

Kan jag använda ett spårningsnummer som min databas enda identifierare för försändelsen?

Använd i stället en intern försändelseidentifierare. Lagra spårningsnumret och relevant transportörskontext som attribut för posten. Det gör delade ordrar, korrigerade spårningsnummer och leverantörsspecifika referenser enklare att hantera utan att ändra identiteten för din interna försändelse.

Källor

  • 17TRACK Tracking API — officiell produktingång för utvärdering av en 17TRACK API-integration.
  • 17TRACK API documentation — officiell referens för implementeringsspecifika begärandeformat, funktioner, svar och integrationskrav. Pseudokoden och förslagen på interna fält i denna guide är exempel på applikationsdesign, inte citat från detta API-avtal.