Skip to main content
ПочетакБлогVodičiTestiranje integracije API-ja za praćenje u razvojnom okruženju: sandbox, testni brojevi, simulirani webhook-ovi

Testiranje integracije API-ja za praćenje u razvojnom okruženju: sandbox, testni brojevi, simulirani webhook-ovi

17TRACK

Da biste testirali integraciju API-ja za praćenje u razvojnom okruženju, koristite tri komplementarne metode: sandbox provajdera ili dokumentovane testne brojeve za ponašanje API-ja, lokalne testne podatke za ponovljive scenarije pošiljki i simulirane webhook-ove za krajnju tačku koja prima podatke. Zatim sprovedite kontrolisanu proveru uživo da biste potvrdili delove koje simulacije ne mogu da dokažu, uključujući akreditive, konfiguraciju pretplate i stvarnu isporuku događaja.

Testiranje integracije API-ja za praćenje u razvojnom sandbox okruženju i testni brojevi

Ovaj vodič je namenjen programerima koji povezuju praćenje pošiljki sa platformom za e-trgovinu, sistemom za upravljanje porudžbinama, ERP sistemom ili servisom za obaveštavanje korisnika. Cilj nije samo primanje uspešnog odgovora API-ja. Potrebno je dokazati da ažuriranja praćenja proizvode ispravno stanje porudžbine bez duplih poruka, izgubljenih događaja ili slučajnog kontakta sa stvarnim korisnicima.

Razdvojite ponašanje provajdera od ponašanja aplikacije

Integracija praćenja ima najmanje dve granice: zahteve koje vaša aplikacija šalje provajderu i ažuriranja koja vaša aplikacija naknadno prima ili preuzima. Uspešan zahtev na prvoj granici ne potvrđuje da druga granica funkcioniše.

Napravite plan testiranja oko tih granica, umesto da očekujete da jedan testni broj za praćenje obuhvati ceo sistem.

Metod testiranjaŠta može da potvrdiŠta sam ne može da potvrdi
Sandbox provajderaPodržane formate zahteva, autentifikaciju i simulirano ponašanje koje je provajder opisaoDostupnost podataka stvarnog prevoznika u produkciji ili ponašanje produkcione isporuke
Dokumentovani testni brojeviOdređene scenarije dodeljene tim brojevimaDruga stanja, prevoznike ili sekvence webhook-ova
Lokalni testni podaci i API mock-oviVaš parser, pravila mapiranja, čuvanje podataka i obradu grešakaDa li stvarni provajder prihvata zahteve ili šalje isti payload
Simulirani webhook zahteviObradu krajnje tačke, validaciju, uklanjanje duplikata i naknadne efekteKonfiguraciju povratnih poziva na strani provajdera ili stvarne ponovne pokušaje isporuke
Kontrolisani test uživoStvarnu povezanost i posmatrani tok pošiljkeSvaku retku grešku, izuzetak ili sekvencu isporuke

Preporučeni pristup: učinite lokalne testove determinističkim, koristite testiranje koje provajder podržava kada je dostupno, a stvarne pošiljke koristite samo za potvrđivanje veze između sistema.

Potvrdite ugovor sa provajderom pre pisanja testnih podataka

Počnite od zvanične dokumentacije za verziju API-ja koju nameravate da koristite. Potvrdite osnovni URL, metod autentifikacije, zahteve za registraciju, šemu odgovora, podešavanje webhook-a i sve dokumentovane mogućnosti testiranja. Nemojte zaključiti da postoji zaseban sandbox samo zato što provajder nudi API.

Za integraciju sa 17TRACK-om koristite stranicu 17TRACK Tracking API i zvaničnu API dokumentaciju kao početne tačke. Pre izrade primera specifičnih za provajdera proverite tamo primenljive specifikacije zahteva i povratnih poziva. Primeri u nastavku su namerno testni podaci kojima upravlja aplikacija, a ne prikazi šeme 17TRACK API-ja.

Razjasnite sledeća pitanja pre povezivanja razvojnog koda sa spoljnim nalogom:

  • Da li su razvojni i produkcioni akred govori odvojeni i kom okruženju svaki akreditiv daje pristup?
  • Da li sandbox podržava povratne pozive ili samo testiranje zahtev–odgovor?
  • Da li su testni brojevi dokumentovani i koje tačne ishode proizvode?
  • Da li registracije ili drugi testni zahtevi mogu da troše kvotu naloga ili kreiraju trajne zapise?
  • Koja su dokumentovana pravila za autentifikaciju povratnih poziva, potvrdu prijema, vremensko ograničenje i ponovne pokušaje?
  • Koji identifikatori povezuju registraciju praćenja, pošiljku, prevoznika i događaj povratnog poziva?

