Slik får du siste forsendelsesstatus via API uten å vente på en webhook
For å få den nyeste tilgjengelige forsendelsesstatusen uten å vente på en webhook, sender du en autentisert forespørsel til sporingsleverandørens API for forespørsler om forsendelser. Bruk svaret til å oppdatere applikasjonen umiddelbart, og la deretter webhook-er være aktivert for påfølgende endringer. Det viktige skillet er at en forespørsel vanligvis henter leverandørens sist lagrede sporingsinformasjon; den utløser ikke nødvendigvis en ny kontroll hos transportøren.

Denne metoden er nyttig når en kunde åpner en bestillingsside, en kundestøtteagent trenger en oppdatering, eller systemet må gjenopprettes etter et tapt varsel. En pålitelig implementering kombinerer forespørsler ved behov, tydelige indikatorer for aktualitet og beskyttelse mot duplikate eller feilordnede oppdateringer.
Bestem hva «nyeste forsendelsesstatus» betyr
Før du velger et endepunkt, må du skille mellom tre operasjoner som kan høres like ut, men som gir ulike resultater.
| Operasjon | Hva den gjør | Hva den ikke fastslår |
|---|---|---|
| Les din egen database | Returnerer sporingsinformasjonen applikasjonen allerede har. | Om leverandøren har mottatt en nyere oppdatering. |
| Send forespørsel til sporings-API-et | Henter informasjon som er tilgjengelig gjennom leverandørens forespørselsoperasjon. | Om en ny kontroll hos transportøren fant sted under forespørselen. |
| Be om oppdatering av sporing | Ber om en ny kontroll oppstrøms, dersom leverandøren tilbyr denne operasjonen. | At transportøren har en ny skanning, eller at oppdateringen fullføres synkront. |
Bruk en forespørsel når du trenger et svar nå. Undersøk en oppdateringsoperasjon bare når du trenger at leverandøren forsøker en ny kontroll oppstrøms. Ikke anta at en parameter som omgår hurtigbufferen, gjentakelse av en forespørsel eller en HTTP-cache-control-header tvinger transportøren til å levere ny informasjon.
Synligheten for en forsendelse har flere trinn: transportøren registrerer en hendelse, sporingsleverandøren henter den, og applikasjonen mottar eller henter den. En direkte API-forespørsel kan omgå ventetiden for levering av varsler, men kan ikke eliminere forsinkelser tidligere i denne kjeden.
Kontroller forespørselskontrakten før du skriver kode
Utvikleren som integrerer sporingstjenesten, har ansvaret for denne arbeidsflyten. Start med leverandørens gjeldende dokumentasjon, ikke et endepunkt kopiert fra et gammelt integrasjonseksempel. Bekreft disse detaljene:
- Forsendelsesidentitet: Godtar forespørselen et sporingsnummer, en intern forsendelses-ID eller et sporingsnummer kombinert med en transportør-ID?
- Registreringskrav: Må forsendelsen registreres før den kan forespørres?
- Autentisering: Hvilken header eller autentiseringsmekanisme kreves?
- Betydningen av svaret: Returnerer operasjonen lagret informasjon, starter den innhenting, eller returnerer den en jobb som skal kontrolleres senere?
- Resultatbehandling: Kan et vellykket HTTP-svar inneholde en feil på forsendelsesnivå eller et ventende resultat?
- Bruksbegrensninger: Hvilke begrensninger for forespørselsfrekvens, batch-størrelse og konto gjelder?
- Felt for aktualitet: Hvilke tidsstempler representerer hendelser hos transportøren, oppdateringer fra leverandøren og generering av svaret?
For en 17TRACK-integrasjon er Tracking API det relevante produktet, ikke en forbrukersporingsside eller et sporingsgrensesnitt i en nettbutikk. Bruk den offisielle API-dokumentasjonen for å bekrefte operasjonen for forespørsler om sporingsinformasjon, autentisering, forespørselsfelt og svarstruktur for integrasjonen. Behandle forespørsler og webhook-håndtering som separate applikasjonsbaner som oppdaterer den samme forsendelsesposten.
Unngå å hardkode antakelser om oppdateringsatferd eller forespørselsfrekvens. Disse detaljene må samsvare med operasjonen og tjenestevilkårene du faktisk bruker.
Bygg et oppslag ved behov gjennom backend-laget ditt
Et praktisk design er å eksponere et autentisert endepunkt i din egen applikasjon. Nettleseren ber dette endepunktet om en forsendelsesoppdatering; serveren kontrollerer autorisasjonen, avgjør om en leverandørforespørsel er nødvendig, og returnerer et normalisert resultat.
Følgende rute er et eksempel på et endepunkt du oppretter i applikasjonen. Det er ikke et 17TRACK-endepunkt eller en spesifikasjon for leverandørforespørsler.
GET /api/orders/{order_id}/shipment-statusBruk bestillingsidentifikatoren til å slå opp forsendelsen på serveren. Ikke la en bruker hente en annen kundes sporingshistorikk bare ved å erstatte et sporingsnummer i en forespørsel. Oppbevar leverandørens API-legitimasjon på backend-laget, ikke i JavaScript i nettleseren eller i en mobilapplikasjonspakke.
En forespørselsflyt du kan implementere
- Autoriser tilgang. Bekreft at kunden eller medarbeideren har tillatelse til å se bestillingen.
- Finn forsendelsen. Les det lagrede sporingsnummeret og transportørinformasjonen, der det er relevant.
- Kontroller lokal aktualitet. Hvis det allerede finnes en nylig vellykket forespørsel, bruker du den på nytt i henhold til applikasjonens policy for aktualitet.
- Send forespørsel til leverandøren ved behov. Bruk den dokumenterte operasjonen og en begrenset tidsavbruddsverdi.
- Valider resultatet. Kontroller både HTTP-resultatet og resultatet på forsendelsesnivå.
- Slå sammen informasjonen. Bruk de samme reglene for normalisering og avstemming som for webhook-hendelser.
- Returner status og aktualitet. Inkluder tidspunktet for den nyeste hendelsen og tidspunktet for den siste vellykkede kontrollen hos leverandøren når dette er tilgjengelig.
Den lokale policyen for aktualitet er en teknisk beslutning, ikke en uttalelse om hvor ofte transportøren oppdaterer informasjon. Velg den ut fra kravene til grensesnittet, leverandørens begrensninger, forsendelsesvolumet og den observerte nytteverdien av forespørsler. En kunde som gjentatte ganger klikker på en oppdateringsknapp, bør ikke kunne opprette en ubegrenset strøm av forespørsler oppstrøms.
Normaliser svaret uten å finne på aktualitet
Applikasjonen kan returnere et stabilt internt format selv når leverandørenes svarstrukturer varierer. Dette illustrerende objektet er din egen applikasjonskontrakt, ikke en faktisk leverandørpayload:
{
"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 bare ut hvert tidsstempel når betydningen er kjent. Tidspunktet da serveren mottok et svar, hører hjemme i metadataene for forespørselen; det må ikke presenteres som tidspunktet da pakken beveget seg. Hvis leverandøren ikke oppgir et tidsstempel for leverandøroppdatering, lar du feltet være fraværende eller null i stedet for å erstatte det med et annet tidsstempel.
For kundegrensesnittet bør du skille mellom meldingene: «Siste hendelse hos transportøren» beskriver aktivitet for forsendelsen, mens «Sporing kontrollert» beskriver applikasjonens aktivitet med å hente informasjon. Dette skillet hindrer at en uendret skanning ser ut som om den nettopp er registrert.
Hindre at API-forespørsler og webhook-er overskriver hverandre
Når begge mekanismene er aktive, kan den samme hendelsen komme inn gjennom en forespørsel og en webhook. De kan også fullføres i en annen rekkefølge enn de ble startet. En forespørsel som ble startet først, kan fullføres etter at en webhook allerede har levert nyere informasjon.
Ikke bruk logikk der det siste svaret vinner. Payloaden som mottas sist, er ikke nødvendigvis den nyeste tilstanden for forsendelsen.
- Bruk én felles oppdateringspipeline. Send resultater fra forespørsler og webhook-payloads gjennom de samme funksjonene for validering, normalisering og lagring.
- Fjern duplikate hendelser. Foretrekk en dokumentert hendelses-ID. Hvis ingen finnes, bygger du et nøye definert fingeravtrykk fra tilgjengelige felt som hendelsestidspunkt, status, sted og beskrivelse.
- Bruk ordrefelt med kjent betydning. En dokumentert revisjon eller sekvens er mer nyttig enn å anta at mottakstidspunktet representerer hendelsesrekkefølgen.
- Bevar historikken. En nylig mottatt hendelse kan fylle et historisk hull uten å endre det nåværende sammendraget for forsendelsen.
- Tillat korrigeringer. Statuser utgjør ikke en universell lineær stige. Følg dokumentert korrigeringsatferd i stedet for permanent å avvise enhver tilsynelatende tilbakesprang.
Når hendelsesrekkefølgen er usikker, beholder du den opprinnelige payloaden og opprinnelsen for videre undersøkelser. Ikke løse tvetydighet ved å finne på et hendelsestidsstempel eller anta at alle tidsstempler fra transportøren bruker samme tidssone.
Behandle manglende data og mislykkede forespørsler forskjellig
Et tomt resultat, et uendret resultat og en mislykket forespørsel bør ikke føre til samme melding til kunden.
Forespørselen lykkes, men statusen er ikke endret
Behold den eksisterende forsendelsesstatusen og oppdater tidspunktet for den siste vellykkede forespørselen. Ikke opprett en ny forsendelseshendelse bare fordi et nytt oppslag ble fullført. Hvis kunden trenger mer informasjon, viser du den eksisterende hendelseshistorikken og forklarer at ingen nyere sporingshendelse ble returnert.
Forsendelsen har ingen sporingsinformasjon ennå
Kontroller om registrering kreves, om identifikatoren og transportøren er riktige, og hvordan leverandøren representerer ventende innhenting. Fravær av hendelser beviser ikke i seg selv at sporingsnummeret er ugyldig eller at pakken er tapt. Bevar leverandørens skille mellom en ukjent identifikator, en registrert forsendelse som venter på informasjon, og en forespørsel som ikke kunne behandles.
Leverandørforespørselen får tidsavbrudd eller mislykkes
Hvis du har en tidligere gyldig status, returnerer du den med en tydelig indikasjon på at den siste kontrollen ikke lyktes. La tidspunktet for den tidligere vellykkede forespørselen stå uendret. En nettverksfeil er ikke et leveringsavvik og bør ikke endre pakkens forretningsstatus.
Bruk begrensede nye forsøk med tilbakeslag og tilfeldig variasjon ved passende midlertidige feil. Ikke gjenta forsøk på ugyldig legitimasjon eller feilformede forespørsler. Når et svar inneholder Retry-After, tolker du det i henhold til leverandørens kontrakt og HTTP-semantikk. HTTP-spesifikasjonen tillater at verdien uttrykkes som en forsinkelse i sekunder eller som en HTTP-dato.
Flere forespørsler kommer for samme forsendelse
Slå sammen samtidige oppslag slik at de kan dele én forespørsel oppstrøms. Bruk begrensninger per konto og forsendelse, og hindre at et automatisk nytt forsøk multipliseres på tvers av flere applikasjonslag. Når batch-behandling støttes, må du kontrollere resultatet for hver forsendelse i stedet for å behandle hele batchen som vellykket fordi HTTP-forespørselen ble fullført.
Bruk polling som en kontrollert reserveløsning
Uten webhook-er kan planlagt polling holde databasen oppdatert, men dette krever en tydelig driftspolicy. Bestem hvilke forsendelser som fortsatt er aktuelle, hvordan feil påvirker planen, og når rutinemessig polling skal stoppe.
For de fleste integrasjoner er et hybriddesign et fornuftig utgangspunkt: webhook-er håndterer endringer i bakgrunnen, forespørsler ved behov betjener interaktive forespørsler, og avstemmingsjobber kontrollerer poster som trenger oppmerksomhet. Dette er en arkitekturanbefaling, ikke en garanti for at kostnadene minimeres for alle kontoer.
- Prioriter aktive forsendelser og poster med uløste feil ved innhenting.
- Unngå å forespørre alle historiske forsendelser ved hver planlagte kjøring.
- Definer hvordan fullførte forsendelser skal håndteres, inkludert eventuelle korrigeringsperioder virksomheten din krever.
- Følg med på hvor ofte forespørsler faktisk finner ny informasjon.
- Undersøk problemer med levering av webhook-er i stedet for å skjule dem med stadig hyppigere polling.
Overvåk ventetid for leverandørforespørsler, mislykkede forespørsler, svar på begrensninger og forskjeller mellom data fra forespørsler og poster som er oppdatert via webhook. Overvåk separat alderen på den nyeste hendelsen hos transportøren. Vellykkede API-svar kan forekomme samtidig som sporingsinformasjonen ikke er endret.
Test arbeidsflyten før lansering
En vellykket forespørsel er bare den første testen. Bekreft situasjonene som ellers kan skape villedende statusoppdateringer:
- En webhook kommer inn mens en forespørsel ved behov fortsatt kjører.
- To kunder eller medarbeiderøkter ber om samme forsendelse samtidig.
- Leverandøren returnerer HTTP-suksess, men rapporterer en feil på forsendelsesnivå.
- En forespørsel mislykkes etter at applikasjonen allerede har gyldig sporingsinformasjon.
- En hendelse mangler tidssone eller inneholder en ukjent statuskode.
- En korrigering fra transportøren endrer et tidligere vist resultat.
- En bruker forsøker å få tilgang til en forsendelse som tilhører en annen konto.
Lanseringskriteriet bør være at applikasjonen returnerer den best kjente informasjonen om forsendelsen, forklarer aktualiteten nøyaktig og ikke ødelegger denne informasjonen når forespørsler mislykkes eller kommer i feil rekkefølge.
Vanlige spørsmål
Tvinger et API-oppslag transportøren til å skanne eller oppdatere en pakke?
Nei. Det å hente sporingsinformasjon kan ikke føre til en fysisk skanning. Om en forespørsel utløser et oppslag oppstrøms, avhenger av den dokumenterte operasjonen. Selv en støttet oppdatering kan returnere uendret informasjon hvis transportøren ikke har noen nyere hendelse.
Kan jeg bruke API-forespørsler uten å konfigurere webhook-er?
Hvis leverandøren støtter den nødvendige arbeidsflyten for forespørsler, kan du bygge en integrasjon rundt forespørsler ved behov eller polling. Bekreft kravene til registrering og forespørsler først. Deretter er applikasjonen din ansvarlig for å avgjøre når den skal kontrollere, begrense forespørselsvolumet og oppdage endringer.
Hvor ofte bør jeg hente forsendelsesstatus med polling?
Det finnes ikke ett universelt intervall. Velg en tidsplan som passer leverandørens begrensninger, forsendelsesvolumet ditt og forretningsverdien av å finne oppdateringer tidligere. Mål hvor ofte polling returnerer nye hendelser, og juster deretter i stedet for å anta at hyppige forespørsler gir ferskere data fra transportøren.
Hvorfor returnerer API-et informasjon jeg allerede mottok via en webhook?
Begge banene kan vise til den samme underliggende forsendelsesposten. En webhook leverer et varsel, mens en forespørsel henter informasjon ved behov. At den samme hendelsen mottas gjennom begge, er ikke nødvendigvis en feil; applikasjonen bør fjerne duplikatet.
Bør oppdateringsknappen hete «Oppdater sporing»?
Bare hvis denne formuleringen beskriver operasjonen nøyaktig. Hvis knappen henter lagrede data fra leverandøren, er «Se etter oppdateringer» tydeligere. Vis den siste hendelsen hos transportøren separat fra tidspunktet da applikasjonen sist fullførte en vellykket kontroll.
Kilder
- 17TRACK Tracking API — offisiell produktreferanse for sporings-API-integrasjonen som omtales i denne veiledningen.
- 17TRACK API-dokumentasjon — referanse for leverandørspesifikke operasjoner, autentisering, forespørselsfelt og behandling av svar.
- RFC 9110, Section 10.2.3: Retry-After — definerer headerens former for forsinkelse i sekunder og HTTP-dato.


