Skip to main content
ПочетакБлогVodičiTok rada API-ja za praćenje pošiljke: od registracije pošiljke do preuzimanja detalja praćenja

Tok rada API-ja za praćenje pošiljke: od registracije pošiljke do preuzimanja detalja praćenja

17TRACK

Tok rada API-ja za praćenje pošiljaka počinje slanjem broja za praćenje i svih potrebnih podataka o prevozniku, proverom da li je registracija uspešna, čekanjem da podaci o praćenju postanu dostupni i preuzimanjem statusa pošiljke i istorije događaja. Za integraciju u produkcionom okruženju, programeri takođe moraju da povežu svaki zapis praćenja sa porudžbinom, obrade delimične greške, bezbedno obrađuju ažuriranja i razlikuju prihvaćenu registraciju od stvarnog skeniranja kod prevoznika.

Tok rada Shipment Tracking API-ja od registracije pošiljke do preuzimanja

Ovaj vodič objašnjava taj tok rada programerima koji povezuju platformu za e-trgovinu, sistem za upravljanje porudžbinama, aplikaciju skladišta ili alat za korisničku podršku. On odvaja preporuke za dizajn aplikacije od zahteva specifičnih za provajdera. Za integraciju sa 17TRACK-om, koristite zvaničnu API dokumentaciju da biste pre implementacije primera u nastavku potvrdili šemu zahteva, autentifikaciju, podržane operacije i polja odgovora.

Razumevanje onoga što registracija omogućava — i onoga što ne omogućava

Registracija pošiljke kod servisa za praćenje znači slanje identifikatora kako bi servis mogao da prati ili upravlja tom pošiljkom u skladu sa svojim API ugovorom. To nije ista operacija kao kupovina poštarine, generisanje nalepnice za slanje, zakazivanje preuzimanja ili predaja paketa prevozniku.

U aplikaciji razdvojite tri ishoda:

  • Zahtev primljen: API je vratio odgovor na vaš HTTP zahtev.
  • Registracija prihvaćena: Servis je prihvatio pojedinačni zapis praćenja na obradu.
  • Informacije o praćenju dostupne: Servis ima informacije o pošiljci koje vaša aplikacija može da preuzme ili primi.

Ove ishode ne treba svoditi na jednu oznaku „uspešno“. Prihvaćen broj za praćenje možda još nema događaje prevoznika. Isto tako, uspešan HTTP odgovor za grupni zahtev ne znači da je svaka stavka u grupi prihvaćena; proverite strukturu rezultata na nivou aplikacije koju definiše provajder.

1. Pripremite identitet pošiljke i konfiguraciju API-ja

Pre slanja zahteva za registraciju odlučite kako će pošiljka biti identifikovana u vašem sistemu. Sam identifikator porudžbine obično nije dovoljan jer jedna porudžbina može biti podeljena na više paketa. Svakoj pošiljci ili paketu dodelite sopstveni interni zapis i povežite taj zapis sa odgovarajućom porudžbinom.

Koristan interni zapis obuhvata sledeće informacije. Ovo su predložena polja aplikacije, a ne šema zahteva za 17TRACK.

  • Interni ID pošiljke: Stabilni identifikator paketa.
  • Referenca porudžbine: Porudžbina ili zapis ispunjenja porudžbine kojem pošiljka pripada.
  • Broj za praćenje: Identifikator koji je izdao prevoznik, sačuvan kao tekst kako bi se sačuvale vodeće nule.
  • Podaci o prevozniku: Identitet prevoznika koji je dostavio vaš sistem za ispunjenje porudžbine, ako je poznat.
  • Referenca provajdera: Identifikator koji je vratio servis za praćenje i koji je potreban za kasnije operacije.
  • Stanje registracije: Evidencija o tome da li je slanje na čekanju, prihvaćeno, odbijeno ili čeka usklađivanje.
  • Stanje praćenja: Najnoviji status pošiljke, koji se vodi odvojeno od stanja registracije.

