Kuinka integroida lähetysseuranta-API verkkokauppaasi

Jos haluat integroida lähetysseuranta-API:n verkkokauppaasi, yhdistä tilausjärjestelmäsi seurantapalveluntarjoajaan, lähetä lähetys- ja kuljetustiedot suojatulla palvelinpuolen pyynnöllä, tallenna normalisoidut seurantatapahtumat ja näytä tuloksena oleva tila asiakas- ja tukikäyttöliittymissä. Luotettava toteutus on enemmän kuin seurantatunnuskentän lisääminen: sen on käsiteltävä kuljetusliikkeen valinta, tilapäivitykset, toimituspoikkeukset, uudelleenyritykset, tietosuoja ja tapa, jolla asiakkaat tosiasiassa käyttävät oston jälkeisiä tietoja.

Tässä oppaassa selitetään käytännöllinen integraatiotapa verkkokauppojen omistajille, kehittäjille ja operatiivisille tiimeille. Siinä käytetään viitteenä 17TRACKin virallista Tracking API -dokumentaatiota, mutta samat suunnitteluperiaatteet pätevät myös arvioitaessa toista usean kuljetusliikkeen palveluntarjoajaa.

Päätä, mitä integraation on saavutettava

Aloita liiketoimintatuloksesta API-päätepisteen sijaan. Useimmat kaupat haluavat vähentää yhteydenottoja aiheesta ”Missä tilaukseni on?”, tarjota ostajille selkeän toimitusnäkymän ja auttaa operatiivista tiimiä tunnistamaan viivästyneet lähetykset ennen asiakkaan valitusta. Nämä tavoitteet edellyttävät erilaisia tietoja ja työnkulkuja.

• Asiakasnäkyvyys: näytä lähetyksen ajantasainen tila, arvioidut toimitustiedot niiden ollessa saatavilla, kuljetusliikkeen tiedot ja viimeisin merkityksellinen tapahtuma.
• Operatiivinen näkyvyys: anna henkilöstölle mahdollisuus löytää viivästyneet, pysähtyneet, palautetut tai poikkeustilassa olevat lähetykset eri kuljetusliikkeiltä.
• Automaattinen viestintä: käynnistä hyväksytyt sähköposti-, SMS- tai muut ilmoitukset, kun lähetys saavuttaa määritetyn tilan.
• Tietojen yhdenmukaisuus: muunna eri kuljetusliikkeiden tapahtumamerkinnät pienemmäksi joukoksi tiloja, joita kauppasi voi käyttää luotettavasti.

Määritä nämä tulokset ennen toteutustavan valitsemista. Seuranta-API voi tarjota lähetystietoja, mutta se ei automaattisesti päätä, mitkä tapahtumat ansaitsevat asiakasilmoituksen tai miten kauppasi tulisi käsitellä osoiteongelmaa.

Valitse oikea integraatioarkkitehtuuri

Tyypillisessä arkkitehtuurissa on neljä kerrosta: kaupankäyntialusta, integraatiopalvelu, seurantapalveluntarjoaja ja asiakaspuolen käyttökokemus. Integraatiopalvelu voi olla taustasovellus, tilaustenhallintajärjestelmä tai palvelimeton työnkulku. Tämän logiikan pitäminen palvelimella on yleensä turvallisempaa kuin API-tunnistetietojen sijoittaminen selaimen koodiin.

Peruskulku näyttää tältä:

1. Maksettu tilaus toimitetaan, ja sille annetaan seurantatunnus sekä kuljetusliike.
2. Taustajärjestelmäsi lähettää lähetystiedot seurantapalveluntarjoajalle.
3. Palveluntarjoaja palauttaa seurannan tunnisteen tai seurantatiedot API-suunnittelunsa mukaisesti.
4. Järjestelmäsi tallentaa palveluntarjoajan viitteen ja yhdistää lähetystapahtumat sisäisiin tiloihin.
5. Ajastettu päivitysprosessi tai tuettu tapahtumailmoitus päivittää lähetyksen.
6. Verkkokauppasi, tilaussivusi, tukityökalusi ja ilmoituspalvelusi lukevat omista normalisoiduista tiedoistasi.

