Skip to main content
ПочетакБлогVodičiKako registrovati broj za praćenje putem API-ja: polja zahteva, kodovi prevoznika i odgovori

Kako registrovati broj za praćenje putem API-ja: polja zahteva, kodovi prevoznika i odgovori

17TRACK

Da biste registrovali broj za praćenje putem API-ja, pošaljite autentifikovani zahtev za registraciju koji sadrži broj za praćenje pošiljke i, kada je potrebno, identifikator prevoznika. Zatim proverite odgovor za svaku poslatu pošiljku — ne samo HTTP status — i sačuvajte da li je registracija uspešna, neuspešna ili ostaje neizvesna. Registracija pokreće tok praćenja; ona ne dokazuje da je prevoznik skenirao paket niti da su događaji praćenja već dostupni.

Kako registrovati broj za praćenje putem API zahteva i polja

Ovaj vodič je namenjen programerima koji povezuju sistem za upravljanje porudžbinama, skladišnu aplikaciju ili platformu za e-trgovinu sa API-jem za praćenje. Kao konkretan primer integracije koristi 17TRACK i objašnjava koje detalje treba proveriti u dokumentaciji za izabranu verziju API-ja.

Šta registracija radi — a šta ne radi

Zahtev za registraciju govori servisu za praćenje koju pošiljku želite da prati. To se razlikuje od kupovine transportne etikete, zakazivanja preuzimanja ili zahteva prevozniku da kreira pošiljku. U tipičnoj integraciji, tok slanja prvo generiše broj za praćenje, a vaša aplikacija zatim registruje taj broj.

U svojoj aplikaciji razdvojite ova tri događaja:

  • Pošiljka kreirana: vaš sistem za slanje dodelio je broj za praćenje.
  • Registracija prihvaćena: servis za praćenje prihvatio je pošiljku za praćenje.
  • Informacije o praćenju primljene: događaji prevoznika postali su dostupni putem servisa za praćenje.

Ne ažurirajte porudžbinu na „u transportu“ samo zato što je registracija uspešna. Novokreirana etiketa možda još nema fizički sken prijema. Status pošiljke koji se prikazuje korisnicima treba da potiče od događaja praćenja obrađenih prema vašim pravilima mapiranja statusa, a ne od odgovora registracije.

Za integracije sa 17TRACK počnite od pregleda Tracking API-ja, a zvaničnu API dokumentaciju koristite kao merodavni izvor za krajnje tačke, definicije polja, autentifikaciju i kodove odgovora. Primeri u nastavku usmereni su na registraciju, a ne na odvojene zadatke preuzimanja rezultata ili prijema ažuriranja.

Pripremite polja zahteva pre pisanja API poziva

Najkorisnija priprema je mali ugovor o poljima između vašeg sistema za slanje i integracije za praćenje. Odredite odakle potiče svaka vrednost, da li može nedostajati i kako će biti proverena.

Polje ili vrednostSvrhaPravilo implementacije
Broj za praćenjeIdentifikuje pošiljku koju treba pratiti.Čuvajte ga i prenosite kao string; sačuvajte početne nule.
Identifikator prevoznikaIdentifikuje prevoznika u sistemu provajdera za praćenje.Koristite identifikator naveden u dokumentaciji provajdera, a ne interni kod skladišta.
Interna referencaPovezuje registraciju sa vašim zapisom pošiljke.Koristite podržano referentno polje ako je dostupno; u svakom slučaju zadržite sopstveno mapiranje u bazi podataka.
Dodatni identifikacioni podaciMogu pomoći pri identifikaciji pošiljke kada prevoznik zahteva više od broja za praćenje.Šaljite samo polja dokumentovana za tu integraciju i prevoznika.
API akreditivAutentifikuje nalog koji šalje zahtev.Čuvajte ga na serveru i izuzmite iz dnevnika aplikacije.

Tretirajte broj za praćenje kao identifikator

Nikada ne pretvarajte broj za praćenje u ceo broj. Numerička konverzija može ukloniti početne nule, a velike vrednosti mogu izgubiti preciznost u nekim programskim okruženjima. Uklonite slučajne razmake na početku i kraju, ali nemojte uklanjati interpunkciju niti menjati velika i mala slova, osim ako to podržavaju relevantna dokumentacija ili format prevoznika.

