Så registrerar du ett spårningsnummer via API: förfrågningsfält, transportörskoder och svar
För att registrera ett spårningsnummer via API skickar du en autentiserad registreringsbegäran som innehåller försändelsens spårningsnummer och, när det krävs, en transportörsidentifierare. Kontrollera sedan svaret för varje inskickad försändelse – inte bara HTTP-statusen – och spara om registreringen lyckades, misslyckades eller fortfarande är osäker. Registreringen startar spårningsarbetsflödet; den bevisar inte att transportören har skannat paketet eller att spårningshändelser redan är tillgängliga.
Den här guiden är avsedd för utvecklare som ansluter ett orderhanteringssystem, en lagerapplikation eller en e-handelsplattform till ett spårnings-API. Den använder 17TRACK som ett konkret integrationsexempel och förklarar vilka uppgifter som måste kontrolleras mot dokumentationen för den valda API-versionen.
17TRACK API Global Shipment Tracking SolutionAnslut till fler än 3 500 transportörer världen över via ett enda API för enkel, exakt och tillförlitlig paketspårning.
Prova gratis →
Vad registreringen gör – och inte gör
En registreringsbegäran talar om för en spårningstjänst vilken försändelse du vill spåra. Den skiljer sig från att köpa en fraktetikett, boka en upphämtning eller be en transportör skapa en försändelse. I en typisk integration genererar fraktarbetsflödet först ett spårningsnummer, och därefter registrerar din applikation numret.
Branded Order Tracking SolutionLeverera en bättre kundupplevelse och öka antalet återkommande köp med varumärkesanpassad spårning och automatiska aviseringar.
Prova gratis →
Håll dessa tre händelser åtskilda i din applikation:
- Försändelse skapad: ditt fraktsystem har tilldelat ett spårningsnummer.
- Registrering accepterad: spårningstjänsten har accepterat försändelsen för spårning.
- Spårningsinformation mottagen: transportörens händelser har blivit tillgängliga via spårningstjänsten.
Uppdatera inte en order till ”under transport” enbart för att registreringen lyckades. En nyskapad etikett kanske ännu inte har fått en fysisk mottagningsskanning. Den kundsynliga försändelsestatusen bör baseras på spårningshändelser som tolkas genom dina statusmappningsregler, inte på registreringssvaret.
För 17TRACK-integrationer börjar du med översikten över Tracking API och använder den officiella API-dokumentationen som källa för slutpunkter, fältdefinitioner, autentisering och svarskoder. Exemplen nedan fokuserar på registrering och inte på de separata uppgifterna att hämta resultat eller ta emot uppdateringar.
Förbered begäransfälten innan du skriver API-anropet
Den mest användbara förberedelsen är ett litet fältavtal mellan ditt fraktsystem och din spårningsintegration. Bestäm varifrån varje värde kommer, om det kan saknas och hur det ska valideras.
| Fält eller värde | Syfte | Implementeringsregel |
|---|---|---|
| Spårningsnummer | Identifierar försändelsen som ska spåras. | Lagra och överför det som en sträng; bevara inledande nollor. |
| Transportörsidentifierare | Identifierar transportören i spårningsleverantörens system. | Använd leverantörens dokumenterade identifierare, inte en intern lagerkod. |
| Intern referens | Kopplar registreringen till din försändelsepost. | Använd ett referensfält som stöds om det finns; behåll alltid din egen databasmappning. |
| Ytterligare identifieringsdata | Kan hjälpa till att identifiera en försändelse när en transportör kräver mer än spårningsnumret. | Skicka endast fält som dokumenterats för integrationen och transportören. |
| API-autentiseringsuppgift | Autentiserar det anropande kontot. | Förvara den på servern och uteslut den från applikationsloggar. |
Behandla spårningsnumret som en identifierare
Konvertera aldrig ett spårningsnummer till ett heltal. Numerisk konvertering kan ta bort inledande nollor, och stora värden kan förlora precision i vissa programmeringsmiljöer. Ta bort oavsiktliga blanksteg runt numret, men ta inte bort skiljetecken och ändra inte skiftläge om inte den relevanta dokumentationen eller transportörens format stöder sådan normalisering.
Validera uppenbara indatafel innan du anropar API:t: tomma strängar, oväntade radbrytningar och ett ordernummer som kopierats till spårningsnummerfältet. Undvik att införa en universell längd- eller teckenregel för alla transportörer. En valideringsregel som passar en transportör kan avvisa giltiga nummer från en annan.
Håll orderreferenser åtskilda från försändelseidentiteter
En order kan innehålla flera paket, och en ersättningsförsändelse kan få ett nytt spårningsnummer. Modellera registreringen på försändelse- eller paketnivå i stället för att anta ett spårningsnummer per order.
Om du använder en tagg eller ett referensfält som stöds av leverantören bör du föredra en ogenomskinlig försändelsereferens framför kundens e-postadress eller gatuadress. Din egen databas bör fortfarande vara den auktoritativa kopplingen mellan order, försändelser, spårningsnummer och transportörsmappningar.
Välj rätt transportörskod
En transportörskod är inte nödvändigtvis en universell branschidentifierare. Värdet som känns igen av en spårningsplattform kan skilja sig från transportörsnamnet som lagras i ditt fraktsystem. Även två system som använder numeriska koder kan tilldela olika nummer till samma transportör.
Underhåll en uttrycklig mappning från din frakttjänst till spårningsleverantörens transportörsidentifierare. När det behövs ska du skilja mellan en transportörs regionala verksamhet eller tjänst och dess bredare varumärke. En mappning som endast bygger på ett visningsnamn kan bli tvetydig när fraktsystem använder alias.
- När transportören är känd: använd den dokumenterade transportörsidentifieraren när den stöds, särskilt när spårningsnummerformat överlappar.
- När transportören är okänd: använd automatisk identifiering endast genom den dokumenterade metoden. Anta inte att utelämnande, en tom sträng, noll och null betyder samma sak.
- När resultatet verkar fel: kontrollera originaletiketten, frakttjänsten och mappningen innan du registrerar samma nummer upprepade gånger.
Automatisk identifiering är användbar, men den är inte ett bevis på att en viss transportör fysiskt innehar försändelsen. På samma sätt garanterar en giltig transportörskod inte att det angivna spårningsnumret tillhör den transportören.
Håll transportörsmappningar konfigurerbara i stället för att sprida dem i applikationskoden. Registrera när en mappning senast kontrollerades och inkludera en känd försändelse i regressionstester när du ändrar den.
Exempel: skicka en 17TRACK-registreringsbegäran
Följande exempel visar 17TRACK v2.2-registreringsslutpunkten, autentiseringshuvudet 17token och en array som innehåller ett objekt med ett spårningsnummer. Bekräfta före driftsättning att denna version och dess begäranskrav överensstämmer med ditt konto och den officiella dokumentationen. Spårningsnumret är en platshållare och måste ersättas med en riktig försändelseidentifierare.
curl --request POST \
--url 'https://api.17track.net/track/v2.2/register' \
--header "17token: ${TRACKING_API_TOKEN}" \
--header 'Content-Type: application/json' \
--data '[
{
"number": "YOUR_TRACKING_NUMBER"
}
]'
Detta minimala exempel visar inte transportörsval eller transportörsspecifika kompletterande fält. Kontrollera registreringsdokumentationen för att avgöra hur transportörsidentifiering fungerar när transportörsfältet utelämnas och om din försändelse behöver ytterligare information. Om du anger en transportör ska du använda det dokumenterade fältet carrier och den identifierare som förväntas av den API-versionen.
Kör denna begäran från en servermiljö. Bädda inte in token i en offentlig butik, ett webbläsarskript eller en mobilapplikation som distribueras till kunder. En miljövariabel är praktisk i ett lokalt exempel; produktionsdistributioner bör använda organisationens kontroller för hemlighetshantering.
Testa en känd försändelse och granska hela svaret innan du ökar volymen. Testa sedan en ogiltig indata och en batch som innehåller både giltiga och ogiltiga objekt. Dessa kontroller visar om integrationen faktiskt hanterar resultat på objektnivå i stället för att bara känna igen ett HTTP-framgångssvar.
Läs svaret på tre nivåer
En tillförlitlig svarshanterare besvarar tre separata frågor: nådde begäran tjänsten, accepterade tjänsten åtgärden och vad hände med varje försändelse?
1. HTTP- och transportresultat
En anslutningstimeout, ett TLS-fel eller ett avbrutet svar talar inte nödvändigtvis om huruvida servern behandlade begäran. Markera resultatet som osäkert tills du kan stämma av det. En lyckad HTTP-status bekräftar ett lyckat HTTP-utbyte, men du måste fortfarande granska applikationssvaret.
2. Resultat på begäransnivå
Granska API:ts dokumenterade övergripande resultat- och fält för fel. Autentiseringsfel, felaktig JSON och kontobegränsningar kräver olika åtgärder. Spara leverantörens ursprungliga felkod och meddelande i stället för att reducera varje fel till ”spårning otillgänglig”.
Anta inte att en numerisk applikationskod har samma betydelse som en HTTP-statuskod. Deras betydelser kommer från olika lager och måste tolkas separat.
3. Resultat på försändelsenivå
Vid batchregistrering ska du ta hänsyn till varje inskickat objekt. Ett svar kan skilja mellan accepterade och avvisade försändelser; din parser bör följa det exakta schemat som dokumenterats för den valda versionen. Markera inte en hel batch som registrerad enbart för att ett objekt lyckades.
Normalisera leverantörssvar till dina egna stabila applikationstillstånd. Din databas kan till exempel använda accepted, rejected och uncertain. Detta är föreslagna interna tillstånd, inte bokstavliga 17TRACK-svarsvärden. Behåll leverantörens ursprungliga svar enligt en lämplig policy för lagring och åtkomst så att utvecklare kan undersöka avvikelser.
En användbar registreringspost innehåller internt försändelse-ID, inskickat nummer, transportörsval, försökstid, API-version, resultat och leverantörens feldetaljer. Håll registreringsstatus åtskild från leveransstatus.
Hantera omförsök utan att skapa en ändlös loop
Omförsökspolicyn bör bero på felet, inte enbart på om ett undantag inträffade.
- Ogiltig indata: korrigera fältet innan du försöker igen. Det är osannolikt att det hjälper att upprepa en oförändrad felaktig begäran.
- Autentiseringsfel: kontrollera autentiseringsuppgifter och kontokonfiguration. Undvik att upprepade gånger skicka samma felande batch.
- Hastighetsbegränsning: följ dokumenterade gränser och tillämpliga instruktioner för omförsök. Använd begränsad backoff i stället för omedelbara parallella omförsök.
- Tillfälligt tjänstefel: försök igen inom en definierad gräns för antal försök och tid.
- Timeout efter inskickning: stäm av försändelsens registreringsstatus med hjälp av dokumenterat API-beteende innan du antar att det första försöket misslyckades.
- Duplicatrelaterat svar: kontrollera om försändelsen redan är registrerad och korrekt kopplad till din applikationspost.
Anta inte att registreringen är idempotent om inte dokumentationen definierar detta beteende. Deduplikering på applikationssidan minskar oavsiktliga upprepade inskickningar, men fastställer inte leverantörens policy för hantering av dubbletter.
Använd en intern unikhetsregel som passar din försändelsemodell. Spårningsnumret ensamt kanske inte är en tillräcklig permanent nyckel för alla transportörer och långa lagringsperioder. Bevara transportörskontext och din egen försändelseidentifierare, och dokumentera hur ersättningar och korrigerade nummer hanteras.
Övervaka registrering separat från spårningsuppdateringar
API-övervakningen bör skilja ett integrationsfel från en försändelse som helt enkelt saknar en ny transportörshändelse. Dessa tillstånd kräver olika ansvariga och olika lösningar.
Vid registrering ska du övervaka antal accepterade och avvisade, felkategorier, osäkra resultat, kö för omförsök och svarslatens. För efterföljande spårning ska mottagnings- eller hämtningsfel för uppdateringar övervakas separat. Undvik att tilldela numeriska larmtrösklar innan du förstår normal trafik och leverantörens dokumenterade driftsgränser.
En praktisk produktionskontroll bör besvara följande:
- Har varje försändelse som väntar på spårning en registreringspost?
- Kan varje accepterad registrering spåras tillbaka till rätt paket?
- Dirigeras avvisade objekt till någon som kan korrigera de underliggande uppgifterna?
- Stäms osäkra begäranden av i stället för att överges eller försöka om på obestämd tid?
- Härleds kundsynliga statusar från försändelsehändelser och inte från att registreringen accepterats?
- Är autentiseringsuppgifter och onödig personlig information uteslutna från loggar?
För e-handelsverksamhet är det operativa överlämnandet lika viktigt som API-anropet. Utvecklare bör ansvara för transport- och tolkningsfel; frakt- eller leveransteamen bör kunna undersöka felaktiga etiketter, transportörsmappningar och saknad försändelseinformation.
Vanliga frågor
Kan jag registrera ett spårningsnummer före den första transportörsskanningen?
Registrering och transportörsskanningar är separata händelser. En tjänst kan acceptera ett nummer innan spårningshändelser är tillgängliga, beroende på dess valideringsregler. Tolka inte acceptans som ett bevis på att transportören har tagit emot paketet.
Måste jag alltid ange en transportörskod?
Det beror på API:ts dokumenterade identifieringsbeteende och den aktuella försändelsen. Om transportören är känd kan en uttrycklig, korrekt mappad identifierare minska tvetydighet. Om den är okänd ska du använda den dokumenterade metoden för automatisk identifiering i stället för att hitta på ett transportörsvärde.
Varför returnerade API:t HTTP-framgång medan en försändelse misslyckades?
HTTP-begäran kan lyckas samtidigt som applikationen avvisar ett enskilt objekt. Läs det övergripande applikationsresultatet och resultaten på försändelsenivå. Denna skillnad är särskilt viktig för batchbegäranden.
Vad ska jag göra när en registreringsbegäran får timeout?
Behandla resultatet som osäkert. Servern kan ha behandlat begäran innan anslutningen bröts. Kontrollera leverantörens dokumenterade dubblettbeteende och tillgängliga metoder för registrerings- eller spårningsuppslagning, och stäm sedan av eller försök igen enligt en begränsad policy.
Konfigurerar registrering automatiskt spårningsaviseringar?
Anta inte att den gör det. Registrering, hämtning av spårning och webhook-konfiguration är separata integrationsfrågor. Kontrollera relevant dokumentation och testa hela uppdateringsvägen innan du förlitar dig på den för kundaviseringar.
Källor
- 17TRACK API-dokumentation – referens för registreringsslutpunkter, autentisering, begäransfält, transportörsidentifierare, svarsscheman och felhantering. Anpassa implementeringsdetaljerna till den API-version du distribuerar.
- Översikt över 17TRACK Tracking API – officiell utgångspunkt för spårnings-API-produkten och resurser för utvecklarintegration.


