Skip to main content
HemBloggGuiderSå här hämtar du den senaste leveransstatusen via API utan att vänta på en webhook

Så här hämtar du den senaste leveransstatusen via API utan att vänta på en webhook

17TRACK

För att få den senast tillgängliga leveransstatusen utan att vänta på en webhook skickar du en autentiserad begäran till din spårningsleverantörs API för leveransfrågor. Använd svaret för att omedelbart uppdatera din applikation och låt sedan webhookar förbli aktiverade för efterföljande ändringar. Den viktiga skillnaden är att en fråga vanligtvis hämtar leverantörens senast lagrade spårningsinformation; den utlöser inte nödvändigtvis en ny kontroll hos transportören.

Så hämtar du den senaste leveransstatusen via API utan

Detta tillvägagångssätt är användbart när en kund öppnar en ordersida, när en supportmedarbetare behöver en uppdatering eller när ditt system behöver återhämta sig från en missad avisering. En tillförlitlig implementering kombinerar behovsbaserade frågor, tydliga indikatorer för aktualitet och skydd mot duplicerade eller felordnade uppdateringar.

Bestäm vad ”senaste leveransstatus” betyder

Innan du väljer en endpoint bör du skilja mellan tre åtgärder som kan låta likartade men ge olika resultat.

ÅtgärdVad den görVad den inte fastställer
Läs din egen databasReturnerar spårningsinformation som din applikation redan har.Om leverantören har tagit emot en nyare uppdatering.
Fråga spårnings-API:tHämtar information som är tillgänglig via leverantörens frågefunktion.Om en ny sökning hos transportören genomfördes under begäran.
Begär en uppdatering av spårningenBegär ytterligare en kontroll uppströms, om leverantören erbjuder den åtgärden.Att transportören har en ny skanning eller att uppdateringen slutförs synkront.

Använd en fråga när du behöver ett svar nu. Undersök en uppdateringsfunktion endast när du behöver att leverantören försöker göra ytterligare en kontroll uppströms. Anta inte att en cachebrytande parameter, en upprepad begäran eller en HTTP-header för cachekontroll tvingar en transportör att leverera ny information.

Leveranssynlighet omfattar flera steg: transportören registrerar en händelse, spårningsleverantören hämtar den och din applikation tar emot eller hämtar den. En direkt API-begäran kan kringgå väntan på aviseringens leverans, men den kan inte eliminera förseningar tidigare i kedjan.

Kontrollera frågekontraktet innan du skriver kod

Utvecklaren som integrerar spårningstjänsten ansvarar för detta arbetsflöde. Börja med leverantörens aktuella dokumentation, inte med en endpoint som kopierats från ett gammalt integrationsexempel. Bekräfta följande detaljer:

  • Leveransens identitet: Accepterar frågan ett spårningsnummer, ett internt leverans-ID eller ett spårningsnummer tillsammans med en transportörsidentifierare?
  • Registreringskrav: Måste leveransen registreras innan den kan efterfrågas?
  • Autentisering: Vilken header eller autentiseringsmekanism krävs?
  • Betydelsen av svaret: Returnerar åtgärden lagrad information, initierar den insamling eller returnerar den ett jobb som ska kontrolleras senare?
  • Resultathantering: Kan ett lyckat HTTP-svar innehålla ett fel på leveransnivå eller ett väntande resultat?
  • Användningsbegränsningar: Vilka hastighetsbegränsningar, batchbegränsningar och kontospecifika restriktioner gäller?
  • Fält för aktualitet: Vilka tidsstämplar representerar händelser hos transportören, uppdateringar hos leverantören och genereringen av svaret?

För en 17TRACK-integration är Tracking API den relevanta produkten, snarare än en konsumentsida för spårning eller ett gränssnitt för butiksspårning. Använd den officiella API-dokumentationen för att bekräfta åtgärden för frågning av spårningsinformation, autentisering, begärandefält och svarsstruktur för din integration. Hantera frågningar och webhookar som separata applikationsvägar som uppdaterar samma leveranspost.