Proverite očigledne greške u unosu pre poziva API-ja: prazne stringove, neočekivane prelome redova i broj porudžbine kopiran u polje za broj za praćenje. Nemojte nametati jedno univerzalno pravilo dužine ili znakova svim prevoznicima. Pravilo koje odgovara jednom prevozniku može odbaciti važeće brojeve drugog prevoznika.

Držite reference porudžbina odvojeno od identiteta pošiljki

Porudžbina može imati više paketa, a zamenska pošiljka može uvesti još jedan broj za praćenje. Modelujte registraciju na nivou pošiljke ili paketa, umesto da pretpostavite jedan broj za praćenje po porudžbini.

Ako koristite oznaku ili referentno polje koje podržava provajder, dajte prednost neprozirnoj referenci pošiljke umesto imejla ili kućne adrese korisnika. Vaša baza podataka treba da ostane merodavna veza između porudžbina, pošiljki, brojeva za praćenje i mapiranja prevoznika.

Izaberite odgovarajući kod prevoznika

Kod prevoznika nije nužno univerzalni industrijski identifikator. Vrednost koju prepoznaje platforma za praćenje može se razlikovati od naziva prevoznika sačuvanog u vašem softveru za slanje. Čak i dva sistema koji koriste numeričke kodove mogu istom prevozniku dodeliti različite brojeve.

Održavajte eksplicitno mapiranje između svoje usluge slanja i identifikatora prevoznika kod provajdera za praćenje. Kada je potrebno, razlikujte regionalnu operaciju ili uslugu prevoznika od njegovog šireg brenda. Mapiranje zasnovano samo na prikazanom nazivu može postati dvosmisleno kada sistemi za slanje koriste alijase.

  • Kada je prevoznik poznat: koristite dokumentovani identifikator prevoznika kada je podržan, naročito kada se formati brojeva za praćenje preklapaju.
  • Kada je prevoznik nepoznat: koristite automatsko otkrivanje samo putem dokumentovanog mehanizma. Nemojte pretpostaviti da izostavljanje, prazan string, nula i null znače isto.
  • Kada rezultat izgleda pogrešno: proverite originalnu etiketu, uslugu slanja i mapiranje pre ponovne registracije istog broja.

Automatsko otkrivanje je korisno, ali nije dokaz da određeni prevoznik fizički drži pošiljku. Isto tako, važeći kod prevoznika ne garantuje da dostavljeni broj za praćenje pripada tom prevozniku.

Mapiranja prevoznika držite podesivim umesto da ih rasipate kroz kod aplikacije. Zabeležite kada je mapiranje poslednji put provereno i uključite poznatu pošiljku u regresione testove svaki put kada ga menjate.

Primer: slanje zahteva za registraciju na 17TRACK

Sledeći primer prikazuje 17TRACK v2.2 krajnju tačku za registraciju, zaglavlje za autentifikaciju 17token i niz koji sadrži jedan objekat sa brojem za praćenje. Pre puštanja u rad potvrdite da se ova verzija i njeni zahtevi podudaraju sa vašim nalogom i zvaničnom dokumentacijom. Broj za praćenje je zamenski tekst i mora biti zamenjen stvarnim identifikatorom pošiljke.

curl --request POST \
  --url 'https://api.17track.net/track/v2.2/register' \
  --header "17token: ${TRACKING_API_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "number": "YOUR_TRACKING_NUMBER"
    }
  ]'

Ovaj minimalni primer ne prikazuje izbor prevoznika niti dodatna polja specifična za prevoznika. Proverite dokumentaciju registracije da biste utvrdili kako funkcioniše otkrivanje prevoznika kada je polje prevoznika izostavljeno i da li su vašoj pošiljci potrebne dodatne informacije. Ako navedete prevoznika, koristite dokumentovano polje carrier i identifikator koji očekuje ta verzija API-ja.

Ovaj zahtev pokrećite iz serverskog okruženja. Nemojte ugrađivati token u javnu prodavnicu, skriptu pregledača ili mobilnu aplikaciju distribuiranu korisnicima. Promenljiva okruženja je praktična za lokalni primer; produkciona okruženja treba da koriste kontrole za upravljanje tajnama vaše organizacije.

