Shipping API:n toimituksen tila: tilakoodit, webhookit ja poikkeushälytykset

Toimitus-API:n toimitustila kuvaa paketin etenemistä, ei sitä, onnistuiko API-pyyntö. Luotettavan seurannan rakentamiseksi pidä HTTP-vastauskoodit erillään lähetyksen tiloista, käsittele webhookit olettamatta, että ne saapuvat kerran tai järjestyksessä, ja muuta toimenpiteitä vaativat poikkeukset hälytyksiksi, joilla on selkeä vastuuhenkilö. Tekniikka- ja verkkokauppatoimintojen tiimeille tavoitteena on lähetysrekisteri, joka säilyy luotettavana, vaikka kuljetusyhtiön päivitykset viivästyvät, saapuvat duplikaatteina tai niitä korjataan.

Tässä oppaassa selitetään, miten kyseinen rekisteri rakennetaan, miten saapuvat seurantatapahtumat käsitellään ja miten toimitusongelma erotetaan seurannan integraatio-ongelmasta.

Erota HTTP-koodit, API-tulokset ja lähetyksen tilat

Ilmaisu ”tilakoodi” voi viitata kolmeen eri tasoon. Niiden sekoittaminen luo harhaanjohtavia koontinäyttöjä ja tarpeettomia asiakasilmoituksia.

Taso	Mitä se kertoo	Esimerkkitulkinta
HTTP-vastaus	HTTP-pyynnön tulos	200-vastaus osoittaa HTTP-tason onnistumisen; se ei tarkoita, että paketti olisi toimitettu.
API:n liiketoimintatulos	Onnistuiko pyydetty toiminto palveluntarjoajan sovellussääntöjen mukaisesti	Vastausrunko voi ilmoittaa, että seurantarekisteröinti hylättiin, myös onnistuneen HTTP-vastauksen sisällä, jos API käyttää tällaista rakennetta.
Lähetyksen tila	Paketin ilmoitettu fyysinen tai toiminnallinen tila	Kuljetuksessa, noutoa odottamassa tai toimitettu.

HTTP-semanttien standardi määrittelee HTTP-vastausten merkitykset. Esimerkiksi 202 Accepted tarkoittaa, että pyyntö hyväksyttiin käsiteltäväksi, mutta käsittely ei välttämättä ole vielä valmis. Se ei ole todiste siitä, että kuljetusyhtiö olisi vastaanottanut paketin.

Samoin epäonnistunut seurantapyyntö ei todista, että lähetys olisi lakannut liikkumasta. Sovelluksesi voi menettää näkyvyyden tilapäisesti, vaikka fyysinen toimitus jatkuu normaalisti. Valvo näitä tasoja toisistaan riippumatta.

Luo tilamalli hävittämättä kuljetusyhtiön tietoja

Kaikkien toimitus-APIen ja kuljetusyhtiöiden yhteistä yleistä numeerista toimitustilan koodia ei ole. Yhden integraation arvoa ei pidä tulkita toisen palveluntarjoajan määritysten avulla. Käytä toteuttamasi API-version dokumentaatiota.

Käytännöllisessä sisäisessä mallissa yhdistyvät pieni joukko normalisoituja tiloja ja alkuperäinen kuljetusyhtiön tapahtuma. Normalisointi tukee yhdenmukaista raportointia; alkuperäinen tapahtuma säilyttää selvityksessä tarvittavat yksityiskohdat.

