info-icon


Webhook kehittäjän opas

Johdanto

FedExin Tracking Webhook -toiminnot tarjoavat lähes reaaliaikaisia päivityksiä lähetysten tilasta niiden koko elinkaaren ajan.

Toisin kuin seurannan API:t, jotka edellyttävät sovellusten pyytävän lähetysten tilatietoja, webhookit välittävät lähetyksiä koskevat päivitykset automaattisesti sitä mukaa, kun uusia tietoja tulee saataville.

Tässä oppaassa käsitellään:

  • Kolme integraation periaatetta
  • Miten webhookit toimivat
  • Webhookien hyötykuormien käsittely
  • Asiakasilmoitukset
  • Aikaleimat
  • Parhaat käytännöt ja yleiset integrointiongelmat

Kolme integraation periaatetta

Onnistuneissa webhook integraatioissa noudatetaan kolmea periaatetta.

Käsittele jokaista webhookin hyötykuormaa lähetyksen tilapäivityksenä

Älä oleta, että jokainen hyötykuorma tarkoittaa uutta seurannan vaihetta. FedEx julkaisee uuden hyötykuorman aina, kun uusia lähetystietoja tulee saataville.

Hyötykuorma voi sisältää:

  • Uuden seurantatapahtuman
  • Päivitetyt toimitusennusteet
  • Toimitustodistuksen tiedot
  • Vastaanottajan tiedot
  • Muita lähetystietojen muutoksia

Useilla hyötykuormilla voi olla sama seurannan vaihe, vaikka ne sisältävät eri lähetystietoja.

Tallenna ja yhdistä lähetystiedot

Jokainen hyötykuorma voi sisältää uusia tai päivitettyjä lähetystietoja. Tallenna jokainen webhookin hyötykuorma ja yhdistä uudet tiedot olemassa olevaan lähetystietueeseen.

Älä korvaa olemassa olevaa lähetystietuetta uusimmalla hyötykuormalla. Säilytä sen sijaan aiemmin vastaanotetut lähetystiedot ja yhdistä niihin uudet tiedot, jotta lähetystietue pysyy täydellisenä ja ajan tasalla lähetyksen koko elinkaaren ajan.

Käytä liiketoimintasääntöjä toimintojen ohjaamiseen

Käytä liiketoimintasääntöjä sen määrittämiseen, milloin järjestelmiä päivitetään tai asiakkaille ilmoitetaan.

Älä käynnistä toimintoja pelkän tapahtumakoodin perusteella. Ennen kuin päivität asiakkaille suunnattuja sovelluksia tai lähetät ilmoituksia, arvioi seuraavat asiat:

  • Seurannan vaiheet
  • Lähetyksen saatavuus
  • Ilmoituksen ajoitus
  • Liiketoimintavaatimukset

Suositeltu käsittelymalli

Seuraava kaavio havainnollistaa, miten webhook-integraation kolme periaatetta toimivat yhdessä tyypillisessä toteutuksessa. Jokainen webhookin hyötykuorma käsitellään lähetyksen tilapäivityksenä, yhdistetään keskitettyyn lähetystietueeseen ja arvioidaan liiketoimintasääntöjen perusteella ennen kuin sovellukset päivitetään tai asiakkaille lähetetään ilmoituksia.


Miten webhookit toimivat

FedEx julkaisee uuden webhookin hyötykuorman aina, kun lähetyksen tiedot muuttuvat tai tulevat saataville. Lähetys voi tuottaa elinkaarensa aikana useita hyötykuormia, myös useita samaan seurannan vaiheeseen liittyviä hyötykuormia.

Muita hyötykuormia voivat olla:

  • Seurannan vaiheet: noudettu, kuljetuksessa, jakelussa ja toimitettu.
  • Lähetyksen tiedot: kuvallinen toimitustodistus (PPOD), allekirjoitettu toimitustodistus (SPOD), GPS-toimitustodistus (GPS POD) ja vastaanottajan tiedot.
  • Toimitusennusteen päivitykset: arvioidun toimituspäivän ja -kellonajan muutokset.
  • Toimituspoikkeamat: lähetys- ja toimituspoikkeamia koskevat päivitykset ja niiden syyt.
  • Lähetyksen metatietojen päivitykset: osoitepäivitykset, viitteet ja palvelutiedot.
  • Operatiiviset korjaukset: seurannan lisävaiheet ja previousEvents-päivitykset.

Huomautus: kuvallista toimitustodistusta ei ole saatavilla kaikista toimitetuista lähetyksistä. Saatavuus riippuu toimitustyypistä, allekirjoitusvaatimuksista ja muista liiketoimintasäännöistä.

Jokainen hyötykuorma kuvaa lähetyksen viimeisintä tiedossa olevaa tilaa. Käsittele jokainen hyötykuorma, jotta lähetystietueesi pysyy täydellisenä ja ajan tasalla.

Webhook päivitysten ymmärtäminen

