UPS Tracking API -webhookit: mitä ne ovat, miten ne toimivat ja käyttötapaukset
UPS:n seuranta-API:n webhookit antavat sovellukselle mahdollisuuden vastaanottaa lähetyspäivityksiä, kun seurantatapahtuma on saatavilla, sen sijaan että se kysyisi toistuvasti seurantapalvelulta uusinta tilaa. Ne ovat hyödyllisiä verkkokaupoille, logistiikkatiimeille, markkinapaikoille ja kehittäjille, jotka rakentavat tilaustenhallinnan työnkulkuja. Käytännön hyöty ei ole ainoastaan nopeampi tilan synkronointi: hyvin suunniteltu webhook-työnkulku voi päivittää asiakkaille näkyviä sivuja, käynnistää poikkeamien käsittelyn ja vähentää tarpeettomia seurantapyyntöjä.
Tarkka todennusmenetelmä, tapahtumamalli, pyyntörajoitukset, hyötykuorman kentät ja tilivaatimukset riippuvat UPS:n kehittäjätuotteesta ja integraatioympäristöstä. Kehittäjien tulee tarkistaa nämä tiedot ajantasaisesta UPS-dokumentaatiosta ennen tuotantoyhteyden rakentamista.
Mikä on UPS:n seuranta-API:n webhook?
Seuranta-API tarjoaa ohjelmallisen tavan pyytää lähetystietoja. Webhook lisää lähtevän ilmoituksen mallin: kun sovellus on tilannut asiaankuuluvat päivitykset, palvelu lähettää HTTP-pyynnön sovelluksen hallinnoimaan päätepisteeseen, kun määritetty tapahtuma toteutuu.
Tilausjärjestelmä voi esimerkiksi tallentaa UPS-seurantanumeron ja rekisteröidä webhook-päätepisteen. Kun lähetyksen tila muuttuu, vastaanottava järjestelmä voi saada ilmoituksen, joka sisältää jonkin yhdistelmän seurantanumerosta, tilasta, aikaleimasta, sijainnista, toimitusarviosta tai poikkeamatiedoista. Vastaanottava järjestelmä validoi viestin, päivittää oman tietueensa ja päättää, mitä toimintoa seuraavaksi tarvitaan.
Webhook ei ole sama asia kuin seurantaseurantasivu. Seurantasivu on suunniteltu ihmisen tarkasteltavaksi. Webhook on suunniteltu ohjelmiston käsiteltäväksi. Se ei myöskään takaa, että jokainen kuljetusyhtiön skannaus toimitetaan täsmälleen kerran tai täydellisessä järjestyksessä. Tuotantojärjestelmät tulee rakentaa ottaen huomioon päällekkäiset viestit, viivästynyt toimitus, uudelleenyritykset ja ajoittainen täsmäytys.
Miten työnkulku yleensä toimii
- Kehittäjä luo tai määrittää käyttöoikeudet soveltuvan UPS-kehittäjätilin kautta ja hankkii API:n edellyttämät tunnistetiedot.
- Sovellus lähettää tai tallentaa lähetyksen tunnisteen, yleensä seurantanumeron, yhdessä sisäisten tila- ja asiakasviitteiden kanssa.
- Kehittäjä määrittää julkisesti saavutettavan HTTPS-päätepisteen ja noudattaa palveluntarjoajan tilaus- tai rekisteröintimenettelyä, jos sitä vaaditaan.
- Seurantapalvelu lähettää HTTP-ilmoituksen, kun tilattu päivitys on saatavilla.
- Päätepiste todentaa tai varmistaa pyynnön, jäsentää hyötykuorman ja tarkistaa, että lähetys tunnetaan.
- Sovellus kuittaa pyynnön nopeasti ja käsittelee liiketoimintatoiminnon sen jälkeen jonon tai taustatyöntekijän kautta.
- Järjestelmä tallentaa tapahtuman, soveltaa idempotenssisääntöjä ja päivittää tila-, varasto-, tuki- tai asiakasviestinnän työnkulun.
Kuittauksen ja käsittelyn erottaminen on tärkeää. Webhookin lähettäjä voi yrittää lähetystä uudelleen, jos päätepiste on hidas tai palauttaa virheen. Vastaanottaja, joka suorittaa laajoja tietokantaoperaatioita, lähettää sähköposteja tai käsittelee varastotoimia ennen vastaamista, voi aiheuttaa aikakatkaisuja ja päällekkäisiä toimituksia.
Webhook-ilmoitukset verrattuna kyselyyn
| Lähestymistapa | Miten se toimii | Tärkein kompromissi |
|---|---|---|
| Kysely | Sovelluksesi pyytää uusimman tilan aikataulun mukaisesti. | Se on helppo ymmärtää, mutta toistuvat pyynnöt voivat lisätä viivettä ja tarpeetonta liikennettä. |
| Webhook-toimitus | Seurantapalvelu lähettää ilmoituksen, kun päivitys on saatavilla. | Se voi vähentää ajastettua tarkistamista, mutta edellyttää suojattua ja luotettavaa vastaanottajaa sekä palautumisprosessia. |
| Hybridimalli | Webhookit käynnistävät normaalin käsittelyn, kun taas kysely tai täsmäytys etsii puuttuvia tapahtumia. | Se vaatii enemmän suunnittelua, mutta on usein kestävämpi kuin yhteen toimitustapaan luottaminen. |
Webhook ei automaattisesti poista API-pyyntöjen tarvetta. Jotkin integraatiot käyttävät ilmoitusta signaalina ja kutsuvat sen jälkeen seuranta-API:a uusimman auktoritatiivisen tietueen hakemiseksi. Tästä voi olla hyötyä, kun webhook-hyötykuorma on suppea tapahtuma, kun sovellus tarvitsee ilmoitukseen sisältymättömiä lähetystietoja tai kun yritys haluaa yhden normalisointipolun kaikille päivityksille.
Mitä seuranta-webhookin hyötykuorman tulisi sisältää?
Hyötykuormat vaihtelevat palveluntarjoajan ja tuotteen mukaan. Älä suunnittele tietokantaasi oletettujen kenttänimien varaan ennen kuin ajantasainen dokumentaatio ja testivastaukset on tarkistettu. Yleisesti seurantatapahtuman on ehkä tunnistettava:
- Lähetys tai seurantanumero
- Tapahtuman tai lähetyksen tila
- Tapahtuma-aika ja, jos ilmoitettu, paikallinen aikavyöhyke
- Skannauksen kuvaus tai operatiivinen viesti
- Sijaintitiedot, jos saatavilla
- Toimitusarvio tai toimitusvahvistus, jos ilmoitettu
- Poikkeaman ilmaisin tai kuvaus
- Palveluntarjoajan tapahtumatunniste tai muu päällekkäisyyksien poistamiseen hyödyllinen arvo
Käsittele tilatekstiä palveluntarjoajan tietona, ei yleispätevänä liiketoimintasääntönä. Nimike, kuten ”kuljetuksessa”, ”poikkeama” tai ”toimitettu”, on ehkä muunnettava sisäiseen tilamalliin. Järjestelmäsi tulee säilyttää alkuperäinen kuljetusyhtiön tila normalisoidun tilan lisäksi, jotta tukihenkilöstö voi tutkia erot menettämättä lähdeviestiä.
Käytännön käyttötapaukset
Asiakkaan toimituspäivitykset
Verkkokauppa-alusta voi käyttää seurantatapahtumia tilaussivun päivittämiseen tai asiakasilmoituksen lähettämiseen. Paras laukaisin riippuu liiketoimintasäännöstä. Lähetyksen vastaanottoskannaus voi vahvistaa toimituksen edistymisen, kun taas poikkeamatapahtuma voi edellyttää tukiviestiä yleisen tilasähköpostin sijaan. Vältä ilmoituksen lähettämistä jokaisesta skannauksesta, elleivät asiakkaat ole nimenomaisesti pyytäneet tällaista yksityiskohtaisuutta.
Poikkeamien hallinta
Webhook voi ohjata mahdolliset toimitusongelmat tarkistusjonoon. Esimerkkejä ovat toimituspoikkeama, osoitteeseen liittyvä ongelma tai lähetys, joka ei ole edennyt odotetusti. Integraation tulee erottaa toisistaan tiedoksi tarkoitettu skannaus ja operatiivinen poikkeama. Sen tulee myös määrittää vastuut: asiakastuki voi hoitaa viestinnän, kun taas toimitustiimi voi tutkia lähetystä tai osoitetta.
Varaston ja tilaustenhallinnan synkronointi
Varasto- tai tilaustenhallintajärjestelmä voi käyttää seurantatapahtumia toimitustietueen päivittämiseen ilman, että henkilökunnan tarvitsee tarkistaa kuljetusyhtiön sivustoa manuaalisesti. Tämä on erityisen hyödyllistä, kun yksi tilaus sisältää useita paketteja. Tietomallissa tulee säilyttää pakettikohtaiset seurantatietueet sen sijaan, että koko tilaukselle liitettäisiin yksi tila, koska saman tilauksen paketit voivat kulkea tai saapua eri aikoina.
Palautukset ja käänteinen logistiikka
Palautustyönkulut voivat käyttää seurantatapahtumia tunnistamaan, milloin paketti on matkalla takaisin myyjälle tai milloin se saapuu palautuskeskukseen. Tapahtuman ei pitäisi yksinään oikeuttaa hyvitykseen, ellei myyjän käytännössä nimenomaisesti käytetä tätä ehtoa. Palautus voi edellyttää tarkastusta, varaston täsmäytystä tai petostarkistusta sen jälkeen, kun kuljetusyhtiö ilmoittaa toimituksesta.
Operatiivinen raportointi
Normalisoidut seurantatapahtumat voivat tukea raportteja lähetyksen etenemisestä, poikkeamien määrästä ja toimitustuloksista. Raporteissa tulee määritellä käsitteet selkeästi. Esimerkiksi ”toimitettu” voi tarkoittaa kuljetusyhtiön ilmoittamaa toimitustapahtumaa, kun taas ”ajoissa” edellyttää määritettyä luvattua päivämäärää, määräaikaa, aikavyöhykettä sekä osoitteenmuutosten tai asiakkaan pyytämien viivästysten käsittelytapaa.
Vain UPS-integraatio vai usean kuljetusyhtiön API?
UPS-kohtainen integraatio voi olla sopiva, kun yritys toimittaa pääasiassa UPS:n kautta ja haluaa käyttää sen virallista kehittäjäympäristöä suoraan. Se voi myös olla yksinkertaisin vaihtoehto, kun nykyisessä tilausjärjestelmässä on jo UPS-liitin ja tarvittavat työnkulut ovat rajalliset.
Usean kuljetusyhtiön seuranta-API on erilainen arkkitehtoninen valinta. Se voi tarjota yhden integraatiomallin eri kuljetusyhtiöille, mutta sovelluksen on silti käsiteltävä kuljetusyhtiökohtaisia tilamerkityksiä, kattavuuseroja, todennusvaatimuksia ja tietojen laatua. Usean kuljetusyhtiön palvelua ei pidä valita pelkästään siksi, että se ilmoittaa tarjoavansa webhookin. Tarkista tuetut kuljetusyhtiöt, tapahtumien normalisointi, dokumentaatio, testiympäristö, säilytyssäännöt ja operatiivinen tuki.
17TRACKin Tracking API on relevantti tiimeille, jotka arvioivat usean kuljetusyhtiön seurantatapaa, kun taas sen virallista API-dokumentaatiota tulee käyttää nykyisten ominaisuuksien, pyyntömuotojen ja integraatiovaatimusten varmistamiseen. Se ei korvaa sen tarkistamista, ovatko tietyn UPS-työnkulun edellyttämät kuljetusyhtiöt ja tapahtumat tuettuja aiotussa käyttötapauksessa.
Toteutuksen tarkistuslista
- Vahvista tuotteen laajuus. Tarkista, tukeeko valittu UPS-palvelu sovelluksesi tarvitsemia seurantatoimintoja ja ilmoitusmallia.
- Käytä HTTPS:ää. Vastaanottaja tulee suojata siirron aikana, eikä tunnistetietoja pidä paljastaa URL-osoitteissa tai lokeissa.
- Vahvista aitous. Noudata palveluntarjoajan dokumentoitua allekirjoitus-, tunnus- tai varmennusmenetelmää. Jos menetelmää ei ole saatavilla, käytä palveluun sopivia verkkokontrolleja ja pyyntöjen validointia.
- Tee käsittelystä idempotenttia. Tallenna tapahtumatunniste, jos se on saatavilla, tai luo vakaisiin tapahtumakenttiin perustuva varovainen päällekkäisyyksien poistamisen avain.
- Hyväksy tapahtumat väärässä järjestyksessä. Käytä tapahtumien aikaleimoja ja dokumentoitua tilasiirtymäkäytäntöä sen sijaan, että olettaisit saapumisjärjestyksen vastaavan skannausjärjestystä.
- Palauta vastaus nopeasti. Siirrä pidemmät tehtävät jonoon ja seuraa epäonnistuneita toimituksia, uudelleenyrityksiä ja käsittelemättömien viestien jonoja.
- Täsmäytä puutteet. Ajasta hallittu varmennusprosessi lähetyksille, joilla ei ole tuoretta päivitystä, joilla on epäonnistunut toimitus tai joiden tila on ristiriitainen.
- Suojaa henkilötiedot. Rajoita tallennettavia osoite- ja vastaanottajatietoja, rajoita käyttöoikeuksia ja määritä liiketoiminnan tarpeita vastaavat säilytyssäännöt.
- Testaa todelliset liiketoimintatapaukset. Sisällytä toimitetut lähetykset, poikkeamat, peruutetut tilaukset, päällekkäiset tapahtumat, tuntemattomat seurantanumerot ja viivästyneet ilmoitukset.
Yleiset vältettävät virheet
Yleisin suunnitteluvirhe on käsitellä webhookia täydellisenä totuuden lähteenä ilman uudelleenyrityksiin tai puuttuviin tapahtumiin varautumista. Toinen virhe on päivittää tilauksen tila suoraan vapaamuotoisesta tekstistä ilman muunnoskerrosta. Tämä voi tuottaa virheellisiä asiakasviestejä, kun kuljetusyhtiön terminologia muuttuu tai kun tapahtuma koskee vain yhtä pakettia.
Tiimien tulee myös välttää webhook-päätepisteen paljastamista ilman väärinkäytön hallintaa, tarpeettomia henkilötietoja sisältävien täydellisten hyötykuormien kirjaamista sekä asiakasilmoitusten lähettämistä ennen kuin tapahtuma on läpäissyt perustason validoinnin. Älä myöskään lupaa toimituspäiviä pelkästään siksi, että seurantavastaus sisältää arvion. Arviot voivat muuttua, ja asiakkaalle suunnatun sanamuodon tulee kuvastaa tätä epävarmuutta.
Miten integraatiotapa valitaan
Valitse suora UPS-integraatio, kun kuljetusyhtiöiden määrä on rajallinen, tiimi pystyy ylläpitämään kuljetusyhtiökohtaista logiikkaa ja tarvittavat viralliset ominaisuudet ovat saatavilla. Harkitse usean kuljetusyhtiön seuranta-API:a, kun yritys tarvitsee yhden sisäisen rajapinnan useille kuljetusyhtiöille ja sillä on tarpeeksi volyymia tai monimutkaisuutta abstraktiokerroksen perustelemiseksi. Kummassakin tapauksessa vertaa todellista dokumentaatiota ja testikäyttäytymistä, älä pelkkiä ominaisuuksien nimiä.
Suorita ennen tuotantoon siirtymistä konseptitesti edustavilla seurantanumeroilla ja vikatilanteilla. Varmista, miten tilaukset luodaan, miten tunnistetiedot vaihdetaan, miten ilmoitukset varmennetaan, miten päällekkäiset tapahtumat näkyvät, miten historiallisia päivityksiä käsitellään ja mitä tapahtuu, jos vastaanottaja ei ole käytettävissä. Nämä vastaukset määrittävät, säilyykö integraatio luotettavana alkuperäisen demon jälkeen.
Usein kysytyt kysymykset
Onko UPS:n seuranta-API:n webhook parempi kuin kysely?
Kumpikaan lähestymistapa ei ole automaattisesti parempi. Webhookit voivat vähentää ajastettua tarkistamista ja mahdollistaa nopeammat reaktiot, kun taas kyselyä voi olla helpompi hallita ja se voi auttaa täsmäyttämään puuttuneet tapahtumat. Monet tuotantojärjestelmät käyttävät webhook-ilmoituksia yhdessä rajattujen täsmäytyspyyntöjen kanssa.
Tarvitsenko webhookia, jos seuraan vain pientä määrää lähetyksiä?
Ei välttämättä. Pienessä ja harvoin tapahtuvassa työnkulussa dokumentoitu kyselyprosessi tai olemassa oleva alustaintegraatio voi riittää. Webhookista tulee houkuttelevampi, kun päivitysten täytyy käynnistää automaattisia toimintoja tai kun säännöllinen manuaalinen tarkistaminen aiheuttaa operatiivista työtä.
Voiko webhook taata, että jokainen UPS-skannaus saapuu järjestelmääni?
Sinun ei pidä olettaa niin. Toimituskäyttäytyminen, uudelleenyritykset, tapahtumien järjestys ja säilytys riippuvat tietystä palvelusta. Sisällytä integraatioon valvonta, idempotenssi ja täsmäytys sekä vahvista sovellettavat takuut ajantasaisesta UPS-dokumentaatiosta.
Pitäisikö jokaisen seurantatapahtuman käynnistää asiakassähköposti?
Yleensä ei. Muunna kuljetusyhtiön tapahtumat asiakasviestinnän säännöiksi ja varaa viestit vastaanottajalle hyödyllisiin virstanpylväisiin tai poikkeamiin. Säilytä alkuperäinen tapahtuma sisäistä historiaa varten, vaikka se ei synnyttäisi ilmoitusta.
Milloin yrityksen kannattaa käyttää usean kuljetusyhtiön seuranta-API:a?
Sitä kannattaa arvioida, kun yritys toimittaa useiden kuljetusyhtiöiden kautta ja haluaa yhteisen seurantatyönkulun. Päätöksessä tulee huomioida kuljetusyhtiöiden tuki, normalisoidut tiedot, webhook-käyttäytyminen, dokumentaatio, turvallisuus, testaus ja integraation ylläpitämiseen tarvittava työ.
