Skip to main content
HjemBloggVeiledninger15 spørsmål du bør stille en Tracking API-leverandør før du går i produksjon

15 spørsmål du bør stille en Tracking API-leverandør før du går i produksjon

17TRACK

Før du setter et sporings-API i produksjon, bør du spørre hvordan det håndterer de faktiske transportørene og forsendelsestypene dine, hva hendelsene betyr, hvordan oppdateringer leveres, og hva som skjer når dataene eller integrasjonen svikter. De 15 spørsmålene nedenfor gir utviklings- og driftsteam en praktisk måte å teste disse svarene på før kunder, supportmedarbeidere eller automatiserte arbeidsflyter blir avhengige av dem.

15 spørsmål du bør stille en leverandør av sporings-API-er før lansering

En vellykket demonstrasjon er ikke en produksjonstest. Bruk et representativt utvalg av forsendelser, inkludert forsinkede, returnerte og vanskelige pakker. Be om dokumentasjon, en eksempelpayload eller et testresultat for hvert svar. Registrer alle uavklarte punkter med en ansvarlig person og en beslutningsdato i stedet for å anta at de blir håndtert etter lansering.

Start med å avklare forsendelser og databetydning

1. Hvilke av våre faktiske forsendelser kan dere spore, og hva betyr dekning?

Gi leverandøren et utvalg av transportørene og tjenestene dine, par avsender- og mottakerland samt formater for sporingsnumre. Be leverandøren identifisere hvilke forsendelser den kan godta, hvilke transportører den kan identifisere automatisk, og hvor du må oppgi en transportørkode. At en transportør står på en liste, betyr ikke at alle tjenester, overleveringer eller forsendelsestyper vil generere hendelsene applikasjonen din trenger.

Test reelle eksempler fra ruter med høyt volum og operasjonelle særtilfeller. Ta med en forsendelse som bytter transportør underveis dersom dette skjer i virksomheten din. Registrer om API-et avviser en forsendelse, godtar den uten å finne hendelser, eller returnerer hendelser med begrensede detaljer. Disse utfallene krever ulik håndtering i et ordrebehandlingssystem.

2. Hva kreves for å registrere en forsendelse, og hvordan hindrer dere doble registreringer?

Avklar nødvendige identifikatorer, regler for valg av transportør, tidspunkt for registrering og responsen på et ugyldig eller ennå ikke aktivt sporingsnummer. Spør om et sporingsnummer alene er tilstrekkelig for ditt bruksområde, eller om ytterligere informasjon er nødvendig. Bekreft hva som skjer hvis den samme forsendelsen sendes inn to ganger, enten av det samme systemet eller av separate tjenester.

Bygg én registreringsflyt med tydelig ansvarsfordeling: hvilket system som sender inn forsendelser, hvilket som lagrer leverandørens identifikator, og hvilket som prøver på nytt ved en usikker innsending. Hvis en forespørsel får tidsavbrudd etter at leverandøren har behandlet den, må et ukritisk nytt forsøk ikke i det stille opprette en ny post eller duplisere varsler nedstrøms.

3. Hva betyr statusene deres, og kan vi se de underliggende transportørhendelsene?

Be om en statusordbok og representative råhendelser. Begreper som under transport, ute for levering, avvik, levert og returnert er nyttige sammendrag, men forretningsreglene dine kan trenge flere detaljer. Finn ut om leverandøren oppgir transportørens originale beskrivelser sammen med standardiserte statuser, og hvordan den håndterer en hendelse som ikke passer tydelig inn.

Avtal din egen interne statusmodell før lansering. Bestem spesielt hvilken hendelse som kan avslutte en forsendelse, utløse en leveringsmelding eller starte en avviksflyt. Ikke behandle en bred statusetikett som bevis på en bestemt fysisk hendelse med mindre de underliggende dataene støtter denne tolkningen.

4. Hvilke tidsstempler og lokasjoner oppgis, og hvordan skal vi tolke dem?

For hver hendelse må du skille mellom tidspunktet transportøren sier at den fant sted, og tidspunktet leverandøren mottok eller publiserte den. Spør om tidssoner, manglende tidsforskyvninger, presisjonen til lokasjoner og oppdateringer som kommer etter senere hendelser. En nylig mottatt hendelse kan beskrive en eldre skanning; sortering utelukkende etter mottakstidspunkt kan gi en misvisende tidslinje.

