Skip to main content
DomovBlogVodnikiKatere podatke bi moral vrniti API za sledenje? 12 polj poleg trenutnega stanja?

Katere podatke bi moral vrniti API za sledenje? 12 polj poleg trenutnega stanja?

17TRACK

API za sledenje mora vrniti več kot le oznako, kot je »V tranzitu«. Poleg trenutnega stanja poiščite identifikatorje pošiljke, identiteto prevoznika, podrobne informacije o stanju, izvirna sporočila prevoznika, zgodovino dogodkov, časovne žige dogodkov, lokacije, predvidene datume dostave, izjeme, predaje med prevozniki, podrobnosti o dostavi in metapodatke o svežini podatkov. Teh 12 skupin podatkov razvijalcem skupaj pomaga graditi zanesljive delovne tokove, operativnim ekipam pa zagotavlja dovolj konteksta za ukrepanje.

Katere podatke mora vrniti API za sledenje: 12 polj poleg stanja

To je priporočena pogodba odziva za razvijalce, tehnične kupce in ekipe za e-trgovinsko poslovanje – ne trditev, da vsak prevoznik ali API zagotavlja vsako polje. Nekatere vrednosti upravičeno ne bodo na voljo. Boljša zasnova te vrzeli jasno označi, namesto da jih zapolni s predpostavkami.

Kaj naredi podatke o sledenju uporabne?

Trenutno stanje odgovarja na eno ozko vprašanje: kakšno je povzeto stanje pošiljke? Ni nujno, da pojasni, kaj se je zgodilo, kdaj se je zgodilo, ali so informacije aktualne oziroma kaj naj nekdo stori naslednje.

Na primer, dve pošiljki lahko obe prikazujeta »V tranzitu«, vendar zahtevata različna odziva. Pri eni je morda na voljo nedavno skeniranje v sortirnem centru in ni prijavljenih težav. Pri drugi je v zgodovini dogodkov morda zabeležena nerešena težava z naslovom. Aplikacija, ki bere le glavno stanje, lahko spregleda to razliko.

Odziv ocenite glede na tri praktične naloge: povezovanje pošiljke s pravilnim naročilom, natančno pojasnjevanje njenega napredka in odločanje, ali je ukrep upravičen. Naslednja polja podpirajo te naloge. Imena polj so ponazoritvena; niso univerzalni standard ali shema določenega ponudnika.

12 polj, ki jih je treba oceniti poleg trenutnega stanja

1. Identifikatorji pošiljke in sledenja

Odziv mora določiti pošiljko, ki jo opisuje. Uporabne vrednosti vključujejo poslano številko za sledenje, identifikator zapisa sledenja API-ja in referenco stranke, ki jo lahko vaš sistem poveže z zapisom izpolnitve naročila ali paketa.

Ne predpostavljajte, da eno naročilo pomeni eno pošiljko. Naročilo je lahko razdeljeno na več paketov, zamenjava pa lahko ustvari novo pošiljko. Zapise sledenja shranjujte na ravni paketa ali izpolnitve naročila, nato pa jih povežite z naročilom. Številke za sledenje shranjujte kot nize, da se oblikovanje in začetne ničle ne izgubijo.

2. Identiteta prevoznika

Poleg berljivega imena prevoznika poiščite stabilen identifikator prevoznika. Kjer je na voljo, mora odziv razlikovati med prevoznikom, ki ga je izrecno poslala vaša aplikacija, in prevoznikom, izbranim s samodejnim zaznavanjem.

Kontekst prevoznika je pomemben pri razlagi številke za sledenje in njenih dogodkov. Če je zaznavanje dvoumno, mora vaša integracija omogočiti razrešitev, namesto da negotovo ujemanje tiho prikaže kot potrjeno. Informacije o ravni storitve hranite ločeno: samo ime prevoznika ne določa, ali pošiljka uporablja ekspresno, poštno ali drugo storitev.

3. Normalizirane podrobnosti stanja

Poleg glavnega stanja zahtevajte dokumentirano kodo podrobnosti ali podstanje. Široka kategorija lahko pošiljko opiše kot izjemo, podrobnost pa opredeli neuspešen poskus dostave, težavo z naslovom ali zadržanje, povezano s carino.