Ako ponašanje pri testiranju nije jasno dokumentovano, zatražite potvrdu od provajdera. U međuvremenu nastavite da testirate sopstvenu logiku obrade pomoću mock-ova. Nepotvrđena mogućnost sandbox-a predstavlja neizvesnost u planiranju, a ne dokaz da provajder tu mogućnost nema.

Napravite izolovano razvojno okruženje

Koristite zasebnu bazu podataka ili izolovan tenant, odvojene tajne i sintetičke porudžbine. E-poštu, SMS poruke i druga obaveštenja usmerite na testne odredišne adrese ili servis za prihvat obaveštenja. Pošiljka označena kao isporučena u testnim podacima ne sme da pokrene poruku stvarnom kupcu.

Dodajte eksplicitnu oznaku okruženja internim zapisima i evidencijama. Akreditive provajdera čuvajte na serveru, izvan kontrole verzija, i uklonite tajne iz snimaka zahteva. Ako su za povratne pozive potrebni privremeni javni pristup i dostupnost, izložite samo predviđenu razvojnu rutu i zadržite njene kontrole autentifikacije.

Pre slanja događaja kreirajte mali skup poznatih porudžbina. Uključite dve pošiljke povezane sa jednom porudžbinom i, ako vaša aplikacija to podržava, isti tekst broja za praćenje u kontekstu različitih prevoznika. Ovi slučajevi otkrivaju pretpostavke da broj za praćenje sam po sebi uvek identifikuje jedinstveni poslovni zapis.

Unapred definišite očekivani efekat svakog testa: stanje pošiljke, povezanost sa porudžbinom, stavke vremenske linije, broj obaveštenja i revizijski zapis. Tako se demonstracija pretvara u tvrdnju koja može proći ili pasti.

Testne brojeve koristite samo za dokumentovanu namenu

Broj za praćenje ima dve različite uloge u testiranju. Može biti ulaz koji se koristi za potvrđivanje registracije, a može i identifikovati pošiljku koja proizvodi događaje praćenja. Broj koji prođe validaciju formata ne mora nužno da pruži korisnu istoriju događaja.

Kada su zvanični testni brojevi dostupni

Uz svaki broj zabeležite scenario koji je provajder naveo. Ne treba pretpostaviti da broj dokumentovan za isporučenu pošiljku simulira izuzetak, povrat ili neuspešan pokušaj isporuke. Takođe proverite da li je rezultat fiksan, da li se menja tokom vremena ili zahteva izbor određenog prevoznika.

Ove brojeve čuvajte u posebnoj konfiguraciji integracionih testova. Nemojte ih rasipati po jediničnim testovima, gde promena spoljnog ponašanja može učiniti inače determinističke testove nepouzdanim.

Kada zvanični testni brojevi nisu potvrđeni

Koristite sintetičke identifikatore unutar sopstvene aplikacije i simulirajte granicu provajdera. Nikada nemojte izmisliti broj koji izgleda uverljivo i pretpostaviti da je rezervisan za testiranje: može odgovarati stvarnoj pošiljci.

Za validaciju uživo koristite pošiljke koje kontrolišete i kojima ste ovlašćeni da pristupate. Izbegavajte kopiranje brojeva za praćenje sa javnih snimaka ekrana ili iz razgovora sa korisnicima. Istoriju pošiljke tretirajte kao potencijalno osetljivu jer može sadržati lokacije, vremenske oznake i podatke o isporuci.

Starija isporučena pošiljka može pomoći pri proveri parsiranja, ali je loša zavisnost za kontinuiranu integraciju. Dostupnost istorijskih podataka i spoljni odgovor mogu se promeniti. Sačuvajte anonimizovani testni podatak za ponovljive testove, a proveru uživo držite odvojeno.

Kreirajte testne podatke oko značajnih prelaza pošiljke

Testne podatke gradite na osnovu dokumentovane šeme i, kada su dostupni, anonimizovanih stvarnih odgovora. Testne podatke provajdera držite odvojeno od internog normalizovanog modela događaja. Testirajte adapter između njih kako interni mock ne bi prikrio neispravan parser provajdera.

Koristan početni skup obuhvata sledeće scenarije:

  • Još nema događaja praćenja: zadržite pošiljku bez tvrdnje da je u kretanju ili isporučena.
  • U tranzitu: ažurirajte vremensku liniju i sačuvajte ispravnu povezanost sa porudžbinom.
  • Na dostavi: primenite pravila obaveštavanja bez tretiranja isporuke kao završene.
  • Isporučeno: zabeležite završetak i jednom pokrenite predviđenu poslovnu radnju.
  • Izuzetak ili pokušaj isporuke: sačuvajte razliku u odnosu na završenu isporuku.
  • Povratno kretanje: izbegavajte tumačenje svakog kasnijeg skeniranja kao napretka ka prvobitnom primaocu.
  • Nepoznato stanje: zadržite dovoljno informacija za dijagnostiku bez izmišljanja mapiranja stanja.