Älä tee jokaisesta sivun katselusta kuljetusliikkeen tai seuranta-API:n kutsua. Tällainen suunnittelu voi aiheuttaa hitaita asiakaskokemuksia, päällekkäisiä pyyntöjä, nopeusrajoitusongelmia ja epäjohdonmukaisia tuloksia. Tallenna viimeisin hyväksytty seurantatila tietokantaasi ja päivitä sitä hallituilla taustatöillä tai palveluntarjoajan tukemalla päivitysmekanismilla.

Vahvista palveluntarjoajan dokumentaatio ennen koodaamista

Ennen toteutusta tutustu palveluntarjoajan viralliseen API-dokumentaatioon, joka koskee todennusta, pyyntömuotoja, vastauskenttiä, tuettuja kuljetusliikkeitä, virheenkäsittelyä, päivitysmekanismeja ja tilivaatimuksia. 17TRACK tarjoaa erillisen Tracking API -tuotesivun ja kehittäjädokumentaation. Käytä näitä sivuja nykyisen API-käyttäytymisen auktoriteettina sen sijaan, että luottaisit foorumeilta tai vanhoista integraatio-oppaista kopioituihin esimerkkeihin.

Laadi dokumentaation perusteella lyhyt vaatimuslista:

• Miten API-tunnistetiedot myönnetään, tallennetaan, vaihdetaan ja peruutetaan?
• Vaatiiko pyyntö kuljetusliikekoodin, vai voiko palvelu tunnistaa kuljetusliikkeen seurantatunnuksesta?
• Mitkä vastauskentät yksilöivät lähetyksen, tilan, sijainnin, aikaleimat ja poikkeusviestin?
• Miten asynkroniset päivitykset toimitetaan, jos tili tukee niitä?
• Mitkä ovat dokumentoidut pyyntörajoitukset, laskutussäännöt, aikakatkaisuodotukset ja virhekoodit?
• Miten päällekkäiset seurantatunnukset, virheelliset tunnukset, tuntemattomat kuljetusliikkeet ja toimitetut lähetykset käsitellään?

Älä päättele ominaisuutta tuotteen nimestä. Esimerkiksi ”reaaliaikainen” voi kuvata tuotteen asemointia eikä taata, että jokainen kuljetusliikkeen tapahtuma näkyy välittömästi. Toteutuksesi tulee selittää, että kuljetusliikkeen skannaukset voivat viivästyä ja että API ei voi luoda skannausta, josta kuljetusliike ei ole ilmoittanut.

Valmistele tilaus- ja lähetystiedot

Seuranta kannattaa yleensä luoda toimituksen täyttämisen yhteydessä, ei tilauksen luomisen yhteydessä. Tilaus voi olla maksettu mutta vielä pakkaamatta, ja seurantatunnus voidaan luoda ennen kuin kuljetusliike on vastaanottanut paketin. Päätä, minkä toimitustyönkulun tapahtuman tulee luoda seurantatietue.

Sisäisen lähetystietueesi tulee vähintään erottaa seuraavat arvot:

• Sisäinen tilaus-ID ja toimituksen ID
• Seurantatunnus
• Kuljetusliikkeen nimi tai kuljetusliikekoodi
• Kohdemaa tai -alue, jos se on operatiivisesti tarpeen
• Palveluntarjoajan seuranta-ID tai tilausviite, jos se palautetaan
• Nykyinen normalisoitu tila
• Viimeisimmän tapahtuman aikaleima ja viimeisimmän synkronoinnin aikaleima
• Palveluntarjoajan raaka vastaus tai hallittu tarkastusviite

Pidä tilaustiedot ja lähetystiedot erillään. Yksi tilaus voi sisältää useita paketteja, osatoimituksia tai eri kuljetusliikkeitä. Oletus yhdestä tilauksesta ja yhdestä seurantatunnuksesta epäonnistuu usein, kun varasto lähettää tuotteet erikseen.