Za poslovno logiko uporabljajte stabilne kode, za prikaz pa berljive oznake. Preverite, kako ponudnik dogodke prevoznika preslika v te kode, vključno z obravnavo neznanih ali nepreslikanih dogodkov. Normalizirana oznaka olajša uporabo podatkov različnih prevoznikov, vendar ne sme izbrisati razlik, ki jih vaša podporna ekipa potrebuje.

4. Izvirna sporočila in kode prevoznika

Ko so na voljo, ohranite izvirni opis dogodka in kodo dogodka prevoznika. Te vrednosti podpornim agentom zagotavljajo kontekst, ki lahko manjka pri normaliziranem stanju, zlasti kadar prevoznik uporablja posebno operativno besedilo.

Izvirno besedilo hranite ločeno od prevedenih ali preoblikovanih opisov. V nasprotnem primeru bi lahko razlago za stranko zamenjali za natančno besedilo prevoznika. Pri prikazu obravnavajte besedilo prevoznika kot nezaupanja vreden vnos: ustrezno ga ubežite in ga ne izpisujte kot izvršljiv HTML.

5. Zgodovina dogodkov sledenja

Uporaben odziv mora razkriti časovnico pošiljke, ne le njenega zadnjega dogodka. Vsak dogodek mora po možnosti vključevati identifikator, stanje ali kodo, opis, časovni žig in razpoložljive podatke o lokaciji.

Preverite, ali API vrne celotno zgodovino, omejeno časovno obdobje ali straničene rezultate. Določite tudi, kako so predstavljeni popravki in podvojena opažanja. Vaša aplikacija ne sme predpostavljati, da je prvi element vedno najnovejši, razen če pogodba odziva izrecno zagotavlja takšno razvrstitev.

6. Časovni žigi dogodkov in podatki o časovnem pasu

Čas nastanka dogodka se razlikuje od časa, ko ga je API prejel ali vrnil. Če je mogoče, ohranite oba. Ta razlika pomaga pojasniti, zakaj lahko na novo prejeto obvestilo opisuje nekaj, kar se je zgodilo prej.

Zahtevajte časovne žige z izrecnimi odmiki od UTC ali zapisom UTC. RFC 3339 določa obliko časovnega žiga, primerno za internetne protokole, vključno s številčnimi časovnimi odmiki. Če vir zagotavlja le lokalni čas brez znanega odmika, ohranite to negotovost, namesto da ga tiho obravnavate kot UTC. Nikoli ne nakazujte natančnosti do sekunde, če osnovni vir zagotavlja le datum.

7. Lokacije dogodkov in geografija pošiljke

Kadar so na voljo, poiščite strukturirane sestavne dele lokacije, kot so mesto, regija, država in poštna številka. Ohranite tudi neobdelani niz lokacije, če bi pretvorba v strukturirana polja lahko povzročila izgubo pomena.

Lokacija skeniranja ni nujno trenutni položaj paketa. Prav tako zadnji prijavljeni objekt ni dokaz, da je paket še vedno tam. Strani, namenjene strankam, naj ga opišejo kot zadnjo prijavljeno lokacijo. Iz nepopolnega besedila skeniranja ne sklepajte o koordinatah ali natančnem naslovu dostave.

8. Predvideni datum ali časovno okno dostave

Polje predvidene dostave mora določiti, ali vsebuje posamezen datum ali časovno okno, kdo ga je ustvaril in kdaj je bilo nazadnje posodobljeno. Ocena prevoznika in ločeno izračunana napoved morata ostati razločljivi.

Ocene, ki vsebuje le datum, ne pretvarjajte v natančen čas prihoda. Vaša integracija mora obravnavati tudi spremenjene ali umaknjene ocene, ne da bi na strani za sledenje obdržala zastarelo obljubo. Če ocena ne obstaja, prikažite, da ni na voljo, namesto da jo izračunate na podlagi nepodprte predpostavke.

9. Razlog izjeme in zahtevano dejanje

Informacije o izjemi morajo pojasniti težavo in, kadar vir to podpira, navesti dejanje, odgovorno stran ali rok. Splošno obvestilo o zamudi se operativno razlikuje od zahteve po podatkih prejemnika.

