Skip to main content
HjemBloggVeiledningerTesting av en Tracking API-integrasjon i utviklingsmiljøet: sandbox, testnumre, mock-webhooks

Testing av en Tracking API-integrasjon i utviklingsmiljøet: sandbox, testnumre, mock-webhooks

17TRACK

For å teste en integrasjon med et sporings-API under utvikling kan du bruke tre utfyllende metoder: en leverandørsandkasse eller dokumenterte testnumre for API-atferd, lokale testdata for repeterbare forsendelsesscenarioer og simulerte webhooks for mottaksendepunktet ditt. Kjør deretter en kontrollert test i produksjonsmiljøet for å validere delene som simuleringer ikke kan bevise, blant annet legitimasjon, abonnementsoppsett og faktisk hendelseslevering.

Testing a Tracking API Integration in Development Sandbox Test Numbers

Denne veiledningen er for utviklere som kobler forsendelsessporing til en e-handelsplattform, et ordrebehandlingssystem, et ERP-system eller en kundemeldingstjeneste. Målet er ikke bare å motta et vellykket API-svar. Målet er å bevise at sporingsoppdateringer produserer riktig ordrestatus uten dupliserte meldinger, tapte hendelser eller utilsiktet kontakt med ekte kunder.

17TRACK API

Forenkle global pakkesporing med forsendelsesoppdateringer fra over 3 500 transportører.

Lær mer →

Skill mellom leverandørens atferd og applikasjonens atferd

En sporingsintegrasjon har minst to grenser: forespørsler applikasjonen din sender til leverandøren, og oppdateringer applikasjonen din mottar eller henter etterpå. En vellykket forespørsel ved den første grensen viser ikke at den andre grensen fungerer.

Merkevarebasert ordresporingsløsning

Gi kundene en bedre opplevelse og øk antallet gjenkjøp med merkevarebasert sporing og automatiserte varsler.

Prøv gratis →

Bygg testplanen rundt disse grensene i stedet for å forvente at ett testsporingsnummer skal teste hele systemet.

TestmetodeHva den kan validereHva den ikke kan fastslå alene
LeverandørsandkasseStøttede forespørselsformater, autentisering og simulert atferd som er beskrevet av leverandørenTilgjengelighet av transportørdata i produksjon eller leveringsatferd i produksjon
Dokumenterte testnumreDe spesifikke scenarioene som er knyttet til numreneAndre statuser, transportører eller webhook-sekvenser
Lokale testdata og API-mockerParseren, tilordningsreglene, lagringen og feilhåndteringen dinOm den virkelige leverandøren godtar forespørsler eller sender samme nyttelast
Simulerte webhook-forespørslerEndepunkthåndtering, validering, deduplisering og nedstrømseffekterTilbakekallskonfigurasjon på leverandørsiden eller virkelige leveringsforsøk på nytt
Kontrollert test i produksjonReell tilkobling og den observerte forsendelsesarbeidsflytenAlle sjeldne feil, unntak eller leveringssekvenser

Anbefalt fremgangsmåte: gjør lokale tester deterministiske, bruk leverandørstøttet testing når det er tilgjengelig, og reserver ekte forsendelser for å bekrefte forbindelsen mellom systemene.

Bekreft leverandørens kontrakt før du skriver testdata

Start med den offisielle dokumentasjonen for API-versjonen du har tenkt å bruke. Bekreft basis-URL-en, autentiseringsmetoden, registreringskravene, svarskjemaet, webhook-oppsettet og eventuelle dokumenterte testfunksjoner. Ikke anta at det finnes en separat sandkasse bare fordi leverandøren tilbyr et API.

For en 17TRACK-integrasjon kan du bruke 17TRACK Tracking API-siden og den offisielle API-dokumentasjonen som utgangspunkt. Bekreft gjeldende spesifikasjoner for forespørsler og tilbakekall der før du bygger leverandørspesifikke eksempler. Eksemplene nedenfor er bevisst testdata som eies av applikasjonen, og representerer ikke 17TRACK API-skjemaet.

Avklar disse spørsmålene før du kobler utviklingskode til en ekstern konto:

  • Er utviklings- og produksjonslegitimasjon separat, og hvilket miljø gir hver legitimasjon tilgang til?
  • Støtter en sandkasse tilbakekall, eller bare forespørsel–svar-testing?
  • Er testnumre dokumentert, og hvilke nøyaktige resultater produserer de?
  • Kan registreringer eller andre testforespørsler bruke opp kontokvoten eller opprette permanente poster?
  • Hvilke regler for autentisering av tilbakekall, bekreftelse, tidsavbrudd og nye forsøk er dokumentert?
  • Hvilke identifikatorer knytter en sporingsregistrering, forsendelse, transportør og tilbakekallshendelse sammen?