Test payloaden mot databaseskjemaet og visningen mot kundene. Bestem hvordan en hendelse skal vises når den lokale tidssonen er usikker, og unngå å presentere et nøyaktig leveringstidspunkt eller en presis lokasjon hvis kilden ikke oppgir dette.

5. Hvordan representeres avvik, returer og leveringsbevis?

Be om eksempler på mislykkede leveringsforsøk, tollstans, adresseproblemer, returer til avsender og leverte forsendelser. Spør hvilke detaljer som er standardiserte, hvilke som fortsatt er transportørspesifikke, og om leveringsbekreftelsen inneholder dokumentasjon i tilfellene som er viktige for deg. Ikke anta at en levert-status inkluderer mottakernavn, signatur, bilde eller annet bevis.

Knytt hvert avvik til en ansvarlig handlingseier. Noen hendelser krever gjennomgang av support, mens andre ikke krever noen kundemelding før mer informasjon foreligger. Hvis leveringsbevis er nødvendig i en tvisteløsningsflyt, bør tilgjengelighet og format være et eget godkjenningskriterium, ikke en underforstått del av sporingsdekningen.

Test hvordan oppdateringer når systemene dine

6. Leverer dere oppdateringer via webhook, polling eller begge deler, og når bør vi bruke hver metode?

Be om den dokumenterte leveringsmodellen, eksempler på payloads, oppsett av abonnementer og veiledning for å hente inn tapte oppdateringer. Hvis webhooks tilbys, må du finne ut om de varsler om en endret forsendelse, gir et komplett øyeblikksbilde eller inneholder én enkelt hendelse. Hvis polling er nødvendig eller brukes som reserve, bør du avklare riktig forespørselsmønster og hvordan endrede poster identifiseres.

Velg modell basert på arbeidsflyten. En tidslinje som vises til kunden, kan tåle en annen oppdateringsforsinkelse enn en kø for avvik. Arkitekturen din bør ikke love umiddelbare varsler bare fordi integrasjonen bruker webhooks: Transportøren må først gjøre hendelsen tilgjengelig, og hvert påfølgende system må behandle den.

7. Hva skjer når varsler dupliseres, forsinkes eller kommer i feil rekkefølge?

Spør om leverandøren prøver mislykkede leveringer på nytt, hvor lenge den gjør det, og hvilken respons den forventer fra endepunktet ditt. Be om en stabil hendelses- eller forsendelsesidentifikator dersom en slik finnes. Test deretter det samme varselet to ganger, send en eldre hendelse etter en nyere, og returner midlertidig en feil fra endepunktet ditt.

Mottakeren bør utformes slik at den bare bekrefter det den har godtatt på en sikker måte, behandler nye forsøk uten å gjenta kundemeldinger og bygger opp en korrekt tidslinje når hendelser kommer i feil rekkefølge. Hvis et foreslått design er avhengig av nøyaktig én levering av hvert varsel, må du utfordre denne antakelsen før lansering.

8. Hvordan måler vi hvor ferske dataene er, og hva påvirker dette?

Spør hva leverandøren kan måle på hvert trinn: tidspunktet for transportørens hendelse, leverandørens mottakstidspunkt og leveringstidspunktet til systemet ditt. Skill disse målingene fra eventuelle forpliktelser leverandøren påtar seg. Et langt tidsrom mellom den fysiske bevegelsen og oppdateringen i applikasjonen kan skyldes forhold hos transportøren, leverandørens behandling eller din egen kø.

Mål disse tidsrommene under en pilot for representative forsendelser og undersøk avvik. Sett varslingsgrenser ut fra det arbeidsflyten faktisk krever. Hvis en forsinket skanning kan føre til en skadelig kundemelding eller en uteblitt eskalering, bør du definere en reserveprosess, for eksempel en etikett for gamle data eller manuell gjennomgang.

9. Hvordan beskyttes API-legitimasjon og webhook-forespørsler?

Be om dokumentasjon for autentisering og håndtering av legitimasjon. Bekreft hvordan legitimasjon utstedes, avgrenses, roteres og tilbakekalles, om test- og produksjonslegitimasjon er separate, og hvordan en webhook-mottaker kan kontrollere at en forespørsel er ekte. Spør også hvilke beskyttelser som finnes mot gjentatte webhook-forespørsler.

