Potek dela API-ja za sledenje pošiljkam: od registracije pošiljke do pridobivanja podrobnosti o sledenju
Potek dela API-ja za sledenje pošiljkam se začne s pošiljanjem sledilne številke in vseh zahtevanih podatkov o prevozniku, preverjanjem, ali je bila registracija uspešna, omogočanjem, da podatki o sledenju postanejo na voljo, ter pridobivanjem statusa pošiljke in zgodovine dogodkov. Pri produkcijski integraciji morajo razvijalci vsak zapis sledenja povezati tudi z naročilom, obravnavati delne napake, varno obdelovati posodobitve ter razlikovati med sprejeto registracijo in dejanskim skeniranjem pri prevozniku.
Ta vodnik pojasnjuje ta potek dela za razvijalce, ki povezujejo platformo za e-trgovino, sistem za upravljanje naročil, skladiščno aplikacijo ali orodje za podporo strankam. Priporočila za zasnovo aplikacije ločuje od zahtev API-ja, specifičnih za ponudnika. Za integracijo 17TRACK pred izvedbo spodnjih primerov uporabite uradno dokumentacijo API-ja, da potrdite shemo zahtev, preverjanje pristnosti, podprte operacije in polja odgovorov.
Razumite, kaj registracija omogoča – in česa ne
Registracija pošiljke pri storitvi za sledenje pomeni predložitev identifikatorja, da lahko storitev pošiljko sledi ali jo upravlja v skladu s svojo pogodbo API. To ni enaka operacija kot nakup poštnine, ustvarjanje odpremne etikete, naročilo prevzema ali predaja paketa prevozniku.
V aplikaciji ločite tri izide:
- Zahteva prejeta: API je vrnil odgovor na vašo zahtevo HTTP.
- Registracija sprejeta: Storitev je posamezni zapis sledenja sprejela v obdelavo.
- Podatki o sledenju na voljo: Storitev ima informacije o pošiljki, ki jih lahko vaša aplikacija pridobi ali prejme.
Teh izidov ne smete združiti v eno samo zastavico »uspeh«. Sprejeta sledilna številka morda še nima dogodkov prevoznika. Prav tako uspešen odgovor HTTP za paketno zahtevo ne pomeni, da je bil sprejet vsak element paketa; preverite strukturo rezultata na ravni aplikacije, ki jo določa ponudnik.
1. Pripravite identiteto pošiljke in konfiguracijo API-ja
Pred pošiljanjem zahteve za registracijo določite, kako bo pošiljka identificirana v vašem sistemu. Sam identifikator naročila običajno ni dovolj, saj je lahko eno naročilo razdeljeno na več paketov. Vsaki pošiljki ali paketu dodelite lasten notranji zapis in ga povežite z ustreznim naročilom.
Uporaben notranji zapis vključuje naslednje podatke. To so predlagana polja aplikacije, ne shema zahteve 17TRACK.
- Notranji ID pošiljke: Stabilni identifikator paketa.
- Referenca naročila: Naročilo ali zapis izpolnitve naročila, ki mu pripada.
- Sledilna številka: Identifikator, ki ga je izdal prevoznik in je shranjen kot besedilo, da se ohranijo začetne ničle.
- Podatki o prevozniku: Identiteta prevoznika, ki jo zagotavlja vaš sistem izpolnitve naročil, če je znana.
- Referenca ponudnika: Kateri koli identifikator, ki ga vrne storitev za sledenje in je potreben za poznejše operacije.
- Stanje registracije: Zapis o tem, ali je oddaja v čakanju, sprejeta, zavrnjena ali čaka na uskladitev.
- Stanje sledenja: Najnovejši status pošiljke, ki se vzdržuje ločeno od stanja registracije.
Pred oddajo preverite vnos. Odstranite nenamerno okoliško presledovanje, vendar sledilne številke ne preoblikujte na podlagi predpostavk o formatu prevoznika. Izvirno vrednost ohranite za odpravljanje težav. Če je prevoznik znan, ga preslikajte v dokumentirani identifikator prevoznika ponudnika, namesto da pošljete neformalno prikazno ime.
Preverjanje pristnosti konfigurirajte na strežniški strani. Poverilnice hranite zunaj izvorne kode, razvojno in produkcijsko konfiguracijo ločite ter skrivnosti iz dnevnikov odstranite ali zakrijte. Potrdite dokumentirano različico API-ja, omejitve zahtev, omejitve paketov in zahteve računa, namesto da bi si izposodili vrednosti iz nepovezane integracije.
2. Registrirajte pošiljko in zabeležite rezultat na ravni elementa
Zapis sledenja pošljite z uporabo operacije registracije, opisane v dokumentaciji ponudnika. Vključite samo obvezna polja in neobvezne podatke, ki imajo določen namen. Izogibajte se pošiljanju imen strank, naslovov ali drugih osebnih podatkov samo zato, ker so na voljo v vaši podatkovni zbirki naročil.
Naslednja psevdokoda prikazuje zaporedje v aplikaciji. Imena funkcij so zgolj ponazoritvena; niso končne točke API-ja ali metode SDK-ja.
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)
Shranite dovolj informacij za razlago dogajanja: notranji ID pošiljke, čas oddaje, številko poskusa, izid na ravni elementa in morebitno referenco zahteve ponudnika. Ne zanašajte se samo na začasen dnevnik delavca. Ekipa za podporo strankam in operativna ekipa potrebujeta trajen odgovor na vprašanje, ali je bila pošiljka uspešno vključena.
Paketne oddaje obravnavajte posamično
Če API podpira paketno registracijo, vsak vrnjeni element povežite z izvirno pošiljko. Celotnega paketa ne označite kot sprejetega samo zato, ker se je zahteva HTTP uspešno zaključila. Sprejete elemente shranite, zavrnjene ločite, nejasne rezultate pa obravnavajte posebej.
S tem preprečite, da bi ena neveljavna sledilna številka povzročila nepotrebne ponovne poskuse zapisov, ki so že uspeli. Operativnemu osebju to zagotovi tudi uporaben seznam zapisov, ki jih je treba popraviti.
Časovne prekoračitve obravnavajte kot neznan izid
Časovna prekoračitev ne dokazuje, da registracija ni uspela. Ponudnik je morda zahtevo sprejel, preden je bila vaša povezava prekinjena. Pred slepim ponovnim pošiljanjem uporabite dokumentirano vedenje idempotentnosti, obravnavo dvojnikov ali operacije iskanja za uskladitev rezultata.
Če vedenje ponudnika pri dvojnikih ni jasno, ga preizkusite z nadzorovanimi zapisi in pred omogočanjem samodejnih ponovnih poskusov potrdite pogodbo. Notranje odstranjevanje podvojenih registracijskih opravil je še vedno koristno, vendar ne nadomesti razumevanja, kako oddaljena storitev obravnava ponovljene zahteve.
3. Počakajte, da prispejo prvi podatki o sledenju
Po sprejetju registracije podatki o sledenju morda ne bodo takoj na voljo. Etiketa lahko obstaja, še preden je prevoznik zabeležil fizični dogodek obdelave. Manjkajoče informacije lahko zahtevajo tudi preverjanje sledilne številke, izbire prevoznika ali zahtev za iskanje, specifičnih za pošiljko.
To stanje predstavite izrecno. »Registrirano; čaka na podatke o sledenju« je natančneje kot »V tranzitu« ali »Registracija ni uspela«. Ne izmišljajte predvidenega časa dostave ali dogodka premika, da bi zapolnili prazen vmesnik.
Ko zapis ostane prazen, preverjajte v praktičnem vrstnem redu:
- Potrdite, da je bila posamezna registracija sprejeta.
- Primerjajte poslano sledilno številko z zapisom izpolnitve naročila.
- Preverite preslikavo prevoznika in vse dokumentirane dodatne zahteve za iskanje.
- Na strani za sledenje prevoznika preverite isto pošiljko.
- Če ima prevoznik dogodke, vaša integracija pa ne, preglejte odgovore pri pridobivanju in se obrnite na ponudnika API-ja z zakritimi diagnostičnimi podatki.
Izogibajte se univerzalnemu čakalnemu obdobju brez dokazov. Pravila za stopnjevanje naj upoštevajo prevozno storitev, pričakovani postopek predaje in vaše lastne operativne zaveze.
4. Pridobite podatke o sledenju in jih pravilno razlagajte
Ko je zapis na voljo, pokličite dokumentirano operacijo za podrobnosti sledenja z uporabo zahtevanih identifikatorjev. Ne predpostavljajte, da registracija in pridobivanje sprejemata enaka polja. Nekatere pogodbe API razlikujejo med sledilnimi številkami, identifikatorji prevoznikov in referencami zapisov, ki jih ustvari ponudnik.
Aplikacija naj razlikuje med tremi plastmi informacij:
- Povzetek pošiljke: Splošno stanje, ki se uporablja na nadzornih ploščah, straneh naročil in pri operativnih filtrih.
- Zgodovina dogodkov: Posamezna opažanja, vključno z opisi dogodkov, časovnimi žigi in lokacijami, kadar so navedeni.
- Metapodatki pridobivanja: Kdaj je aplikacija informacije prejela ali pridobila in ali se je zahteva uspešno zaključila.
Uspešno iskanje pomeni, da je bila operacija pridobivanja uspešna. Ne pomeni, da se je paket od prejšnjega iskanja premaknil. Pred ustvarjanjem obvestila ali nadaljnjega delovnega toka vrnjene podatke o sledenju primerjajte s shranjenim zapisom.
Čas dogodka ločite od časa pridobivanja
Čas, povezan z dogodkom prevoznika, shranite ločeno od časa, ko ga je prejel vaš sistem. Dogodek, pridobljen danes popoldne, lahko opisuje prejšnje skeniranje. Če njegov čas dogodka nadomestite s časom pridobivanja, bo star posodobitveni podatek videti kot nov fizični premik.
Ohranite izvirni časovni žig in morebitni navedeni odmik. Časovne žige normalizirajte za primerjavo samo, kadar je časovni pas znan. Če dogodek nima podatka o časovnem pasu, ohranite to negotovost, namesto da mu tiho dodelite časovni pas strežnika.
Ob normaliziranem statusu ohranite tudi izvirni pomen
Normaliziran status je uporaben za združevanje pošiljk med prevozniki, vendar lahko izvirni opis dogodka operativno težavo pojasni natančneje. Kjer je mogoče, ohranite oboje. Sama široka kategorija izjeme podpornemu agentu morda ne pove, ali je naslednji korak preverjanje naslova, stik s prejemnikom ali čakanje na novo posodobitev.
Iz nejasnega statusa ne sklepajte na jamstvo za dostavo, potrjeno izgubo ali določen carinski izid. Stopnjevanje izvedite na podlagi osnovnih informacij in svoje operativne politike.
5. Zapise posodabljajte z anketiranjem ali spletnimi kavlji
Enkratno pridobivanje podrobnosti zadostuje za preizkus povezljivosti, ne pa za vzdrževanje vidljivosti pošiljke. Produkcijska zasnova potrebuje mehanizem posodabljanja. Potrdite mehanizme, ki jih podpira izbrani ponudnik, in pogoje, povezane z njimi.
Pri anketiranju aplikacija po urniku zahteva podatke o sledenju. Zahteve razporedite znotraj dokumentiranih omejitev, izogibajte se ponavljajočemu se poizvedovanju po nespremenjenih zapisih brez razloga in pri ponovljivih napakah uporabite postopno podaljševanje intervala. Odprtje strani naročila s strani stranke ne sme samodejno sprožiti neomejene zahteve do zunanje storitve; shranjen pogled sledenja lahko prikaže stran, medtem ko ga nadzorovan proces v ozadju osveži.
Če uporabljate spletne kavlje, dohodne zahteve preverite z dokumentiranim mehanizmom preverjanja ponudnika. Sprejeta sporočila shranite ali jih trajno postavite v čakalno vrsto, preden jih potrdite v skladu s pogodbo spletnega kavlja, nato pa dogodke obdelajte asinhrono.
Sprejemnik zasnujte tako, da prenaša dvojnike in nepričakovano zaporedje prihodov, razen če dokumentirana pogodba dostave zagotavlja drugače. Kadar je na voljo, za odstranjevanje dvojnikov uporabite identifikator dogodka ponudnika. V nasprotnem primeru določite in preizkusite prstni odtis na podlagi ustreznih polj dogodka, pri čemer upoštevajte, da bodo morda potrebne prilagoditve za vaše podatke.
Integracija, vodena s spletnimi kavlji, lahko za uskladitev uporablja tudi nadzorovano pridobivanje. Obnovitveno opravilo lahko na primer preveri zapise, na katere je vplival izpad sprejemnika. To je vzorec odpornosti, ne dovoljenje za ignoriranje omejitev hitrosti ali navodil, specifičnih za ponudnika.
6. Informacije o sledenju pretvorite v varna poslovna dejanja
Pred sprožitvijo dejanj, usmerjenih v stranke, posodobite notranji zapis pošiljke. Ohranite trajen zapis obvestil in prehodov delovnega toka, da ponovljen dogodek ne bo ustvaril ponovljenih sporočil.
Poslovna dejanja preslikajte na pomembne spremembe, ne na vsak odgovor API-ja. Na novo opažen dogodek dostave lahko upraviči obvestilo o dostavi. Ponovljen odgovor z istim dogodkom ga ne sme. Izjema lahko upraviči notranji pregled, vendar mora sporočilo stranki odražati dejansko vsebino dogodka.
Določite, kako boste obravnavali dogodke, prejete po tem, ko je bila pošiljka obravnavana kot zaključena. Ne izbrišite zgodovine dogodkov in trajno ne blokirajte vseh poznejših posodobitev samo zato, ker je povzetek dosegel končno stanje. Pravila hrambe, usklajevanja in obveščanja morajo upoštevati upravičene popravke, ne da bi vedno znova odpirala zaključene delovne tokove.
Uporaba poteka dela pri integraciji 17TRACK
Pri integraciji po meri sta ustrezni začetni točki stran API-ja za sledenje 17TRACK in njegova dokumentacija za razvijalce. Stran izdelka uporabite za oceno ponudbe, dokumentacijo pa za določitev dejanske integracijske pogodbe. Potrošniške strani za sledenje niso nadomestilo za specifikacije API-ja.
Pred pisanjem adapterja potrdite obliko preverjanja pristnosti, operacije registracije in pridobivanja, pravila identifikacije prevoznika, obravnavo odgovorov na ravni elementa in veljavne omejitve zahtev. Pri obdelavi na podlagi spletnih kavljev potrdite tudi shemo koristnega tovora, postopek preverjanja, zahteve za potrditve in vedenje pri ponovnih poskusih.
Te podrobnosti, specifične za ponudnika, hranite znotraj adapterja, namesto da predpostavke o poljih odgovorov razpršite po celotnem sistemu naročil. Preostanek aplikacije lahko nato deluje z notranjimi koncepti, kot so izid registracije, status pošiljke, zgodovina dogodkov in zadnja uspešna sinhronizacija.
Preverjanja pred zagonom, ki odkrijejo drage napake
- Sprejet, vendar prazen zapis: Vmesnik kaže, da so podatki o sledenju v čakanju, ne da se paket premika.
- Mešan rezultat paketa: Vsaka pošiljka prejme lasten shranjeni izid.
- Časovna prekoračitev po oddaji: Delavec uskladi negotov izid, namesto da bi predpostavil neuspeh.
- Ponovljen dogodek: Časovnica pošiljke in obvestilo stranki ostaneta brez dvojnikov.
- Starejši dogodek, prejet pozneje: Dogodek se ohrani, ne da bi slepo nadomestil novejši povzetek.
- Nedostopna zunanja storitev: Stran za stranko lahko prikaže zadnji shranjeni rezultat z ustreznim prikazom ažurnosti.
- Nepravilna preslikava prevoznika: Zapis je mogoče popraviti po dokumentirani poti za obnovitev.
- Razdeljeno naročilo: Vsak paket ohrani svoje stanje sledenja in zgodovino dogodkov.
- Izpostavitev poverilnic ali koristnega tovora: Dnevniki vsebujejo diagnostične reference, ne da bi razkrivali skrivnosti ali nepotrebne osebne podatke.
Praktično merilo dokončanja ni zgolj prejem uspešnega odgovora za registracijo. Gre za možnost sledenja paketu od oddaje prek posodobitev, razlage praznega ali neuspešnega rezultata ter obnovitve prekinjene obdelave brez izgube dogodkov ali podvajanja dejanj za stranke.
Pogosta vprašanja
Ali registracija sledilne številke ustvari pošiljko?
Ne v tukaj opisanem poteku dela. Registracija sledenja pošlje obstoječi identifikator storitvi za sledenje. Ustvarjanje etikete, nakup poštnine in naročilo prevoznika so ločene operacije, razen če jih določen API izrecno združuje.
Zakaj so podatki o sledenju prazni, če je registracija uspešna?
Sprejetje registracije in razpoložljivost podatkov o sledenju sta različna pogoja. Prevoznik morda še ni zabeležil dogodka ali pa je treba preveriti sledilno številko, preslikavo prevoznika ali dodatne informacije za iskanje. Preden zapis obravnavate kot uspešno registriran, preglejte rezultat na ravni elementa.
Ali naj pošiljko registriram vsakič, ko pridobim njen status?
Ponavljajoče se registracije ne uporabljajte kot privzeti mehanizem osveževanja. Shranite sprejeto stanje registracije in uporabite dokumentirani mehanizem pridobivanja ali posodabljanja. Upoštevajte izrecna pravila ponudnika za popravke, ponovno aktivacijo ali podvojene oddaje.
Ali naj uporabim anketiranje ali spletne kavlje?
Uporabite mehanizem, ki ustreza dokumentirani pogodbi API-ja in vašim operativnim zahtevam. Anketiranje zahteva nadzorovan urnik zahtev. Spletni kavlji zahtevajo varen, trajen sprejemnik in obdelavo, varno pred dvojniki. Kjer je podprto, lahko posodobitve prek spletnih kavljev s ciljno uskladitvijo zagotovijo praktično pot obnovitve.
Ali lahko sledilno številko uporabim kot edini identifikator pošiljke v podatkovni zbirki?
Namesto tega uporabite notranji identifikator pošiljke. Sledilno številko in ustrezen kontekst prevoznika shranite kot atributa tega zapisa. Tako boste lažje upravljali razdeljena naročila, popravljene sledilne številke in reference, specifične za ponudnika, ne da bi spremenili identiteto notranje pošiljke.
Viri
- 17TRACK Tracking API — uradna vstopna točka izdelka za ocenjevanje integracije API-ja 17TRACK.
- Dokumentacija API-ja 17TRACK — uradna referenca za formate zahtev, specifične za izvedbo, operacije, odgovore in zahteve integracije. Psevdokoda in predlogi notranjih polj v tem vodniku so primeri zasnove aplikacije, ne navedki iz te pogodbe API-ja.