Proverite ulazne podatke pre slanja. Uklonite slučajne razmake oko vrednosti, ali nemojte menjati broj za praćenje na osnovu pretpostavki o formatu prevoznika. Sačuvajte originalnu vrednost radi rešavanja problema. Ako je prevoznik poznat, mapirajte ga na dokumentovani identifikator prevoznika kod provajdera umesto slanja neformalnog naziva za prikaz.

Konfigurišite autentifikaciju na serverskoj strani. Čuvajte akreditive van sistema za kontrolu izvornog koda, odvojite razvojnu i produkcionu konfiguraciju i uklonite tajne iz dnevnika. Potvrdite dokumentovanu verziju API-ja, ograničenja zahteva, ograničenja grupa i zahteve naloga, umesto da preuzimate vrednosti iz nepovezane integracije.

2. Registrujte pošiljku i sačuvajte rezultat na nivou stavke

Pošaljite zapis praćenja koristeći operaciju registracije opisanu u dokumentaciji provajdera. Uključite samo obavezna polja i opcione informacije koje imaju jasno definisanu svrhu. Nemojte slati imena kupaca, adrese ili druge lične podatke samo zato što su dostupni u bazi porudžbina.

Sledeći pseudokod prikazuje redosled operacija u aplikaciji. Nazivi funkcija su ilustrativni; oni nisu API krajnje tačke niti metode SDK-a.

shipment = load_internal_shipment(shipment_id)
validate_tracking_input(shipment)

result = tracking_adapter.register(shipment)

if result.item_accepted:
    save_registration_result(shipment_id, result)
elif result.outcome_unknown:
    schedule_registration_reconciliation(shipment_id)
else:
    save_registration_error(shipment_id, result)
    route_for_retry_or_correction(result)

Sačuvajte dovoljno informacija da se objasni šta se dogodilo: interni ID pošiljke, vreme slanja, broj pokušaja, ishod na nivou stavke i svaku referencu zahteva provajdera. Nemojte se oslanjati samo na privremeni dnevnik radnika. Timovima korisničke podrške i operacija potreban je trajan odgovor na pitanje da li je pošiljka uspešno uključena u praćenje.

Grupna slanja obrađujte pojedinačno

Ako API podržava grupnu registraciju, povežite svaku vraćenu stavku sa originalnom pošiljkom. Nemojte označiti celu grupu kao prihvaćenu samo zato što je HTTP zahtev uspešno završen. Sačuvajte prihvaćene stavke, izdvojite odbijene i zasebno istražite nejasne rezultate.

Tako se sprečava da jedan neispravan broj za praćenje izazove nepotrebno ponovno slanje zapisa koji su već uspešni. Operativnom osoblju se takođe pruža konkretna lista zapisa koje treba ispraviti.

Ishod isteka vremena tretirajte kao nepoznat

Istek vremena ne dokazuje da registracija nije uspela. Provajder je možda prihvatio zahtev pre nego što je veza prekinuta. Koristite dokumentovano ponašanje idempotentnosti, obradu duplikata ili operacije pretrage da biste uskladili rezultat pre ponovnog slanja bez provere.

Ako ponašanje provajdera pri duplikatima nije jasno, testirajte ga sa kontrolisanim zapisima i potvrdite ugovor pre uključivanja automatskih ponovnih pokušaja. Interno uklanjanje duplikata poslova registracije i dalje je korisno, ali ne zamenjuje razumevanje načina na koji udaljeni servis obrađuje ponovljene zahteve.

3. Omogućite da stignu prve informacije o praćenju

Nakon prihvatanja registracije, detalji praćenja možda neće odmah biti dostupni. Nalepnica može postojati pre nego što prevoznik zabeleži fizički događaj rukovanja. Nedostatak informacija može zahtevati i proveru broja za praćenje, izbora prevoznika ili zahteva za pretragu koji su specifični za pošiljku.