Käytä idempotenttia prosessia. Jos toimitusjärjestelmä yrittää samaa pyyntöä uudelleen, integraation tulee päivittää olemassa olevaa lähetystä sen sijaan, että se loisi päällekkäisiä tilauksia tai asiakasviestejä. Käytännöllinen idempotenssiavain voi yhdistää sisäisen toimituksen ID:n, kuljetusliikkeen tunnisteen ja seurantatunnuksen palveluntarjoajan omien vaatimusten mukaisesti.

Normalisoi kuljetusliikkeiden tilat asiakkaille

Kuljetusliikkeet käyttävät erilaisia merkintöjä ja tapahtumajärjestyksiä. Kauppasi tulee ylläpitää pientä sisäistä tilamallia, kuten Tiedot vastaanotettu, Matkalla, Jakelussa, Toimitettu, Poikkeus ja Palautettu. Säilytä alkuperäinen kuljetusliikkeen tapahtuma tukihenkilöstölle, mutta käytä normalisoitua tilaa verkkokaupan logiikassa.

Normalisointisääntöjen tulee olla yksiselitteisiä. ”Tarra luotu” -tapahtumaa ei tule esittää todisteena paketin liikkumisesta. ”Toimitettu” tulee käsitellä kuljetusliikkeen ilmoittamana tapahtumana, ei takuuna siitä, että asiakas on fyysisesti löytänyt paketin. Poikkeusta ei tule muuttaa hiljaisesti tilaksi ”matkalla” vain siksi, että lähetys saattaa jatkaa myöhemmin.

Määritä myös tilojen ensisijaisuus ja taantumien käsittely. Viivästynyt kuljetusliikkeen syöte voi saapua väärässä järjestyksessä. Vertaa tapahtumien aikaleimoja niiden ollessa saatavilla, tallenna raakatapahtuma ja vältä uudemman toimitetun tilan korvaamista vanhemmalla matkalla-tilalla. Jos aikaleimat puuttuvat tai ovat epäselviä, merkitse tietue varovaista päivitystä varten sen sijaan, että keksisit tapahtumajärjestyksen.

Rakenna palvelinpuolen pyyntövirta

Taustajärjestelmäsi tulee tarkistaa saapuvat toimitustiedot ennen seurantapalveluntarjoajan kutsumista. Tarkista, että seurantatunnus on mukana, poista tahattomat välilyönnit, tarkista odotettu muoto tarvittaessa ja varmista, että kuljetusliikkeen arvo on hyväksyttävä. Älä hylkää epätavallisia mutta kelvollisia seurantatunnuksia vain siksi, etteivät ne vastaa suppeaa paikallista kaavaa.

Palveluntarjoajasta riippumaton pyyntövirta voidaan esittää näin:

receive fulfillment event
validate order and shipment fields
check for an existing idempotency key
send the documented tracking request from the server
store the provider response and internal shipment record
queue a refresh or process the supported update event
publish only approved fields to the storefront

Käytä lyhyitä aikakatkaisuja, rajattuja uudelleenyrityksiä ja eksponentiaalista perääntymistä tilapäisille virheille. Älä yritä uudelleen jokaista virhettä. Todennusvirhe, virheellinen pyyntö tai tukematon kuljetusliike edellyttää yleensä korjausta toistuvien kutsujen sijaan. Kirjaa korrelaatio-ID, pyynnön tulos ja palveluntarjoajan virheluokka, mutta vältä API-avainten, asiakkaiden täydellisten osoitteiden tai tarpeettomien henkilötietojen kirjoittamista sovelluslokeihin.

Pidä palveluntarjoajan vastaus erillään asiakaspuolen mallista. Näin palveluntarjoajan vaihtaminen, yhdistämissäännön korjaaminen ja julkisen tilaussivun kautta paljastettavien tietojen rajoittaminen on helpompaa.

Suunnittele asiakkaan seurantakokemus

