Skip to main content
DomovBlogVodnikiPreizkušanje integracije API-ja za sledenje v razvoju: peskovnik, testne številke, simulirani spletni kaveljci

Preizkušanje integracije API-ja za sledenje v razvoju: peskovnik, testne številke, simulirani spletni kaveljci

17TRACK

Za preizkušanje integracije API-ja za sledenje v razvojnem okolju uporabite tri dopolnilne metode: peskovnik ponudnika ali dokumentirane testne številke za preverjanje vedenja API-ja, lokalne testne podatke za ponovljive scenarije pošiljk ter lažne spletne kavlje za vašo sprejemno končno točko. Nato izvedite nadzorovano preverjanje v živo, da potrdite dele, ki jih simulacije ne morejo dokazati, vključno s poverilnicami, konfiguracijo naročnine in dejanskim dostavljanjem dogodkov.

Preizkušanje integracije API-ja za sledenje v razvojnem peskovniku in testnih številk

Ta vodnik je namenjen razvijalcem, ki povezujejo sledenje pošiljkam z e-trgovinsko platformo, sistemom za upravljanje naročil, ERP-sistemom ali storitvijo za obveščanje strank. Cilj ni zgolj prejeti uspešen odgovor API-ja. Dokazati morate, da posodobitve sledenja ustvarijo pravilno stanje naročila brez podvojenih sporočil, izgubljenih dogodkov ali nenamernega stika z resničnimi strankami.

Ločite vedenje ponudnika od vedenja aplikacije

Integracija sledenja ima vsaj dve meji: zahteve, ki jih vaša aplikacija pošilja ponudniku, ter posodobitve, ki jih vaša aplikacija pozneje prejme ali pridobi. Uspešna zahteva na prvi meji ne dokazuje, da druga meja deluje.

Načrt testiranja oblikujte okoli teh meja, namesto da bi pričakovali, da bo ena testna številka za sledenje preverila celoten sistem.

Način testiranjaKaj lahko preveriČesa sam ne more dokazati
Peskovnik ponudnikaPodprte oblike zahtev, preverjanje pristnosti in simulirano vedenje, ki ga opisuje ponudnikRazpoložljivosti podatkov prevoznikov v produkciji ali vedenja dostave v produkciji
Dokumentirane testne številkePosebne scenarije, dodeljene tem številkamDrugih statusov, prevoznikov ali zaporedij spletnih kavljev
Lokalni testni podatki in posnemovalniki API-jaVaš razčlenjevalnik, pravila preslikave, shranjevanje in obravnavo napakAli pravi ponudnik sprejema zahteve ali ustvarja enak tovor podatkov
Lažne zahteve spletnih kavljevObravnavo končne točke, preverjanje, odstranjevanje dvojnikov in učinke v nadaljnjih sistemihKonfiguracije povratnih klicev na strani ponudnika ali resničnih ponovnih poskusov dostave
Nadzorovani test v živoResnično povezljivost in opaženi potek pošiljkeVsake redke napake, izjeme ali zaporedja dostave

Priporočen pristop: lokalne teste naredite deterministične, kjer je mogoče uporabite testiranje, ki ga podpira ponudnik, pošiljke v živo pa prihranite za potrjevanje povezave med sistemi.

Pred izdelavo testnih podatkov potrdite pogodbo s ponudnikom

Začnite z uradno dokumentacijo različice API-ja, ki jo nameravate uporabljati. Potrdite osnovni URL, način preverjanja pristnosti, zahteve za registracijo, shemo odgovorov, nastavitev spletnih kavljev in vse dokumentirane možnosti testiranja. Ne sklepajte, da obstaja ločen peskovnik samo zato, ker ponudnik ponuja API.

Za integracijo 17TRACK uporabite stran API-ja za sledenje 17TRACK in uradno dokumentacijo API-ja kot izhodišče. Pred izdelavo primerov, specifičnih za ponudnika, tam preverite veljavne specifikacije zahtev in povratnih klicev. Spodnji primeri so namerno testni podatki v lasti aplikacije in ne predstavljajo sheme API-ja 17TRACK.

Pred povezavo razvojne kode z zunanjim računom razrešite ta vprašanja:

  • Ali so razvojne in produkcijske poverilnice ločene in do katerega okolja omogoča dostop posamezna poverilnica?
  • Ali peskovnik podpira povratne klice ali samo testiranje zahteva–odgovor?
  • Ali so testne številke dokumentirane in katere točne rezultate ustvarijo?
  • Ali lahko registracije ali druge testne zahteve porabijo kvoto računa ali ustvarijo trajne zapise?
  • Katera pravila preverjanja pristnosti povratnih klicev, potrditve, časovne omejitve in ponovnih poskusov so dokumentirana?
  • Kateri identifikatorji povezujejo registracijo sledenja, pošiljko, prevoznika in dogodek povratnega klica?