Prijavljena dejstva hranite ločeno od odločitev v lastnem delovnem toku. Vaše podjetje lahko na primer po določenem obdobju brez posodobitve odpre podporno nalogo. To je interno pravilo eskalacije in ne dokaz, da je prevoznik paket razglasil za izgubljenega. Iz dvoumnega besedila sledenja ne ustvarjajte navodil za plačilo ali zahtev po občutljivih podatkih.

10. Predaje med prevozniki in povezane številke za sledenje

Kadar se pošiljka premika med operaterji, uporabni podatki vključujejo naslednjega prevoznika, povezano številko za sledenje ter razmerje med prvotnimi in nadaljnjimi zapisi. To lahko pomaga ohraniti neprekinjenost, ko se pri dostavi uporablja drug identifikator.

Prijavljeno predajo obravnavajte kot razmerje, namesto da prepišete prvotnega prevoznika. Zapisov ne združujte zgolj zato, ker so njihovi cilji ali številke za sledenje podobni. Če razmerje ni posredovano ali kako drugače potrjeno, ga pustite nerazrešenega, namesto da si izmislite neprekinjeno pot.

11. Rezultat dostave in reference dokazil

Ko je dostava prijavljena, mora odziv zagotoviti zabeleženi čas dostave in vse razpoložljive podrobnosti, na primer opis varnega mesta ali kategorijo prejemnika. Referenca dokazila o dostavi je lahko uporabna tudi takrat, ko jo prevoznik in storitev omogočata.

Stanja »Dostavljeno« ne obravnavajte kot dokaz, da je paket osebno prevzel predvideni prejemnik. Podpisi, fotografije, imena in natančne lokacije lahko vsebujejo osebne podatke. Omejite dostop, teh podrobnosti ne izpostavljajte na javnih straneh za sledenje ter preverite zahteve glede avtorizacije ali poteka veljavnosti povezav do dokazil.

12. Svežina, stanje pridobivanja in metapodatki odziva

Zahtevajte dovolj metapodatkov za razlikovanje med najnovejšim dogodkom pošiljke in zadnjim uspešnim pridobivanjem podatkov. Uporabne vrednosti vključujejo zadnje uspešno preverjanje, zadnji neuspešni poskus, čas ustvarjanja odziva ter podatek, ali so vrnjeni podatki predpomnjeni ali delni.

Uspešna zahteva API-ja sama po sebi ne potrjuje, da je prevoznik objavil novo skeniranje. Semantika odziva HTTP opisuje rezultat zahteve; napredek pošiljke spada v podatke aplikacije. Napake pri pridobivanju hranite ločeno od izjem pošiljke, da začasna težava s povezavo ne postane lažno opozorilo o dostavi.

Manjkajoči podatki morajo imeti opredeljen pomen

Prisotnost polja je le del pogodbe. Vaša ekipa mora razumeti tudi, kaj pomeni odsotna vrednost. Ocena dostave morda ni na voljo pri viru, še ni bila pridobljena ali po dostavi ni več uporabna. Te situacije ne bi smele samodejno ustvariti istega sporočila za stranko.

  • Neznano: Vrednost še ni bila ugotovljena.
  • Ni posredovano: Vir vrednosti ni zagotovil v pridobljenih podatkih.
  • Ni relevantno: Polje se za ta zapis ali stanje ne uporablja.
  • Pridobivanje ni uspelo: Sistem ni mogel dokončati ustreznega iskanja.

To so priporočene razlike, ne obvezne dobesedne vrednosti. Ne glede na izbrano predstavitev jo dokumentirajte. Izogibajte se nadomestnim datumom, praznim objektom, ki so videti kot veljavni zapisi, in privzetim koordinatam, ki bi jih lahko zamenjali za resnične lokacije.

Kako preizkusiti odziv pred integracijo