Hvis testatferden ikke er tydelig dokumentert, bør du be leverandøren bekrefte den. Fortsett samtidig å teste din egen behandlingslogikk med mocker. En ubekreftet sandkassefunksjon er en planleggingsusikkerhet, ikke et bevis på at leverandøren mangler funksjonen.

Bygg et isolert utviklingsmiljø

Bruk en separat database eller en isolert leietaker, separate hemmeligheter og syntetiske ordrer. Send e-post, SMS og andre varsler til testdestinasjoner eller en varslingssluse. En forsendelse som er markert som levert i testdata, må ikke utløse en melding til en ekte kjøper.

Legg til en eksplisitt miljømarkør i interne poster og logger. Oppbevar leverandørlegitimasjon på serveren, utenfor kildekontrollen, og fjern hemmeligheter fra forespørselsopptak. Hvis midlertidig offentlig tilgang er nødvendig for tilbakekall, må du bare eksponere det tiltenkte utviklingsendepunktet og beholde autentiseringskontrollene.

Opprett et lite sett med kjente ordrer før du sender hendelser. Ta med to forsendelser knyttet til én ordre og, hvis applikasjonen støtter det, den samme sporingsnummerstrengen under ulike transportørkontekster. Disse tilfellene avslører antakelser om at et sporingsnummer alene alltid identifiserer én unik forretningspost.

Definer på forhånd forventet effekt av hver test: forsendelsesstatus, ordrekobling, tidslinjeposter, antall varsler og revisjonspost. Da blir en demonstrasjon til en påstand som kan bestå eller feile.

Bruk testnumre bare til det dokumenterte formålet

Et sporingsnummer har to ulike roller i testing. Det kan være et inndatafelt som brukes til å validere registrering, og det kan identifisere en forsendelse som produserer sporingshendelser. Et nummer som består formatvalideringen, gir ikke nødvendigvis en nyttig hendelseshistorikk.

Når offisielle testnumre er tilgjengelige

Registrer leverandørens oppgitte scenario sammen med hvert nummer. Et nummer som er dokumentert for en levert forsendelse, bør ikke antas å simulere et unntak, en retur eller et mislykket leveringsforsøk. Kontroller også om resultatet er fast, endres over tid eller krever valg av en bestemt transportør.

Oppbevar disse numrene i en egen konfigurasjon for integrasjonstester. Ikke spre dem i enhetstester, der endret ekstern atferd kan gjøre ellers deterministiske tester upålitelige.

Når offisielle testnumre ikke er bekreftet

Bruk syntetiske identifikatorer i din egen applikasjon og simuler leverandørgrensen. Du må aldri finne på et nummer som ser plausibelt ut og anta at det er reservert for testing; det kan tilhøre en ekte forsendelse.

For validering i produksjon bør du bruke forsendelser du kontrollerer og har tillatelse til å få tilgang til. Unngå å kopiere sporingsnumre fra offentlige skjermbilder eller kundesamtaler. Behandle forsendelseshistorikk som potensielt sensitiv, fordi den kan inneholde steder, tidsstempler og leveringsinformasjon.

En eldre levert forsendelse kan være nyttig for å validere parsing, men er en dårlig avhengighet for kontinuerlig integrasjon. Tilgjengeligheten av historiske data og det eksterne svaret kan endres. Bevar et anonymisert testdataeksempel for repeterbare tester og hold produksjonstesten separat.

Opprett testdata rundt meningsfulle forsendelsesoverganger

Bygg testdata fra det dokumenterte skjemaet og, når det er tilgjengelig, anonymiserte virkelige svar. Hold leverandørens nyttelasttestdata atskilt fra din interne normaliserte hendelsesmodell. Test adapteren mellom dem slik at en intern mock ikke skjuler en ødelagt leverandørparser.

Et nyttig startsett dekker disse scenarioene:

  • Ingen sporingshendelser ennå: behold forsendelsen uten å hevde at den er under transport eller levert.
  • Under transport: oppdater tidslinjen og behold riktig ordrekobling.
  • Ute for levering: bruk varslingspolicyen din uten å behandle leveringen som fullført.
  • Levert: registrer fullføring og utfør den tiltenkte forretningshandlingen én gang.
  • Unntak eller forsøkt levering: behold forskjellen fra en fullført levering.
  • Retur under transport: unngå å tolke hver senere skanning som fremdrift mot den opprinnelige mottakeren.
  • Ukjent status: behold nok informasjon til diagnostisering uten å finne på en statustilordning.