Esimerkinomainen sisäinen tila	Merkitys	Toiminnallinen huomio
Tiedot vastaanotettu	Sähköiset lähetyksen tiedot ovat olemassa.	Älä pidä tarran luomista vahvistettuna fyysisenä luovutuksena.
Kuljetuksessa	Seurantarekisteri osoittaa liikkumista toimitusverkostossa.	Tämä laaja luokka voi sisältää eri kuljetusvaiheita.
Jakelussa	Paketin ilmoitetaan olevan jakelureitillä.	Älä muuta tätä ehdottomaksi toimitustakuuksi.
Noutoa odottamassa	Vastaanottajan odotetaan noutavan paketin.	Lisää nouto-ohjeet tai määräajat vain, jos lähde tukee niitä.
Toimitettu	Seurantalähde ilmoittaa toimituksesta.	Toimitusskannaus ei yksin ratkaise asiakkaan ilmoitusta siitä, ettei hän ole saanut lähetystä.
Poikkeus	Tapahtuma voi vaatia huomiota tai keskeyttää normaalin etenemisen.	Säilytä syy sen sijaan, että pitäisit jokaista poikkeusta kadonneena lähetyksenä.
Palautus käynnissä tai palautettu	Paketti on matkalla takaisin tai palautuksen ilmoitetaan valmistuneen.	Pidä palautuksen eteneminen erillään toimituksesta alkuperäiselle vastaanottajalle.
Tuntematon	Saatavilla olevia tietoja ei voida yhdistää luotettavasti.	Tutki määritystä tai tietopuutetta sen sijaan, että keksisit toimitustilan.

Nämä tunnisteet ovat ehdotettu sovellusmalli, eivät virallinen 17TRACK-koodiluettelo. Säilytä palveluntarjoajan tilakoodi, alitila, kuvaus, tapahtuma-aika, aikavyöhyketiedot, sijainti ja vastaanottoaika, jos ne ovat saatavilla. Säilytä myös määrityksen versio, jotta myöhemmät määritysmuutokset voidaan tarkastaa.

Usean kuljetusyhtiön toteutuksessa 17TRACK Tracking API on sopiva integraatiovaihtoehto. Määritä toteutussopimus sen virallisen API-dokumentaation avulla sen sijaan, että kopioisit esimerkinomaiset tunnisteet palveluntarjoajakohtaisiin kenttiin. Vahvista sovellettavat tilamääritelmät, webhook-määritykset, todennusvaatimukset ja vastausten semantiikka ennen sovittimen rakentamista.

Rakenna webhook-käsittely kestävän vastaanoton ympärille

Webhook on HTTP-pyyntö, joka lähetetään päätepisteeseesi tapahtumasta ilmoittamiseksi. Se voi vähentää toistuvan kyselyn tarvetta, mutta sitä ei pidä pitää välittömän, järjestyksessä tapahtuvan tai täsmälleen kerran tapahtuvan toimituksen takuuna. Suunnittele vastaanottaja kestämään uudelleenyritykset, keskeytykset ja odottamattomat hyötykuormat, ellei palveluntarjoaja nimenomaisesti takaa muuta.

1. Todenna pyyntö. Käytä palveluntarjoajan dokumentoitua varmennusmenetelmää. Jos allekirjoituksia tuetaan, tarkista ne määritetyllä algoritmilla ja raakapyyntötavuilla. Älä keksi allekirjoitusotsaketta tai oleta, että jokainen palvelu käyttää HMACia.
2. Vahvista hyötykuorma. Tarkista pakolliset kentät, tyypit, hyötykuorman koko ja yhteys lähetykseen, jota tilisi hallinnoi. Käsittele tuntemattomat valinnaiset kentät rikkomatta tarpeettomasti tulevaa yhteensopivuutta.
3. Tallenna ennen kuittausta. Tallenna hyväksytty tapahtuma tai aseta se kestävään jonoon ennen dokumentoidun onnistumisvastauksen lähettämistä. Jos tallennus epäonnistuu, älä kuittaa tapahtumaa turvallisesti vastaanotetuksi.
4. Käsittele asynkronisesti. Suorita tilojen määritys, tilausten päivitykset ja ilmoituspäätökset mahdollisuuksien mukaan pyyntökäsittelijän ulkopuolella.
5. Tee sivuvaikutuksista idempotentteja. Toistuva tapahtuma ei saa luoda uutta tukipyyntöä tai lähettää samaa asiakasviestiä uudelleen.

Tarkka kuittauskoodi, aikakatkaisu, uudelleenyritysaikataulu ja toistokäyttäytyminen riippuvat palveluntarjoajasta. Tarkista nämä yksityiskohdat erikseen. Yleinen ohje ”palauta 200” ei korvaa webhook-sopimusta.

Käytä HTTPS:ää ja pidä tunnistetiedot poissa URL-osoitteista ja tavallisista lokeista. Suojaa tallennettujen hyötykuormien käyttöoikeudet, koska seurantatiedot voivat sisältää henkilötietoja. OWASP REST Security Cheat Sheet sisältää asiaankuuluvia ohjeita siirtosuojauksesta, syötteiden validoinnista ja päätepisteiden turvallisuudesta.