Ovo stanje predstavite eksplicitno. „Registrovano; čeka se informacija o praćenju“ tačnije je od „U tranzitu“ ili „Registracija nije uspela“. Nemojte izmišljati procenu isporuke ili događaj kretanja da biste popunili prazan interfejs.

Kada zapis ostane prazan, proveravajte sledećim praktičnim redosledom:

  1. Potvrdite da je pojedinačna registracija prihvaćena.
  2. Uporedite poslati broj za praćenje sa zapisom ispunjenja porudžbine.
  3. Proverite mapiranje prevoznika i sve dokumentovane dodatne zahteve za pretragu.
  4. Na sopstvenoj stranici prevoznika proverite praćenje iste pošiljke.
  5. Ako prevoznik ima događaje, a vaša integracija ih nema, proverite odgovore pri preuzimanju i kontaktirajte provajdera API-ja sa redigovanim dijagnostičkim informacijama.

Izbegavajte uvođenje univerzalnog perioda čekanja bez dokaza. Pravila eskalacije treba da odražavaju uslugu slanja, očekivani proces predaje i vaše operativne obaveze.

4. Preuzmite detalje praćenja i pravilno ih protumačite

Kada zapis postane dostupan, pozovite dokumentovanu operaciju za detalje praćenja koristeći identifikatore koje ona zahteva. Nemojte pretpostaviti da registracija i preuzimanje prihvataju ista polja. Neki API ugovori razlikuju brojeve za praćenje, identifikatore prevoznika i reference zapisa koje generiše provajder.

Aplikacija treba da razlikuje tri nivoa informacija:

  • Sažetak pošiljke: Ukupno stanje koje se koristi na kontrolnim tablama, stranicama porudžbina i u operativnim filterima.
  • Istorija događaja: Pojedinačna zapažanja, uključujući opise događaja, vremenske oznake i lokacije kada su dostavljene.
  • Metapodaci preuzimanja: Vreme kada je aplikacija primila ili preuzela informacije i da li je zahtev uspešno završen.

Uspešna pretraga znači da je operacija preuzimanja uspela. To ne znači da se paket pomerio od prethodne pretrage. Uporedite vraćene informacije o praćenju sa sačuvanim zapisom pre generisanja obaveštenja ili pokretanja narednog toka rada.

Vreme događaja držite odvojeno od vremena preuzimanja

Vreme povezano sa događajem prevoznika čuvajte odvojeno od vremena kada ga je vaš sistem primio. Događaj preuzet danas popodne može opisivati ranije skeniranje. Zamena vremena događaja vremenom preuzimanja učinila bi da staro ažuriranje izgleda kao novo fizičko kretanje.

Sačuvajte originalnu vremensku oznaku i svaku dostavljenu vremensku razliku. Normalizujte vremenske oznake radi poređenja samo kada je vremenska zona poznata. Ako događaj nema podatke o vremenskoj zoni, zadržite tu neizvesnost umesto da mu tiho dodelite vremensku zonu servera.

Uz normalizovani status sačuvajte izvorno značenje

Normalizovani status je koristan za grupisanje pošiljaka među prevoznicima, ali originalni opis događaja može preciznije objasniti operativni problem. Sačuvajte oba podatka kada su dostupna. Sama široka kategorija izuzetka možda neće reći agentu podrške da li treba proveriti adresu, kontaktirati primaoca ili sačekati novo ažuriranje.

Nemojte iz nejasnog statusa zaključivati da postoji garancija isporuke, potvrđen gubitak ili određeni ishod carinskog postupka. Eskalirajte na osnovu stvarnih informacija i svoje operativne politike.

5. Održavajte zapise ažurnim putem anketiranja ili webhook-ova

Jednokratno preuzimanje detalja dovoljno je za testiranje povezivosti, ali nije dovoljno za održavanje vidljivosti pošiljke. Produkcioni dizajn zahteva mehanizam za ažuriranje. Potvrdite koje mehanizme podržava izabrani provajder i koji uslovi važe za njih.