Za ove scenarije koristite sopstvene normalizovane nazive, a zatim eksplicitno mapirajte dokumentovane vrednosti provajdera na njih. Nemojte pretpostaviti da različiti API-ji koriste iste oznake stanja ili da oznaka svuda ima isto poslovno značenje.

Takođe menjajte oblik podataka: praznu listu događaja, nedostajuća opciona polja, dodatna nepoznata polja, Unicode nazive lokacija, vremenske oznake sa pomacima vremenske zone i neispravne obavezne vrednosti. Parser treba da prihvati kompatibilna proširenja, a da odbije podatke koji se ne mogu bezbedno obraditi.

Šaljite simulirane webhook-ove kroz stvarnu putanju prijema

Simulirani webhook treba da prođe kroz prijemnu rutu, međuprogram za autentifikaciju, validaciju, čuvanje podataka i obradu radnika — ne samo da pozove završnu funkciju za ažuriranje stanja.

Sledeći payload predstavlja sintetički interni događaj. Nazivi polja, ID događaja i stanje služe kao ilustracija; oni nisu ugovor za povratni poziv provajdera.

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

Sačuvajte ga kao tracking-event.json i pošaljite lokalnom testnom prijemniku:

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

Ova komanda potvrđuje samo lokalno rutiranje i obradu. Ne dokazuje autentifikaciju provajdera. Razvojnu rutu namenjenu samo razvoju držite nedostupnom u produkciji ili testirajte produkcioni prijemnik koristeći dokumentovani metod autentifikacije provajdera i zasebnu testnu tajnu.

Testirajte autentifikaciju bez slabljenja produkcionih kontrola

Ako provajder navodi potpisane povratne pozive, implementirajte upravo tu šemu umesto proizvoljnog zaglavlja potpisa ili algoritma. Kod šema koje potpisuju bajtove zahteva zadržite originalno telo radi provere; parsiranje i ponovno serijalizovanje JSON-a mogu promeniti te bajtove.

Testirajte ispravnu autentifikaciju, nedostajuće akreditive, izmenjena tela i neispravne potpise gde je primenljivo. Ako dokumentovana šema uključuje vremenske oznake ili zaštitu od ponovne reprodukcije, testirajte i ta pravila. HMAC je standardizovana konstrukcija za autentifikaciju poruka, ali njegovo postojanje ne dokazuje da ga određeni provajder praćenja koristi.

Testirajte duplikate, redosled i oporavak

Obrada pošiljki treba da ostane ispravna kada isto ažuriranje stigne više puta ili kada događaji stignu neočekivanim redosledom. Ovo su defanzivni testni scenariji, a ne tvrdnje o garanciji isporuke određenog provajdera.

TestOčekivano ponašanje aplikacije
Pošaljite isti događaj dva putaZadržite jedan logički događaj i izbegnite duplirana obaveštenja korisnicima.
Pošaljite starije skeniranje u tranzitu nakon isporukeSačuvajte korisnu istoriju bez automatskog vraćanja stanja isporuke.
Pošaljite istovremena ažuriranjaPrimenite dosledne prelaze stanja uprkos istovremenim radnicima.
Zaustavite obradu nakon trajnog prijemaOporavite se i obradite sačuvani događaj bez zahteva za novim povratnim pozivom.
Izazovite grešku u čuvanju pre trajnog prijemaNemojte lažno potvrditi uspešno prihvatanje.
Pošaljite nepoznatu pošiljkuSledite definisanu politiku karantina ili odbijanja; nikada ne nagađajte povezanost sa porudžbinom.

Kada je dostupan, za uklanjanje duplikata prednost dajte dokumentovanom stabilnom identifikatoru događaja. U suprotnom pažljivo definišite identitet na osnovu relevantnih polja i testirajte kolizije. Sam broj za praćenje nije identitet događaja jer jedna pošiljka može proizvesti mnogo legitimnih ažuriranja.

Odvojite istoriju događaja od trenutne projekcije pošiljke. Čuvanje istorijskih skeniranja ne znači da svako kasno pristiglo skeniranje treba da prepiše prikazano stanje. Pravilo „koristi najnoviju vremensku oznaku“ takođe nije potpuno: ispravke, tokovi povrata i različita značenja vremenskih oznaka zahtevaju eksplicitnu obradu.

Kod asinhrone obrade potvrdu pošaljite tek nakon što događaj stigne do trajne tačke predaje, kao što je potvrđen zapis u inboxu ili trajni red, u skladu sa vašom arhitekturom. Sledite dokumentovane zahteve provajdera za potvrdu prijema. HTTP definiše semantiku statusnih kodova, ali raspored ponovnih pokušaja određenog pošiljaoca mora proisteći iz njegovog ugovora.

