Skip to main content
HomeBlogGidsenHoe u de nieuwste verzendstatus via de API kunt ophalen zonder op een webhook te wachten

Hoe u de nieuwste verzendstatus via de API kunt ophalen zonder op een webhook te wachten

17TRACK

Om de laatst beschikbare verzendstatus te verkrijgen zonder op een webhook te wachten, stuurt u een geauthenticeerd verzoek naar de shipment-query-API van uw trackingprovider. Gebruik het antwoord om uw applicatie onmiddellijk bij te werken en houd webhooks vervolgens ingeschakeld voor volgende wijzigingen. Het belangrijke onderscheid is dat een query doorgaans de laatst opgeslagen trackinginformatie van de provider ophaalt; dit activeert niet noodzakelijkerwijs een nieuwe controle bij de vervoerder.

Hoe u via API de nieuwste verzendstatus verkrijgt zonder

Deze aanpak is nuttig wanneer een klant een bestelpagina opent, een supportmedewerker een update nodig heeft of uw systeem moet herstellen van een gemiste melding. Een betrouwbare implementatie combineert on-demand-query's, duidelijke versheidsindicatoren en beveiligingen tegen dubbele of niet in de juiste volgorde ontvangen updates.

Bepaal wat “laatste verzendstatus” betekent

Voordat u een endpoint kiest, moet u onderscheid maken tussen drie bewerkingen die vergelijkbaar kunnen klinken, maar verschillende resultaten opleveren.

BewerkingWat deze doetWat deze niet vaststelt
Uw eigen database lezenRetourneert trackinginformatie die uw applicatie al bevat.Of de provider een nieuwere update heeft ontvangen.
De tracking-API opvragenHaalt informatie op die beschikbaar is via de querybewerking van de provider.Of er tijdens dat verzoek een nieuwe lookup bij de vervoerder heeft plaatsgevonden.
Een trackingvernieuwing aanvragenVraagt een nieuwe controle upstream aan, als de provider die bewerking aanbiedt.Dat de vervoerder een nieuwe scan heeft of dat de vernieuwing synchroon wordt voltooid.

Gebruik een query wanneer u nu een antwoord nodig hebt. Onderzoek een vernieuwing alleen wanneer u wilt dat de provider opnieuw upstream controleert. Ga er niet van uit dat het toevoegen van een cache-bustingparameter, het herhalen van een verzoek of het verzenden van een HTTP-cache-controlheader een vervoerder ertoe dwingt nieuwe informatie te leveren.

De zichtbaarheid van een zending kent verschillende fasen: de vervoerder registreert een gebeurtenis, de trackingprovider verkrijgt deze en uw applicatie ontvangt of haalt deze op. Een rechtstreeks API-verzoek kan het wachten op de bezorging van een melding omzeilen, maar kan vertragingen eerder in die keten niet elimineren.

Controleer het querycontract voordat u code schrijft

De ontwikkelaar die de trackingservice integreert, beheert deze workflow. Begin met de actuele documentatie van de provider, niet met een endpoint dat uit een oud integratievoorbeeld is gekopieerd. Controleer deze details:

  • Identiteit van de zending: Accepteert de query een trackingnummer, een interne shipment-ID of een trackingnummer gecombineerd met een vervoerders-ID?
  • Registratievereisten: Moet de zending worden geregistreerd voordat deze kan worden opgevraagd?
  • Authenticatie: Welke header of welk authenticatiemechanisme is vereist?
  • Betekenis van het antwoord: Retourneert de bewerking opgeslagen informatie, start deze gegevensverzameling of retourneert deze een taak die later moet worden gecontroleerd?
  • Verwerking van resultaten: Kan een succesvolle HTTP-respons een fout op zendingniveau of een resultaat in behandeling bevatten?
  • Gebruiksbeperkingen: Welke snelheidslimieten, batchlimieten en accountspecifieke beperkingen zijn van toepassing?
  • Versheidsvelden: Welke tijdstempels vertegenwoordigen gebeurtenissen bij de vervoerder, updates van de provider en het genereren van de respons?

Voor een 17TRACK-integratie is de Tracking API het relevante product, en niet een trackingpagina voor consumenten of een trackinginterface van een storefront. Gebruik de officiële API-documentatie om de querybewerking voor trackinginformatie, authenticatie, aanvraagvelden en responsstructuur voor uw integratie te bevestigen. Behandel query's en webhookverwerking als afzonderlijke applicatiepaden die hetzelfde zendingrecord bijwerken.