Kod anketiranja, aplikacija prema rasporedu zahteva detalje praćenja. Zahteve raspoređujte u okviru dokumentovanih ograničenja, izbegavajte ponovljeno upitivanje nepromenjenih zapisa bez razloga i koristite eksponencijalno odlaganje za greške koje se mogu ponoviti. Otvaranje stranice porudžbine od strane kupca ne bi trebalo automatski da pokreće neograničen zahtev prema nadređenom servisu; sačuvani prikaz praćenja može poslužiti za prikaz stranice, dok ga kontrolisani pozadinski proces osvežava.

Ako koristite webhook-ove, proverite dolazne zahteve pomoću dokumentovanog mehanizma verifikacije provajdera. Prihvaćene poruke sačuvajte ili trajno stavite u red čekanja pre potvrde prijema u skladu sa ugovorom webhook-a, a zatim događaje obrađujte asinhrono.

Prijemnik napravite tako da podnosi duplikate i neočekivani redosled pristizanja, osim ako dokumentovani ugovor o isporuci garantuje drugačije. Za uklanjanje duplikata koristite identifikator događaja provajdera kada je dostupan. U suprotnom definišite i testirajte otisak zasnovan na odgovarajućim poljima događaja, uz razumevanje da će možda biti potrebna prilagođavanja vašim podacima.

Integracija zasnovana na webhook-ovima može koristiti i kontrolisano preuzimanje radi usklađivanja. Na primer, posao oporavka može proveriti zapise na koje je uticao prekid rada prijemnika. To je obrazac otpornosti, a ne dozvola za zanemarivanje ograničenja brzine ili smernica specifičnih za provajdera.

6. Pretvorite informacije o praćenju u bezbedne poslovne radnje

Ažurirajte interni zapis pošiljke pre pokretanja radnji usmerenih ka kupcu. Čuvajte trajnu evidenciju obaveštenja i prelazaka između stanja toka rada kako ponovljeni događaj ne bi generisao ponovljene poruke.

Poslovne radnje mapirajte na značajne promene, a ne na svaki odgovor API-ja. Novo uočeni događaj isporuke može opravdati obaveštenje o isporuci. Ponovljeni odgovor koji sadrži isti događaj ne bi trebalo da ga opravda. Izuzetak može zahtevati internu proveru, ali poruka kupcu treba da odražava ono što događaj zaista kaže.

Definišite kako postupate sa događajima primljenim nakon što je pošiljka smatrana završenom. Nemojte brisati istoriju događaja niti trajno blokirati sva kasnija ažuriranja samo zato što je sažetak dostigao završno stanje. Pravila zadržavanja, usklađivanja i obaveštavanja treba da obuhvate legitimne ispravke bez ponovnog i nepotrebnog otvaranja završenih tokova rada.

Primena toka rada na integraciju sa 17TRACK-om

Za prilagođenu integraciju praćenja, relevantne početne tačke su 17TRACK stranica Tracking API-ja i dokumentacija za programere. Stranicu proizvoda koristite za procenu ponude, a dokumentaciju za utvrđivanje stvarnog ugovora integracije. Stranice za praćenje namenjene korisnicima nisu zamena za API specifikacije.

Pre pisanja adaptera potvrdite format autentifikacije, operacije registracije i preuzimanja, pravila identifikacije prevoznika, obradu odgovora na nivou stavke i primenljiva ograničenja zahteva. Za obradu zasnovanu na webhook-ovima potvrdite i šemu korisnog sadržaja, postupak verifikacije, zahteve za potvrdu prijema i ponašanje pri ponovnim pokušajima.

Ove detalje specifične za provajdera zadržite unutar adaptera umesto da pretpostavke o poljima odgovora širite kroz sistem porudžbina. Ostatak aplikacije tada može raditi sa internim konceptima kao što su ishod registracije, status pošiljke, istorija događaja i poslednja uspešna sinhronizacija.

