Skip to main content
HjemBlogVejledningerSådan får du den seneste forsendelsesstatus via API uden at vente på en webhook

Sådan får du den seneste forsendelsesstatus via API uden at vente på en webhook

17TRACK

For at hente den senest tilgængelige forsendelsesstatus uden at vente på en webhook skal du sende en godkendt anmodning til din trackingudbyders API til forespørgsler om forsendelser. Brug svaret til straks at opdatere din applikation, og lad derefter webhooks være aktiveret for efterfølgende ændringer. Den vigtige forskel er, at en forespørgsel normalt henter udbyderens senest gemte trackingoplysninger; den udløser ikke nødvendigvis et nyt opslag hos transportøren.

Sådan henter du den seneste forsendelsesstatus via API uden

Denne tilgang er nyttig, når en kunde åbner en ordreside, en supportmedarbejder har brug for en opdatering, eller dit system skal gendannes efter en mistet notifikation. En pålidelig implementering kombinerer behovsbaserede forespørgsler, tydelige indikatorer for aktualitet og sikkerhedsforanstaltninger mod duplikerede eller forkert rækkefølgeordnede opdateringer.

Beslut, hvad “seneste forsendelsesstatus” betyder

Før du vælger et endpoint, skal du skelne mellem tre handlinger, der kan lyde ens, men giver forskellige resultater.

HandlingHvad den gørHvad den ikke fastslår
Læs din egen databaseReturnerer trackingoplysninger, som din applikation allerede har.Om udbyderen har modtaget en nyere opdatering.
Forespørg i tracking-API'etHenter oplysninger, der er tilgængelige via udbyderens forespørgselsfunktion.Om der blev foretaget et nyt opslag hos transportøren under denne anmodning.
Anmod om en trackingopdateringAnmoder om endnu et upstream-opslag, hvis udbyderen tilbyder denne funktion.At transportøren har en ny scanning, eller at opdateringen gennemføres synkront.

Brug en forespørgsel, når du har brug for et svar nu. Undersøg kun en opdateringsfunktion, når du har brug for, at udbyderen forsøger endnu et upstream-opslag. Antag ikke, at en cache-busting-parameter, en gentagelse af en anmodning eller en HTTP-cache-control-header tvinger en transportør til at levere nye oplysninger.

Synlighed i forbindelse med forsendelser har flere trin: transportøren registrerer en hændelse, trackingudbyderen henter den, og din applikation modtager eller henter den. En direkte API-anmodning kan omgå ventetiden på levering af en notifikation, men den kan ikke fjerne forsinkelser tidligere i kæden.

Kontrollér forespørgselskontrakten, før du skriver kode

Udvikleren, der integrerer trackingtjenesten, ejer denne arbejdsgang. Start med udbyderens aktuelle dokumentation, ikke et endpoint, der er kopieret fra et gammelt integrationseksempel. Bekræft disse detaljer:

  • Forsendelsesidentitet: Accepterer forespørgslen et trackingnummer, et internt forsendelses-ID eller et trackingnummer kombineret med en transportøridentifikator?
  • Registreringskrav: Skal forsendelsen registreres, før den kan forespørges?
  • Godkendelse: Hvilken header eller godkendelsesmekanisme kræves?
  • Betydningen af svaret: Returnerer handlingen gemte oplysninger, starter den indsamling, eller returnerer den et job, der skal kontrolleres senere?
  • Resultathåndtering: Kan et vellykket HTTP-svar indeholde en fejl på forsendelsesniveau eller et afventende resultat?
  • Brugsbegrænsninger: Hvilke hastighedsgrænser, batchgrænser og kontospecifikke begrænsninger gælder?
  • Felter for aktualitet: Hvilke tidsstempler repræsenterer transportørens hændelser, udbyderens opdateringer og genereringen af svaret?

For en 17TRACK-integration er Tracking API det relevante produkt, ikke en forbrugertracking-side eller en trackinggrænseflade i en webshop. Brug den officielle API-dokumentation til at bekræfte forespørgslen efter trackingoplysninger, godkendelse, anmodningsfelter og svarstruktur for din integration. Behandl forespørgsler og webhook-håndtering som separate applikationsstier, der opdaterer den samme forsendelsespost.