Ocenite dejanske podatkovne pakete prevoznikov, storitev in dostavnih poti, ki jih uporablja vaše podjetje. Shema lahko navede izbirno polje, ne da bi zagotavljala, da ga bo vsak osnovni vir izpolnil. Pri integraciji 17TRACK uporabite uradno dokumentacijo Tracking API, da preverite pogodbo odziva, namesto da konceptualna imena polj v tem priročniku obravnavate kot parametre, pripravljene za kopiranje.

  1. Ustvarite reprezentativen vzorec. Vključite na novo registrirane pošiljke, aktivne pošiljke, poskuse dostave, dokončane dostave in razpoložljive primere predaj.
  2. Sledite poljem nazaj do dogodkov. Preverite, ali prikazano stanje, najnovejši dogodek in podrobnosti dostave opisujejo skladen zapis. Neskladja raziščite, namesto da jih skrijete.
  3. Preizkusite zakasnele in ponovljene posodobitve. Znova obdelajte isti podatkovni paket in po novejšem dogodku prejmite starejšega. Preverite, da noben primer ne ustvari podvojenih obvestil ali nepravilno obrne prikazanega stanja.
  4. Preizkusite manjkajoče in napačno oblikovane vrednosti. Vključite manjkajoče ocene, neznane lokacije, neznane kode stanja in nepopolne časovne žige. Aplikacija mora ostati uporabna, ne da bi si izmišljala nadomestne vrednosti.
  5. Ločite napake prenosa od rezultatov sledenja. Napaka preverjanja pristnosti, časovna omejitev ali napačno oblikovan odziv mora voditi v pot integracijske napake, ne v delovni tok izjeme pošiljke.
  6. Preverite pogled stranke. Prepričajte se, da se interne reference, neobdelane diagnostične podrobnosti in osebni podatki ne razkrijejo na javnih straneh ali v obvestilih.

Pri posodobitvah na podlagi webhookov preverite tudi identifikatorje dostave, preverjanje pristnosti, vedenje pri ponovnih poskusih in obravnavo ponovnega predvajanja v dokumentaciji ponudnika. To so zahteve integracije, ne dejstva o pošiljki. Vaš prejemnik mora varno obdelati ponovljene dostave in ne sme predpostavljati, da vrstni red prihoda ustreza vrstnemu redu dogodkov.

Merilo sprejemljivosti mora biti praktično: ali lahko vaša aplikacija pojasni pošiljko brez nepodprtih trditev in ali lahko vaša operativna ekipa prepozna naslednje upravičeno dejanje? Manjši, dobro opredeljen podatkovni paket je lahko uporabnejši od večjega odziva, polnega nepojasnjenih izbirnih vrednosti.

Pogosta vprašanja

Ali mora biti vseh 12 skupin podatkov izpolnjenih pri vsaki pošiljki?

Ne. Dokazila o dostavi, nadaljnje številke za sledenje in predvideni datumi dostave morda niso na voljo ali niso relevantni. Namesto univerzalne izpolnjenosti zahtevajte jasne opredelitve polj in predvidljivo vedenje pri manjkajočih vrednostih. Polja, ki so najpomembnejša, preverite glede na dejansko mešanico vaših pošiljk.

Ali naj shranimo neobdelani odziv ali le normalizirana polja?

Za logiko aplikacije shranjujte normalizirana polja. Ohranitev ustreznih izvornih podatkovnih paketov lahko pomaga tudi pri odpravljanju napak in spremembah preslikav, ob upoštevanju zahtev glede zasebnosti, varnosti, pogodb in hrambe. Omejite dostop in občutljivih vsebin ne hranite zgolj zato, ker se pojavijo v odzivu.

Kateri časovni žig mora določiti najnovejši dogodek?

Uporabite dokumentirano kronologijo dogodkov in pravila razvrščanja ponudnika ter upoštevajte časovne pasove in popravke. Čas prejema pove, kdaj je vaš sistem izvedel za dogodek, ne nujno, kdaj se je ta zgodil. Če so časovni žigi nepopolni ali v nasprotju, ohranite dvoumnost, namesto da trdite, da poznate natančno zaporedje.

Ali lahko API za sledenje potrdi, da je paket izgubljen?

Izgubo obravnavajte kot prijavljeno s strani prevoznika le, če vir izrecno podpira takšno razlago. Dolgo obdobje brez skeniranj lahko v skladu z vašimi operativnimi pravili upraviči preiskavo, vendar samo tišina ne dokazuje izgube. »Zastarelo sledenje« in »prijavljeno kot izgubljeno« naj ostaneta ločena pojma.

Ali stanje »Dostavljeno« zadostuje za zaključek pritožbe stranke?

Ne samodejno. Določa prijavljeni rezultat sledenja, vendar morda ne razreši spora prejemnika. Preglejte razpoložljive podrobnosti dostave, račun stranke in svoj podporni postopek. Oznake stanja ne obravnavajte kot nadomestilo za preiskavo nasprotujočih si informacij.

Viri