Undvik att hårdkoda antaganden om uppdateringsbeteende eller frågefrekvens. Dessa detaljer måste stämma överens med den åtgärd och de tjänstevillkor du faktiskt använder.

Bygg en behovsbaserad sökning via din backend

En praktisk utformning är att exponera en autentiserad endpoint i din egen applikation. Webbläsaren begär en leveransuppdatering från denna endpoint; din server kontrollerar behörigheten, avgör om en fråga till leverantören behövs och returnerar ett normaliserat resultat.

Följande rutt är ett exempel på en endpoint som du skulle skapa i din applikation. Den är inte en 17TRACK-endpoint eller en specifikation för leverantörens begäran.

GET /api/orders/{order_id}/shipment-status

Använd orderidentifieraren för att slå upp leveransen på servern. Låt inte en anropare hämta en annan kunds spårningshistorik genom att helt enkelt ersätta ett spårningsnummer i en begäran. Förvara leverantörens API-autentiseringsuppgifter på din backend i stället för i JavaScript i webbläsaren eller i ett paket för en mobilapplikation.

Ett begärandeflöde du kan implementera

  1. Verifiera åtkomst. Bekräfta att kunden eller medarbetaren får se ordern.
  2. Identifiera leveransen. Läs det lagrade spårnings-ID:t och transportörsinformationen där det är tillämpligt.
  3. Kontrollera lokal aktualitet. Om en nylig lyckad fråga redan finns, återanvänd den enligt din applikations policy för aktualitet.
  4. Fråga leverantören vid behov. Använd den dokumenterade åtgärden och en begränsad tidsgräns för begäran.
  5. Validera resultatet. Kontrollera både HTTP-resultatet och resultatet på leveransnivå.
  6. Sammanfoga informationen. Tillämpa samma normaliserings- och avstämningsregler som används för webhookhändelser.
  7. Returnera status och aktualitet. Inkludera den senaste händelsetiden och tiden för den senaste lyckade kontrollen hos leverantören när den finns tillgänglig.

Den lokala policyn för aktualitet är ett tekniskt beslut, inte ett påstående om hur ofta transportören uppdaterar information. Välj den utifrån dina gränssnittskrav, leverantörens begränsningar, leveransvolymen och den observerade nyttan av frågor. En kund som upprepade gånger klickar på en uppdateringsknapp bör inte skapa en obegränsad ström av förfrågningar uppströms.

Normalisera svaret utan att hitta på aktualitet

Din applikation kan returnera ett stabilt internt format även när leverantörernas svarsstrukturer skiljer sig åt. Detta illustrativa objekt är ditt eget applikationskontrakt, inte en faktisk nyttolast från leverantören:

{
  "shipment_id": "internal-shipment-id",
  "status": "in_transit",
  "latest_event_at": null,
  "provider_updated_at": null,
  "last_successful_query_at": null,
  "retrieval_state": "success",
  "source": "provider_query"
}

Fyll endast i varje tidsstämpel när dess betydelse är känd. Tiden då din server tog emot ett svar hör till dina frågemetadata och får inte presenteras som tiden då paketet förflyttades. Om leverantören inte tillhandahåller en tidsstämpel för leverantörsuppdateringen ska du lämna fältet utelämnat eller null i stället för att ersätta det med en annan tidsstämpel.

I kundgränssnittet ska meddelandena skiljas åt: ”Senaste händelse hos transportören” beskriver leveransaktivitet, medan ”Spårning kontrollerad” beskriver din applikations hämtning. Denna åtskillnad förhindrar att en oförändrad skanning verkar vara nyregistrerad.

Förhindra att API-frågor och webhookar skriver över varandra