Če vedenje pri testiranju ni jasno dokumentirano, prosite ponudnika za potrditev. Medtem nadaljujte s testiranjem lastne logike obdelave s posnemovalniki. Nepotrjena zmožnost peskovnika je negotovost pri načrtovanju, ne dokaz, da ponudnik te zmožnosti nima.

Vzpostavite izolirano razvojno okolje

Uporabite ločeno zbirko podatkov ali izoliranega najemnika, ločene skrivnosti in sintetična naročila. E-pošto, SMS-sporočila in druga obvestila usmerite na testne prejemnike ali v ponor obvestil. Pošiljka, označena kot dostavljena v testnih podatkih, ne sme sprožiti sporočila resničnemu kupcu.

Notranjim zapisom in dnevnikom dodajte izrecno oznako okolja. Poverilnice ponudnika hranite na strežniku, zunaj nadzora različic, skrivnosti pa odstranite iz zajemov zahtev. Če je za povratne klice potreben začasen javni dostop, izpostavite samo predvideno razvojno pot in ohranite njene kontrole preverjanja pristnosti.

Pred pošiljanjem dogodkov ustvarite manjši nabor znanih naročil. Vključite dve pošiljki, povezani z enim naročilom, in, če vaša aplikacija to podpira, isti niz številke za sledenje v različnih kontekstih prevoznikov. Ti primeri razkrijejo predpostavke, da številka za sledenje sama vedno določa enoličen poslovni zapis.

Vnaprej določite pričakovani učinek vsakega testa: stanje pošiljke, povezavo z naročilom, vnose na časovnici, število obvestil in revizijski zapis. Tako predstavitev spremenite v trditev, ki je lahko uspešna ali neuspešna.

Testne številke uporabljajte samo za njihov dokumentirani namen

Številka za sledenje ima dve različni vlogi pri testiranju. Lahko je vhodni podatek za preverjanje registracije in lahko določa pošiljko, ki ustvarja dogodke sledenja. Številka, ki prestane preverjanje oblike, ni nujno uporabna za zgodovino dogodkov.

Ko so na voljo uradne testne številke

Ob vsaki številki zabeležite scenarij, ki ga je navedel ponudnik. Za številko, dokumentirano za dostavljeno pošiljko, ne smete predpostaviti, da simulira izjemo, vračilo ali neuspešen poskus dostave. Preverite tudi, ali je rezultat fiksen, se sčasoma spreminja ali zahteva izbiro določenega prevoznika.

Te številke hranite v namenski konfiguraciji integracijskih testov. Ne razpršite jih po testih enot, kjer bi lahko spreminjajoče se zunanje vedenje povzročilo nezanesljivost sicer determinističnih testov.

Ko uradne testne številke niso potrjene

V lastni aplikaciji uporabite sintetične identifikatorje in posnemajte mejo ponudnika. Nikoli ne izmišljajte verjetno izgledajoče številke in ne predpostavljajte, da je rezervirana za testiranje: lahko ustreza resnični pošiljki.

Za preverjanje v živo uporabite pošiljke, ki jih nadzorujete in do katerih imate dovoljen dostop. Izogibajte se kopiranju številk za sledenje iz javnih posnetkov zaslona ali pogovorov s strankami. Zgodovine pošiljk obravnavajte kot potencialno občutljive, saj lahko vsebujejo lokacije, časovne žige in podatke o dostavi.

Starejša dostavljena pošiljka lahko pomaga pri preverjanju razčlenjevanja, vendar je slaba odvisnost za neprekinjeno integracijo. Razpoložljivost zgodovinskih podatkov in zunanji odgovor se lahko spremenita. Za ponovljive teste ohranite saniran testni podatek, preverjanje v živo pa naj ostane ločeno.

Ustvarite testne podatke okoli pomembnih prehodov pošiljke

Testne podatke ustvarite iz dokumentirane sheme in, kadar so na voljo, saniranih resničnih odgovorov. Testne podatke ponudnika hranite ločeno od notranjega normaliziranega modela dogodkov. Preizkusite adapter med njima, da notranji posnemovalnik ne bi skril pokvarjenega razčlenjevalnika ponudnika.

Uporaben začetni nabor zajema te scenarije:

  • Še ni dogodkov sledenja: pošiljko ohranite, ne da bi trdili, da je v premiku ali dostavljena.
  • V tranzitu: posodobite časovnico in ohranite pravilno povezavo z naročilom.
  • Na dostavi: uporabite svojo politiko obveščanja, vendar dostave ne obravnavajte kot dokončane.
  • Dostavljeno: zabeležite dokončanje in enkrat sprožite predvideno poslovno dejanje.
  • Izjema ali poskus dostave: ohranite razlikovanje od dokončane dostave.
  • Vračilo: vsakega poznejšega skeniranja ne razlagajte kot napredovanje proti prvotnemu prejemniku.
  • Neznan status: ohranite dovolj informacij za diagnozo, ne da bi si izmislili preslikavo statusa.