Undgå at hardkode antagelser om opdateringsadfærd eller forespørgselsfrekvens. Disse detaljer skal passe til den handling og de servicevilkår, du faktisk bruger.

Byg et behovsbaseret opslag gennem din backend

Et praktisk design er at eksponere et godkendt endpoint i din egen applikation. Browseren anmoder om en forsendelsesopdatering fra dette endpoint; din server kontrollerer autorisationen, afgør om en forespørgsel til udbyderen er nødvendig, og returnerer et normaliseret resultat.

Følgende route er et eksempel på et endpoint, du ville oprette i din applikation. Det er ikke et 17TRACK-endpoint eller en specifikation for en udbyderanmodning.

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

Brug ordreidentifikatoren til at slå forsendelsen op på serveren. Lad ikke en kaldende part hente en anden kundes trackinghistorik blot ved at udskifte et trackingnummer i en anmodning. Opbevar udbyderens API-legitimationsoplysninger på din backend i stedet for i browserens JavaScript eller i en mobilapplikationspakke.

Et forespørgselsforløb, du kan implementere

  1. Godkend adgang. Bekræft, at kunden eller medarbejderen må se ordren.
  2. Find forsendelsen. Læs det gemte tracking-ID og eventuelt transportøroplysninger.
  3. Kontrollér lokal aktualitet. Hvis der allerede findes en nylig vellykket forespørgsel, skal den genbruges i henhold til din applikations politik for aktualitet.
  4. Forespørg udbyderen efter behov. Brug den dokumenterede handling og en begrænset timeout for anmodningen.
  5. Validér resultatet. Kontrollér både HTTP-resultatet og resultatet på forsendelsesniveau.
  6. Sammenflet oplysningerne. Anvend de samme normaliserings- og afstemningsregler som for webhook-hændelser.
  7. Returnér status og aktualitet. Medtag den seneste hændelsestid og tidspunktet for den seneste vellykkede kontrol hos udbyderen, når de er tilgængelige.

Den lokale politik for aktualitet er en teknisk beslutning, ikke en erklæring om transportørens opdateringsfrekvens. Vælg den ud fra dine krav til brugergrænsefladen, udbyderens begrænsninger, forsendelsesvolumen og den observerede nytte af forespørgsler. En kunde, der gentagne gange klikker på en opdateringsknap, bør ikke skabe en ubegrænset strøm af upstream-anmodninger.

Normalisér svaret uden at opfinde aktualitet

Din applikation kan returnere et stabilt internt format, selv når udbydernes svarstrukturer er forskellige. Dette illustrerende objekt er din egen applikationskontrakt, ikke en faktisk payload fra en udbyder:

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

Udfyld hvert tidsstempel kun, når dets betydning er kendt. Det tidspunkt, hvor din server modtog et svar, hører hjemme i dine forespørgselsmetadata; det må ikke præsenteres som tidspunktet, hvor pakken blev flyttet. Hvis udbyderen ikke leverer et tidsstempel for udbyderopdateringen, skal feltet være fraværende eller null i stedet for at blive udfyldt med et andet tidsstempel.

For kundegrænsefladen skal meddelelserne adskilles: “Seneste hændelse hos transportøren” beskriver forsendelsesaktivitet, mens “Tracking kontrolleret” beskriver din applikations hentningsaktivitet. Denne forskel forhindrer, at en uændret scanning ser ud til at være ny.

Forhindr API-forespørgsler og webhooks i at overskrive hinanden

Når begge mekanismer er aktive, kan den samme hændelse ankomme via en forespørgsel og en webhook. De kan også afsluttes i en anden rækkefølge end den, de blev startet i. En forespørgsel, der blev startet først, kan blive færdig, efter at en webhook allerede har leveret nyere oplysninger.