När båda mekanismerna är aktiva kan samma händelse komma via en fråga och en webhook. De kan också slutföras i en annan ordning än de startades. En fråga som startades först kan slutföras efter att en webhook redan har levererat nyare information.

Använd inte logik där det senast mottagna svaret vinner. Den senast mottagna nyttolasten är inte nödvändigtvis det senaste leveranstillståndet.

  • Dela en gemensam uppdateringspipeline. Skicka frågeresultat och webhooknyttolaster genom samma validerings-, normaliserings- och lagringsfunktioner.
  • Avduplicera händelser. Föredra en dokumenterad händelseidentifierare. Om ingen sådan finns, skapa ett noggrant definierat fingeravtryck från tillgängliga fält som händelsetid, status, plats och beskrivning.
  • Använd ordningsfält med känd semantik. En dokumenterad revision eller sekvens är mer användbar än att anta att ankomsttiden representerar händelseordningen.
  • Bevara historiken. En nyss mottagen händelse kan fylla en lucka i historiken utan att ändra den aktuella leveransöversikten.
  • Tillåt korrigeringar. Statusar utgör inte en universellt linjär stege. Följ det dokumenterade korrigeringsbeteendet i stället för att permanent avvisa varje uppenbar bakåtövergång.

När händelseordningen är osäker ska du behålla den ursprungliga nyttolasten och dess ursprung för undersökning. Lös inte tvetydigheter genom att skapa en händelsetidsstämpel eller anta att alla tidsstämplar från transportörer använder samma tidszon.

Hantera saknade uppgifter och misslyckade begäranden på olika sätt

Ett tomt resultat, ett oförändrat resultat och en misslyckad begäran bör inte leda till samma kundmeddelande.

Frågan lyckas men statusen har inte ändrats

Behåll den befintliga leveransstatusen och uppdatera tiden för den senaste lyckade frågan. Skapa inte en ny leveranshändelse enbart för att en ny sökning slutfördes. Om kunden behöver mer information visar du den befintliga händelsehistoriken och förklarar att ingen nyare spårningshändelse returnerades.

Leveransen har ännu ingen spårningsinformation

Kontrollera om registrering krävs, om identifieraren och transportören är korrekta och hur leverantören representerar väntande insamling. Avsaknad av händelser bevisar inte i sig att spårningsnumret är ogiltigt eller att paketet har gått förlorat. Bevara leverantörens åtskillnad mellan en okänd identifierare, en registrerad leverans som väntar på information och en begäran som inte kunde behandlas.

Leverantörens begäran överskrider tidsgränsen eller misslyckas

Om du har en tidigare giltig status ska du returnera den med en tydlig uppgift om att den senaste kontrollen inte lyckades. Låt tidsstämpeln för den tidigare lyckade frågan förbli oförändrad. Ett nätverksfel är inte ett leveransundantag och bör inte ändra paketets affärsstatus.

Använd begränsade återförsök med exponentiell fördröjning och jitter för lämpliga tillfälliga fel. Försök inte upprepade gånger med ogiltiga autentiseringsuppgifter eller felaktiga begäranden. När ett svar innehåller Retry-After ska du tolka det enligt leverantörens kontrakt och HTTP-semantik. HTTP-specifikationen tillåter att värdet anges som en fördröjning i sekunder eller som ett HTTP-datum.

Flera begäranden anländer för samma leverans

Samordna samtidiga sökningar så att de kan dela en enda begäran uppströms. Tillämpa begränsningar per konto och leverans och förhindra att ett automatiskt återförsök mångfaldigas över flera applikationslager. När batchbearbetning stöds ska du granska resultatet för varje leverans i stället för att behandla hela batchen som lyckad bara för att HTTP-begäran slutfördes.

Använd polling som en kontrollerad reservlösning

Utan webhookar kan schemalagd polling hålla din databas uppdaterad, men det kräver en tydlig driftpolicy. Bestäm vilka leveranser som fortfarande är aktuella, hur fel påverkar schemat och när rutinmässig polling ska upphöra.