Bruk egne normaliserte navn for disse scenarioene, og tilordne deretter uttrykkelig leverandørens dokumenterte verdier til dem. Ikke anta at ulike API-er bruker de samme statusetikettene, eller at en etikett har identisk forretningsbetydning overalt.

Varier også datastrukturen: en tom hendelsesliste, manglende valgfrie felt, ekstra ukjente felt, Unicode-stedsnavn, tidsstempler med tidssoneforskyvninger og ugyldige obligatoriske verdier. Parseren bør tåle kompatible tillegg, men avvise data som ikke kan behandles på en trygg måte.

Send simulerte webhooks gjennom den virkelige mottaksbanen

En simulert webhook bør teste mottaksruten, autentiseringsmellomvaren, valideringen, lagringen og arbeiderbehandlingen – ikke bare kalle den endelige funksjonen for statusoppdatering.

Følgende nyttelast representerer en syntetisk intern hendelse. Feltnavnene, hendelses-ID-en og statusen er illustrerende; de utgjør ikke en kontrakt for leverandørens tilbakekall.

{
  "event_id": "dev-event-001",
  "shipment_id": "dev-shipment-001",
  "tracking_number": "INTERNAL-TEST-001",
  "status": "in_transit",
  "occurred_at": "2025-01-15T10:00:00Z"
}

Lagre den som tracking-event.json og send den til en lokal testmottaker:

curl --request POST \
  http://localhost:3000/dev/tracking-events \
  --header 'Content-Type: application/json' \
  --data-binary @tracking-event.json

Denne kommandoen validerer bare lokal ruting og håndtering. Den demonstrerer ikke leverandørautentisering. Hold en rute som bare er for utvikling utilgjengelig i produksjon, eller test produksjonsmottakeren med leverandørens dokumenterte autentiseringsmetode og en separat testhemmelighet.

Test autentisering uten å svekke produksjonskontrollene

Hvis leverandøren angir signerte tilbakekall, må du implementere akkurat denne ordningen i stedet for å velge en vilkårlig signaturheader eller algoritme. For ordninger som signerer forespørselsbytes, må du beholde den opprinnelige kroppen for verifisering; parsing og ny serialisering av JSON kan endre disse bytene.

Test gyldig autentisering, manglende legitimasjon, manipulerte kropper og feil signaturer der det er relevant. Hvis den dokumenterte ordningen inkluderer tidsstempler eller beskyttelse mot replay, må du også teste disse reglene. HMAC er en standardisert konstruksjon for meldingsautentisering, men at den eksisterer, fastslår ikke at en bestemt sporingsleverandør bruker den.

Test duplikater, rekkefølge og gjenoppretting

Behandlingen av forsendelser bør forbli korrekt når samme oppdatering kommer flere ganger, eller når hendelser kommer i uventet rekkefølge. Dette er defensive testscenarioer, ikke påstander om en bestemt leverandørs garanti for levering.

TestForventet applikasjonsatferd
Send samme hendelse to gangerBehold én logisk hendelse og unngå dupliserte kundemeldinger.
Send en eldre transittskanning etter leveringBehold nyttig historikk uten automatisk å tilbakestille levert-statusen.
Send samtidige oppdateringerBruk konsistente statusoverganger til tross for samtidige arbeidere.
Stopp behandlingen etter varig mottakGjenopprett og behandle den lagrede hendelsen uten å kreve et nytt tilbakekall.
La lagringen feile før mottaket er varigIkke bekreft feilaktig at mottaket er vellykket.
Send en ukjent forsendelseFølg en definert karantene- eller avvisningspolicy; gjett aldri ordrekoblingen.

Foretrekk en dokumentert stabil hendelsesidentifikator for deduplisering når en slik finnes. Ellers må du definere en nøye avgrenset identitet basert på relevante felt og teste kollisjoner. Et sporingsnummer alene er ikke en hendelsesidentitet, fordi én forsendelse kan generere mange legitime oppdateringer.

Skill hendelseshistorikk fra den gjeldende forsendelsesprojeksjonen. Å beholde historiske skanninger betyr ikke at enhver sent ankommende skanning må overskrive den viste statusen. Heller ikke er «bruk det nyeste tidsstempelet» en komplett regel: korrigeringer, returforløp og ulike betydninger av tidsstempler krever uttrykkelig håndtering.