Seurantasivun tulee vastata nopeasti kolmeen kysymykseen: mikä on nykyinen tila, mitä tapahtui viimeksi ja mitä asiakkaan tulee tehdä seuraavaksi? Näytä tilausviite, lähetysnumero tietosuojan huomioivassa muodossa, kuljetusliikkeen nimi, viimeisimmän tapahtuman aika ja selkeä selitys poikkeuksille.

Älä näytä tyhjää aikajanaa teknisenä virheenä. Ennen ensimmäistä kuljetusliikkeen skannausta kerro, että toimitustiedot on vastaanotettu eikä liike välttämättä vielä näy. Poikkeuksesta tulee antaa selkokielinen selitys vain, kun lähdetiedot tukevat sitä. Jos kuljetusliike ilmoittaa osoiteongelmasta, linkitä tukiprosessiin tai asiakaspalvelutoimintoon, jonka yrityksesi voi todella tarjota.

Jos kauppasi toimii Shopifyn tai muun kaupankäyntialustan päällä, tarkista, miten alusta tarjoaa toimitustapahtumat, asiakastilit, tilausten tilasivut ja ilmoitusmallit. Shopifyn virallinen kehittäjädokumentaatio sisältää resursseja webhookeille ja toimitustiedoille. Alustojen API:t ja versioitu dokumentaatio voivat muuttua, joten varmista sovelluksesi käyttämä versio ennen tuotantotyötä.

Käytä ilmoituksia harkiten

Lähetystapahtumat ovat hyödyllisiä laukaisimia, mutta viestin lähettäminen jokaisesta kuljetusliikkeen skannauksesta voi aiheuttaa ilmoitusväsymystä. Määritä liiketoimintasäännöt esimerkiksi ilmoittamaan lähetyksen luonnista, merkittävästä etenemisestä matkalla, jakelusta, toimituksesta ja valituista poikkeuksista. Estä päällekkäiset ilmoitukset ja lisää vähimmäisväli toistuville viivästysviesteille.

Erota operatiiviset hälytykset asiakasilmoituksista. Tukitiimin on ehkä tiedettävä, ettei lähetys ole muuttunut useaan päivään, kun taas asiakas tarvitsee viestin vasta, kun kuljetusliike ilmoittaa konkreettisesta poikkeuksesta. Aikarajan tulee perustua palvelutasoon, määränpäähän, kuljetusliikkeeseen ja toimitustapaan eikä yleiseen lukuun, jolla ei ole operatiivista perustaa.

Testaa todellisilla toimitustilanteilla

Yhden seurantatunnuksen onnistunut vastaus ei riitä tuotantokäynnistykseen. Luo testimatriisi, joka sisältää useita kuljetusliikkeitä, maita, lähetystyyppejä ja tapahtumatiloja. Testaa vähintään:

• Äskettäin luotu lähetys ilman kuljetusliikkeen skannausta
• Normaalisti matkalla oleva lähetys
• Jakelussa oleva lähetys
• Toimitettu lähetys
• Poikkeus tai osoitteeseen liittyvä tapahtuma
• Palautettu lähetys
• Virheellinen seurantatunnus
• Päällekkäinen toimitustapahtuma
• Viivästynyt palveluntarjoajan vastaus tai aikakatkaisu
• Väärässä järjestyksessä saapuva tapahtuma

Mittaa muutakin kuin API:n saatavuutta. Tarkista, päivittyykö oikea tilaus, näkeekö asiakas ymmärrettävää kieltä, estetäänkö päällekkäiset ilmoitukset ja pystyykö tukihenkilöstö tunnistamaan alkuperäisen kuljetusliikkeen tapahtuman. Ota ensin käyttöön rajattu julkaisu, säilytä operatiivinen vararatkaisu ja seuraa virheluokkia julkaisun jälkeen.

Tietoturva, tietosuoja ja ylläpito