För de flesta integrationer är en hybridutformning en rimlig utgångspunkt: webhookar hanterar bakgrundsändringar, behovsbaserade frågor hanterar interaktiva begäranden och avstämningsjobb kontrollerar poster som behöver uppmärksamhet. Detta är en arkitekturrekommendation, inte en garanti för att kostnaden minimeras för varje konto.

  • Prioritera aktiva leveranser och poster med olösta hämtningsfel.
  • Undvik att fråga efter varje historisk leverans vid varje schemalagd körning.
  • Definiera hur slutförda leveranser hanteras, inklusive eventuell korrigeringsperiod som verksamheten kräver.
  • Följ hur ofta frågor hittar verkligt ny information.
  • Undersök problem med webhookleveranser i stället för att dölja dem med allt tätare polling.

Övervaka leverantörens svarstid, misslyckade frågor, svar om hastighetsbegränsningar och skillnader mellan efterfrågade uppgifter och webhookmatade poster. Övervaka separat åldern på den senaste händelsen hos transportören. Lyckade API-svar kan förekomma samtidigt som spårningsinformationen inte har ändrats.

Testa arbetsflödet före lansering

En lyckad begäran är bara det första testet. Verifiera situationer som annars kan skapa missvisande statusuppdateringar:

  • En webhook anländer medan en behovsbaserad fråga fortfarande körs.
  • Två kunder eller medarbetarsessioner begär samma leverans samtidigt.
  • Leverantören returnerar HTTP-framgång men rapporterar ett fel på leveransnivå.
  • En begäran misslyckas efter att din applikation redan har giltig spårningsinformation.
  • En händelse saknar tidszon eller innehåller en obekant statuskod.
  • En korrigering hos transportören ändrar ett tidigare visat resultat.
  • En användare försöker få åtkomst till en leverans som tillhör ett annat konto.

Ditt lanseringskriterium bör vara att applikationen returnerar den bästa kända leveransinformationen, förklarar dess aktualitet korrekt och inte förstör informationen när begäranden misslyckas eller anländer i fel ordning.

Vanliga frågor

Tvingar en API-fråga transportören att skanna eller uppdatera ett paket?

Nej. Hämtning av spårningsinformation kan inte orsaka en fysisk skanning. Om en begäran utlöser en sökning uppströms beror på den dokumenterade åtgärden. Även en stödd uppdatering kan returnera oförändrad information om transportören inte har någon nyare händelse.

Kan jag använda API-frågor utan att konfigurera webhookar?

Om leverantören stöder det nödvändiga frågearbetsflödet kan du bygga en integration kring behovsbaserade begäranden eller polling. Bekräfta registrerings- och frågekraven först. Därefter ansvarar din applikation för att avgöra när den ska kontrollera, begränsa begärandevolymen och upptäcka ändringar.

Hur ofta bör jag polla leveransstatus?

Det finns inget universellt intervall. Välj ett schema som passar leverantörens begränsningar, din leveransvolym och affärsvärdet av att hitta uppdateringar tidigare. Mät hur ofta polling returnerar nya händelser och justera sedan, i stället för att anta att frekventa begäranden ger färskare data från transportören.

Varför returnerar API:t information som jag redan har fått via en webhook?

Båda vägarna kan exponera samma underliggande leveranspost. En webhook levererar en avisering, medan en fråga hämtar information på begäran. Att ta emot samma händelse via båda är inte nödvändigtvis ett fel; din applikation bör avduplicera den.

Bör uppdateringsknappen säga ”Uppdatera spårning”?

Endast om formuleringen korrekt beskriver åtgärden. Om knappen hämtar lagrade leverantörsuppgifter är ”Kontrollera uppdateringar” tydligare. Visa den senaste händelsen hos transportören separat från tiden då din applikation senast slutförde en lyckad kontroll.

Källor