Poista tapahtumien kaksoiskappaleet tukahduttamatta todellisia päivityksiä

Suosi dokumentoitua, pysyvää tapahtumatunnistetta, jos sellainen on saatavilla. Muussa tapauksessa muodosta deduplikointiavain huolellisesti valitusta yhdistelmästä, johon kuuluvat lähetyksen tunniste, tapahtuman aikaleima, tapahtumakoodi ja sijainti. Testaa lähestymistapa todellisilla hyötykuormilla: kahdella aidolla tapahtumalla voi olla sama aikaleima, ja sama tapahtuma voi saapua hieman erilaisella kuvaustekstillä.

Käytä erillisiä deduplikointisäätimiä tapahtumien vastaanottoon ja niiden jälkeisiin toimintoihin. Tilapäivitys voidaan joutua tallentamaan uudelleen korjauksena, vaikka asiakasilmoitus pitäisi edelleen estää. Anna jokaiselle ilmoitukselle tai tukipyyntötoiminnolle oma kestävä tunniste.

Pidä tapahtuma-aika erillään vastaanottoajasta

Oletetaan, että kuljetuksessa oleva tapahtuma saavuttaa järjestelmäsi jakelussa-tapahtuman jälkeen, mutta sen kuljetusyhtiön aikaleima on aikaisempi. Tallenna se historiaan muuttamatta nykyistä tilaa automaattisesti takaisin tilaan ”kuljetuksessa”.

Aikaleimojen järjestys yksin ei riitä joka tilanteessa. Puuttuvat aikavyöhykkeet, korjatut skannaukset ja ristiriitaiset lähteet edellyttävät selkeitä sääntöjä. Säilytä aikaleimojen tarkkuus ja siirtymät, kirjaa milloin järjestelmäsi vastaanotti kunkin tapahtuman ja käytä dokumentoituja palveluntarjoajan järjestystietoja, jos niitä on saatavilla. Älä pakota jäykkää vain eteenpäin kulkevaa tilaporrasta: toimitusyritykset, uudelleenohjaukset, palautukset ja korjaukset voivat aiheuttaa oikeutettuja siirtymiä, jotka näyttävät kulkevan taaksepäin.

Muuta poikkeukset vastuullisiksi toimenpiteiksi

Poikkeushälytyksen tulee selittää, mitä tapahtui, mitä on tehtävä ja kuka vastaa seuraavasta vaiheesta. Yleinen ”lähetyspoikkeus”-viesti jättää toimintohenkilöstön toistamaan saman selvityksen ja voi huolestuttaa asiakkaita auttamatta heitä.

Aloita pienellä reitityskäytännöllä:

• Osoite- tai pääsyongelma: Ohjaa asia asiakastukeen ongelman varmistamista ja kuljetusyhtiön käytettävissä olevan korjausprosessin tarkistamista varten. Älä lupaa osoitteen muuttamista ennen kuin sen mahdollisuus on vahvistettu.
• Nouto vaaditaan: Ilmoita vastaanottajalle, kun lähde tarjoaa käyttökelpoiset nouto-ohjeet. Säilytä vahvistettu määräaika.
• Tullitoimenpide vaaditaan: Määritä asia sen mukaan, kenen on toimitettava pyydetyt asiakirjat tai tiedot. Pelkkä tulliin liittyvä tapahtuma ei osoita maksun olevan erääntynyt.
• Toimitusyritys epäonnistui: Tarkista ilmoitettu seuraava vaihe ennen uudelleentoimituksen tai noudon suosittelemista.
• Palautus lähettäjälle: Avaa toiminnallinen tarkistus. Älä myönnä hyvitystä automaattisesti pelkän yleisen seurantatunnisteen perusteella, ellei käytäntösi nimenomaisesti salli sitä.
• Kuljetusyhtiön ilmoittama katoaminen tai vahingoittuminen: Ohjaa asia korvausvaatimuksesta vastaavalle henkilölle ja säilytä tapahtuman todisteet. Pidä korvauspäätökset erillään yleisestä viiveiden havaitsemisesta.