Seuraava esimerkki osoittaa, miten saman lähetyksen elinkaaren aikana voidaan muodostaa useita webhook hyötykuormia. Jotkin hyötykuormat tuovat mukanaan uuden seurannan vaiheen. Toiset lisäävät lähetystä koskevia tietoja, kuten toimitusennusteita, toimitustodistuksen tietoja tai lähetyksen tietoja.

Tärkeää: samasta seurannan vaiheesta voidaan luoda useita webhookin hyötykuormia. Käsittele jokainen hyötykuorma ja varmista, että uudet lähetystiedot sisällytetään lähetystietueeseen.


Webhookien hyötykuormien käsittely

Käsittele jokainen webhookin hyötykuorma lähetyksen tilapäivityksenä.

Älä oleta, että jokainen webhookin hyötykuorma tarkoittaa uutta seurannan vaihetta. FedEx lähettää uuden hyötykuorman aina, kun uusia lähetystietoja tulee saataville. Esimerkiksi toimitettu lähetys voi tuottaa lisää hyötykuormia, kun toimitustodistuksen tietoja, vastaanottajan tietoja tai muita lähetystietoja lisätään tai päivitetään.

Kysy jokaisen hyötykuorman kohdalla:

  • Mikä seurannan vaihe muuttui?
  • Mitkä lähetyksen tiedot ovat muuttuneet?
  • Vaikuttaako päivitys asiakkaille tarkoitettuun sovellukseen?
  • Aiheuttaako päivitys ilmoituksen?

Käsittele lähetyshistoriaa

Seuraa kumpaakin seuraavista: scanEvent ja previousEvents.

  • scanEvent sisältää hyötykuormaan liittyvän seurannan tämänhetkisen vaiheen.
  • previousEvents sisältää lähetyksen muita historiatietoja, kuten merkittäviä tapahtumia, jotka eivät välttämättä näy nykyisenä scanEvent-tapahtumana.

Osa seurannan vaiheista näkyy previousEvents-tiedoissa sen sijaan, että ne julkaistaisiin uutena scanEvent-tapahtumana. Sovellukset, jotka käsittelevät vain scanEvent-tapahtumia, voivat jättää lähetysten päivityksiä huomaamatta ja muodostaa puutteellisia lähetyshistorioita. Käsittele molemmat noudot, jotta saat kokonaiskuvan lähetyksestä.

Ylläpidä lähetystietuetta

Tallenna jokainen webhookin hyötykuorma ja yhdistä uudet tiedot olemassa olevaan lähetystietueeseen.

Täydellinen lähetystietue tarjoaa lähes reaaliaikaisen näkymän seuraaviin:

  • Lähetysten seurannan koontinäytöt
  • Asiakaspalvelusovellukset
  • Tilaustenhallintajärjestelmät (OMS)

Päivitä lähetyksen tietuetta jokaisen hyötykuorman tiedoilla, jotta lähetyksestä säilyy mahdollisimman tarkka ja kattava kokonaiskuva.


Asiakasilmoitukset

Valitse ilmoitusstrategia liiketoimintasi vaatimusten ja sen perusteella, kuinka yksityiskohtaisia tietoja haluat antaa lähetyksestä.

FedExin Tracking Webhook -toiminnot lähettävät päivityksiä seurannan vaiheista ja lähetystietojen muutoksista lähes reaaliajassa. Määritä liiketoimintasääntöjen avulla, mitkä päivitykset ovat yrityksesi kannalta olennaisia ja mitkä voidaan jättää huomiotta.

Yleisiä ilmoitusstrategioita ovat muun muassa:

Lähes reaaliaikaiset ilmoitukset

Lähetä ilmoitukset heti merkittävän seurannan vaiheen jälkeen.

Edut

  • Nopein asiakasviestintä
  • Pienin viive

Huomioitavaa: lähetyksen lisätietoja ei välttämättä ole vielä saatavilla.

Monipuoliset ilmoitukset

Odota muutama minuutti seurannan vaiheen jälkeen, jotta lähetyksen lisätiedot ehtivät saapua.

Odota esimerkiksi toimituksen vahvistavan seurantatapahtuman jälkeen muutama minuutti, jotta voit kerätä seuraavat tiedot:

  • Toimitustodistus (POD)
  • allekirjoitettu toimitustodistus (Signature Proof of Delivery, SPOD)
  • GPS-toimitustodistus
  • Vastaanottajan tiedot

Edut

  • Kattavammat lähetyksen tilapäivitykset asiakkaille
  • Vähemmän jatkoilmoituksia
  • Vähemmän yhteydenottoja asiakastukeen

FedEx suosittelee odottamaan noin viisi minuuttia toimituksen vahvistavan seurantatapahtuman jälkeen, sillä toimitustodistuksen tiedot lisätään usein pian ensimmäisen toimitustapahtuman jälkeen.

Ilmoitusten ajoitusta koskevat suositukset

