Siuntos sekimo API darbo eiga: nuo siuntos registravimo iki sekimo informacijos gavimo
Siuntos sekimo API darbo eiga prasideda pateikiant sekimo numerį ir visą reikiamą vežėjo informaciją, patikrinant, ar registracija buvo sėkminga, suteikiant laiko sekimo duomenims tapti prieinamiems ir gaunant siuntos būseną bei įvykių istoriją. Produkcinėje integracijoje kūrėjai taip pat turi susieti kiekvieną sekimo įrašą su užsakymu, tvarkyti dalinius gedimus, saugiai apdoroti atnaujinimus ir atskirti priimtą registraciją nuo faktinio vežėjo nuskaitymo.
Šiame vadove kūrėjams paaiškinama ši darbo eiga, kai jie jungia elektroninės prekybos platformą, užsakymų valdymo sistemą, sandėlio programą arba klientų aptarnavimo įrankį. Jame atskiriamos programos projektavimo rekomendacijos nuo konkretaus teikėjo API reikalavimų. Integruodami 17TRACK, prieš įgyvendindami toliau pateiktus pavyzdžius naudokite oficialią API dokumentaciją, kad patvirtintumėte užklausos schemą, autentifikavimą, palaikomas operacijas ir atsakymo laukus.
Supraskite, ką registracija atlieka ir ko neatlieka
Siuntos registravimas sekimo paslaugoje reiškia identifikatoriaus pateikimą, kad paslauga galėtų sekti arba valdyti siuntą pagal savo API sutartį. Tai nėra tas pats, kas pašto išlaidų apmokėjimas, siuntimo etiketės sukūrimas, paėmimo užsakymas ar siuntos perdavimas vežėjui.
Programoje atskirkite tris rezultatus:
- Užklausa gauta: API grąžino atsakymą į jūsų HTTP užklausą.
- Registracija priimta: paslauga priėmė atskirą sekimo įrašą apdoroti.
- Sekimo informacija prieinama: paslauga turi siuntos informaciją, kurią jūsų programa gali gauti arba priimti.
Šių rezultatų nereikėtų sujungti į vieną „sėkmės“ požymį. Priimtas sekimo numeris dar gali neturėti jokių vežėjo įvykių. Taip pat sėkmingas HTTP atsakymas į paketinę užklausą neįrodo, kad kiekvienas paketo elementas buvo priimtas; patikrinkite teikėjo apibrėžtą programos lygmens rezultatų struktūrą.
1. Paruoškite siuntos identitetą ir API konfigūraciją
Prieš pateikdami registracijos užklausą nuspręskite, kaip siunta bus identifikuojama jūsų sistemoje. Vien užsakymo identifikatoriaus paprastai nepakanka, nes vienas užsakymas gali būti padalytas į kelias siuntas. Kiekvienai siuntai ar paketui sukurkite atskirą vidinį įrašą ir susiekite jį su atitinkamu užsakymu.
Naudingą vidinį įrašą sudaro ši informacija. Tai siūlomi programos laukai, o ne 17TRACK užklausos schema.
- Vidinis siuntos ID: stabilus jūsų paketo identifikatorius.
- Užsakymo nuoroda: užsakymo arba įvykdymo įrašas, kuriam priklauso siunta.
- Sekimo numeris: vežėjo išduotas identifikatorius, saugomas kaip tekstas, kad būtų išsaugoti pradiniai nuliai.
- Vežėjo informacija: jūsų užsakymų vykdymo sistemos pateikta vežėjo tapatybė, jei ji žinoma.
- Teikėjo nuoroda: bet koks sekimo paslaugos grąžintas identifikatorius, reikalingas vėlesnėms operacijoms.
- Registracijos būsena: jūsų įrašas, nurodantis, ar pateikimas laukiamas, priimtas, atmestas arba laukia suderinimo.
- Sekimo būsena: naujausia siuntos būsena, saugoma atskirai nuo registracijos būsenos.
Prieš pateikdami užklausą patikrinkite įvestį. Pašalinkite atsitiktinius tarpus pradžioje ir pabaigoje, tačiau neperrašykite sekimo numerio remdamiesi prielaidomis apie vežėjo formatą. Išsaugokite pradinę reikšmę trikčių šalinimui. Jei vežėjas žinomas, susiekite jį su dokumentacijoje nurodytu teikėjo vežėjo identifikatoriumi, o ne siųskite neoficialų rodomą pavadinimą.
Autentifikavimą konfigūruokite serverio pusėje. Saugokite prisijungimo duomenis ne šaltinio kode, atskirkite kūrimo ir produkcinę konfigūraciją bei pašalinkite paslaptis iš žurnalų. Patvirtinkite dokumentacijoje nurodytą API versiją, užklausų limitus, paketų limitus ir paskyros reikalavimus, o ne perimkite reikšmes iš nesusijusios integracijos.
2. Užregistruokite siuntą ir įrašykite elemento lygmens rezultatą
Pateikite sekimo įrašą naudodami teikėjo dokumentacijoje aprašytą registracijos operaciją. Įtraukite tik būtinus laukus ir pasirenkamą informaciją, turinčią aiškią paskirtį. Nesiųskite klientų vardų, adresų ar kitų asmens duomenų vien todėl, kad jie yra jūsų užsakymų duomenų bazėje.
Toliau pateiktas pseudokodas iliustruoja programos seką. Funkcijų pavadinimai yra iliustraciniai; tai nėra API galiniai taškai ar SDK metodai.
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)
Išsaugokite pakankamai informacijos, kad galėtumėte paaiškinti, kas įvyko: vidinį siuntos ID, pateikimo laiką, bandymo numerį, elemento lygmens rezultatą ir bet kokią teikėjo užklausos nuorodą. Nepasikliaukite vien trumpalaikiu darbuotojo žurnalu. Klientų aptarnavimo ir veiklos komandoms reikia patikimo atsakymo, ar siunta buvo sėkmingai įtraukta.
Partines užklausas tvarkykite atskirai
Jei API palaiko paketinę registraciją, susiekite kiekvieną grąžintą elementą su pradine siunta. Nepažymėkite viso paketo kaip priimto vien todėl, kad HTTP užklausa buvo baigta sėkmingai. Išsaugokite priimtus elementus, atskirkite atmestus ir atskirai ištirkite neaiškius rezultatus.
Taip išvengsite situacijos, kai dėl vieno netinkamo sekimo numerio be reikalo pakartotinai siunčiami jau sėkmingi įrašai. Be to, veiklos darbuotojai gaus konkretų įrašų, kuriuos reikia taisyti, sąrašą.
Skirtį laikykite neaiškiu rezultatu
Skirtis neįrodo, kad registracija nepavyko. Teikėjas galėjo priimti užklausą prieš nutrūkstant jūsų ryšiui. Prieš aklai pateikdami užklausą iš naujo naudokite dokumentuotą idempotentiškumo elgseną, pasikartojančių užklausų tvarkymą arba paieškos operacijas rezultatui suderinti.
Kai teikėjo elgsena pasikartojančių užklausų atveju neaiški, išbandykite ją su kontroliuojamais įrašais ir prieš įjungdami automatinius pakartojimus patvirtinkite sutartį. Vidinis registracijos užduočių dubliavimo panaikinimas vis tiek naudingas, tačiau jis nepakeičia supratimo, kaip nuotolinė paslauga tvarko pakartotines užklausas.
3. Palaukite, kol gausite pirmąją sekimo informaciją
Priėmus registraciją, sekimo informacija gali būti prieinama ne iš karto. Etiketė gali egzistuoti dar prieš vežėjui užregistruojant fizinio tvarkymo įvykį. Trūkstama informacija taip pat gali reikšti, kad reikia patikrinti sekimo numerį, vežėjo pasirinkimą arba konkrečiai siuntai taikomus paieškos reikalavimus.
Šią būseną išreikškite aiškiai. „Užregistruota; laukiama sekimo informacijos“ yra tiksliau nei „Vežama“ arba „Registracija nepavyko“. Nekurkite pristatymo prognozės ar judėjimo įvykio vien tam, kad užpildytumėte tuščią sąsają.
Kai įrašas lieka tuščias, tikrinkite praktiška tvarka:
- Patvirtinkite, kad atskira registracija buvo priimta.
- Palyginkite pateiktą sekimo numerį su užsakymo vykdymo įrašu.
- Patikrinkite vežėjo susiejimą ir visus dokumentacijoje nurodytus papildomus paieškos reikalavimus.
- Patikrinkite to paties vežėjo siuntos sekimo puslapį.
- Jei vežėjas turi įvykių, o jūsų integracija jų nerodo, išnagrinėkite gavimo atsakymus ir susisiekite su API teikėju pateikdami nuasmenintą diagnostinę informaciją.
Venkite nustatyti visuotinį laukimo laikotarpį neturėdami įrodymų. Eskalavimo taisyklės turėtų atspindėti siuntimo paslaugą, numatomą perdavimo procesą ir jūsų veiklos įsipareigojimus.
4. Gaukite sekimo duomenis ir teisingai juos interpretuokite
Kai įrašas prieinamas, iškvieskite dokumentacijoje aprašytą sekimo duomenų gavimo operaciją naudodami reikiamus identifikatorius. Nemanykite, kad registracijai ir gavimui naudojami tie patys laukai. Kai kuriose API sutartyse atskiriami sekimo numeriai, vežėjų identifikatoriai ir teikėjo sugeneruotos įrašų nuorodos.
Programa turėtų atskirti tris informacijos sluoksnius:
- Siuntos santrauka: bendra būsena, naudojama skydeliuose, užsakymų puslapiuose ir veiklos filtruose.
- Įvykių istorija: atskiri stebėjimai, įskaitant įvykių aprašymus, laiko žymas ir vietas, jei jos pateiktos.
- Gavimo metaduomenys: kada programa gavo arba iškvietė informaciją ir ar užklausa buvo įvykdyta sėkmingai.
Sėkminga paieška reiškia, kad gavimo operacija pavyko. Tai nereiškia, kad paketas pajudėjo nuo ankstesnės paieškos. Prieš kurdami pranešimą ar tolesnę darbo eigą palyginkite grąžintą sekimo informaciją su išsaugotu įrašu.
Įvykio laiką laikykite atskirai nuo gavimo laiko
Vežėjo įvykiui priskirtą laiką saugokite atskirai nuo laiko, kada jūsų sistema jį gavo. Šią popietę gautas įvykis gali apibūdinti ankstesnį nuskaitymą. Pakeitus įvykio laiką gavimo laiku, senas atnaujinimas atrodytų kaip naujas fizinis judėjimas.
Išsaugokite pradinę laiko žymą ir bet kokį pateiktą poslinkį. Laiko žymas normalizuokite palyginimui tik tada, kai laiko juosta žinoma. Jei įvykis neturi informacijos apie laiko juostą, išsaugokite šį neapibrėžtumą, o ne tyliai priskirkite serverio laiko juostą.
Išsaugokite pradinę reikšmę kartu su normalizuota būsena
Normalizuota būsena naudinga grupuojant skirtingų vežėjų siuntas, tačiau pradinis įvykio aprašymas gali tiksliau paaiškinti veiklos problemą. Jei įmanoma, saugokite abu. Vien plati išimties kategorija gali nepasakyti klientų aptarnavimo darbuotojui, ar reikia tikrinti adresą, susisiekti su gavėju, ar laukti kito atnaujinimo.
Neišveskite pristatymo garantijos, patvirtinto praradimo ar konkretaus muitinės rezultato iš neaiškios būsenos. Eskaluokite pagal pagrindinę informaciją ir savo veiklos politiką.
5. Atnaujinkite įrašus naudodami apklausą arba saityno kablius
Vienkartinio duomenų gavimo pakanka ryšiui patikrinti, bet ne siuntos matomumui palaikyti. Produkcinėje architektūroje reikia atnaujinimo mechanizmo. Patvirtinkite pasirinkto teikėjo palaikomus mechanizmus ir jiems taikomas sąlygas.
Naudojant apklausą, programa pagal tvarkaraštį prašo sekimo duomenų. Planuokite užklausas neviršydami dokumentuotų limitų, be priežasties pakartotinai neklauskite nepasikeitusių įrašų ir pakartotinoms klaidoms naudokite laipsniškai ilginamus intervalus. Klientui atidarius užsakymo puslapį neturėtų būti automatiškai siunčiama neribota aukštesnio lygio užklausa; puslapį gali aptarnauti išsaugotas sekimo vaizdas, o kontroliuojamas foninis procesas jį atnaujinti.
Jei naudojate saityno kablius, gaunamas užklausas patikrinkite naudodami teikėjo dokumentuotą tikrinimo mechanizmą. Priimtus pranešimus išsaugokite arba patikimai įtraukite į eilę prieš patvirtindami jų gavimą pagal saityno kablio sutartį, o įvykius apdorokite asinchroniškai.
Sukurkite gavėją taip, kad jis toleruotų dublikatus ir netikėtą gavimo tvarką, nebent dokumentuota pristatymo sutartis garantuoja kitaip. Jei įmanoma, dubliavimui panaikinti naudokite teikėjo įvykio identifikatorių. Kitu atveju apibrėžkite ir išbandykite pirštų atspaudą pagal tinkamus įvykio laukus, pripažindami, kad jį gali reikėti pritaikyti jūsų duomenims.
Saityno kabliais paremta integracija taip pat gali naudoti kontroliuojamą gavimą suderinimui. Pavyzdžiui, atkūrimo užduotis gali patikrinti įrašus, kuriuos paveikė gavėjo sutrikimas. Tai atsparumo modelis, o ne leidimas nepaisyti užklausų limitų ar konkretaus teikėjo nurodymų.
6. Paverskite sekimo informaciją saugiais verslo veiksmais
Prieš inicijuodami klientams matomus veiksmus atnaujinkite vidinį siuntos įrašą. Saugokite patikimą pranešimų ir darbo eigos perėjimų istoriją, kad pasikartojantis įvykis nesukurtų pasikartojančių pranešimų.
Verslo veiksmus susiekite su prasmingais pokyčiais, o ne su kiekvienu API atsakymu. Naujai pastebėtas pristatymo įvykis gali pagrįsti pranešimą apie pristatymą. Pakartotinis atsakymas su tuo pačiu įvykiu – ne. Išimtis gali pagrįsti vidinę peržiūrą, tačiau klientui skirtas pranešimas turėtų atspindėti tai, kas iš tikrųjų nurodyta įvykyje.
Apibrėžkite, kaip tvarkysite įvykius, gautus po to, kai siunta buvo laikoma užbaigta. Neištrinkite įvykių istorijos ir visam laikui neužblokuokite vėlesnių atnaujinimų vien todėl, kad santrauka pasiekė galutinę būseną. Saugojimo, suderinimo ir pranešimų taisyklės turėtų atsižvelgti į teisėtus pataisymus, tačiau neperkelti užbaigtų darbo eigų į pradžią pakartotinai.
Darbo eigos taikymas 17TRACK integracijoje
Individualiai sekimo integracijai aktualūs pradiniai šaltiniai yra 17TRACK Tracking API puslapis ir jo kūrėjų dokumentacija. Produkto puslapį naudokite pasiūlymui įvertinti, o dokumentaciją – faktinei integracijos sutarčiai nustatyti. Vartotojų sekimo puslapiai nepakeičia API specifikacijų.
Prieš rašydami adapterį patvirtinkite autentifikavimo formatą, registravimo ir gavimo operacijas, vežėjo identifikavimo taisykles, elemento lygmens atsakymų tvarkymą ir taikomus užklausų limitus. Apdorodami saityno kablius taip pat patvirtinkite naudingosios apkrovos schemą, tikrinimo procesą, patvirtinimo reikalavimus ir pakartojimų elgseną.
Šią konkrečiam teikėjui skirtą informaciją laikykite adapteryje, o ne paskleiskite atsakymo laukų prielaidas po visą užsakymų sistemą. Tuomet likusi programa galės naudoti vidines sąvokas, tokias kaip registracijos rezultatas, siuntos būsena, įvykių istorija ir paskutinis sėkmingas sinchronizavimas.
Patikros prieš paleidimą, padedančios išvengti brangių klaidų
- Priimtas, bet tuščias įrašas: sąsaja rodo, kad sekimo informacija laukiama, o ne kad paketas juda.
- Mišrus paketo rezultatas: kiekviena siunta gauna atskirai išsaugotą rezultatą.
- Skirtis po pateikimo: darbuotojas suderina neaiškų rezultatą, o ne daro prielaidą, kad operacija nepavyko.
- Pasikartojantis įvykis: siuntos laiko juosta ir kliento pranešimas lieka nedubliuoti.
- Vėliau gautas senesnis įvykis: įvykis išsaugomas aklai nepakeičiant naujesnės santraukos.
- Nepasiekiama aukštesnio lygio paslauga: kliento puslapyje gali būti rodomas paskutinis išsaugotas rezultatas su tinkama šviežumo nuoroda.
- Neteisingas vežėjo susiejimas: įrašą galima pataisyti dokumentuotu atkūrimo keliu.
- Padalytas užsakymas: kiekvienas paketas išsaugo savo sekimo būseną ir įvykių istoriją.
- Prisijungimo duomenų arba naudingosios apkrovos atskleidimas: žurnaluose yra diagnostinės nuorodos, tačiau neatskleidžiamos paslaptys ar nereikalinga asmeninė informacija.
Praktinis užbaigtumo kriterijus nėra vien sėkmingo registracijos atsakymo gavimas. Svarbu gebėti atsekti paketą nuo pateikimo iki atnaujinimų, paaiškinti tuščią arba nesėkmingą rezultatą ir atkurti nutrūkusį apdorojimą neprarandant įvykių ar nekartojant klientų veiksmų.
DUK
Ar sekimo numerio registracija sukuria siuntą?
Ne pagal čia aprašytą darbo eigą. Sekimo registracija pateikia esamą identifikatorių sekimo paslaugai. Etiketės sukūrimas, pašto išlaidų apmokėjimas ir vežėjo užsakymas yra atskiros operacijos, nebent konkreti API jas aiškiai sujungia.
Kodėl po sėkmingos registracijos sekimo duomenys tušti?
Registracijos priėmimas ir sekimo duomenų prieinamumas yra skirtingos sąlygos. Vežėjas dar galėjo neužregistruoti įvykio arba gali reikėti patikrinti sekimo numerį, vežėjo susiejimą ar papildomą paieškos informaciją. Prieš laikydami įrašą sėkmingai užregistruotu patikrinkite elemento lygmens rezultatą.
Ar turėčiau registruoti siuntą kiekvieną kartą, kai gaunu jos būseną?
Nenaudokite pakartotinės registracijos kaip numatytojo atnaujinimo mechanizmo. Išsaugokite priimtos registracijos būseną ir naudokite dokumentuotą gavimo arba atnaujinimo mechanizmą. Laikykitės aiškių teikėjo taisyklių dėl pataisymų, pakartotinio suaktyvinimo ar pasikartojančių pateikimų.
Ar turėčiau naudoti apklausą, ar saityno kablius?
Naudokite mechanizmą, kuris atitinka dokumentuotą API sutartį ir jūsų veiklos reikalavimus. Apklausai reikalingas kontroliuojamas užklausų tvarkaraštis. Saityno kabliams reikalingas saugus, patikimas gavėjas ir dublikatus toleruojantis apdorojimas. Jei palaikoma, saityno kablių atnaujinimai kartu su tikslingu suderinimu gali būti praktiškas atkūrimo kelias.
Ar galiu naudoti sekimo numerį kaip vienintelį siuntos identifikatorių duomenų bazėje?
Naudokite vidinį siuntos identifikatorių. Sekimo numerį ir susijusį vežėjo kontekstą saugokite kaip šio įrašo atributus. Taip lengviau valdyti padalytus užsakymus, pataisytus sekimo numerius ir konkrečiam teikėjui skirtas nuorodas, nekeičiant vidinės siuntos tapatybės.
Šaltiniai
- 17TRACK Tracking API — oficialus produkto pradžios taškas vertinant 17TRACK API integraciją.
- 17TRACK API dokumentacija — oficialus įgyvendinimo užklausų formatų, operacijų, atsakymų ir integracijos reikalavimų šaltinis. Šiame vadove pateiktas pseudokodas ir vidinių laukų pasiūlymai yra programos projektavimo pavyzdžiai, o ne šios API sutarties citatos.