Jokaisen hälytyksen tulee sisältää lähetyksen tunniste, tilausviite, tapahtuman syy, lähteen aikaleima, viimeisin tunnettu tila, nimetty vastuuhenkilö ja seuraava toimenpide. Lisää linkki asiaankuuluvaan sisäiseen tietueeseen sen sijaan, että paljastaisit tarpeettomia asiakastietoja jaetuissa viestintäkanavissa.

Käsittele ”ei päivitystä” erillisenä tilanteena

Lähetys, josta ei ole tuoretta skannausta, ei ole automaattisesti kadonnut. Se voi olla tarkastuspisteiden välillä, odottaa ensimmäistä fyysistä skannausta tai kärsiä näkyvyyskatkoksesta.

Määritä passiivisuuskynnykset palvelun, reitin, toimitusvaiheen ja liiketoimintalupauksen mukaan sen sijaan, että käyttäisit yhtä yleistä ajastinta. Erota paketti, joka ei ole koskaan saanut vastaanottoskannausta, paketista, jonka päivitykset loppuivat verkostoon saapumisen jälkeen. Jos historiallista näyttöä on vähän, käytä kynnystä tutkimuksen käynnistämiseen, älä katoamisen julistamiseen.

Estä toistuvat hälytykset, kun muuttumaton tapaus on avoinna. Nosta asian prioriteettia, kun uutta näyttöä ilmenee, sovittu seuranta jää tekemättä tai asiakkaalle luvattu toimitus edellyttää toimenpiteitä.

Valvo integraation toimintakuntoa erillään toimitusten suorituskyvystä

API-valvonta vastaa siihen, toimiiko seurannan integraatiosi. Toimitusten valvonta vastaa siihen, mitä lähetyksille tapahtuu. Terve päätepiste voi vastaanottaa vanhentuneita kuljetusyhtiön tietoja, kun taas käytöstä poissa oleva päätepiste voi jäädä paitsi normaalisti liikkuvien pakettien päivityksistä.

• Pyyntöjen toimintakunto: Seuraa todennusvirheitä, aikakatkaisuja, nopeusrajoitusvastauksia, palvelinvirheitä ja sovellustason hylkäyksiä.
• Webhookien toimintakunto: Seuraa varmennusvirheitä, kuittauksen viivettä, tallennusvirheitä, duplikaattitoimituksia ja käsittelyvirheitä.
• Käsittelyn toimintakunto: Valvo jonon ikää, käsittelemättömiä tapahtumia, määritysvirheitä ja ilmoitusvirheitä.
• Seurannan ajantasaisuus: Mittaa aika viimeisimmästä lähdetapahtumasta erillään ajasta viimeiseen onnistuneeseen vastaanottoosi.
• Toiminnalliset tulokset: Seuraa ratkaisemattomia poikkeuksia, vastuuhenkilön nimeämiseen kuluvaa aikaa ja myöhässä olevia seurantatoimia.

Noudata pyyntöjen uudelleenyrityksissä palveluntarjoajan nopeusrajoitus- ja uudelleenyritysohjeita. Vältä sokeasti toistamasta toimintoja, jotka voivat luoda kaksoisrekisteröintejä tai muita sivuvaikutuksia; käytä dokumentoituja idempotenssimekanismeja, jos niitä on saatavilla.

Jos mahdollista, käytä täsmäytysprosessia viimeisimmän seurantatietueen hakemiseen käyttökatkosten tai epäiltyjen puuttuvien tapahtumien jälkeen. Aseta sen tiheys sopimus- ja nopeusrajoitusten puitteisiin. Webhookit ja täsmäytys palvelevat eri tarkoituksia: toinen toimittaa muutokset, kun taas toinen auttaa havaitsemaan ja korjaamaan aukkoja.

Testaa virhetilanteet ennen asiakasilmoitusten käyttöönottoa

Aloita vain sisäiseen käsittelyyn tarkoitetulla käytöllä ja tarkasta edustavat lähetykset ennen kuin sallit tilamuutosten lähettää asiakasviestejä. Testaa muutakin kuin normaalia etenemistä kuljetuksesta toimitetuksi.