Pre povećanja obima testirajte jednu poznatu pošiljku i pregledajte kompletan odgovor. Zatim testirajte nevažeći unos i paket koji sadrži i važeće i nevažeće stavke. Ove provere otkrivaju da li vaša integracija zaista obrađuje ishode na nivou stavke, a ne samo prepoznaje uspešan HTTP odgovor.

Čitajte odgovor na tri nivoa

Pouzdan obrađivač odgovora daje odgovor na tri odvojena pitanja: da li je zahtev stigao do servisa, da li je servis prihvatio operaciju i šta se dogodilo sa svakom pošiljkom?

1. HTTP i transportni ishod

Istek vremena veze, TLS greška ili prekinut odgovor ne govore nužno da li je server obradio zahtev. Označite taj ishod kao neizvestan dok ga ne uskladite. HTTP status uspeha potvrđuje uspešnu HTTP razmenu, ali i dalje morate pregledati odgovor aplikacije.

2. Ishod na nivou zahteva

Pregledajte dokumentovani rezultat najvišeg nivoa API-ja i polja greške. Greške autentifikacije, neispravan JSON i ograničenja naloga zahtevaju različite postupke. Sačuvajte originalni kod i poruku greške provajdera umesto da svaki neuspeh svedete na „praćenje nije dostupno“.

Nemojte pretpostaviti da numerički kod aplikacije ima isto značenje kao HTTP statusni kod. Njihova značenja potiču iz različitih slojeva i moraju se tumačiti odvojeno.

3. Ishod na nivou pošiljke

Kod paketne registracije obuhvatite svaku poslatu stavku. Odgovor može razlikovati prihvaćene i odbijene pošiljke; vaš parser treba da prati tačnu šemu dokumentovanu za izabranu verziju. Nemojte označiti ceo paket kao registrovan samo zato što je jedna stavka uspešna.

Normalizujte odgovore provajdera u sopstvena stabilna stanja aplikacije. Na primer, baza može koristiti accepted, rejected i uncertain. To su predložena interna stanja, a ne doslovne vrednosti odgovora 17TRACK. Originalni odgovor provajdera držite dostupnim u skladu sa odgovarajućom politikom zadržavanja i pristupa kako bi programeri mogli da istraže neslaganja.

Korisni zapis registracije sadrži interni ID pošiljke, poslati broj, izbor prevoznika, vreme pokušaja, verziju API-ja, ishod i detalje greške provajdera. Status registracije držite odvojeno od statusa isporuke.

Obradite ponovne pokušaje bez stvaranja beskonačne petlje

Politika ponovnih pokušaja treba da zavisi od greške, a ne samo od toga da li je došlo do izuzetka.

  • Nevažeći unos: ispravite polje pre ponovnog pokušaja. Ponavljanje nepromenjenog neispravnog zahteva verovatno neće pomoći.
  • Greška autentifikacije: proverite akreditive i konfiguraciju naloga. Izbegavajte ponavljanje istog neuspešnog paketa.
  • Ograničenje brzine: pratite dokumentovana ograničenja i primenljiva uputstva za ponovni pokušaj. Koristite ograničeni period čekanja umesto trenutnih paralelnih pokušaja.
  • Privremeni pad servisa: ponovite pokušaj u okviru definisanog budžeta pokušaja i vremena.
  • Istek vremena nakon slanja: uskladite stanje registracije pošiljke koristeći dokumentovano ponašanje API-ja pre nego što pretpostavite da prvi pokušaj nije uspeo.
  • Odgovor povezan sa duplikatom: proverite da li je pošiljka već registrovana i pravilno povezana sa zapisom vaše aplikacije.

Nemojte pretpostaviti da je registracija idempotentna osim ako dokumentacija definiše takvo ponašanje. Dedupliciranje na nivou aplikacije smanjuje slučajna ponovljena slanja, ali ne utvrđuje politiku provajdera za obradu duplikata.