Provere pre pokretanja koje otkrivaju skupe greške

  • Prihvaćen, ali prazan zapis: Interfejs prikazuje da se informacije o praćenju čekaju, a ne da se paket kreće.
  • Mešoviti rezultat grupe: Svaka pošiljka dobija sopstveni sačuvani ishod.
  • Istek vremena nakon slanja: Radnik usklađuje neizvestan rezultat umesto da pretpostavi neuspeh.
  • Ponovljeni događaj: Vremenska linija pošiljke i obaveštenje kupcu ostaju bez duplikata.
  • Stariji događaj primljen kasnije: Događaj se čuva bez slepe zamene novijeg sažetka.
  • Nedostupan nadređeni servis: Stranica kupca može prikazati poslednji sačuvani rezultat uz odgovarajuću oznaku svežine.
  • Neispravno mapiranje prevoznika: Zapis se može ispraviti kroz dokumentovani put oporavka.
  • Podeljena porudžbina: Svaki paket zadržava sopstveno stanje praćenja i istoriju događaja.
  • Izloženi akreditivi ili korisni sadržaj: Dnevnici sadrže dijagnostičke reference bez otkrivanja tajni ili nepotrebnih ličnih podataka.

Praktični kriterijum završenosti nije samo primanje uspešnog odgovora registracije. Potrebno je moći pratiti paket od slanja kroz ažuriranja, objasniti prazan ili neuspešan rezultat i oporaviti se od prekinute obrade bez gubitka događaja ili dupliranja radnji prema kupcu.

Česta pitanja

Da li registracija broja za praćenje kreira pošiljku?

Ne u ovde opisanom toku rada. Registracija praćenja šalje postojeći identifikator servisu za praćenje. Kreiranje nalepnice, kupovina poštarine i rezervacija prevoznika zasebne su operacije, osim ako ih određeni API izričito objedinjuje.

Zašto su detalji praćenja prazni nakon uspešne registracije?

Prihvatanje registracije i dostupnost podataka o praćenju različita su stanja. Prevoznik možda još nije zabeležio događaj ili je potrebno proveriti broj za praćenje, mapiranje prevoznika ili dodatne informacije za pretragu. Proverite rezultat na nivou stavke pre nego što zapis smatrate uspešno registrovanim.

Da li treba da registrujem pošiljku svaki put kada preuzimam njen status?

Nemojte ponovljenu registraciju koristiti kao podrazumevani mehanizam osvežavanja. Sačuvajte stanje prihvaćene registracije i koristite dokumentovani mehanizam preuzimanja ili ažuriranja. Pridržavajte se izričitih pravila provajdera za ispravke, ponovnu aktivaciju ili slanje duplikata.

Da li treba da koristim anketiranje ili webhook-ove?

Koristite mehanizam koji odgovara dokumentovanom API ugovoru i vašim operativnim zahtevima. Anketiranje zahteva kontrolisani raspored zahteva. Webhook-ovi zahtevaju bezbedan i trajan prijemnik i obradu otpornu na duplikate. Kada su podržana, ažuriranja putem webhook-ova uz ciljano usklađivanje mogu pružiti praktičan put oporavka.

Mogu li broj za praćenje koristiti kao jedini identifikator pošiljke u bazi?

Umesto toga koristite interni identifikator pošiljke. Broj za praćenje i relevantan kontekst prevoznika čuvajte kao atribute tog zapisa. Tako se podeljene porudžbine, ispravljeni brojevi za praćenje i reference specifične za provajdera lakše upravljaju bez promene identiteta interne pošiljke.

Izvori

  • 17TRACK Tracking API — zvanična početna stranica proizvoda za procenu integracije sa 17TRACK API-jem.
  • 17TRACK API dokumentacija — zvanična referenca za formate zahteva, operacije, odgovore i zahteve integracije specifične za implementaciju. Pseudokod i predlozi internih polja u ovom vodiču primeri su dizajna aplikacije, a ne citati ovog API ugovora.