• Duplikaattiwebhook luo yhden tarkoitetun asiakasilmoituksen.
• Myöhään saapuva vanhempi tapahtuma ei korvaa nykyistä tilaa virheellisesti.
• Tuntematon tila säilytetään ja merkitään huomattavaksi sen sijaan, että se yhdistettäisiin hiljaisesti tilaan ”toimitettu”.
• Epäonnistunut kestävä tallennus ei tuota onnistunutta kuittausta.
• Tilapäinen myöhemmän järjestelmän käyttökatkos jättää tapahtumat uudelleenyritystä varten saataville.
• Toimitetuksi merkittyä tapahtumaa seuraava korjaus säilyy tarkastettavana.
• Monipakettitilaus ei muutu kokonaan toimitetuksi, kun vain yksi paketti on toimitettu.
• API-katkos hälyttää tekniikkatiimiä ilmoittamatta automaattisesti asiakkaille, että heidän pakettinsa ovat viivästyneet.

Julkaisukriteerin tulee olla toiminnallinen yhdenmukaisuus: lähetysrekisterin, asiakasviestin ja tukitoimenpiteen on oltava yhdenmukaisia saman taustalla olevan näytön kanssa. Pelkkä onnistunut webhook-vastaus ei osoita toimituskokemuksen toimivan.

UKK

Tarkoittaako HTTP 200, että paketti on toimitettu?

Ei. Se osoittaa pyynnön onnistumisen HTTP-tasolla. Lue API:n liiketoimintatulos ja lähetyksen tilakentät erikseen. Webhookin tapauksessa onnistunut kuittaus koskee ilmoituksen vastaanottoa, ei paketin fyysistä toimitusta.

Pitäisikö seurantapäivityksissä käyttää webhookeja vai kyselyä?

Käytä webhookeja tapahtumapohjaisiin päivityksiin, kun palveluntarjoaja tukee niitä. Jos mahdollista ja toiminnallisesti perusteltua, lisää rajattu täsmäytyskysely aukkojen korjaamiseksi. Pelkkä kysely voi olla sopiva, kun webhookeja ei ole saatavilla, mutta sen tiheyden on noudatettava palveluntarjoajan rajoituksia ja ajantasaisuusvaatimuksiasi.

Miksi seurantatila voi muuttua ”toimitettu”-tilan jälkeen?

Lähde voi korjata tapahtumaa tai integraatiosi voi vastaanottaa viivästyneitä tai ristiriitaisia tietoja. Säilytä historia ja arvioi uudempi näyttö sen sijaan, että pitäisit toimitettua tilaa teknisesti muuttumattomana. Ilmoitettu toimitus ja asiakkaan vahvistus vastaanotosta ovat myös eri asioita.

Kuinka nopeasti poikkeushälytys pitäisi lähettää?

Perusta kiireellisyys vaadittuun toimenpiteeseen ja vahvistettuun määräaikaan. Vastaanottajan toimenpiteitä vaativa ongelma edellyttää erilaista käsittelyä kuin tiedottava viive. Käsittelynopeus ei voi korvata myöhään julkaistua kuljetusyhtiön tapahtumaa, joten säilytä sekä lähteen että vastaanoton aikaleimat.

Pitäisikö asiakkaiden nähdä kuljetusyhtiön raakatila?

Yleensä asiakkaat hyötyvät selkeästä selityksestä ja tuetusta seuraavasta vaiheesta selittämättömän koodin sijaan. Säilytä raakatiedot tukea ja auditointia varten. Älä koskaan yksinkertaista tilaa vahvemmaksi lupaukseksi kuin mitä taustalla oleva tapahtuma tukee.

Lähteet

• RFC 9110: HTTP Semantics — HTTP-tilakoodien merkitysten, kuten 200:n ja 202:n, lähde.
• OWASP REST Security Cheat Sheet — API- ja webhook-päätepisteisiin liittyviä turvallisuusohjeita.
• 17TRACK Tracking API — käsitellyn seurannan integraatiovaihtoehdon virallinen tuoteviite.
• 17TRACK API Documentation — palveluntarjoajakohtaisten integraatiovaatimusten virallinen viite; tämän oppaan esimerkinomaiset skeemat ja työnkulkusuositukset eivät korvaa kyseistä sopimusta.