Ilmoitusten ajoitus vaihtelee asiakkaan ja käyttötapauksen mukaan. Seuraavia suosituksia käytetään kuitenkin yleisesti vastaanottajalle oston jälkeen lähetettävissä ilmoituksissa. Valitse muille ilmoitustyypeille (yrityskäyttäjille, asiakaspalveluedustajille ja niin edelleen) käyttötapaukseesi sopiva ilmoitusstrategia.

  • Arvioitu toimitus: Odota noin 15 minuuttia sen jälkeen, kun sekä Commit Date että ensimmäinen arvioitu toimituspäivä (EDD) ovat saatavilla.
  • Jakelussa: lähetä välittömästi tai yrityksesi aikataulun mukaisesti (esimerkiksi päivittäin kello 8.00).
  • Toimitettu: odota noin 5 minuuttia, jotta toimitustietojen täydennykset ehtivät saapua.
  • Toimitusyritys: noudata samaa menettelyä kuin kohdassa Toimitettu, jotta toimitustiedot ehtivät saapua.

Liiketoimintatietoihin perustuvien ilmoitussääntöjen luominen

Kaikki lähetyksen päivitykset eivät edellytä ilmoitusta. Määritä ilmoitussäännöt, jotka tukevat liiketoimintavaatimuksiasi.

Suositeltu toimintatapa

Älä laukaise ilmoituksia pelkästään seuraavan perusteella: eventCode.

Arvioi:

  • Seurannan vaihe
  • Vaaditut lähetystiedot
  • Liiketoimintasäännöt

Luo ilmoituksia vain, kun vaaditut tiedot ovat saatavilla.

Tämä toimintatapa auttaa ehkäisemään:

  • Päällekkäisiä ilmoituksia
  • Puuttuvat toimitustiedot
  • Puutteelliset toimitusilmoitukset
  • Tarpeettomat jatkoilmoitukset

Aikaleimat

Käytä käyttötarkoitukseesi sopivaa aikaleimaa.

  • eventCreateTime: lähetystapahtuman ajankohta. Käytä sitä asiakkaille näkyvässä seurantahistoriassa.
  • Viestin lähetysaika: ajankohta, jolloin FedEx lähetti webhookin hyötykuorman. Käytä sitä vain virheenkorjaukseen ja seurantaan, älä asiakkaille suunnatuissa palveluissa.

eventCreateTime ilmaisee lähetystapahtuman ajankohdan. FedEx ei päivitä tätä arvoa, kun lähetyksen tietoja täydennetään myöhemmin. Esimerkiksi toimitustapahtuman alkuperäinen eventCreateTime -arvo säilyy, vaikka myöhemmät hyötykuormat lisäisivät toimitustodistuksen tietoja tai muita lähetystä koskevia päivityksiä. Siksi eventCreateTime -arvoa tulee käyttää tapahtuman ajankohdan määrittämiseen, ei siihen liittyvien lähetystietojen lisäämisajankohdan määrittämiseen.

Joissakin tapauksissa tapahtuman kellonaika ei välttämättä ole saatavilla. Tällöin aikaleima voi sisältää oletusarvon 00:00:00. Muut hyötykuormat voivat sisältää tarkemman aikaleiman, kun sellainen on saatavilla.


Parhaat käytännöt ja yleiset integrointiongelmat

Parhaat käytännöt

  • Käsittele jokainen webhookin hyötykuorma – jokainen viesti voi sisältää uuden seurantatapahtuman tai lähetystietojen päivityksen.
  • Yhdistä inkrementaaliset päivitykset olemassa olevaan lähetystietueeseesi.
  • Seuraa sekä scanEvent että previousEvents -tietoja, jotta saat talteen lähetyksen koko historian.
  • Käynnistä asiakasilmoitukset liiketoimintasääntöjen eikä pelkästään käsittelemättömien tapahtumien perusteella.
  • Varaa aikaa odotettavissa oleville tietojen täydennyksille (esimerkiksi kuvallinen toimitustodistus (PPOD), SPOD ja GPS) ennen asiakkaille ilmoittamista.
  • Suunnittele idempotentti ja vikasietoinen käsittely, joka hallitsee viestien kaksoiskappaleet ja epäjärjestyksessä saapuvat viestit.

Yleiset integraatio-ongelmat

  • Oletus siitä, että jokainen hyötykuorma edustaa uutta merkittävää seurannan vaihetta.
  • Lähetystietueen korvaaminen uusimmalla hyötykuormalla.
  • Tukeutuminen pelkästään seuraavaan: scanEvent.
  • Ilmoitusten laukaiseminen pelkästään seuraavan perusteella: eventCode.
  • Oletus siitä, että ensimmäisenä toimitettu hyötykuorma sisältää kaikki toimitusta koskevat tiedot.
  • Oletus siitä, että webhook-viestit saapuvat vain kerran tai aikajärjestyksessä.

Yhteenveto

Käsittele jokainen webhookin hyötykuorma lähetyksen tilapäivityksenä. Tallenna ja yhdistä lähetysten päivitykset, seuraa sekä scanEvent- että previousEvents -tietoja ja määritä liiketoimintasääntöjen avulla, milloin sovelluksia päivitetään tai asiakkaille lähetetään ilmoituksia.

Tämä toimintatapa auttaa varmistamaan lähetysten tarkan näkyvyyden, kattavan seurantahistorian ja parempaan tietopohjaan perustuvan asiakasviestinnän.