Status dostave API-ja za pošiljanje: statusne kode, spletne kljuke in opozorila o izjemah
Stanje dostave, ki ga opisuje API za pošiljanje, prikazuje napredek paketa, ne pa tega, ali je bila zahteva API uspešna. Za zanesljivo sledenje ločite kode odgovorov HTTP od statusov pošiljke, obdelujte spletne kljuke, ne da bi predpostavljali, da prispejo samo enkrat ali v pravilnem vrstnem redu, ter izjeme, ki zahtevajo ukrepanje, pretvorite v opozorila z jasno določenimi odgovornimi osebami. Za ekipe za inženiring ter operacije v e-trgovini je cilj zapis pošiljke, ki ostane zanesljiv, tudi ko so posodobitve prevoznika zakasnjene, podvojene ali popravljene.
Ta vodnik pojasnjuje, kako strukturirati tak zapis, obravnavati prejete dogodke sledenja ter razlikovati med težavo pri dostavi in težavo pri integraciji sledenja.
Ločite kode HTTP, rezultate API-ja in statuse pošiljk
Izraz »statusna koda« se lahko nanaša na tri različne ravni. Njihovo mešanje ustvarja zavajajoče nadzorne plošče in nepotrebna obvestila strankam.
| Raven | Kaj vam pove | Primer razlage |
|---|---|---|
| Odgovor HTTP | Rezultat zahteve HTTP | Odgovor 200 pomeni uspeh na ravni HTTP; ne pomeni, da je bil paket dostavljen. |
| Poslovni rezultat API-ja | Ali je bila zahtevana operacija uspešna v skladu s pravili aplikacije ponudnika | Telo odgovora lahko sporoči, da je bila registracija sledenja zavrnjena, tudi znotraj uspešnega odgovora HTTP, če API uporablja takšno zasnovo. |
| Status pošiljke | Prijavljeno fizično ali operativno stanje paketa | V tranzitu, čaka na prevzem ali dostavljeno. |
Standard semantike HTTP določa pomene odgovorov HTTP. Na primer, 202 Accepted pomeni, da je bila zahteva sprejeta v obdelavo, vendar obdelava še ni nujno končana. To ni dokaz, da je prevoznik sprejel paket.
Prav tako neuspešna zahteva za sledenje ne dokazuje, da se je pošiljka prenehala premikati. Vaša aplikacija lahko začasno izgubi vidljivost, medtem ko fizična dostava poteka normalno. Te ravni spremljajte neodvisno.
Ustvarite model statusov, ne da bi zavrgli podrobnosti prevoznika
Ne obstaja univerzalna številčna koda statusa dostave, ki bi jo uporabljali vsi API-ji za pošiljanje in vsi prevozniki. Vrednosti iz ene integracije ne smete razlagati z uporabo preslikave drugega ponudnika. Uporabite dokumentacijo za določeno različico API-ja, ki jo izvajate.
Praktični notranji model združuje manjši nabor normaliziranih statusov z izvirnim dogodkom prevoznika. Normalizacija podpira dosledno poročanje, izvirni dogodek pa ohrani podrobnosti, potrebne za preiskavo.
| Ponazoritveni notranji status | Pomen | Operativno opozorilo |
|---|---|---|
| Informacije prejete | Elektronske informacije o pošiljki obstajajo. | Ustvarjanja etikete ne obravnavajte kot potrjen fizični prevzem. |
| V tranzitu | Zapis sledenja kaže premikanje po dostavnem omrežju. | Ta široka kategorija lahko vključuje različne faze prevoza. |
| Na dostavi | Poročano je, da je paket na dostavni poti. | Tega ne spreminjajte v brezpogojno zagotovilo dostave. |
| Čaka na prevzem | Pričakuje se, da bo prejemnik prevzel paket. | Navodila ali roke za prevzem vključite samo, kadar jih podpira vir. |
| Dostavljeno | Vir sledenja poroča o dostavi. | Sken dostave sam po sebi ne razreši strankine trditve, da paketa ni prejela. |
| Izjema | Dogodek lahko zahteva pozornost ali prekine običajen napredek. | Ohranite razlog in vsake izjeme ne obravnavajte kot izgubo. |
| Vračilo v teku ali vrnjeno | Paket se vrača ali pa je poročano, da je bilo vračilo dokončano. | Napredek vračila ločite od dostave prvotnemu prejemniku. |
| Neznano | Razpoložljivih informacij ni mogoče zanesljivo preslikati. | Raziščite preslikavo ali vrzel v podatkih, namesto da bi si izmislili stanje dostave. |
Te oznake so predlagani aplikacijski model in ne uradni seznam kod 17TRACK. Kadar je mogoče, ohranite statusno kodo ponudnika, podstatus, opis, čas dogodka, podatke o časovnem pasu, lokacijo in čas prejema. Ohranite tudi različico preslikave, da bo mogoče poznejše spremembe preslikave revidirati.
Za izvedbo z več prevozniki je 17TRACK Tracking API ustrezna možnost integracije. Uporabite njegovo uradno dokumentacijo API-ja, da določite pogodbo izvedbe, namesto da bi ponazoritvene oznake kopirali v polja, specifična za ponudnika. Pred izdelavo adapterja potrdite veljavne definicije statusov, konfiguracijo spletnih kljuk, zahteve glede preverjanja pristnosti in semantiko odgovorov.
Obdelavo spletnih kljuk zasnujte okoli trajnega prejema
Spletna kljuka je zahteva HTTP, poslana vaši končni točki za poročanje o dogodku. Zmanjša lahko potrebo po ponavljajočem se preverjanju, vendar je ne smete obravnavati kot zagotovilo za takojšnjo dostavo, dostavo v pravilnem vrstnem redu ali dostavo natanko enkrat. Sprejemnik zasnujte tako, da prenaša ponovne poskuse, prekinitve in nepričakovane vsebine, razen če ponudnik izrecno zagotavlja drugače.
- Preverite pristnost zahteve. Uporabite dokumentirano metodo preverjanja ponudnika. Če so podpisi podprti, jih preverite z navedenim algoritmom in surovimi bajti zahteve. Ne izmišljajte glave podpisa in ne predpostavljajte, da vsaka storitev uporablja HMAC.
- Preverite vsebino. Preverite obvezna polja, tipe, velikost vsebine in povezavo s pošiljko, ki jo upravlja vaš račun. Neznana izbirna polja obravnavajte, ne da bi po nepotrebnem prekinili združljivost za prihodnost.
- Shranite pred potrditvijo. Sprejeti dogodek shranite ali ga uvrstite v trajno čakalno vrsto, preden pošljete dokumentirani uspešni odgovor. Če shranjevanje ni uspešno, dogodka ne potrdite kot varno prejetega.
- Obdelujte asinhrono. Kjer je praktično, preslikavo statusov, posodobitve naročil in odločitve o obvestilih izvajajte zunaj obravnavalnika zahteve.
- Stranski učinki naj bodo idempotentni. Ponovljen dogodek ne sme ustvariti še ene zahteve za podporo ali poslati dodatne kopije istega sporočila stranki.
Natančna potrditvena koda, časovna omejitev, urnik ponovnih poskusov in vedenje pri ponovitvi so odvisni od ponudnika. Te podrobnosti izrecno preverite. Splošno navodilo »vrnite 200« ni nadomestilo za pogodbo spletne kljuke.
Uporabljajte HTTPS in poverilnic ne vključujte v URL-je ali običajne dnevnike. Za shranjene vsebine uporabite nadzor dostopa, saj lahko podatki o sledenju vsebujejo osebne podatke. OWASP REST Security Cheat Sheet vsebuje ustrezne napotke o zaščiti prenosa, preverjanju vhodnih podatkov in varnosti končnih točk.
Podvajajte dogodke brez zatiranja resničnih posodobitev
Kadar je na voljo, uporabite dokumentiran in stabilen identifikator dogodka. Sicer izpeljite ključ za odstranjevanje dvojnikov iz skrbno izbrane kombinacije identitete pošiljke, časovnega žiga dogodka, kode dogodka in lokacije. Ta pristop preizkusite na dejanskih vsebinah: dva legitimna dogodka si lahko delita časovni žig, isti dogodek pa lahko prispe z nekoliko drugačnim opisnim besedilom.
Za sprejem dogodkov in nadaljnja dejanja uporabite ločene nadzore odstranjevanja dvojnikov. Posodobitev statusa bo morda treba znova shraniti kot popravek, medtem ko mora obvestilo stranki ostati zatirano. Vsakemu obvestilu ali dejanju zahtevka določite lastno trajno identiteto.
Čas dogodka ločite od časa prejema
Predpostavimo, da dogodek »v tranzitu« doseže vaš sistem za dogodkom »na dostavi«, vendar je njegov časovni žig prevoznika zgodnejši. Shranite ga v zgodovino, ne da bi samodejno spremenili trenutni status nazaj v »v tranzitu«.
Samo razvrščanje po časovnih žigih ne zadostuje za vsak primer. Manjkajoči časovni pasovi, popravljeni skeni in nasprotujoči si viri zahtevajo izrecna pravila. Ohranite natančnost časovnih žigov in odmike, zabeležite, kdaj je vaš sistem prejel posamezen dogodek, ter uporabite dokumentirane informacije ponudnika o zaporedju, kadar so na voljo. Ne vsiljujte toge lestvice statusov, ki se lahko premikajo samo naprej: poskusi dostave, preusmeritve, vračila in popravki lahko ustvarijo legitimne prehode, ki so videti kot premik nazaj.
Izjeme pretvorite v dejanja z jasno odgovornostjo
Opozorilo o izjemi mora pojasniti, kaj se je zgodilo, kateri ukrep je potreben in kdo je odgovoren za naslednji korak. Splošno sporočilo »izjema pri pošiljki« operativno osebje prisili, da ponovi isto preiskavo, stranke pa lahko vznemiri, ne da bi jim pomagalo.
Začnite z majhno usmerjevalno politiko:
- Težava z naslovom ali dostopom: Primer usmerite k podpori strankam, da preveri težavo in razpoložljivi postopek popravka pri prevozniku. Spremembe naslova ne obljubljajte, preden ne potrdite, da je mogoča.
- Potreben prevzem: Prejemnika obvestite, kadar vir zagotavlja uporabna navodila za prevzem. Ohranite preverjeni rok.
- Potrebno carinsko ukrepanje: Primer dodelite glede na to, kdo mora predložiti zahtevane dokumente ali informacije. Sam carinski dogodek ne dokazuje, da je treba plačati dajatev.
- Neuspešen poskus dostave: Preden svetujete ponovno dostavo ali prevzem, preverite poročani naslednji korak.
- Vračilo pošiljatelju: Odprite operativni pregled. Samodejno ne izdajajte vračila samo na podlagi splošne oznake sledenja, razen če vaša politika to izrecno dovoljuje.
- Izguba ali poškodba, ki jo je prijavil prevoznik: Primer usmerite k odgovorni osebi za zahtevke in ohranite dokaze o dogodku. Odločitve o zahtevkih ločite od splošnega zaznavanja zamud.
Vsako opozorilo mora vsebovati identifikator pošiljke, referenco naročila, razlog dogodka, izvorni časovni žig, zadnje znano stanje, dodeljeno odgovorno osebo in naslednji ukrep. Vključite povezavo do ustreznega notranjega zapisa, namesto da bi v skupnih komunikacijskih kanalih razkrivali nepotrebne podatke o stranki.
»Brez posodobitve« obravnavajte kot ločeno stanje
Pošiljka brez nedavnega skena ni samodejno izgubljena. Lahko je med kontrolnimi točkami, čaka na prvi fizični sken ali pa jo je prizadela vrzel v vidljivosti.
Pragove neaktivnosti določite glede na storitev, pot, fazo pošiljanja in poslovno zavezo, namesto da bi uporabljali en univerzalni časovnik. Ločite paket, ki nikoli ni prejel skena prevzema, od paketa, ki se je prenehal posodabljati po vstopu v omrežje. Če je zgodovinskih dokazov malo, prag uporabite za sprožitev preiskave, ne za razglasitev izgube.
Ponavljajoča opozorila zatrete, dokler nespremenjeni primer ostaja odprt. Stopnjo obravnave zvišajte, ko se pojavijo novi dokazi, ko dogovorjeno nadaljnje ukrepanje ni izvedeno ali ko zaveza glede dostave stranki zahteva posredovanje.
Zdravje integracije spremljajte ločeno od uspešnosti dostave
Spremljanje API-ja odgovarja na vprašanje, ali vaša integracija sledenja deluje. Spremljanje dostave odgovarja na vprašanje, kaj se dogaja s pošiljkami. Zdrava končna točka lahko prejema zastarele podatke prevoznika, nedosegljiva končna točka pa lahko zgreši posodobitve paketov, ki se normalno premikajo.
- Zdravje zahtev: Spremljajte napake pri preverjanju pristnosti, časovne omejitve, odgovore zaradi omejitve hitrosti, napake strežnika in zavrnitve na ravni aplikacije.
- Zdravje spletnih kljuk: Spremljajte napake pri preverjanju, zakasnitev potrditve, napake pri shranjevanju, podvojene dostave in napake pri obdelavi.
- Zdravje obdelave: Spremljajte starost čakalne vrste, neobdelane dogodke, napake preslikave in napake obvestil.
- Svežina sledenja: Čas od zadnjega izvornega dogodka merite ločeno od časa od zadnjega uspešnega sprejema v vašem sistemu.
- Operativni rezultati: Spremljajte nerešene izjeme, čas do prevzema odgovornosti in zamujena nadaljnja ukrepanja.
Pri ponovnih poskusih zahtev upoštevajte navodila ponudnika glede omejitev hitrosti in ponovitev. Ne ponavljajte slepo operacij, ki bi lahko ustvarile podvojene registracije ali druge stranske učinke; kjer je mogoče, uporabite dokumentirane mehanizme idempotentnosti.
Kjer je podprto, uporabite postopek usklajevanja za pridobitev najnovejšega zapisa sledenja po izpadih ali ob sumu na zgrešene dogodke. Pogostost določite znotraj pogodbenih omejitev in omejitev hitrosti. Spletne kljuke in usklajevanje imajo različna namena: prvo dostavlja spremembe, drugo pa pomaga zaznati in popraviti vrzeli.
Pred vklopom obvestil strankam preizkusite primere napak
Začnite z obdelavo, namenjeno samo notranji uporabi, in preglejte reprezentativne pošiljke, preden dovolite, da spremembe statusa pošiljajo sporočila strankam. Preizkusite več kot običajni napredek od »v tranzitu« do »dostavljeno«.
- Podvojena spletna kljuka ustvari eno predvideno obvestilo stranki.
- Dogodek, ki prispe pozneje in je starejši, ne zamenja napačno trenutnega stanja.
- Neznani status se ohrani in označi, namesto da bi bil tiho preslikan v »dostavljeno«.
- Neuspešen trajni zapis ne ustvari uspešne potrditve.
- Začasni izpad nadaljnjega sistema pusti dogodke na voljo za ponovni poskus.
- Dogodek »dostavljeno«, ki mu sledi popravek, ostane sledljiv za revizijo.
- Naročilo z več paketi ne postane v celoti dostavljeno, ko je dostavljen samo en paket.
- Izpad API-ja opozori inženiring, ne da bi strankam samodejno sporočil, da njihovi paketi zamujajo.
Merilo za izdajo mora biti operativna doslednost: zapis pošiljke, sporočilo stranki in ukrep podpore se morajo ujemati z istimi osnovnimi dokazi. Sam uspešen odgovor spletne kljuke ne dokazuje, da izkušnja dostave deluje.
Pogosta vprašanja
Ali HTTP 200 pomeni, da je bil paket dostavljen?
Ne. Pomeni uspeh zahteve na ravni HTTP. Polja poslovnega rezultata API-ja in statusa pošiljke preberite ločeno. Pri spletni kljuki se uspešna potrditev nanaša na prejem obvestila, ne na fizično dostavo paketa.
Ali naj za posodobitve sledenja uporabim spletne kljuke ali preverjanje?
Ko jih ponudnik podpira, uporabite spletne kljuke za dogodkovne posodobitve. Kjer je podprto in operativno upravičeno, dodajte omejeno preverjanje za usklajevanje, da obnovite vrzeli. Samo preverjanje je lahko ustrezno, kadar spletne kljuke niso na voljo, vendar mora njegova pogostost upoštevati omejitve ponudnika in vaše zahteve glede svežine.
Zakaj se lahko status sledenja spremeni po statusu »dostavljeno«?
Vir lahko popravi dogodek ali pa vaša integracija prejme zakasnjene ali nasprotujoče si informacije. Ohranite zgodovino in ocenite novejše dokaze, namesto da bi status »dostavljeno« tehnično obravnavali kot nespremenljivega. Poročana dostava in strankina potrditev prejema sta tudi različni dejstvi.
Kako hitro je treba poslati opozorilo o izjemi?
Nujnost določite na podlagi zahtevanega ukrepa in preverjenega roka. Težava, ki zahteva ukrepanje prejemnika, zahteva drugačno obravnavo kot informativna zamuda. Hitrost obdelave ne more nadomestiti dogodka prevoznika, ki je bil objavljen pozno, zato ohranite izvorni časovni žig in časovni žig prejema.
Ali naj stranke vidijo surovi status prevoznika?
Strankam običajno bolj koristita jasna razlaga in podprt naslednji korak kot nepojasnjena koda. Surove podrobnosti ohranite za podporo in revizijo. Statusa nikoli ne poenostavite v močnejšo obljubo, kot jo podpira osnovni dogodek.
Viri
- RFC 9110: HTTP Semantics — referenca za pomene statusnih kod HTTP, vključno z 200 in 202.
- OWASP REST Security Cheat Sheet — varnostne smernice, pomembne za končne točke API-ja in spletnih kljuk.
- 17TRACK Tracking API — uradna referenca izdelka za obravnavano možnost integracije sledenja.
- 17TRACK API Documentation — uradna referenca za zahteve integracije, specifične za ponudnika; ponazoritvene sheme in priporočila za poteke dela v tem vodniku niso nadomestilo za to pogodbo.