La sikkerhetsteamet gjennomgå den foreslåtte implementeringen, ikke bare leverandørens funksjonsliste. Hold hemmeligheter ute av klientkode og logger, begrens tilgangen til produksjonslegitimasjon og øv på rotering av legitimasjon. Hvis applikasjonen ikke kan kontrollere en innkommende varsling med den dokumenterte mekanismen, er dette en lanseringsblokkerer for en webhook-basert arbeidsflyt.

10. Hvilke forsendelses- og kundedata lagrer dere, og hvor sendes de?

List opp hvert felt integrasjonen vil sende, inkludert sporingsnumre, ordrehenvisninger, adresser, kontaktopplysninger og eventuelle egendefinerte metadata. Spør hvilke felt som er obligatoriske, hvor lenge data og logger lagres, hvordan forespørsler om sletting fungerer, og hvilke regioner eller underleverandører som er relevante for organisasjonens krav. Skaff kontrakts- eller sikkerhetsdokumentasjon der gjennomgangen krever det.

Begrens mengden data du overfører. En sporingsintegrasjon bør ikke motta kundeinformasjon bare fordi det er praktisk å sende et helt ordreobjekt. Personvern-, juridisk- og sikkerhetsteamene dine bør avgjøre om leverandørens dokumenterte håndtering passer til markedene du opererer i.

Planlegg for feil og operasjonelle endringer

11. Hva er hastighetsbegrensningene, og hvordan bør klienter svare på feil?

Be om begrensninger per endepunkt, legitimasjon og miljø, samt eventuelle regler for samtidighet og anbefalt oppførsel ved nye forsøk. Skill mellom en ugyldig forespørsel, et midlertidig tjenesteproblem og en forespørsel som er blitt hastighetsbegrenset. For HTTP-API-er er betydningen av statuskoder viktig: RFC 6585 definerer 429 for for mange forespørsler, mens RFC 9110 beskriver HTTP-semantikk, inkludert serverfeil.

Beregn forventet trafikk på vanlige dager og under topper, og test en klient som reduserer tempoet, legger arbeid i kø og varsler ved vedvarende feil. Bekreft om en usikker skriveoperasjon kan prøves på nytt på en trygg måte. En policy for nye forsøk som mangedobler trafikken under et avbrudd, kan gjøre gjenopprettingen vanskeligere.

12. Hvordan kommuniseres endringer i skjema, statuser og transportørintegrasjoner?

Spør om API-versjonering, varsler om utfasing, endringslogger og om hendelsesfelt kan legges til uten en versjonsendring. Transportørens beskrivelser og sporingsatferd kan også endres. Finn ut hvordan leverandøren kommuniserer en endring som påvirker én transportør eller rute, i stedet for hele API-et.

Skriv tolerante parsere for valgfrie felt og ukjente statusverdier, men ikke gjør en ukjent verdi om til levert eller mislykket uten å varsle. Lagre nok kildedetaljer til å diagnostisere en endret mapping. Utnevn noen til å gjennomgå leverandørvarsler og oppdatere integrasjonstestene før en endring når kundene.

13. Hva kan vi teste før produksjon, og hvor godt samsvarer testmiljøet med faktisk drift?

Be om tilgang til dokumentasjon, et testmiljø hvis det tilbys, eksempelsvar og en måte å utløse feilstier på. Spør hvilke scenarier som simuleres, og hvilke som krever faktiske forsendelser. En sandkasse kan bevise at koden håndterer en payload, men sier lite om fullstendigheten til transportørhendelser, tidspunkt for oppdateringer eller regional egnethet.

Gjennomfør to typer tester: deterministiske integrasjonstester for parsing, nye forsøk og sikkerhet, samt en begrenset pilot med faktiske forsendelser for operasjonell atferd. Ta med doble innsendinger, tidsavbrudd hos leverandøren, en forsinket skanning, en retur og en ukjent status. Krev at både utviklingsteamet og teamet som skal håndtere avvik, godkjenner resultatene.

14. Hvilke support- og hendelsesforpliktelser gjelder når sporingen slutter å oppdatere seg?

Spør hvilke supportkanaler som er tilgjengelige for kontoen din, hvordan hendelser rapporteres, og hvilke kontraktsfestede tjenesteforpliktelser som eventuelt gjelder for API-et eller leveringen av varsler. Avklar om en oppetidsforpliktelse dekker API-endepunktet, leveringen av sporingsoppdateringer eller begge deler. Dette er ikke det samme operasjonelle utfallet.

