Kako registrirati številko za sledenje prek API-ja: polja zahteve, kode prevoznikov in odzivi
Za registracijo sledilne številke prek API-ja pošljite overjeno registracijsko zahtevo, ki vsebuje sledilno številko pošiljke in po potrebi identifikator prevoznika. Nato preverite odgovor za vsako poslano pošiljko – ne le statusa HTTP – ter shranite, ali je bila registracija uspešna, neuspešna ali ostaja negotova. Registracija začne potek sledenja; ne dokazuje pa, da je prevoznik paket skeniral ali da so dogodki sledenja že na voljo.

Ta vodnik je namenjen razvijalcem, ki sistem za upravljanje naročil, skladiščno aplikacijo ali platformo za e-trgovino povezujejo z API-jem za sledenje. Kot konkreten primer integracije uporablja 17TRACK in pojasnjuje, katere podrobnosti je treba preveriti v dokumentaciji za izbrano različico API-ja.
Kaj registracija omogoča – in česa ne
Registracijska zahteva storitvi za sledenje sporoči, kateri pošiljki želite slediti. To se razlikuje od nakupa odpremne nalepke, rezervacije prevzema ali zahteve prevozniku, naj ustvari pošiljko. V tipični integraciji odpremni potek najprej ustvari sledilno številko, vaša aplikacija pa jo nato registrira.
V aplikaciji ločite te tri dogodke:
- Pošiljka ustvarjena: vaš odpremni sistem je dodelil sledilno številko.
- Registracija sprejeta: storitev za sledenje je pošiljko sprejela za sledenje.
- Informacije o sledenju prejete: dogodki prevoznika so postali na voljo prek storitve za sledenje.
Naročila ne posodobite v stanje »v tranzitu« samo zato, ker je bila registracija uspešna. Na novo ustvarjena nalepka morda še nima fizičnega skena prevzema. Status pošiljke, prikazan stranki, mora izhajati iz dogodkov sledenja, razloženih v skladu z vašimi pravili preslikave statusov, ne iz registracijskega odgovora.
Pri integracijah 17TRACK začnite s pregledom Tracking API in uporabite uradno dokumentacijo API-ja kot avtoriteto za končne točke, opredelitve polj, preverjanje pristnosti in kode odgovorov. Spodnji primeri se osredotočajo na registracijo, ne na ločeni nalogi pridobivanja rezultatov ali prejemanja posodobitev.
Pred pisanjem klica API-ja pripravite polja zahteve
Najkoristnejša priprava je majhna pogodba o poljih med vašim odpremnim sistemom in integracijo za sledenje. Določite, od kod izvira vsaka vrednost, ali lahko manjka in kako bo preverjena.
| Polje ali vrednost | Namen | Pravilo implementacije |
|---|---|---|
| Sledilna številka | Določa pošiljko, ki ji je treba slediti. | Shranite in prenašajte jo kot niz; ohranite začetne ničle. |
| Identifikator prevoznika | Določa prevoznika v sistemu ponudnika sledenja. | Uporabite dokumentirani identifikator ponudnika, ne interne skladiščne kode. |
| Interna referenca | Povezuje registracijo z vašim zapisom pošiljke. | Če je na voljo, uporabite podprto referenčno polje; ne glede na to ohranite lastno preslikavo v podatkovni zbirki. |
| Dodatni identifikacijski podatki | Lahko pomagajo določiti pošiljko, kadar prevoznik zahteva več kot le sledilno številko. | Pošljite samo polja, dokumentirana za to integracijo in prevoznika. |
| Poverilnica API-ja | Overi klicni račun. | Hranite jo na strežniku in jo izključite iz dnevnikov aplikacije. |
S sledilno številko ravnajte kot z identifikatorjem
Sledilne številke nikoli ne pretvorite v celo število. Številčna pretvorba lahko odstrani začetne ničle, velike vrednosti pa lahko v nekaterih programskih okoljih izgubijo natančnost. Odstranite nenamerno začetno ali končno praznino, vendar ne odstranjujte ločil in ne spreminjajte velikosti črk, razen če ustrezna dokumentacija ali oblika prevoznika podpira takšno normalizacijo.
Pred klicem API-ja preverite očitne napake vnosa: prazne nize, nepričakovane prelome vrstic in številko naročila, kopirano v polje sledilne številke. Ne uvajajte enotnega pravila glede dolžine ali znakov za vse prevoznike. Pravilo, ki ustreza enemu prevozniku, lahko zavrne veljavne številke drugega.
Reference naročil ločite od identitet pošiljk
Naročilo lahko vsebuje več paketov, nadomestna pošiljka pa lahko uvede drugo sledilno številko. Registracijo modelirajte na ravni pošiljke ali paketa, namesto da predpostavljate eno sledilno številko na naročilo.
Če uporabljate oznako ali referenčno polje, ki ga podpira ponudnik, raje uporabite neprozorno referenco pošiljke kot strankin e-poštni ali ulični naslov. Vaša podatkovna zbirka mora ostati avtoritativna povezava med naročili, pošiljkami, sledilnimi številkami in preslikavami prevoznikov.
Izberite pravilno kodo prevoznika
Koda prevoznika ni nujno univerzalni industrijski identifikator. Vrednost, ki jo prepozna platforma za sledenje, se lahko razlikuje od imena prevoznika, shranjenega v vaši odpremni programski opremi. Tudi dva sistema, ki uporabljata številčne kode, lahko istemu prevozniku dodelita različni številki.
Vzdržujte izrecno preslikavo od svoje odpremne storitve do identifikatorja prevoznika pri ponudniku sledenja. Po potrebi ločite regionalno poslovanje ali storitev prevoznika od njegove širše blagovne znamke. Preslikava, ki temelji samo na prikaznem imenu, lahko postane dvoumna, kadar odpremni sistemi uporabljajo vzdevke.
- Ko je prevoznik znan: kadar je podprt, uporabite dokumentirani identifikator prevoznika, zlasti kjer se oblike sledilnih številk prekrivajo.
- Ko prevoznik ni znan: samodejno zaznavanje uporabite samo prek dokumentiranega mehanizma. Ne predpostavljajte, da izpuščena vrednost, prazen niz, ničla in null pomenijo isto.
- Ko je rezultat videti napačen: pred večkratno registracijo iste številke preverite izvirno nalepko, odpremno storitev in preslikavo.
Samodejno zaznavanje je uporabno, vendar ni dokaz, da ima določen prevoznik pošiljko fizično v posesti. Prav tako veljavna koda prevoznika ne zagotavlja, da predložena sledilna številka pripada temu prevozniku.
Preslikave prevoznikov naj bodo nastavljive, namesto da jih razpršite po kodi aplikacije. Zabeležite, kdaj je bila preslikava nazadnje preverjena, in pri vsaki spremembi vključite znano pošiljko v regresijske teste.
Primer: pošljite registracijsko zahtevo 17TRACK
Naslednji primer prikazuje registracijsko končno točko 17TRACK v2.2, glavo za preverjanje pristnosti 17token in polje, ki vsebuje en objekt sledilne številke. Pred uvedbo preverite, ali se ta različica in njene zahteve ujemajo z vašim računom in uradno dokumentacijo. Sledilna številka je nadomestna vrednost in jo je treba zamenjati z resničnim identifikatorjem 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"
}
]'Ta minimalni primer ne prikazuje izbire prevoznika ali dodatnih polj, specifičnih za prevoznika. V dokumentaciji za registracijo preverite, kako deluje zaznavanje prevoznika, ko je polje prevoznika izpuščeno, in ali vaša pošiljka potrebuje dodatne informacije. Če navedete prevoznika, uporabite dokumentirano polje carrier in identifikator, ki ga pričakuje ta različica API-ja.
To zahtevo izvedite iz strežniškega okolja. Žetona ne vdelujte v javno trgovino, skripto brskalnika ali mobilno aplikacijo, ki se distribuira strankam. Okoljska spremenljivka je priročna za lokalni primer; produkcijske uvedbe morajo uporabljati nadzorne mehanizme vaše organizacije za upravljanje skrivnosti.
Pred povečanjem obsega preizkusite eno znano pošiljko in preglejte celoten odgovor. Nato preizkusite neveljaven vnos in paket, ki vsebuje veljavne in neveljavne elemente. Ti preverjanji pokažejo, ali vaša integracija dejansko obravnava rezultate na ravni elementov, namesto da zgolj prepozna uspešen odgovor HTTP.
Odgovor preberite na treh ravneh
Zanesljiv obdelovalnik odgovorov odgovori na tri ločena vprašanja: ali je zahteva dosegla storitev, ali je storitev operacijo sprejela in kaj se je zgodilo z vsako pošiljko?
1. Rezultat HTTP in prenosa
Prekoračitev časa povezave, napaka TLS ali prekinjen odgovor ne povedo nujno, ali je strežnik obdelal zahtevo. Ta rezultat označite kot negotov, dokler ga ne morete uskladiti. Uspešen status HTTP potrjuje uspešno izmenjavo HTTP, vendar morate še vedno pregledati odgovor aplikacije.
2. Rezultat na ravni zahteve
Preglejte dokumentirani rezultat API-ja na najvišji ravni in polja z napakami. Napake preverjanja pristnosti, nepravilen JSON in omejitve računa zahtevajo različna dejanja. Shranite izvirno kodo napake in sporočilo ponudnika, namesto da vsako napako zmanjšate na »sledenje ni na voljo«.
Ne predpostavljajte, da ima številčna koda aplikacije enak pomen kot statusna koda HTTP. Njuna pomena izhajata iz različnih plasti in ju je treba razlagati ločeno.
3. Rezultat na ravni pošiljke
Pri paketni registraciji upoštevajte vsak poslani element. Odgovor lahko loči sprejete in zavrnjene pošiljke; razčlenjevalnik mora slediti natančni shemi, dokumentirani za izbrano različico. Celotnega paketa ne označite kot registriranega samo zato, ker je bil en element uspešen.
Odgovore ponudnika normalizirajte v lastna stabilna stanja aplikacije. Vaša podatkovna zbirka lahko na primer uporablja accepted, rejected in uncertain. To so predlagana interna stanja, ne dobesedne vrednosti odgovorov 17TRACK. Izvirni odgovor ponudnika hranite na voljo v skladu z ustrezno politiko hrambe in dostopa, da lahko razvijalci preiščejo neskladja.
Uporaben registracijski zapis vsebuje interni ID pošiljke, poslano številko, izbiro prevoznika, čas poskusa, različico API-ja, rezultat in podrobnosti napake ponudnika. Status registracije naj bo ločen od statusa dostave.
Obravnavajte ponovne poskuse, ne da bi ustvarili neskončno zanko
Pravilnik ponovnih poskusov mora biti odvisen od napake, ne zgolj od tega, ali je prišlo do izjeme.
- Neveljaven vnos: pred ponovnim poskusom popravite polje. Ponavljanje nespremenjene nepravilno oblikovane zahteve verjetno ne bo pomagalo.
- Napaka preverjanja pristnosti: preverite poverilnice in konfiguracijo računa. Izogibajte se večkratnemu pošiljanju istega neuspešnega paketa.
- Omejevanje hitrosti: upoštevajte dokumentirane omejitve in morebitna navodila za ponovni poskus. Uporabite omejeno postopno čakanje namesto takojšnjih vzporednih ponovnih poskusov.
- Začasna napaka storitve: ponovite poskus v okviru določenega proračuna poskusov in časa.
- Prekoračitev časa po pošiljanju: pred predpostavko, da je prvi poskus spodletel, uskladite stanje registracije pošiljke z uporabo dokumentiranega vedenja API-ja.
- Odgovor, povezan z dvojnikom: preverite, ali je pošiljka že registrirana in pravilno povezana z zapisom v vaši aplikaciji.
Ne predpostavljajte, da je registracija idempotentna, razen če dokumentacija to vedenje opredeljuje. Dedupliciranje na strani aplikacije zmanjša nenamerne ponovne oddaje, vendar ne določa pravilnika ponudnika glede obravnave dvojnikov.
Uporabite interno pravilo enoličnosti, primerno vašemu modelu pošiljk. Sama sledilna številka morda ni zadosten trajni ključ med prevozniki in dolgimi obdobji hrambe. Ohranite kontekst prevoznika in svoj identifikator pošiljke ter dokumentirajte obravnavo nadomestnih in popravljenih številk.
Registracijo spremljajte ločeno od posodobitev sledenja
Spremljanje API-ja mora razlikovati med napako integracije in pošiljko, ki preprosto nima novega dogodka prevoznika. Ti stanji zahtevata različna odgovorna področja in različne rešitve.
Pri registraciji spremljajte število sprejetih in zavrnjenih zahtev, kategorije napak, negotove rezultate, zaostanek ponovnih poskusov in zakasnitve odgovorov. Pri nadaljnjem sledenju ločeno spremljajte prejemanje posodobitev ali napake pri pridobivanju. Ne določajte številčnih pragov opozoril, dokler ne razumete običajnega prometa in dokumentiranih operativnih omejitev ponudnika.
Praktično produkcijsko preverjanje mora odgovoriti na naslednja vprašanja:
- Ali ima vsaka pošiljka, ki čaka na sledenje, registracijski zapis?
- Ali je mogoče vsako sprejeto registracijo povezati s pravilnim paketom?
- Ali so zavrnjeni elementi usmerjeni k nekomu, ki lahko popravi osnovne podatke?
- Ali so negotove zahteve usklajene, namesto da bi bile opuščene ali se jim neskončno ponavljali poskusi?
- Ali statusi, prikazani strankam, izhajajo iz dogodkov pošiljke in ne iz sprejema registracije?
- Ali so poverilnice in nepotrebni osebni podatki izključeni iz dnevnikov?
Pri poslovanju e-trgovine je operativna predaja enako pomembna kot sam klic API-ja. Razvijalci morajo biti odgovorni za napake prenosa in razčlenjevanja; odpremne ali izpolnitvene ekipe pa morajo imeti možnost preiskati nepravilne nalepke, preslikave prevoznikov in manjkajoče informacije o pošiljkah.
Pogosta vprašanja
Ali lahko sledilno številko registriram pred prvim skenom prevoznika?
Registracija in skeni prevoznika so ločeni dogodki. Storitev lahko številko sprejme, še preden so dogodki sledenja na voljo, odvisno od njenih pravil preverjanja. Sprejema ne razlagajte kot dokaz, da je prevoznik prejel paket.
Ali moram vedno navesti kodo prevoznika?
To je odvisno od dokumentiranega vedenja API-ja pri zaznavanju in od zadevne pošiljke. Če je prevoznik znan, lahko izrecno in pravilno preslikan identifikator zmanjša dvoumnost. Če ni znan, uporabite dokumentirano metodo samodejnega zaznavanja, namesto da si izmislite vrednost prevoznika.
Zakaj je API vrnil uspeh HTTP, medtem ko je pošiljka spodletela?
Zahteva HTTP je lahko uspešna, medtem ko aplikacija zavrne posamezni element. Preberite rezultat aplikacije na najvišji ravni in rezultate na ravni pošiljke. Ta razlika je posebej pomembna pri paketnih zahtevah.
Kaj naj storim, če registracijski zahtevi poteče čas?
Rezultat obravnavajte kot negotov. Strežnik je zahtevo morda obdelal, preden je povezava odpovedala. Preverite dokumentirano vedenje ponudnika pri dvojnikih ter razpoložljive načine iskanja registracij ali sledenja, nato pa rezultat uskladite ali ponovite poskus v okviru omejenega pravilnika.
Ali registracija samodejno konfigurira obvestila o sledenju?
Ne predpostavljajte, da jih. Registracija, pridobivanje podatkov o sledenju in konfiguracija spletnih kavljev so ločene integracijske zadeve. Preverite ustrezno dokumentacijo in pred zanašanjem na to za obvestila strank preizkusite celotno pot posodobitve.
Viri
- Dokumentacija API-ja 17TRACK – referenca za registracijske končne točke, preverjanje pristnosti, polja zahtev, identifikatorje prevoznikov, sheme odgovorov in obravnavo napak. Podrobnosti implementacije uskladite z različico API-ja, ki jo uvedete.
- Pregled Tracking API 17TRACK – uradno izhodišče za izdelek API-ja za sledenje in vire za integracijo razvijalcev.