Tallenna tunnistetiedot salaisuuksienhallintajärjestelmään tai suojattuun ympäristömuuttujaan, älä teemakoodiin, mobiilikoodiin, lähdekoodinhallintaan tai selainpyyntöihin. Rajoita pääsyä lähetystietoihin roolien perusteella, käytä HTTPS:ää ja tarkista, kuinka kauan raakoja vastauksia ja asiakkaisiin liittyviä kenttiä säilytetään.

Tarkista palveluntarjoajan dokumentaatio ja kaupankäyntialustasi API-versio säännöllisesti. Kuljetusliikkeiden tuki, tapahtumien nimet, todennusvaatimukset ja alustan webhook-käyttäytyminen voivat muuttua. Pidä tilojen yhdistämissäännöt määritettävinä, dokumentoi niiden taustalla olevat oletukset ja mahdollista lähetyksen toistaminen tai täsmäyttäminen ilman uuden asiakasviestin lähettämistä.

17TRACKin API on varteenotettava vaihtoehto arvioitavaksi, kun kauppasi tarvitsee eri kuljetusliikkeiden kattavan erillisen seuranta-integraation. Sopiva valinta riippuu silti käyttämistäsi kuljetusliikkeistä, palvelemistasi maista, tilillesi dokumentoidusta päivityskäyttäytymisestä, odotetusta pyyntömäärästä ja tiimisi tarvitsemista operatiivisista hallintakeinoista. Vahvista nämä kohdat virallisesta dokumentaatiosta ja hallitussa konseptitodistuksessa ennen tuotantosuunnitteluun sitoutumista.

Usein kysytyt kysymykset

Tulisiko seuranta luoda, kun tilaus tehdään?

Yleensä ei. Luo tai aktivoi lähetystietue, kun toimitustyönkulullasi on kuljetusliike ja seurantatunnus. Sen luominen kassalla voi tuottaa tietueita tilauksille, jotka myöhemmin perutaan, jäävät toimittamatta tai jaetaan osiin.

Voiko seuranta-API taata reaaliaikaiset toimitustiedot?

Yksikään API ei voi taata, että jokainen kuljetusliikkeen skannaus näkyy välittömästi. Palveluntarjoaja riippuu kuljetusliikkeen tiedoista, ja kuljetusliikkeiden järjestelmät voivat ilmoittaa tapahtumista viiveellä tai puutteellisesti. Esitä aikaleimat ja tilatiedot täsmällisesti äläkä lupaa tarkkaa päivitysaikaa, elleivät asiaankuuluva dokumentaatio ja palvelusopimus tue lupausta.

Tulisiko selaimen kutsua seuranta-API:a suoraan?

Useimmissa toteutuksissa ei. Käytä palvelinpuolen integraatiota, jotta tunnistetiedot pysyvät suojattuina, vastaukset voidaan normalisoida, uudelleenyrityksiä voidaan hallita ja asiakaspuolen tietoja voidaan suodattaa. Verkkokaupan tulisi yleensä lukea sovelluksesi hyväksyttyä lähetysnäkymää.

Miten kaupan tulisi käsitellä yhden tilauksen useita paketteja?

Mallinna jokainen toimitus tai paketti erillisenä lähetyksenä ja säilytä samalla ylätason tilaus-ID. Tilaussivulla voidaan näyttää kokonaisyhteenveto ja erilliset aikajanat kullekin paketille. Näin viivästynyt paketti ei jää toisen paketin toimitetun tilan taakse.

Mitä tuotantomittaria tulisi seurata ensimmäisenä?

Seuraa koko virtaa toimituksen luonnista oikeaan asiakkaalle näkyvään päivitykseen. Pelkkä API:n onnistuminen ei riitä. Seuraa päällekkäisiä tietueita, vanhentuneita lähetyksiä, yhdistämättömiä tapahtumia, ilmoitusvirheitä ja niiden lähetysten osuutta, jotka vaativat manuaalista korjausta.

Lähteet

• 17TRACK Tracking API
• 17TRACK API Documentation
• Shopify Webhooks Documentation
• Shopify Fulfillment Object Documentation