Vermijd het hardcoderen van aannames over vernieuwingsgedrag of queryfrequentie. Die details moeten overeenkomen met de bewerking en servicevoorwaarden die u daadwerkelijk gebruikt.

Bouw een on-demand-lookup via uw backend

Een praktisch ontwerp is om een geauthenticeerd endpoint in uw eigen applicatie beschikbaar te stellen. De browser vraagt via dat endpoint een zendingupdate op; uw server controleert de autorisatie, bepaalt of een query bij de provider nodig is en retourneert een genormaliseerd resultaat.

De volgende route is een voorbeeld van een endpoint dat u in uw applicatie zou maken. Het is geen 17TRACK-endpoint of providerspecificatie voor verzoeken.

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

Gebruik de orderidentificatie om de zending op de server op te zoeken. Zorg ervoor dat een aanroeper niet simpelweg door een trackingnummer in een verzoek te vervangen de trackinggeschiedenis van een andere klant kan ophalen. Bewaar de API-inloggegevens van de provider op uw backend, niet in JavaScript van de browser of in een mobiele applicatiebundle.

Een verzoekstroom die u kunt implementeren

  1. Autoriseer de toegang. Bevestig dat de klant of medewerker de bestelling mag bekijken.
  2. Identificeer de zending. Lees de opgeslagen trackingidentificatie en vervoerdersinformatie, indien van toepassing.
  3. Controleer de lokale versheid. Als er al een recente succesvolle query bestaat, gebruik deze dan opnieuw volgens het versheidsbeleid van uw applicatie.
  4. Vraag de provider op wanneer dat nodig is. Gebruik de gedocumenteerde bewerking en een begrensde time-out voor het verzoek.
  5. Valideer het resultaat. Controleer zowel de HTTP-uitkomst als het resultaat op zendingniveau.
  6. Voeg de informatie samen. Pas dezelfde normalisatie- en reconciliatieregels toe als voor webhookgebeurtenissen.
  7. Retourneer status en versheid. Voeg indien beschikbaar het tijdstip van de laatste gebeurtenis en het tijdstip van de laatste succesvolle controle bij de provider toe.

Het lokale versheidsbeleid is een technische beslissing, geen uitspraak over de frequentie van updates door de vervoerder. Kies dit beleid op basis van uw interfacevereisten, providerlimieten, verzendvolume en de vastgestelde bruikbaarheid van query's. Een klant die herhaaldelijk op een updateknop klikt, mag geen onbeperkte stroom upstream-verzoeken veroorzaken.

Normaliseer de respons zonder versheid te verzinnen

Uw applicatie kan een stabiel intern formaat retourneren, ook wanneer de responsstructuren van providers verschillen. Dit illustratieve object is uw eigen applicatiecontract en geen echte payload van een provider:

{
  "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"
}

Vul elke tijdstempel alleen in wanneer de betekenis ervan bekend is. Het tijdstip waarop uw server een respons ontving, hoort in uw querymetadata; dit mag niet worden gepresenteerd als het tijdstip waarop het pakket zich verplaatste. Als de provider geen tijdstempel voor de update van de provider verstrekt, laat u dat veld weg of stelt u het in op null in plaats van een andere tijdstempel te gebruiken.

Maak voor de klantinterface onderscheid tussen de meldingen: “Laatste gebeurtenis bij de vervoerder” beschrijft de activiteit van de zending, terwijl “Tracking gecontroleerd” de ophaalactiviteit van uw applicatie beschrijft. Dit onderscheid voorkomt dat een ongewijzigde scan als nieuw geregistreerd lijkt.

Voorkom dat API-query's en webhooks elkaar overschrijven

Zodra beide mechanismen actief zijn, kan dezelfde gebeurtenis via een query en een webhook binnenkomen. Ze kunnen ook in een andere volgorde worden voltooid dan waarin ze zijn gestart. Een query die eerst is gestart, kan worden voltooid nadat een webhook al nieuwere informatie heeft geleverd.

