Kuinka käyttää lähetysseurannan API-rajapintoja ennakoivien toimitusilmoitusten lähettämiseen
Jos haluat lähettää ennakoivia toimitusilmoituksia lähetysseuranta-API:n avulla, yhdistä jokainen paketti tilaukseensa, vastaanota seurantapäivitykset, muunna päivitykset asiakkaalle merkityksellisiksi tapahtumiksi ja käynnistä viestit sähköposti-, SMS- tai sovellusilmoituspalvelusi kautta. Sijoita saapuvan seurantadatan ja lähtevien viestien väliin kestävä jono ja duplikaattitarkistukset, jotta toistuvat tai viivästyneet päivitykset eivät tuota hämmentäviä ilmoituksia.
Tämä opas on tarkoitettu kehittäjille ja verkkokauppojen operatiivisille tiimeille, jotka rakentavat tällaista työnkulkua. Tavoitteena ei ole välittää jokaista kuljetusyhtiön skannausta. Tavoitteena on kertoa asiakkaille, milloin jokin merkityksellinen muuttuu, mitä muutos tarkoittaa ja tarvitseeko heidän toimia.
Suunnittele ilmoitusten työnkulku ennen API:n yhdistämistä
Lähetysseuranta-API tarjoaa seurantatietoja; sovelluksesi päättää, miten niitä käytetään. Käsittele lähetyksen näkyvyyttä ja asiakasviestintää erillisinä vastuualueina, vaikka valitsemasi palvelu tarjoaisi molemmat.
Käytännöllinen arkkitehtuuri koostuu kuudesta vaiheesta:
- Tilauksen yhdistäminen: yhdistä seurantatunnus ja kuljetusyhtiön tunniste tarvittaessa sisäiseen lähetystietueeseen.
- Seurannan rekisteröinti: lähetä tai rekisteröi lähetys palveluntarjoajan integraatiovaatimusten mukaisesti.
- Päivitysten vastaanotto: vastaanota webhook-kutsuja, hae päivityksiä API-pyyntöjen kautta tai yhdistä molemmat lähestymistavat.
- Tapahtumien käsittely: validoi, normalisoi, poista duplikaatit ja arvioi saapuvat tapahtumat.
- Ilmoituspäätös: päätä, lähetetäänkö ilmoitus, kenelle yhteydenotto tehdään sekä mitä kanavaa ja mallia käytetään.
- Viestin toimitus: lähetä ilmoitus ja tallenna viestipalvelun vastaus.
Säilytä asiakkaiden yhteystiedot omassa tilaus- tai viestijärjestelmässäsi, ellei integraatio todella edellytä niiden jakamista. Seurantapalvelu ei yleensä tarvitse asiakkaan sähköpostiosoitetta vain siksi, että sovelluksesi voi yhdistää seurantatapahtuman tilaukseen.
1. Vahvista integraatiosopimus
Ennen vastaanottimen kirjoittamista tarkista palveluntarjoajan dokumentaatiosta todennus, lähetysten rekisteröinti, kuljetusyhtiön tunnistaminen, tuetut päivitysmenetelmät, vastausmuodot, pyyntörajat ja virheenkäsittely. Webhook-integraatioissa tarkista myös, miten kutsut todennetaan, millainen vastaus vahvistaa vastaanoton ja miten epäonnistuneita toimituksia käsitellään.
Jos toteutat 17TRACK-ratkaisun, aloita 17TRACK Tracking API -sivulta ja sen virallisesta API-dokumentaatiosta. Käytä integraatiossasi dokumentoitua sopimusta sen sijaan, että käsittelisit tämän oppaan esimerkkikenttien nimiä 17TRACK-pyyntö- tai vastauskenttinä. Vahvista callback-asetukset, tietoturvavaatimukset ja tiliä koskevat rajoitukset ennen toteutusta.
Valitse päivitysmenetelmä integraatiosopimuksen mukaisesti:
- Webhookit: käytä callback-kutsuja, kun niitä tuetaan ja ne sopivat infrastruktuuriisi. Niiden avulla sovelluksesi voi käsitellä päivitykset palveluntarjoajan lähettäessä ne ilman, että samaa lähetystä pyydetään toistuvasti.
- Polling: hae seurantatietoja aikataulun mukaan, kun callback-kutsuja ei ole saatavilla tai ne eivät sovi käyttötarkoitukseen. Pidä aikataulu dokumentoitujen pyyntörajojen sisällä.
- Yhdistetty lähestymistapa: käytä callback-kutsuja normaaliin käsittelyyn ja valikoivaa API-hakua niiden lähetysten täsmäyttämiseen, joiden päivitykset vaikuttavat vanhentuneilta, jos palveluntarjoaja tukee tällaista työnkulkua.
Älä lupaa asiakkaille välittömiä ilmoituksia vain siksi, että käytät webhookeja. Sovelluksesi ei voi ilmoittaa kuljetusyhtiön tapahtumasta ennen kuin ylemmän tason seurantadata tekee sen saataville.
2. Rakenna todelliset tilaukset kestävä lähetystietue
Käytä ensisijaisena viitteenä sisäistä lähetys-ID:tä, älä pelkkää seurantatunnusta. Tilaus voi sisältää useita paketteja, eikä seurantatunnusten pidä olettaa olevan maailmanlaajuisesti ainutlaatuisia ikuisesti.
Hyödyllinen sisäinen tietue sisältää:
- Sisäisen tilauksen ID:n ja lähetyksen ID:n.
- Seurantatunnuksen ja kuljetusyhtiön tunnisteen, kun ne ovat tiedossa.
- Palveluntarjoajan lähetysviitteen, jos se toimitetaan.
- Nykyisen normalisoidun tilan ja viimeisimmän merkityksellisen tapahtuman.
- Kuljetusyhtiön tapahtuma-ajan sekä aikavyöhykkeen tai siirtymän, jos saatavilla.
- Ajankohdan, jolloin järjestelmäsi vastaanotti päivityksen.
- Viitteen asiakkaan viestintäasetuksiin.
- Ilmoitushistorian ja mahdollisen aktiivisen poikkeamatyönkulun.
Säilytä tapahtuma-aika erillään vastaanottoajasta. Aiemmin tapahtunut skannaus voi saapua uudemman skannauksen jälkeen. Jos sovelluksesi lajittelee vain saapumisjärjestyksen mukaan, se voi erehdyksessä muuttaa toimitetun lähetyksen takaisin kuljetuksessa olevaksi.
Osittaisissa tilauksissa yhdistä ilmoitukset kyseiseen pakettiin. ”Yksi tilauksesi paketeista on saapunut” on tarkempi kuin ”Tilauksesi on saapunut”, kun toinen paketti on edelleen matkalla.
3. Yhdistä seurantatapahtumat asiakkaan päätöksiin
Kuljetusyhtiöiden kuvaukset ovat operatiivista dataa, eivät valmiita asiakasviestejä. Rakenna normalisointikerros, joka säilyttää alkuperäisen tapahtuman ja määrittää samalla sisäisen luokan, jonka ilmoitussäännöt ymmärtävät.
Seuraavat luokat ovat ehdotettuja sovelluskonsepteja, eivät yleismaailmallinen API-tilasanasto:
| Sisäinen luokka | Ilmoituspäätös | Viestinnän raja |
|---|---|---|
| Lähetystiedot vastaanotettu | Lähetä valmistelupäivitys vain, jos siitä on hyötyä. | Älä anna ymmärtää, että kuljetusyhtiö on fyysisesti vastaanottanut lähetyksen pelkän etiketin luomisen perusteella. |
| Kuljetuksessa | Harkitse ilmoittamista ensimmäisen merkityksellisen etenemisen yhteydessä. | Piilota rutiininomaiset terminaaliskannaukset, elleivät ne muuta asiakkaan seuraavaa vaihetta. |
| Jakelu käynnissä | Ilmoita, kun tuettu tapahtuma osoittaa tämän tilan. | Älä muuta tilaa taatuksi saapumisajaksi. |
| Toimitusyritys tai nouto vaaditaan | Lähetä toimia edellyttävä ilmoitus. | Sisällytä määräajat tai nouto-ohjeet vain, kun ne on vahvistettu. |
| Toimituspoikkeama | Arvioi syy ja se, tarvitseeko asiakkaan toimia. | Älä kuvaa jokaista poikkeamaa kadonneeksi paketiksi. |
| Toimitettu | Lähetä pakettikohtainen vahvistus. | Älä keksi vastaanottajaa, toimituspaikkaa tai toimitustodistetta. |
Säilytä epävarmuus. Tuntemattoman tapahtuman tulee siirtyä tarkistus- tai varareitille sen sijaan, että se pakotetaan lähimpään tuttuun luokkaan. Pidä raaka kuvaus tukihenkilöstön saatavilla vianmääritystä varten.
4. Vastaanota päivitykset menettämättä tai toistamatta käsittelyä
Webhook-päätepisteesi tulee validoida pyyntö, tallentaa hyväksytty päivitys pysyvästi ja palauttaa palveluntarjoajan edellyttämä kuittaus. Luo viestit asynkronisesti sen sijaan, että odottaisit sähköposti- tai SMS-palvelua callback-pyynnön aikana.
Toteuta palveluntarjoajan dokumentoitu callback-varmennusmenetelmä. Älä keksi allekirjoitusotsaketta tai oleta, että kaikki palveluntarjoajat käyttävät samaa todennusmenetelmää. Ota käyttöön myös HTTPS, pyyntöjen kokorajoitukset, hyötykuorman validointi ja asianmukaiset käyttöoikeudet.
Yksinkertaistettu käsittelykulku näyttää tältä. Nämä ovat sovellustason toimintoja, eivät toimiva SDK-esimerkki:
vastaanota callback-kutsu
vahvista pyyntö palveluntarjoajan dokumentoidulla menetelmällä
validoi hyötykuorma
tallenna hyväksytty hyötykuorma ja lisää käsittelyjonoon atomisesti
palauta dokumentoitu kuittaus
käsittele jonotettu päivitys
etsi sisäinen lähetys
normalisoi olennaiset tapahtumat
ohita jo käsitellyt tapahtumat
arvioi aikajärjestys ja tilasiirtymä
luo ilmoitustehtävä, jos käytäntö sallii
vahvista tila ja tehtävä yhdessä
lähetä ilmoitustehtävä
tarkista vastaanottajan asetukset ja estämissäännöt
lähetä viesti viestipalveluun
tallenna tulos ja yritä uudelleen vain tarvittaessa
Atomiset vaiheet ovat tärkeitä. Jos sovelluksesi tallentaa tilamuutoksen mutta kaatuu ennen ilmoitustehtävän luomista, asiakas ei ehkä koskaan saa ilmoitusta. Transactional outbox on yksi suunnitteluvaihtoehto: tallenna tilamuutos ja odottava tehtävä samaan tietokantatransaktioon ja anna työntekijän lähettää tehtävä.
Käsittele tuntemattomat lähetysviitteet nimenomaisesti. Eristä ne tutkintaa tai täsmäytystä varten sen sijaan, että arvaisit, minkä asiakkaan tulisi saada ilmoitus.
5. Lisää duplikaattisuoja ja aikajärjestyksen tarkistukset
Suunnittele vastaanotin kestämään toistuvat callback-kutsut ja työntekijöiden uudelleenyritykset. Suosi vakaata palveluntarjoajan tapahtumatunnistetta, jos sellainen on dokumentoitu. Muussa tapauksessa luo deterministinen tapahtuman sormenjälki sopivista kentistä, kuten sisäisestä lähetys-ID:stä, tapahtumakoodista, tapahtuma-ajasta ja sijainnista. Testaa sormenjälki todellisilla hyötykuormilla ennen kuin luotat siihen.
Tapahtumien duplikaattien poisto ja ilmoitusten estäminen ratkaisevat eri ongelmat. Duplikaattien poisto estää saman tapahtuman käsittelyn kahdesti. Estäminen estää useita erillisiä skannauksia tuottamasta olennaisesti samaa asiakasviestiä.
Määritä ilmoituksen identiteetti liiketoimintatapahtuman ympärille. Toimitusvahvistus voi käyttää lähetys-ID:tä ja toimituksen virstanpylvästä. Toimitusyritys voi tarvita yrityskohtaisen identiteetin, koska myöhempi yritys voi olla aidosti uusi tapahtuma.
Järjestyksestä poikkeavissa päivityksissä vertaa tapahtuma-aikoja ja arvioi sallitut tilasiirtymät. Älä oleta, että callback sisältää vain uuden skannauksen; tarkista, edustaako sen dokumentoitu rakenne yksittäistä tapahtumaa, tilannekuvaa vai historiaa. Ohjaa ristiriitaiset päivitykset täsmäytykseen sen sijaan, että hylkäisit kaikki korjaukset hiljaisesti.
6. Kirjoita viestejä, jotka selittävät seuraavan vaiheen
Jokaisen ilmoituksen tulee kertoa kyseinen paketti, vahvistettu muutos ja asiakkaan seuraava vaihe. Sisällytä suojattu seurant لینکki ja tunnistettava tilausviite. Vältä täydellisten osoitteiden tai tarpeettomien henkilötietojen näyttämistä SMS-viesteissä ja lukitusnäytön esikatseluissa.
Esimerkiksi:
- Jakelu käynnissä: ”Tilauksesi {order_reference} paketti on jakelussa. Seuraa sen etenemistä täällä: {tracking_link}.”
- Toimitusta yritetty: ”Kuljetusyhtiö ilmoitti pakettisi toimitusyrityksestä. Tarkista seurant-sivulta saatavilla olevat seuraavat vaiheet: {tracking_link}.”
- Toimitettu: ”Kuljetusyhtiö on merkinnyt tilauksesi {order_reference} paketin toimitetuksi. Katso saatavilla olevat toimitustiedot: {tracking_link}.”
Renderöi paikkamerkit vain validoiduista tiedoista. Jos toimitusarvio on saatavilla ja sopii näytettäväksi, merkitse se arvioksi. Jos tieto puuttuu, jätä se pois sen sijaan, että keksisit päivämäärän.
Poikkeamissa erottele lähetysongelma asiakkaan tehtävästä. Häiriö voi vaatia vain selityksen; vahvistettu osoiteongelma voi edellyttää toimia. Älä ohjaa asiakkaita maksu- tai asiakirjojen lataussivulle pelkästään epäluotettavan vapaan tekstin seurantasisällön perusteella.
Valitse kanavat asiakkaan asetusten, kanavien käyttöoikeuksien, kiireellisyyden ja sovellettavien sääntöjen perusteella. Tarkista suostumus-, kieltäytymis- ja hiljaiset ajat niiden lainkäyttöalueiden ja viestikanavien osalta, joita käytät. Pidä toimituspalvelun ilmoitukset erillään markkinointikampanjoista sen sijaan, että olettaisit samojen lupien kattavan molemmat.
7. Määritä, mitä tapahtuu, kun seuranta hiljenee
Ennakoivan viestinnän tulee kattaa uuden tapahtuman lisäksi myös puuttuva eteneminen, mutta pelkkä hiljaisuus ei todista lähetyksen viivästyneen tai kadonneen.
Luo vanhentuneen seurannan sääntö palvelutason, reitin, viimeisimmän merkityksellisen tapahtuman ja mahdollisen tuetun toimitusarvion perusteella. Aseta kynnysarvot toimintatietojesi ja tukiprosessisi perusteella sen sijaan, että soveltaisit yhtä yleistä odotusaikaa kaikkiin lähetyksiin.
Kun sääntö käynnistyy, tarkista käsittelemättä jääneet tiedot, täsmäytä ne seurantatietolähteen kanssa tuen salliessa ja päätä, avataanko sisäinen tukitehtävä. Jos ilmoitat asiakkaalle, käytä tietojasi vastaavaa sanamuotoa: ”Emme ole vastaanottaneet uutta seurantapäivitystä” eroaa lauseesta ”Pakettisi on kadonnut”.
Nimeä vastuuhenkilö ratkaisemattomille poikkeamille. Ilmoitusjärjestelmä, joka ilmoittaa ongelmasta toistuvasti mutta ei tarjoa reittiä sen ratkaisemiseen, voi lisätä asiakkaiden turhautumista.
8. Testaa koko polku ennen automaattisten lähetysten käyttöönottoa
Suorita työnkulku ensin varjotilassa: vastaanota todellisia tai hyväksyttyjä testitapahtumia, luo ehdotettuja ilmoituksia ja tarkista tulokset ottamatta yhteyttä asiakkaisiin.
- Toista sama callback ja varmista, ettei se luo uutta viestiä.
- Käsittele vanhempi kuljetustapahtuma toimitetun tapahtuman jälkeen ja tarkista siitä seuraava tila.
- Testaa puuttuvat aikaleimat, tuntemattomat tilat ja virheelliset hyötykuormat.
- Simuloi tietokantavirhe ennen kuittausta ja työntekijävirhe tallennuksen jälkeen.
- Testaa viestien aikakatkaisut, mukaan lukien epävarma vastaus, jossa palvelu on saattanut jo hyväksyä viestin.
- Varmista, että osittaiset lähetykset tuottavat pakettikohtaisen sanamuodon.
- Tarkista markkinointikieltoihin ilmoittautuneet vastaanottajat, virheelliset yhteystiedot ja hiljaisten aikojen käsittely.
- Varmista, etteivät seurant लिंकit paljasta toisen asiakkaan tilaustietoja.
Seuraa hyväksyttyjä callback-kutsuja, käsittelyvirheitä, jonon ikää, ilmoitustehtäviä, duplikaattien estämistä ja viestien tuloksia. Mittaa käsittelyviive järjestelmäsi vastaanottoajasta erillään kuljetusyhtiön tapahtuman iästä. Tämä erottelu auttaa selvittämään, johtuiko hidas ilmoitus ylemmän tason datan saatavuudesta vai omasta putkestasi.
Aloita pienellä joukolla hyvin ymmärrettyjä virstanpylväitä. Laajenna sääntöjä vasta, kun tuki- ja operatiiviset tiimit ovat yhtä mieltä siitä, että viestit ovat tarkkoja, toimivia ja vastaanottamisen arvoisia.
Usein kysytyt kysymykset
Lähetysseuranta-API lähettääkö sähköposti- tai SMS-viestejä automaattisesti?
Ei välttämättä. Seurantatietojen käyttö ja asiakasviestintä ovat erillisiä ominaisuuksia. Tarkista palvelun dokumentoitu laajuus. Mukautetussa integraatiossa sovelluksesi voi käsitellä seurantapäivitykset ja lähettää ilmoitukset erillisen viestipalvelun kautta.
Pitäisikö asiakkaalle ilmoittaa jokaisesta seurantaskannauksesta?
Yleensä ei. Aseta etusijalle merkitykselliset virstanpylväät ja tapahtumat, jotka edellyttävät toimia. Useat terminaaliskannaukset voivat merkitä normaalia kuljetusta muuttamatta sitä, mitä asiakkaan tarvitsee tietää. Säilytä yksityiskohtainen historia seurantasivulla.
Voinko taata reaaliaikaiset toimitusilmoitukset?
Voit asettaa ja seurata käsittelytavoitetta sen jälkeen, kun järjestelmäsi vastaanottaa päivityksen. Et voi taata, milloin kuljetusyhtiö tallentaa tai julkaisee skannauksen. Kuvaa palvelu riippuvuuden huomioivilla termeillä.
Kuinka voin estää toimitusviestien duplikaatit?
Käytä pysyvää tapahtumien duplikaattien poistoa, erillistä ilmoitusidentiteettiä jokaiselle liiketoiminnan virstanpylväälle ja transaktionaalista tehtävien luontia. Jos viestipalvelusi tukee idempotenssia, käytä sitä lisäsuojana. Pelkkä muistissa tehtävä duplikaattitarkistus ei säily uudelleenkäynnistysten tai useiden työntekijöiden yli.
Mitä pitäisi tapahtua, jos kuljetusyhtiö korjaa toimitetuksi merkityn tilan?
Säilytä molemmat tapahtumat ja täsmäytä lähetyksen tila. Jos korjaus vaikuttaa olennaisesti asiakkaaseen, lähetä selkeä korjausviesti tai ohjaa asia tukipalveluun käytäntösi mukaisesti. Älä tee toimitetusta tilasta pysyvästi peruuttamatonta vain koodin yksinkertaistamiseksi.
Lähteet
Seuraavat viralliset resurssit ovat edellä käsitellyn 17TRACK-integraation toteutusviitteitä. Tämän oppaan sisäinen skeema, ilmoitussäännöt ja käsittelykulku ovat arkkitehtuurisuosituksia, eivät lainattuja API-sopimuksia.
- 17TRACK Tracking API — virallinen lähtökohta API-integraation arviointiin.
- 17TRACK API documentation — viite palveluntarjoajakohtaisille pyyntömuodoille, todennukselle, seurantatoiminnoille ja integraatiovaatimuksille.


