Kaip užregistruoti sekimo numerį per API: užklausos laukai, vežėjų kodai ir atsakymai
Norėdami užregistruoti sekimo numerį per API, išsiųskite autentifikuotą registracijos užklausą, kurioje būtų siuntos sekimo numeris ir, kai reikalaujama, vežėjo identifikatorius. Tada patikrinkite kiekvienos pateiktos siuntos atsakymą, o ne tik HTTP būseną, ir išsaugokite, ar registracija pavyko, nepavyko, ar jos būsena lieka neaiški. Registracija pradeda sekimo procesą; ji neįrodo, kad vežėjas nuskenavo siuntą arba kad sekimo įvykiai jau pasiekiami.
Šis vadovas skirtas kūrėjams, jungiantiems užsakymų valdymo sistemą, sandėlio programą arba el. prekybos platformą prie sekimo API. Kaip konkretų integracijos pavyzdį jis naudoja 17TRACK ir paaiškina, kurią informaciją reikia patikrinti pagal jūsų pasirinktos API versijos dokumentaciją.
Ką atlieka registracija ir ko ji neatlieka
Registracijos užklausa nurodo sekimo paslaugai, kurią siuntą norite sekti. Ji skiriasi nuo siuntimo etiketės įsigijimo, paėmimo užsakymo ar prašymo vežėjui sukurti siuntą. Įprastoje integracijoje siuntimo procesas pirmiausia sugeneruoja sekimo numerį, o jūsų programa vėliau jį užregistruoja.
Savo programoje šiuos tris įvykius laikykite atskirai:
- Siunta sukurta: jūsų siuntimo sistema priskyrė sekimo numerį.
- Registracija priimta: sekimo paslauga priėmė siuntą sekti.
- Gauta sekimo informacija: vežėjo įvykiai tapo pasiekiami per sekimo paslaugą.
neatnaujinkite užsakymo būsenos į „gabenama“ vien todėl, kad registracija pavyko. Naujai sukurta etiketė dar gali neturėti fizinio priėmimo nuskaitymo. Klientams rodoma siuntos būsena turi būti nustatoma pagal sekimo įvykius, interpretuojamus pagal jūsų būsenų susiejimo taisykles, o ne pagal registracijos atsakymą.
Integruodami 17TRACK, pradėkite nuo Tracking API overview ir naudokite official API documentation kaip pagrindinį šaltinį, kuriame nurodyti galiniai taškai, laukų apibrėžtys, autentifikavimas ir atsakymų kodai. Toliau pateiktuose pavyzdžiuose daugiausia dėmesio skiriama registracijai, o ne atskiroms rezultatų gavimo ar naujinių priėmimo užduotims.
Paruoškite užklausos laukus prieš rašydami API iškvietimą
Naudingiausias pasiruošimas – nedidelė laukų sutartis tarp jūsų siuntimo sistemos ir sekimo integracijos. Nuspręskite, iš kur gaunama kiekviena reikšmė, ar jos gali trūkti ir kaip ji bus tikrinama.
| Laukas arba reikšmė | Paskirtis | Įgyvendinimo taisyklė |
|---|---|---|
| Sekimo numeris | Identifikuoja sekamą siuntą. | Saugokite ir perduokite kaip eilutę; išsaugokite pradinius nulius. |
| Vežėjo identifikatorius | Identifikuoja vežėją sekimo teikėjo sistemoje. | Naudokite teikėjo dokumentacijoje nurodytą identifikatorių, o ne vidinį sandėlio kodą. |
| Vidinė nuoroda | Susieja registraciją su jūsų siuntos įrašu. | Jei galima, naudokite palaikomą nuorodos lauką; nepaisant to, išsaugokite savo duomenų bazės susiejimą. |
| Papildomi identifikavimo duomenys | Gali padėti identifikuoti siuntą, kai vežėjui reikia daugiau nei sekimo numerio. | Pateikite tik tai integracijai ir vežėjui dokumentacijoje nurodytus laukus. |
| API kredencialas | Autentifikuoja kviečiančią paskyrą. | Laikykite serveryje ir neįtraukite į programos žurnalus. |
Laikykite sekimo numerį identifikatoriumi
Niekada nekeiskite sekimo numerio į sveikąjį skaičių. Skaitinė konversija gali pašalinti pradinius nulius, o kai kuriose programavimo aplinkose didelės reikšmės gali prarasti tikslumą. Pašalinkite atsitiktinius tarpus pradžioje ir pabaigoje, tačiau nepašalinkite skyrybos ženklų ir nekeiskite raidžių registro, nebent tai leidžia atitinkama dokumentacija arba vežėjo formatas.
Prieš kviesdami API patikrinkite akivaizdžias įvesties klaidas: tuščias eilutes, netikėtus eilučių lūžius ir į sekimo numerio lauką nukopijuotą užsakymo numerį. Netaikykite vienos universalios ilgio ar simbolių taisyklės visiems vežėjams. Vienam vežėjui tinkama tikrinimo taisyklė gali atmesti teisėtus kito vežėjo numerius.
Užsakymų nuorodas laikykite atskirai nuo siuntų identitetų
Užsakymas gali turėti kelias siuntas, o pakeičianti siunta gali turėti kitą sekimo numerį. Modeliuokite registraciją siuntos arba pakuotės lygiu, o ne manykite, kad vienam užsakymui tenka vienas sekimo numeris.
Jei naudojate teikėjo palaikomą žymos arba nuorodos lauką, rinkitės neaiškią siuntos nuorodą, o ne kliento el. pašto ar gatvės adresą. Jūsų duomenų bazė turi likti autoritetingu ryšiu tarp užsakymų, siuntų, sekimo numerių ir vežėjų susiejimų.
Pasirinkite tinkamą vežėjo kodą
Vežėjo kodas nebūtinai yra universalus pramonės identifikatorius. Sekimo platformos atpažįstama reikšmė gali skirtis nuo vežėjo pavadinimo, saugomo jūsų siuntimo programoje. Net dvi sistemos, naudojančios skaitinius kodus, tam pačiam vežėjui gali priskirti skirtingus numerius.
Prižiūrėkite aiškų savo siuntimo paslaugos ir sekimo teikėjo vežėjo identifikatoriaus susiejimą. Jei reikia, atskirkite regioninę vežėjo veiklą arba paslaugą nuo platesnio prekės ženklo. Vien pavadinimu pagrįstas susiejimas gali tapti dviprasmiškas, kai siuntimo sistemos naudoja alternatyvius pavadinimus.
- Kai vežėjas žinomas: jei palaikoma, naudokite dokumentacijoje nurodytą vežėjo identifikatorių, ypač kai sekimo numerių formatai sutampa.
- Kai vežėjas nežinomas: automatinį aptikimą naudokite tik dokumentacijoje nurodytu būdu. Nemanykite, kad praleidimas, tuščia eilutė, nulis ir null reiškia tą patį.
- Kai rezultatas atrodo neteisingas: prieš pakartotinai registruodami tą patį numerį patikrinkite originalią etiketę, siuntimo paslaugą ir susiejimą.
Automatinis aptikimas yra naudingas, tačiau jis neįrodo, kad konkrečiam vežėjui fiziškai perduota siunta. Taip pat galiojantis vežėjo kodas negarantuoja, kad pateiktas sekimo numeris priklauso tam vežėjui.
Vežėjų susiejimus laikykite konfigūruojamus, o ne išsklaidytus programos kode. Užrašykite, kada susiejimas paskutinį kartą buvo patikrintas, ir kiekvieną kartą jį pakeitę įtraukite žinomą siuntą į regresijos testus.
Pavyzdys: pateikite 17TRACK registracijos užklausą
Toliau pateiktame pavyzdyje iliustruojamas 17TRACK v2.2 registracijos galinis taškas, 17token autentifikavimo antraštė ir masyvas, kuriame yra vienas sekimo numerio objektas. Prieš diegdami patvirtinkite, kad ši versija ir jos užklausos reikalavimai atitinka jūsų paskyrą bei oficialią dokumentaciją. Sekimo numeris yra vietos rezervavimo ženklas ir turi būti pakeistas tikru siuntos identifikatoriumi.
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"
}
]'
Šis minimalus pavyzdys neparodo vežėjo pasirinkimo ar vežėjui būdingų papildomų laukų. Peržiūrėkite registracijos dokumentaciją, kad nustatytumėte, kaip veikia vežėjo aptikimas, kai vežėjo laukas praleidžiamas, ir ar jūsų siuntai reikia papildomos informacijos. Jei nurodote vežėją, naudokite dokumentacijoje aprašytą carrier lauką ir tos API versijos reikalaujamą identifikatorių.
Vykdykite šią užklausą serverio pusėje. Neįterpkite žetono į viešąją parduotuvę, naršyklės scenarijų ar klientams platinamą mobiliąją programą. Aplinkos kintamasis patogus vietiniam pavyzdžiui; gamybiniai diegimai turėtų naudoti jūsų organizacijos slaptųjų duomenų valdymo priemones.
Prieš didindami apimtį, išbandykite vieną žinomą siuntą ir patikrinkite visą atsakymą. Tada išbandykite netinkamą įvestį ir paketą, kuriame yra tinkamų bei netinkamų elementų. Šie patikrinimai parodo, ar jūsų integracija iš tikrųjų tvarko elementų lygio rezultatus, o ne tik atpažįsta sėkmingą HTTP atsakymą.
Skaitykite atsakymą trimis lygiais
Patikimas atsakymų apdorotuvas atsako į tris atskirus klausimus: ar užklausa pasiekė paslaugą, ar paslauga priėmė operaciją ir kas nutiko kiekvienai siuntai?
1. HTTP ir perdavimo rezultatas
Ryšio skirtasis laikas, TLS klaida ar nutrūkęs atsakymas nebūtinai parodo, ar serveris apdorojo užklausą. Pažymėkite rezultatą kaip neaiškų, kol galėsite jį suderinti. Sėkminga HTTP būsena patvirtina sėkmingą HTTP apsikeitimą, tačiau vis tiek turite patikrinti programos atsakymą.
2. Užklausos lygio rezultatas
Patikrinkite API dokumentacijoje aprašytus aukščiausio lygio rezultato ir klaidų laukus. Autentifikavimo klaidoms, netinkamam JSON ir paskyros apribojimams reikia skirtingų veiksmų. Išsaugokite originalų teikėjo klaidos kodą ir pranešimą, o ne sumažinkite kiekvieną nesėkmę iki „sekimas nepasiekiamas“.
Nemanykite, kad skaitinis programos kodas turi tokią pačią reikšmę kaip HTTP būsenos kodas. Jų reikšmės kyla iš skirtingų sluoksnių ir turi būti interpretuojamos atskirai.
3. Siuntos lygio rezultatas
Registruodami paketą, atsižvelkite į kiekvieną pateiktą elementą. Atsakymas gali atskirti priimtas ir atmestas siuntas; jūsų analizatorius turi vadovautis tikslia pasirinktos versijos dokumentacijoje aprašyta schema. Nežymėkite viso paketo kaip užregistruoto vien todėl, kad vienas elementas buvo sėkmingas.
Normalizuokite teikėjo atsakymus į savo stabiliąsias programos būsenas. Pavyzdžiui, jūsų duomenų bazėje gali būti naudojamos accepted, rejected ir uncertain būsenos. Tai siūlomos vidinės būsenos, o ne tiesioginės 17TRACK atsakymų reikšmės. Išsaugokite originalų teikėjo atsakymą pagal tinkamą saugojimo ir prieigos politiką, kad kūrėjai galėtų tirti neatitikimus.
Naudingame registracijos įraše yra vidinis siuntos ID, pateiktas numeris, vežėjo pasirinkimas, bandymo laikas, API versija, rezultatas ir teikėjo klaidos informacija. Registracijos būseną laikykite atskirai nuo pristatymo būsenos.
Tvarkykite pakartotinius bandymus nesukurdami begalinio ciklo
Pakartotinių bandymų politika turi priklausyti nuo gedimo, o ne vien nuo to, ar įvyko išimtis.
- Netinkama įvestis: prieš kartodami pataisykite lauką. Nekintančios netinkamos užklausos kartojimas greičiausiai nepadės.
- Autentifikavimo klaida: patikrinkite kredencialus ir paskyros konfigūraciją. Venkite pakartotinai teikti tą patį nepavykusį paketą.
- Užklausų dažnio ribojimas: laikykitės dokumentacijoje nurodytų ribų ir taikomų pakartojimo instrukcijų. Naudokite ribotą laukimo laiką, o ne iškart vykdomus lygiagrečius bandymus.
- Laikinas paslaugos sutrikimas: kartokite bandymą per nustatytą bandymų ir laiko biudžetą.
- Skirtasis laikas po pateikimo: prieš manydami, kad pirmasis bandymas nepavyko, suderinkite siuntos registracijos būseną pagal dokumentuotą API elgseną.
- Su dublikatu susijęs atsakymas: patikrinkite, ar siunta jau užregistruota ir tinkamai susieta su jūsų programos įrašu.
Nemanykite, kad registracija yra idempotentinė, nebent dokumentacijoje taip apibrėžta. Programos lygio dublikatų šalinimas sumažina atsitiktinių pakartotinių pateikimų skaičių, tačiau nenustato teikėjo dublikatų tvarkymo politikos.
Naudokite jūsų siuntų modeliui tinkamą vidinę unikalumo taisyklę. Vien sekimo numerio gali nepakakti kaip ilgalaikio rakto tarp vežėjų ir ilgų saugojimo laikotarpių. Išsaugokite vežėjo kontekstą ir savo siuntos identifikatorių, taip pat aprašykite, kaip tvarkomos pakeistos ir pataisytos reikšmės.
Registraciją stebėkite atskirai nuo sekimo naujinių
API stebėsena turi atskirti integracijos gedimą nuo siuntos, kuri tiesiog neturi naujo vežėjo įvykio. Šioms sąlygoms reikia skirtingų atsakingų asmenų ir skirtingų sprendimų.
Registracijos atveju stebėkite priėmimų ir atmetimų skaičių, klaidų kategorijas, neaiškius rezultatus, pakartotinių bandymų eilę ir atsako delsą. Vėlesnio sekimo atveju atnaujinimų gavimo arba nuskaitymo klaidas stebėkite atskirai. Nenustatykite skaitinių įspėjimų ribų, kol nesuprasite įprasto srauto ir dokumentacijoje nurodytų teikėjo veikimo ribų.
Praktinis gamybinės aplinkos patikrinimas turėtų atsakyti:
- Ar kiekviena sekimo laukianti siunta turi registracijos įrašą?
- Ar kiekvieną priimtą registraciją galima susieti su tinkama pakuote?
- Ar atmesti elementai nukreipiami asmeniui, galinčiam ištaisyti pagrindinius duomenis?
- Ar neaiškios užklausos suderinamos, o ne paliekamos ar kartojamos neribotą laiką?
- Ar klientams rodomos būsenos nustatomos pagal siuntos įvykius, o ne registracijos priėmimą?
- Ar kredencialai ir nereikalinga asmeninė informacija neįtraukiami į žurnalus?
El. prekybos operacijose veiklos perdavimas yra toks pat svarbus kaip API iškvietimas. Kūrėjai turėtų būti atsakingi už perdavimo ir analizavimo klaidas; siuntimo arba įvykdymo komandos turėtų galėti tirti netinkamas etiketes, vežėjų susiejimus ir trūkstamą siuntų informaciją.
DUK
Ar galiu užregistruoti sekimo numerį prieš pirmąjį vežėjo nuskaitymą?
Registracija ir vežėjo nuskaitymai yra atskiri įvykiai. Paslauga gali priimti numerį dar prieš pasirodant sekimo įvykiams, atsižvelgiant į jos tikrinimo taisykles. Priėmimo nelaikykite įrodymu, kad vežėjas gavo siuntą.
Ar visada turiu pateikti vežėjo kodą?
Tai priklauso nuo API dokumentacijoje aprašytos aptikimo elgsenos ir konkrečios siuntos. Jei vežėjas žinomas, aiškus ir tinkamai susietas identifikatorius gali sumažinti dviprasmiškumą. Jei jis nežinomas, naudokite dokumentacijoje aprašytą automatinio aptikimo metodą, o ne sugalvokite vežėjo reikšmę.
Kodėl API grąžino HTTP sėkmę, nors siunta nepavyko?
HTTP užklausa gali būti sėkminga, o programa gali atmesti atskirą elementą. Perskaitykite aukščiausio lygio programos rezultatą ir siuntos lygio rezultatus. Šis skirtumas ypač svarbus paketų užklausoms.
Ką daryti, kai registracijos užklausos laikas baigiasi?
Laikykite rezultatą neaiškiu. Serveris galėjo apdoroti užklausą prieš nutrūkstant ryšiui. Patikrinkite dokumentacijoje nurodytą teikėjo elgseną su dublikatais ir galimus registracijos arba sekimo paieškos būdus, tada suderinkite arba pakartokite bandymą pagal ribotą politiką.
Ar registracija automatiškai sukonfigūruoja sekimo pranešimus?
Nemanykite, kad taip yra. Registracija, sekimo nuskaitymas ir webhook konfigūravimas yra atskiri integracijos aspektai. Patikrinkite atitinkamą dokumentaciją ir išbandykite visą atnaujinimo kelią prieš pasikliaudami juo klientų pranešimams.
Šaltiniai
- 17TRACK API documentation — registracijos galinių taškų, autentifikavimo, užklausos laukų, vežėjų identifikatorių, atsakymų schemų ir klaidų tvarkymo šaltinis. Įgyvendinimo detales suderinkite su diegiama API versija.
- 17TRACK Tracking API overview — oficialus pradinis taškas, skirtas sekimo API produktui ir kūrėjų integracijos ištekliams.