Sprovedite kontrolisanu proveru uživo i postavite kriterijume za objavljivanje

Kada deterministički testovi prođu, registrujte ovlašćenu pošiljku kroz stvarnu integraciju i potvrdite ceo tok. Proverite da li je provajder prihvatio predviđeni zapis, da konfiguracija povratnog poziva pokazuje na ispravno okruženje i da se dolazni podaci mapiraju na očekivanu pošiljku.

Nemojte zahtevati da se svako stanje pošiljke pojavi tokom te provere uživo. Stvarne pošiljke nisu kontrolisani testni podaci. Pokretanje uživo koristite za proveru povezanosti i uočene kompatibilnosti ugovora; ponovljive testne podatke koristite za retke ili destruktivne scenarije.

Pre objavljivanja zahtevajte sledeće ishode:

  • Dokumentovani uspješni odgovori i odgovori na greške se obrađuju, uključujući greške na nivou stavke ako API podržava grupne operacije.
  • Vremenska ograničenja ne pokreću slepe ponovne pokušaje kreiranja kada je prvi zahtev možda već uspeo.
  • Duplirani događaji ne mogu da kreiraju duplirane poslovne radnje.
  • Nevažeći povratni pozivi ne mogu da promene stanje pošiljke.
  • Greške radnika ostavljaju događaje koji se mogu oporaviti umesto da ih tiho izgube.
  • Razvojni saobraćaj ne može da obavesti stvarne korisnike ili menja produkcione porudžbine.
  • Evidencije povezuju zahteve, primljene događaje, rezultate obrade i pokušaje slanja obaveštenja bez izlaganja tajni.

Objavljivanje je spremno kada možete da objasnite i normalan tok rada i način na koji se sistem oporavlja nakon neizvesnog zahteva, ponovljenog povratnog poziva ili prekinutog radnika. Jedan uspešan upit za praćenje nije dovoljan.

Česta pitanja

Da li mogu da testiram integraciju praćenja bez sandbox-a?

Da. Simulirajte izlaznu granicu API-ja, ponovo reprodukujte dokumentovane testne podatke povratnih poziva i lokalno testirajte normalizaciju i poslovna pravila. Zatim koristite ovlašćenu pošiljku uživo da potvrdite stvarnu povezanost. Ovo pruža značajnu pokrivenost, ali ne reprodukuje nedokumentovano ponašanje provajdera.

Zašto moj zahtev za praćenje uspeva, ali ne vraća događaje?

Prihvatanje zahteva i dostupnost podataka o praćenju različiti su ishodi. Proverite detalje odgovora provajdera, zahteve za registraciju, pravila identifikacije prevoznika i dokumentovano ponašanje za pošiljke bez događaja. Nemojte izmišljati podatke o kretanju ili isporuci da biste popunili praznu vremensku liniju.

Da li uspešan simulirani webhook dokazuje da će stvarni webhook-ovi stići?

Ne. On dokazuje samo putanju koju je simulacija obuhvatila. Stvarna isporuka zavisi i od konfiguracije provajdera, javne dostupnosti, TLS-a, autentifikacije i stvarnog ugovora za povratni poziv. Potvrdite to testnom isporukom koju provajder podržava ili ovlašćenim tokom uživo.

Da li treba da vratim HTTP 200 pre završetka obrade?

Sledite dokumentovani ugovor provajdera o potvrdi prijema. U asinhronom dizajnu potvrdite prijem nakon trajnog prihvatanja, a zatim obradite događaj u radniku. Vraćanje uspeha pre trajnog prihvatanja može izgubiti događaj ako proces odmah nakon toga otkaže.

Kako treba da testiram obaveštenja korisnicima?

Sva razvojna obaveštenja šaljite u kontrolisani prijemnik. Potvrdite odredište, šablon, prelaz koji je pokrenuo slanje i broj slanja. Ponovo reprodukujte isti događaj i simulirajte ponovne pokušaje radnika kako biste proverili da jedno ažuriranje pošiljke ne generiše ponovljene poruke korisniku.

Izvori

  • 17TRACK Tracking API — zvanična početna tačka za proizvod API-ja za praćenje.
  • 17TRACK API documentation — referenca za integracioni ugovor specifičan za provajdera; ovde potvrdite primenljive zahteve za testiranje i povratne pozive.
  • RFC 9110: HTTP Semantics — semantika HTTP odgovora i razmatranja za ponavljanje zahteva.
  • RFC 2104: HMAC — standardizovana konstrukcija za autentifikaciju poruka razmatrana u smernicama za bezbednost povratnih poziva.