Gebruik geen logica waarbij de laatste respons wint. De meest recent ontvangen payload is niet noodzakelijkerwijs de meest recente verzendstatus.

  • Gebruik één updatepipeline. Stuur queryresultaten en webhookpayloads door dezelfde validatie-, normalisatie- en persistentiefuncties.
  • Dedupliceer gebeurtenissen. Geef de voorkeur aan een gedocumenteerde gebeurtenisidentificatie. Als die ontbreekt, maakt u een zorgvuldig gedefinieerde fingerprint op basis van beschikbare velden, zoals tijdstip van de gebeurtenis, status, locatie en beschrijving.
  • Gebruik volgordevelden met een bekende betekenis. Een gedocumenteerde revisie of sequentie is nuttiger dan aannemen dat de aankomsttijd de volgorde van gebeurtenissen weergeeft.
  • Behoud de geschiedenis. Een nieuw ontvangen gebeurtenis kan een historisch gat opvullen zonder het huidige verzendoverzicht te wijzigen.
  • Sta correcties toe. Statussen vormen geen universele lineaire ladder. Volg het gedocumenteerde correctiegedrag in plaats van elke schijnbare achterwaartse overgang permanent af te wijzen.

Wanneer de volgorde van gebeurtenissen onzeker is, bewaart u de oorspronkelijke payload en de herkomst ervan voor onderzoek. Los onduidelijkheid niet op door een tijdstempel voor een gebeurtenis te verzinnen of aan te nemen dat alle tijdstempels van vervoerders dezelfde tijdzone gebruiken.

Behandel ontbrekende gegevens en mislukte verzoeken verschillend

Een leeg resultaat, een ongewijzigd resultaat en een mislukt verzoek mogen niet dezelfde klantmelding opleveren.

De query slaagt, maar de status is niet gewijzigd

Behoud de bestaande verzendstatus en werk het tijdstip van de laatste succesvolle query bij. Genereer geen nieuwe verzendgebeurtenis alleen omdat een nieuwe lookup is voltooid. Als de klant meer details nodig heeft, toont u de bestaande gebeurtenisgeschiedenis en legt u uit dat er geen nieuwere trackinggebeurtenis is geretourneerd.

De zending bevat nog geen trackinginformatie

Controleer of registratie vereist is, of de identificatie en vervoerder correct zijn en hoe de provider wachtende gegevensverzameling weergeeft. Het ontbreken van gebeurtenissen bewijst op zichzelf niet dat het trackingnummer ongeldig is of dat het pakket verloren is gegaan. Behoud het onderscheid dat de provider maakt tussen een onbekende identificatie, een geregistreerde zending die op informatie wacht en een verzoek dat niet kon worden verwerkt.

Het verzoek aan de provider verloopt zonder antwoord of mislukt

Als u een eerdere geldige status hebt, retourneert u die met een expliciete aanduiding dat de laatste controle niet is geslaagd. Laat het tijdstip van de eerdere succesvolle query ongewijzigd. Een netwerkfout is geen leveringsuitzondering en mag de bedrijfsstatus van het pakket niet wijzigen.

Gebruik begrensde retries met backoff en jitter voor geschikte tijdelijke fouten. Herhaal verzoeken met ongeldige inloggegevens of een onjuiste indeling niet steeds opnieuw. Wanneer een respons Retry-After bevat, interpreteert u deze volgens het contract van de provider en de HTTP-semantiek. De HTTP-specificatie staat toe dat deze waarde wordt uitgedrukt als een vertraging in seconden of als een HTTP-datum.

Er komen meerdere verzoeken binnen voor dezelfde zending

Voeg gelijktijdige lookups samen zodat ze één upstream-verzoek kunnen delen. Pas limieten toe per account en zending en voorkom dat een automatische retry zich over meerdere applicatielagen vermenigvuldigt. Wanneer batching wordt ondersteund, controleert u het resultaat van elke zending afzonderlijk in plaats van de hele batch als geslaagd te beschouwen omdat het HTTP-verzoek is voltooid.

Gebruik polling als gecontroleerde fallback

Zonder webhooks kan geplande polling uw database bijgewerkt houden, maar daarvoor is expliciet operationeel beleid nodig. Bepaal welke zendingen in aanmerking blijven komen, hoe fouten het schema beïnvloeden en wanneer routinematige polling stopt.