Koristite interno pravilo jedinstvenosti koje odgovara vašem modelu pošiljke. Sam broj za praćenje možda nije dovoljan trajni ključ između prevoznika i tokom dugih perioda zadržavanja. Sačuvajte kontekst prevoznika i sopstveni identifikator pošiljke i dokumentujte način obrade zamena i ispravljenih brojeva.

Pratite registraciju odvojeno od ažuriranja praćenja

API nadzor treba da razlikuje grešku integracije od pošiljke koja jednostavno nema novi događaj prevoznika. Ovi uslovi zahtevaju različite odgovorne timove i različita rešenja.

Kod registracije pratite broj prihvatanja i odbijanja, kategorije grešaka, neizvesne ishode, zaostatak ponovnih pokušaja i kašnjenje odgovora. Kod naknadnog praćenja odvojeno pratite prijem ažuriranja ili greške pri preuzimanju. Izbegavajte postavljanje numeričkih pragova upozorenja dok ne razumete uobičajeni saobraćaj i dokumentovana operativna ograničenja provajdera.

Praktična produkciona provera treba da odgovori na sledeća pitanja:

  1. Da li svaka pošiljka koja čeka praćenje ima zapis registracije?
  2. Može li se svaka prihvaćena registracija povezati sa ispravnim paketom?
  3. Da li se odbijene stavke prosleđuju osobi koja može ispraviti osnovne podatke?
  4. Da li se neizvesni zahtevi usklađuju umesto da budu napušteni ili beskonačno ponavljani?
  5. Da li statusi koji se prikazuju korisnicima potiču od događaja pošiljke, a ne od prihvatanja registracije?
  6. Da li su akreditive i nepotrebni lični podaci izuzeti iz dnevnika?

Kod poslovanja e-trgovine operativna primopredaja je jednako važna kao i sam API poziv. Programeri treba da budu odgovorni za transportne greške i greške parsiranja; timovi za slanje ili ispunjavanje porudžbina treba da mogu da istraže neispravne etikete, mapiranja prevoznika i nedostajuće informacije o pošiljci.

Česta pitanja

Mogu li da registrujem broj za praćenje pre prvog skeniranja prevoznika?

Registracija i skeniranja prevoznika su odvojeni događaji. Servis može prihvatiti broj pre nego što događaji praćenja postanu dostupni, u skladu sa svojim pravilima validacije. Prihvatanje nemojte tumačiti kao dokaz da je prevoznik primio paket.

Da li uvek moram da navedem kod prevoznika?

To zavisi od dokumentovanog ponašanja API-ja pri otkrivanju i od konkretne pošiljke. Ako je prevoznik poznat, eksplicitni, pravilno mapirani identifikator može smanjiti dvosmislenost. Ako je nepoznat, koristite dokumentovani način automatskog otkrivanja umesto izmišljanja vrednosti prevoznika.

Zašto je API vratio HTTP uspeh dok je pošiljka neuspešna?

HTTP zahtev može uspeti dok aplikacija odbija pojedinačnu stavku. Pročitajte rezultat aplikacije na najvišem nivou i rezultate na nivou pošiljke. Ova razlika je naročito važna kod paketnih zahteva.

Šta treba da uradim kada zahtev za registraciju istekne?

Tretirajte rezultat kao neizvestan. Server je možda obradio zahtev pre nego što je veza prekinuta. Proverite dokumentovano ponašanje provajdera u slučaju duplikata i dostupne metode za pretragu registracije ili praćenja, a zatim uskladite stanje ili ponovite pokušaj u okviru ograničene politike.

Da li registracija automatski podešava obaveštenja o praćenju?

Nemojte pretpostaviti da je tako. Registracija, preuzimanje podataka o praćenju i konfiguracija webhook-a odvojene su integracione teme. Proverite relevantnu dokumentaciju i testirajte kompletan tok ažuriranja pre nego što se oslonite na njega za obaveštavanje korisnika.

Izvori

  • 17TRACK API dokumentacija — referenca za krajnje tačke registracije, autentifikaciju, polja zahteva, identifikatore prevoznika, šeme odgovora i obradu grešaka. Uskladite detalje implementacije sa verzijom API-ja koju koristite.
  • Pregled 17TRACK Tracking API-ja — zvanična početna tačka za proizvod Tracking API i resurse za integraciju programera.