Ved asynkron behandling bør du bare bekrefte etter at hendelsen har nådd et varig overleveringspunkt, for eksempel en lagret innboksoppføring eller en varig kø, i samsvar med arkitekturen din. Følg leverandørens dokumenterte krav til bekreftelse. HTTP definerer betydningen av statuskoder, men en bestemt avsenders tidsplan for nye forsøk må komme fra dennes egen kontrakt.

Kjør en kontrollert test i produksjon og fastsett lanseringskriterier

Når deterministiske tester består, registrerer du en autorisert forsendelse gjennom den virkelige integrasjonen og bekrefter hele banen. Kontroller at leverandøren godtok den tiltenkte posten, at tilbakekallskonfigurasjonen peker på riktig miljø, og at innkommende data tilordnes til forventet forsendelse.

Ikke krev at alle forsendelsesstatuser skal vises under denne testen. Ekte forsendelser kan ikke kontrolleres som testdata. Bruk produksjonskjøringen til å validere tilkobling og observert kontraktskompatibilitet, og bruk avspillbare testdata til å dekke sjeldne eller destruktive scenarioer.

Før lansering må du kreve følgende resultater:

  • Dokumenterte vellykkede svar og feilsvar håndteres, inkludert feil på elementnivå hvis API-et støtter batch-operasjoner.
  • Tidsavbrudd utløser ikke blinde nye opprettingsforsøk når den første forespørselen allerede kan ha lykkes.
  • Dupliserte hendelser kan ikke opprette dupliserte forretningshandlinger.
  • Ugyldige tilbakekall kan ikke endre forsendelsesstatusen.
  • Arbeiderfeil etterlater gjenopprettbare hendelser i stedet for å miste dem i stillhet.
  • Utviklingstrafikk kan ikke varsle ekte kunder eller endre produksjonsordrer.
  • Logger kobler sammen forespørsler, mottatte hendelser, behandlingsresultater og varslingsforsøk uten å eksponere hemmeligheter.

En lansering er klar når du kan forklare både den normale arbeidsflyten og hvordan systemet gjenopprettes etter en usikker forespørsel, et gjentatt tilbakekall eller en avbrutt arbeider. Ett vellykket sporingsoppslag er ikke nok.

Vanlige spørsmål

Kan jeg teste en sporingsintegrasjon uten en sandkasse?

Ja. Simuler den utgående API-grensen, spill av dokumenterte tilbakekallstestdata og test normaliseringen og forretningsreglene dine lokalt. Bruk deretter en autorisert forsendelse i produksjon for å bekrefte faktisk tilkobling. Dette gir god dekning, men gjenskaper ikke udokumentert leverandøratferd.

Hvorfor lykkes sporingsforespørselen min, men returnerer ingen hendelser?

Aksept av forespørselen og tilgjengelighet av sporingsdata er ulike resultater. Kontroller leverandørens svardetaljer, registreringskrav, regler for identifisering av transportør og dokumentert atferd for forsendelser uten hendelser. Ikke lag bevegelses- eller leveringsinformasjon for å fylle en tom tidslinje.

Beviser en vellykket simulert webhook at ekte webhooks vil komme frem?

Nei. Den beviser bare banen som ble testet av simuleringen. Ekte levering avhenger også av leverandørkonfigurasjon, offentlig tilgjengelighet, TLS, autentisering og den faktiske tilbakekallskontrakten. Valider dette med en leverandørstøttet testlevering eller en autorisert arbeidsflyt i produksjon.

Bør jeg returnere HTTP 200 før behandlingen er ferdig?

Følg leverandørens dokumenterte kontrakt for bekreftelse. I en asynkron utforming bør du bekrefte etter varig mottak og deretter behandle i en arbeider. Hvis du returnerer suksess før mottaket er varig, kan en hendelse gå tapt dersom prosessen feiler umiddelbart etterpå.

Hvordan bør jeg teste kundemeldinger?

Send alle utviklingsvarsler til en kontrollert sluse. Kontroller destinasjonen, malen, den utløsende overgangen og antallet sendinger. Spill av samme hendelse på nytt og simuler nye arbeiderforsøk for å kontrollere at én forsendelsesoppdatering ikke genererer gjentatte kundemeldinger.

Kilder

  • 17TRACK Tracking API — offisielt utgangspunkt for sporings-API-produktet.
  • 17TRACK API-dokumentasjon — referanse for leverandørens integrasjonskontrakt; bekreft gjeldende krav til testing og tilbakekall her.
  • RFC 9110: HTTP Semantics — semantikk for HTTP-svar og hensyn ved nye forespørselsforsøk.
  • RFC 2104: HMAC — den standardiserte konstruksjonen for meldingsautentisering som omtales i veiledningen om tilbakekallssikkerhet.