Za te scenarije uporabite lastna normalizirana imena, nato pa dokumentirane vrednosti ponudnika izrecno preslikajte vanje. Ne predpostavljajte, da različni API-ji uporabljajo enake oznake statusov ali da ima oznaka povsod enak poslovni pomen.

Spreminjajte tudi obliko podatkov: prazen seznam dogodkov, manjkajoča neobvezna polja, dodatna neznana polja, imena lokacij Unicode, časovni žigi z odmiki časovnih pasov in napačne zahtevane vrednosti. Razčlenjevalnik mora prenesti združljive dodatke, hkrati pa zavrniti podatke, ki jih ni mogoče varno obdelati.

Lažne spletne kavlje pošljite skozi pravo sprejemno pot

Lažni spletni kavelj mora preizkusiti sprejemno pot, vmesno programsko opremo za preverjanje pristnosti, preverjanje veljavnosti, shranjevanje in obdelavo delavca — ne zgolj poklicati končne funkcije za posodobitev statusa.

Naslednji tovor podatkov predstavlja sintetični notranji dogodek. Imena polj, ID dogodka in status so ponazoritveni; ne predstavljajo pogodbe povratnega klica ponudnika.

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

Shranite ga kot tracking-event.json in ga pošljite lokalnemu testnemu sprejemniku:

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

Ta ukaz preverja samo lokalno usmerjanje in obravnavo. Ne dokazuje preverjanja pristnosti ponudnika. Razvojna pot naj bo v produkciji nedostopna ali pa produkcijski sprejemnik testirajte z dokumentirano metodo preverjanja pristnosti ponudnika in ločeno testno skrivnostjo.

Preverite pristnost, ne da bi oslabili produkcijske kontrole

Če ponudnik določa podpisane povratne klice, uvedite točno to shemo, namesto da izberete poljubno glavo ali algoritem podpisa. Pri shemah, ki podpisujejo bajte zahteve, ohranite izvirno telo za preverjanje; razčlenjevanje in ponovno serializiranje JSON-a lahko te bajte spremeni.

Po potrebi preizkusite veljavno preverjanje pristnosti, manjkajoče poverilnice, spremenjena telesa in napačne podpise. Če dokumentirana shema vključuje časovne žige ali zaščito pred ponovnim predvajanjem, preizkusite tudi ta pravila. HMAC je standardizirana konstrukcija za preverjanje pristnosti sporočil, vendar njegov obstoj ne dokazuje, da ga uporablja določen ponudnik sledenja.

Preizkusite dvojnike, vrstni red in obnovitev

Obdelava pošiljk mora ostati pravilna, ko ista posodobitev prispe večkrat ali ko dogodki prispejo v nepričakovanem vrstnem redu. To so obrambni testni scenariji in ne trditve o jamstvu dostave določenega ponudnika.

TestPričakovano vedenje aplikacije
Pošljite isti dogodek dvakratOhranite en logični dogodek in preprečite podvojena obvestila strankam.
Po dostavi pošljite starejši tranzitni pregledOhranite uporabno zgodovino, ne da bi samodejno razveljavili stanje dostave.
Pošljite sočasne posodobitveKljub sočasnim delavcem uporabite dosledne prehode stanj.
Po trajnem prejemu ustavite obdelavoObnovite in obdelajte shranjeni dogodek brez novega povratnega klica.
Pred trajnim prejemom naj shranjevanje odpoveNe potrjujte lažno uspešnega sprejema.
Pošljite neznano pošiljkoSledite opredeljeni politiki karantene ali zavrnitve; nikoli ne ugibajte povezave z naročilom.

Za odstranjevanje dvojnikov po možnosti uporabite dokumentiran stabilen identifikator dogodka. Sicer določite skrbno omejeno identiteto iz ustreznih polj in preizkusite trke. Sama številka za sledenje ni identiteta dogodka, saj lahko ena pošiljka ustvari številne legitimne posodobitve.

Zgodovino dogodkov ločite od trenutne projekcije pošiljke. Hranjenje zgodovinskih pregledov ne pomeni, da mora vsak pozno prispeli pregled prepisati prikazani status. Prav tako pravilo »uporabi najnovejši časovni žig« ni popolno: popravki, tokovi vračil in različni pomeni časovnih žigov zahtevajo izrecno obravnavo.

Pri asinhroni obdelavi potrdite prejem šele, ko dogodek glede na vašo arhitekturo doseže trajno točko predaje, kot sta potrjen zapis v vhodnem nabiralniku ali trajna čakalna vrsta. Upoštevajte dokumentirane zahteve ponudnika glede potrditve. HTTP določa semantiko statusnih kod, vendar mora urnik ponovnih poskusov določenega pošiljatelja izhajati iz njegove pogodbe.