Voor de meeste integraties is een hybride ontwerp een verstandig uitgangspunt: webhooks verwerken achtergrondwijzigingen, on-demand-query's bedienen interactieve verzoeken en reconciliatietaken controleren records die aandacht nodig hebben. Dit is een architectuuraanbeveling, geen garantie dat de kosten voor elk account worden geminimaliseerd.

  • Geef prioriteit aan actieve zendingen en records met onopgeloste ophaalfouten.
  • Vermijd het opvragen van elke historische zending bij elke geplande uitvoering.
  • Bepaal hoe voltooide zendingen worden verwerkt, inclusief eventuele correctieperiode die uw bedrijf vereist.
  • Houd bij hoe vaak query's daadwerkelijk nieuwe informatie opleveren.
  • Onderzoek problemen met webhookbezorging in plaats van deze te verbergen met steeds frequentere polling.

Monitor de latentie van verzoeken aan de provider, mislukte query's, reacties wegens snelheidslimieten en verschillen tussen opgevraagde gegevens en records die via webhooks zijn gevuld. Monitor afzonderlijk de ouderdom van de laatste gebeurtenis bij de vervoerder. Succesvolle API-responsen kunnen samengaan met trackinginformatie die niet is gewijzigd.

Test de workflow vóór release

Een geslaagd verzoek is slechts de eerste test. Controleer de situaties die anders misleidende statusupdates kunnen veroorzaken:

  • Er komt een webhook binnen terwijl een on-demand-query nog wordt uitgevoerd.
  • Twee klanten of medewerkers vragen tegelijkertijd dezelfde zending op.
  • De provider retourneert HTTP-succes, maar meldt een fout op zendingniveau.
  • Een verzoek mislukt nadat uw applicatie al geldige trackinginformatie bevat.
  • Een gebeurtenis bevat geen tijdzone of bevat een onbekende statuscode.
  • Een correctie door de vervoerder wijzigt een eerder weergegeven resultaat.
  • Een gebruiker probeert toegang te krijgen tot een zending die bij een ander account hoort.

Uw releasecriterium moet zijn dat de applicatie de best bekende verzendinformatie retourneert, de versheid ervan nauwkeurig uitlegt en deze informatie niet beschadigt wanneer verzoeken mislukken of in een andere volgorde binnenkomen.

Veelgestelde vragen

Dwingt het opvragen van de API de vervoerder om een pakket te scannen of bij te werken?

Nee. Het ophalen van trackinginformatie kan geen fysieke scan veroorzaken. Of een verzoek een upstream-lookup activeert, hangt af van de gedocumenteerde bewerking. Zelfs een ondersteunde vernieuwing kan ongewijzigde informatie retourneren als de vervoerder geen nieuwere gebeurtenis heeft.

Kan ik API-query's gebruiken zonder webhooks te configureren?

Als de provider de vereiste queryworkflow ondersteunt, kunt u een integratie bouwen rond on-demand-verzoeken of polling. Bevestig eerst de registratie- en queryvereisten. Uw applicatie is dan verantwoordelijk voor het bepalen wanneer er wordt gecontroleerd, het beheren van het verzoekvolume en het detecteren van wijzigingen.

Hoe vaak moet ik de verzendstatus pollen?

Er bestaat geen universeel interval. Kies een schema dat past bij de limieten van uw provider, uw verzendvolume en de bedrijfswaarde van het eerder vinden van updates. Meet hoe vaak polling nieuwe gebeurtenissen retourneert en pas het schema vervolgens aan, in plaats van aan te nemen dat frequente verzoeken versere gegevens van de vervoerder opleveren.

Waarom retourneert de API informatie die ik al via een webhook heb ontvangen?

Beide paden kunnen hetzelfde onderliggende zendingrecord beschikbaar maken. Een webhook levert een melding, terwijl een query informatie on demand ophaalt. Het ontvangen van dezelfde gebeurtenis via beide paden is niet noodzakelijkerwijs een fout; uw applicatie moet deze dedupliceren.

Moet de updateknop “Tracking vernieuwen” heten?

Alleen als die formulering de bewerking nauwkeurig beschrijft. Als de knop opgeslagen gegevens van de provider ophaalt, is “Controleren op updates” duidelijker. Toon de laatste gebeurtenis bij de vervoerder afzonderlijk van het tijdstip waarop uw applicatie voor het laatst een succesvolle controle heeft voltooid.

Bronnen