Etabler din egen beredskapsplan: hvem oppdager en feil, hvem kontakter leverandøren, når polling eller en annen reserveprosess brukes, og hva kundene ser mens oppdateringene er forsinket. Be om prosessen for å løse et forsendelsesspesifikt dataproblem så vel som et plattformomfattende avbrudd. Test eskaleringsveien før du trenger den.

15. Hvordan beregnes bruk og kostnader, og hva skjer hvis vi avslutter?

Spør hvilke handlinger som teller mot fakturering eller bruksgrenser: innsendinger, sporede forsendelser, forespørsler, varsler eller en annen enhet. Bekreft hvordan doble registreringer, nye forsøk, inaktive forsendelser, overforbruk og testtrafikk behandles i henhold til den foreslåtte avtalen. Få gjeldende vilkår skriftlig i stedet for å anslå kostnader fra en API-demonstrasjon.

Planlegg også for avslutning. Finn ut hvordan du kan eksportere forsendelseshistorikk, hvor lenge tilgangen forblir tilgjengelig, og hva som skjer med aktive sporingsposter. En fungerende avslutningsplan er ikke en forutsigelse om at du vil bytte leverandør; den er en måte å unngå å miste oversikten over forsendelser som allerede er underveis.

Gjør svarene om til en produksjonsbeslutning

En nyttig gjennomgang før lansering har tre resultater:

  • Et resultat for forsendelsesegnethet: et testet utvalg som viser hvilke sporingsposter som ble godtatt, og om hendelsene støtter de planlagte kunde- og driftsflytene.
  • Et integrasjonsresultat: dokumentert håndtering av autentisering, duplikater, nye forsøk, forsinkede hendelser, variasjoner i skjemaet og gjenoppretting etter tapte oppdateringer.
  • En driftsavtale: dokumenterte begrensninger, vilkår for datahåndtering, supportkontakter, kostnadsforutsetninger og ansvarlige for uavklarte risikoer.

17TRACK er én leverandør du kan vurdere dersom et sporings-API for flere transportører passer bruksområdet ditt. Siden for Tracking API og API-dokumentasjonen er utgangspunkter for å kontrollere integrasjonen mot disse spørsmålene. Den samme standarden bør gjelde for alle leverandører: Dokumentasjon viser hvordan et grensesnitt er ment å fungere, mens egne tester med representative forsendelser viser om det fungerer for arbeidsflyten i produksjon. Ikke lanser kundemeldinger eller automatisering av avvik før hendelsene som utløser dem, er validert.

Vanlige spørsmål

Er en sandkassetest nok til å godkjenne et sporings-API for produksjon?

Nei. En sandkasse kan validere forespørselsformater og enkelte typer feilhåndtering, men faktiske forsendelser er nødvendige for å vurdere transportørspesifikke hendelser, tidspunkt og nytten av avviksdata på de faktiske rutene dine. Bruk begge deler, med separate godkjenningskriterier.

Bør vi bruke webhooks eller polling for sporingsoppdateringer?

Bruk leverandørens dokumenterte leveringsalternativer og arbeidsflytens toleranse for forsinkelser som grunnlag for valget. Webhooks kan redusere behovet for gjentatte kontroller når de støttes, men mottakeren må fortsatt håndtere nye forsøk og duplikater. Polling kan være egnet som primærmetode eller som reserveprosess, med forbehold om dokumenterte begrensninger.

Hva er den vanligste feilen ved mapping av sporingsstatuser?

Å bruke én bred status som utløser for en mer spesifikk forretningspåstand. En levert-etikett alene gir for eksempel kanskje ikke beviset som trengs for å løse en tvist. Definer utløsere ved hjelp av de underliggende hendelsesdetaljene leverandøren faktisk oppgir.

Hvem bør godkjenne integrasjonen før lansering?

Utviklingsteamet bør godkjenne pålitelighet og sikkerhet. Drift eller support bør godkjenne nytten av hendelsene og avviksflytene, mens relevante ansvarlige for personvern, juss og innkjøp bør gjennomgå datahåndtering og kommersielle vilkår. Utnevn en navngitt ansvarlig for alle åpne avvik.

Kilder