Izvedite nadzorovano preverjanje v živo in določite merila za izdajo

Ko deterministični testi uspejo, prek prave integracije registrirajte pošiljko, do katere imate dovoljen dostop, in potrdite celotno pot. Preverite, ali je ponudnik sprejel predvideni zapis, ali konfiguracija povratnega klica kaže na pravilno okolje in ali se vhodni podatki preslikajo v pričakovano pošiljko.

Med tem preverjanjem v živo ne zahtevajte, da se prikaže vsak status pošiljke. Resničnih pošiljk ni mogoče nadzorovati kot testnih podatkov. Preverjanje v živo uporabite za potrjevanje povezljivosti in združljivosti opažene pogodbe; redke ali uničujoče scenarije pokrijte s ponovljivimi testnimi podatki.

Pred izdajo zahtevajte naslednje rezultate:

  • Dokumentirani uspešni odgovori in odgovori z napakami so obravnavani, vključno z napakami na ravni elementov, če API podpira paketne operacije.
  • Časovne omejitve ne sprožijo slepih ponovnih poskusov ustvarjanja, kadar je prva zahteva morda že uspela.
  • Podvojeni dogodki ne morejo ustvariti podvojenih poslovnih dejanj.
  • Neveljavni povratni klici ne morejo spremeniti stanja pošiljke.
  • Napake delavcev pustijo obnovljive dogodke, namesto da bi se tiho izgubili.
  • Razvojni promet ne more obvestiti resničnih strank ali spreminjati produkcijskih naročil.
  • Dnevniki povezujejo zahteve, prejete dogodke, rezultate obdelave in poskuse obveščanja, ne da bi razkrivali skrivnosti.

Izdaja je pripravljena, ko lahko razložite običajni potek in način obnovitve sistema po negotovi zahtevi, ponovljenem povratnem klicu ali prekinjenem delavcu. En sam uspešen vpogled v sledenje ni dovolj.

Pogosta vprašanja

Ali lahko integracijo sledenja preizkusim brez peskovnika?

Da. Posnemajte izhodno mejo API-ja, predvajajte dokumentirane testne podatke povratnih klicev ter lokalno preizkusite normalizacijo in poslovna pravila. Nato uporabite pošiljko z dovoljenim dostopom v živo, da potrdite dejansko povezljivost. To zagotavlja precejšnjo pokritost, vendar ne posnema nedokumentiranega vedenja ponudnika.

Zakaj je moja zahteva za sledenje uspešna, vendar ne vrne nobenega dogodka?

Sprejem zahteve in razpoložljivost podatkov sledenja sta različna rezultata. Preverite podrobnosti odgovora ponudnika, zahteve za registracijo, pravila identifikacije prevoznika in dokumentirano vedenje za pošiljke brez dogodkov. Ne ustvarjajte podatkov o premiku ali dostavi, da bi zapolnili prazno časovnico.

Ali uspešen lažni spletni kavelj dokazuje, da bodo prispeli tudi resnični spletni kavlji?

Ne. Dokazuje samo pot, ki jo je preizkusil posnemovalnik. Resnična dostava je odvisna tudi od konfiguracije ponudnika, javne dosegljivosti, TLS-a, preverjanja pristnosti in dejanske pogodbe povratnega klica. To preverite s testno dostavo, ki jo podpira ponudnik, ali z dovoljenim potekom v živo.

Ali naj HTTP 200 vrnem, preden se obdelava konča?

Upoštevajte dokumentirano pogodbo ponudnika glede potrditve. Pri asinhroni zasnovi potrdite po trajnem sprejemu, nato pa obdelavo izvedite v delavcu. Vračanje uspeha pred trajnim sprejemom lahko povzroči izgubo dogodka, če proces takoj zatem odpove.

Kako naj preizkusim obvestila strankam?

Vsa razvojna obvestila pošljite v nadzorovani ponor. Preverite cilj, predlogo, sprožilni prehod in število pošiljanj. Ponovite isti dogodek in simulirajte ponovne poskuse delavca, da preverite, ali ena posodobitev pošiljke ne ustvari ponavljajočih se sporočil strankam.

Viri

  • API za sledenje 17TRACK — uradno izhodišče za izdelek API-ja za sledenje.
  • Dokumentacija API-ja 17TRACK — referenca za integracijsko pogodbo, specifično za ponudnika; tukaj potrdite veljavne zahteve glede testiranja in povratnih klicev.
  • RFC 9110: Semantika HTTP — semantika odgovorov HTTP in vidiki ponavljanja zahtev.
  • RFC 2104: HMAC — standardizirana konstrukcija za preverjanje pristnosti sporočil, obravnavana v navodilih za varnost povratnih klicev.