Brug ikke logik, hvor det senest modtagne svar vinder. Den senest modtagne payload er ikke nødvendigvis den seneste forsendelsestilstand.

  • Del én opdateringspipeline. Send forespørgselsresultater og webhook-payloads gennem de samme validerings-, normaliserings- og lagringsfunktioner.
  • Fjern duplikater fra hændelser. Foretræk en dokumenteret hændelsesidentifikator. Hvis der ikke findes en, skal du opbygge et omhyggeligt defineret fingeraftryk ud fra tilgængelige felter som hændelsestid, status, placering og beskrivelse.
  • Brug rækkefølgefelter med kendt betydning. En dokumenteret revision eller sekvens er mere nyttig end at antage, at ankomsttidspunktet repræsenterer hændelsesrækkefølgen.
  • Bevar historikken. En nyligt modtaget hændelse kan udfylde et historisk hul uden at ændre den aktuelle forsendelsesoversigt.
  • Tillad korrektioner. Statusser udgør ikke en universel lineær trappe. Følg den dokumenterede korrigeringsadfærd i stedet for permanent at afvise enhver tilsyneladende tilbagegående ændring.

Når hændelsesrækkefølgen er usikker, skal den oprindelige payload og dens oprindelse bevares til undersøgelse. Afklar ikke tvetydighed ved at opfinde et hændelsestidsstempel eller antage, at alle transportørtidsstempler bruger den samme tidszone.

Håndter manglende data og mislykkede anmodninger forskelligt

Et tomt resultat, et uændret resultat og en mislykket anmodning bør ikke føre til den samme kundemeddelelse.

Forespørgslen lykkes, men status er ikke ændret

Bevar den eksisterende forsendelsesstatus, og opdatér tidspunktet for den seneste vellykkede forespørgsel. Opret ikke en ny forsendelseshændelse, blot fordi endnu et opslag er gennemført. Hvis kunden har brug for flere detaljer, skal den eksisterende hændelseshistorik vises, og det skal forklares, at der ikke blev returneret en nyere trackinghændelse.

Forsendelsen har endnu ingen trackingoplysninger

Kontrollér, om registrering er påkrævet, om identifikatoren og transportøren er korrekte, og hvordan udbyderen repræsenterer afventende indsamling. Mangel på hændelser beviser ikke i sig selv, at trackingnummeret er ugyldigt, eller at pakken er bortkommet. Bevar udbyderens skelnen mellem en ukendt identifikator, en registreret forsendelse, der afventer oplysninger, og en anmodning, der ikke kunne behandles.

Anmodningen til udbyderen får timeout eller mislykkes

Hvis du har en tidligere gyldig status, skal den returneres med en tydelig angivelse af, at den seneste kontrol ikke lykkedes. Bevar tidsstemplet for den tidligere vellykkede forespørgsel uændret. En netværksfejl er ikke en leveringsundtagelse og bør ikke ændre pakkens forretningsstatus.

Brug begrænsede gentagelser med backoff og jitter ved passende midlertidige fejl. Gentag ikke ugyldige legitimationsoplysninger eller fejlbehæftede anmodninger igen og igen. Når et svar indeholder Retry-After, skal det fortolkes i overensstemmelse med udbyderens kontrakt og HTTP-semantik. HTTP-specifikationen tillader, at værdien udtrykkes som en forsinkelse i sekunder eller som en HTTP-dato.

Flere anmodninger ankommer for den samme forsendelse

Saml samtidige opslag, så de kan dele én upstream-anmodning. Anvend begrænsninger pr. konto og forsendelse, og forhindr, at en automatisk gentagelse bliver mangedoblet på tværs af flere applikationslag. Når batching understøttes, skal resultatet for hver forsendelse undersøges i stedet for at behandle hele batchen som vellykket, fordi HTTP-anmodningen blev gennemført.

Brug polling som en kontrolleret reserve

Uden webhooks kan planlagt polling holde din database opdateret, men det kræver en udtrykkelig drifts politik. Beslut, hvilke forsendelser der fortsat er berettigede, hvordan fejl påvirker tidsplanen, og hvornår rutinemæssig polling stopper.

For de fleste integrationer er et hybridt design et fornuftigt udgangspunkt: webhooks håndterer baggrundsændringer, behovsbaserede forespørgsler betjener interaktive anmodninger, og afstemningsjobs kontrollerer poster, der kræver opmærksomhed. Dette er en arkitekturanbefaling, ikke en garanti for, at det minimerer omkostningerne for alle konti.

  • Prioritér aktive forsendelser og poster med uløste hentningsfejl.
  • Undgå at forespørge om alle historiske forsendelser ved hver planlagte kørsel.
  • Definér, hvordan afsluttede forsendelser håndteres, herunder eventuelle korrigeringsperioder, som din virksomhed kræver.
  • Følg, hvor ofte forespørgsler finder reelt nye oplysninger.
  • Undersøg problemer med webhook-levering i stedet for at skjule dem med stadig hyppigere polling.

Overvåg ventetid for anmodninger til udbyderen, mislykkede forespørgsler, svar på hastighedsbegrænsninger og forskelle mellem forespurgte data og webhook-baserede poster. Overvåg separat alderen på den seneste hændelse hos transportøren. Vellykkede API-svar kan eksistere sammen med trackingoplysninger, der ikke er ændret.

Test arbejdsgangen før udgivelse

En vellykket anmodning er kun den første test. Kontrollér de situationer, der ellers kan skabe vildledende statusopdateringer:

  • En webhook ankommer, mens en behovsbaseret forespørgsel stadig kører.
  • To kunder eller medarbejdersessioner anmoder om den samme forsendelse samtidig.
  • Udbyderen returnerer HTTP-succes, men rapporterer en fejl på forsendelsesniveau.
  • En anmodning mislykkes, efter at din applikation allerede har gyldige trackingoplysninger.
  • En hændelse mangler en tidszone eller indeholder en ukendt statuskode.
  • En korrektion hos transportøren ændrer et tidligere vist resultat.
  • En bruger forsøger at få adgang til en forsendelse, der tilhører en anden konto.

Dit udgivelseskriterium bør være, at applikationen returnerer de bedst kendte forsendelsesoplysninger, forklarer deres aktualitet korrekt og ikke ødelægger oplysningerne, når anmodninger mislykkes eller ankommer i forkert rækkefølge.

Ofte stillede spørgsmål

Tvinger en forespørgsel i API'et transportøren til at scanne eller opdatere en pakke?

Nej. Hentning af trackingoplysninger kan ikke forårsage en fysisk scanning. Om en anmodning udløser et upstream-opslag afhænger af den dokumenterede handling. Selv en understøttet opdatering kan returnere uændrede oplysninger, hvis transportøren ikke har en nyere hændelse.

Kan jeg bruge API-forespørgsler uden at konfigurere webhooks?

Hvis udbyderen understøtter den nødvendige forespørgselsarbejdsgang, kan du bygge en integration omkring behovsbaserede anmodninger eller polling. Bekræft først kravene til registrering og forespørgsler. Din applikation vil derefter være ansvarlig for at beslutte, hvornår der skal kontrolleres, kontrollere anmodningsmængden og registrere ændringer.

Hvor ofte bør jeg polle forsendelsesstatus?

Der findes ikke et universelt interval. Vælg en tidsplan, der passer til udbyderens begrænsninger, din forsendelsesvolumen og forretningsværdien af at finde opdateringer tidligere. Mål, hvor ofte polling returnerer nye hændelser, og justér derefter i stedet for at antage, at hyppige anmodninger giver friskere data fra transportøren.

Hvorfor returnerer API'et oplysninger, som jeg allerede har modtaget via en webhook?

Begge stier kan vise den samme underliggende forsendelsespost. En webhook leverer en notifikation, mens en forespørgsel henter oplysninger efter behov. Det er ikke nødvendigvis en fejl at modtage den samme hændelse via begge; din applikation bør fjerne duplikatet.

Bør opdateringsknappen hedde “Opdatér tracking”?

Kun hvis denne formulering præcist beskriver handlingen. Hvis knappen henter gemte data fra udbyderen, er “Kontrollér for opdateringer” tydeligere. Vis den seneste hændelse hos transportøren separat fra tidspunktet for, hvornår din applikation sidst gennemførte en vellykket kontrol.

Kilder