Kuinka yhdistää lähetysten seurantatiedot Oms-järjestelmään: tilausten yhdistäminen ja synkronointisäännöt
Yhdistä lähetysseurantatiedot tilaustenhallintajärjestelmään (OMS) yhdistämällä jokainen seurattu paketti sisäiseen lähetystietueeseen ja linkittämällä kyseinen lähetys sen tilaukseen ja toimitusriveihin. Vastaanota seurantapäivitykset palveluntarjoajan tukeman rajapinnan kautta, säilytä alkuperäiset tapahtumat ja sovella yksiselitteisiä sääntöjä kaksoiskappaleille, myöhästyneille päivityksille, lähetyksen tilalle ja tilauksen valmistumiselle. Älä käytä pelkkää seurantanumeroa tilauksen tunnisteena äläkä anna yhden toimitustapahtuman sulkea automaattisesti usean paketin tilausta.
Tämä opas on tarkoitettu integraatioinsinööreille ja verkkokauppojen operatiivisille tiimeille, jotka toteuttavat kyseisen yhteyden. Suositeltu suunnittelu erottaa kuljetusliikkeen havainnot liiketoimintapäätöksistä: seurantatiedot kuvaavat paketin matkaa, kun taas OMS päättää, mitä matka tarkoittaa toimituksen, asiakasviestinnän ja tilauksen sulkemisen kannalta.
Määritä, mikä järjestelmä omistaa kunkin tietueen
Ennen API-yhteyden rakentamista sopikaa omistajuudesta OMS-järjestelmän ylläpitäjän, toimitustiimin ja asiakaspalvelutiimin kanssa. Muuten teknisesti onnistunut integraatio voi silti korvata kelvollisia liiketoimintatietoja.
- OMS: Omistaa tilaukset, tilausrivit, vaaditut määrät, peruutukset ja tilauksen valmistumista koskevat säännöt.
- Toimitusjärjestelmä: Omistaa luomansa lähetys- tai pakettitietueet, mukaan lukien pakkausjaot ja tarramääritykset. Järjestelmä voi olla OMS itse tai erillinen varastojärjestelmä.
- Seurantapalveluntarjoaja: Toimittaa seurantahavainnot ja palveluntarjoajan määrittämät tilaluokitukset.
- Integraatiokerros: Omistaa tunnisteiden väliset viittaukset, tapahtumien käsittelyn, normalisoinnin, uudelleenyritysten hallinnan ja synkronoinnin auditointitietueet.
Käsittele näitä suositeltuina rajoina, älä oletuksina ohjelmistostasi. Dokumentoi poikkeukset. Jos varasto esimerkiksi voi vaihtaa toimitustarran, integraatio tarvitsee kyseiseltä järjestelmältä yksiselitteisen päivityksen sen sijaan, että se arvaisi uuden numeron korvaavan vanhan.
Rakenna tilauksen ja paketin välinen yhdistäminen ennen tilojen synkronointia
Käytännöllinen suhde on tilaus → toimitus → paketti → seurantamääritys. OMS-järjestelmäsi voi käyttää eri nimiä tai yhdistää joitakin näistä tietueista. Säilytä suhteet, vaikka tietokantarakenne olisi erilainen.
Tilauksella voi olla useita toimituksia, ja toimitus voi sisältää useita paketteja. Paketti voi myös saada korvaavan seurantamäärityksen tai siihen linkitetyn viimeisen kilometrin tunnisteen. Näiden tunnisteiden ei pidä luoda uusia tilattuja määriä.
| Tietue | Suositellut kentät | Tarkoitus |
|---|---|---|
| Tilaus | Vuokraajan tai myymälän tunnus, muuttumaton OMS-tilaustunnus | Erottaa kauppiaat toisistaan ja välttää riippuvuuden näkyvistä tilausnumeroista. |
| Toimitus | Toimituksen tunnus, tilaustunnus, kohdistettujen rivien tunnukset ja määrät | Tunnistaa, mitä ostettuja tuotteita toimitetaan. |
| Paketti | Sisäinen pakettitunnus, toimituksen tunnus, paketin kohdistukset silloin kun ne ovat saatavilla | Tarjoaa vakaan identiteetin, joka ei riipu seurantatarroista. |
| Seurantamääritys | Määrityksen tunnus, paketin tunnus, palveluntarjoajan tili, kuljetusliikkeen tunniste, seurantanumero, aktiivinen ajanjakso | Yhdistää saapuvat seurantahavainnot oikeaan pakettiin ja määrityksen elinkaareen. |
Yhdistä päivitykset tallennetun viitetaulukon avulla
Kun lähetys luodaan, tallenna sen sisäiset tunnisteet ennen sen rekisteröimistä seurantaan. Tallenna kaikki palveluntarjoajan myöntämät seurantatietueen tunnukset, jotka dokumentoitu rekisteröintiprosessi palauttaa. Jos palveluntarjoaja tukee kauppiasviitettä, käytä läpinäkymätöntä sisäistä viitettä ja säilytä yhdistäminen paikallisesti.
Ratkaise saapuvia päivityksiä varten ensin tallennettu palveluntarjoajan tietueen tunnus oikean palveluntarjoajan tilin ja vuokraajan sisällä. Jos tunniste ei ole käytettävissä, käytä dokumentoitua yhdistelmää, joka koostuu seurantanumerosta, kuljetusliikkeen identiteetistä, tilikontekstista ja määrityshistoriasta. Käsittele tätä hakustrategiana, ei takuuna siitä, että yhdistelmä olisi maailmanlaajuisesti yksilöllinen.
Älä yhdistä asiakkaan nimen, sähköpostiosoitteen tai rajaamattoman näkyvän tilausnumeron perusteella. Säilytä seurantanumerot merkkijonoina, jotta alkunollat säilyvät. Vältä merkkien poistamista tai kirjainkoon muuttamista, ellei kyseinen kuljetusliike tai palveluntarjoajasopimus salli tällaista normalisointia.
Jos haku ei palauta osumaa tai palauttaa useita mahdollisia osumia, siirrä päivitys tutkittavaksi. Ratkaisematon tapahtuma on turvallisempi kuin varma päivitys väärän asiakkaan tilaukseen.
Käsittele jaetut tilaukset luomatta keksittyjä pakettikohdistuksia
Oletetaan esimerkiksi tilaus, joka sisältää kolme yksikköä. Paketti A sisältää kaksi yksikköä ja paketti B yhden. Paketin A toimitus tarkoittaa, että kahdella yksiköllä on toimitustodiste; se ei tarkoita, että koko tilaus olisi toimitettu.
Jos toimitusjärjestelmä tallentaa vain sen, että molemmat paketit kuuluvat samaan toimitukseen, älä keksi yksikkötason kohdistuksia. Voit silti laskea, onko kaikki vaaditut paketit toimitettu, mutta tuotetason toimitusraportoinnin tulee pysyä poissa käytöstä tai nimenomaisesti epävarmana, kunnes kohdistustiedot ovat saatavilla.
Yhdistä seurant API kestävän tiedonkeruukerroksen kautta
Käytä putkea, joka pitää palveluntarjoajan viestinnän erillään OMS-kirjoituksista:
Lähetyksen luonti → seurannan rekisteröinti → saapuva päivitys tai ajastettu haku → pysyvä tapahtumien tallennus → yhdistäminen ja normalisointi → OMS-päivitys → täsmäytys
17TRACK-toteutuksessa Tracking API product page ja virallinen API-dokumentaatio ovat olennaisia lähtökohtia. Vahvista sovellettava rekisteröintirajapinta, kuljetusliikkeiden tunnisteet, päivitysten toimitusvaihtoehdot, todennusvaatimukset, tilamääritelmät ja tilirajoitukset ennen sovittimen toteuttamista. Tämän oppaan tietomalli on integraatiosuositus, ei väite siitä, että 17TRACK käyttäisi näitä kenttänimiä tai tarjoaisi natiiviliitintä OMS-järjestelmääsi.
Jos valitsemasi palveluntarjoaja tukee webhookeja, todenna saapuvat pyynnöt sen dokumentoidulla mekanismilla ja tallenna hyväksytyt viestit pysyvästi ennen niiden kuittaamista. Pidä hitaat OMS-toiminnot pyyntöpolun ulkopuolella. Noudata palveluntarjoajan todellista kuittaus- ja uudelleenyrityssopimusta sen sijaan, että olettaisit tietyn vastausrungon tai aikakatkaisun.
Jos kysely on tarpeen, tallenna haun eteneminen siellä, missä API tukee sitä, hallitse samanaikaisuutta ja noudata dokumentoituja nopeusrajoituksia. Webhookin vastaanotto tai onnistunut kyselypyyntö ei kumpikaan todista, että OMS päivitettiin; tallenna nämä tulokset erikseen.
Määritä uudelleenyritykset ja myöhäiset tapahtumat kestävät synkronointisäännöt
1. Tee käsittelystä idempotenttia
Saman havainnon käsittely kahdesti ei saa monistaa lähetystä, kasvattaa määriä kahdesti tai lähettää samaa asiakasilmoitusta uudelleen. HTTP ei tee mielivaltaisesta POST-toiminnosta idempotenttia; integraation on toteutettava kaksoiskappaleiden suojaus. RFC 9110 selittää HTTP-metodien idempotenssin.
Käytä vakaata palveluntarjoajan tapahtumatunnusta, kun sellainen on dokumentoitu ja saatavilla. Muussa tapauksessa määritä sormenjälki määrityksen tunnuksesta ja olennaisista tapahtumakentistä, kuten tapahtuman aikaleimasta, lähdetilasta ja sijainnista. Dokumentoi törmäysten tai muuttuneiden tapahtumakuvausten mahdollisuus. Säilytä raakahavainto myös silloin, kun se ei johda uuteen OMS-toimintoon.
Suojaa jokainen sivuvaikutus erikseen. Esimerkiksi OMS-tilan kirjoituksella ja sähköposti-ilmoituksella on oltava omat kaksoiskappaleiden estomekanisminsa. Käytä transaktionaalista outboxia tai vastaavaa pysyvää työ tietuetta, jotta prosessin kaatuminen ei jätä hyväksyttyä tapahtumaa ilman ajastettua päivitystä.
2. Tallenna tapahtuma-aika ja vastaanottoaika erikseen
Tapahtuman esiintymisaika ja aika, jolloin integraatiosi vastaanotti sen, vastaavat eri kysymyksiin. Tallenna molemmat alkuperäisen aikaleimaesityksen ja mahdollisen annetun aikavyöhykeoffsetin kanssa. Älä määritä hiljaisesti varaston aikavyöhykettä tapahtumalle, jonka aikavyöhyke on tuntematon.
Myöhään saapuvan matkalla olevan lähetyksen skannauksen pitäisi normaalisti täydentää historiaa korvaamatta uudempaa toimitettu-tilaa. Aikaleimat eivät kuitenkaan yksin riitä: palveluntarjoaja voi antaa korjauksen ja tapahtumista voi puuttua aikatietoja. Käytä saatavilla olevia dokumentoituja järjestys- tai revisiokenttiä sekä yksiselitteistä korjauskäytäntöä.
3. Normalisoi tilat poistamatta lähdetietoja
Luo pieni sisäinen sanasto, jonka OMS ymmärtää, kuten kuljetusliikkeen hyväksyntää odottava, kuljetuksessa, jakelussa, toimitettu, poikkeus ja palautumassa. Yhdistä palveluntarjoajan dokumentoidut tilat siihen. Nämä ovat ehdotettuja sisäisiä luokkia, eivät yleispäteviä kuljetusliikkeiden määritelmiä.
Tallenna alkuperäinen tilakoodi, kuvaus, tapahtuman sijainti, palveluntarjoajan tietueviite ja yhdistämissäännön versio. Yhdistämätön arvo tulee ohjata tarkistettavaan tilaan sen sijaan, että se oletusarvoisesti tulkittaisiin toimitetuksi tai epäonnistuneeksi. Tarran luomista ei pidä pitää todisteena kuljetusliikkeen fyysisestä vastaanotosta, ellei lähdetapahtuma nimenomaisesti tue tätä tulkintaa.
4. Käytä siirtymäsääntöjä, älä yksinkertaista numeerista järjestystä
Lähetyksen tilat eivät aina muodosta suoraa ketjua. Poikkeusta voi seurata normaali kuljetus, eikä toimitusyritys ole sama asia kuin toimitus. Palautus voi alkaa aiemman toimitustapahtuman jälkeen.
- Salli poikkeuksen poistuminen, kun myöhempi näyttö tukee liikkeen jatkumista.
- Estä tavallista historiallista skannausta korvaamasta toimitettua tilaa hiljaisesti.
- Salli dokumentoitu korjaus hallitun revisiopolun kautta.
- Seuraa palautusta erillään lähtevän toimituksen valmistumisesta, jos OMS tukee sitä.
- Ohjaa epäselvä tai ristiriitainen näyttö operatiiviseen jonoon.
Versioi nämä säännöt. Kun yhdistäminen muuttuu, päätä, koskeeko se vain uusia tapahtumia vai tarvitsevatko historiatietueet hallitun uudelleenlaskennan.
Laske tilauksen tila vaadittujen toimitusvelvoitteiden perusteella
Paketin tila ja tilauksen tila tulee tallentaa erillisiin kenttiin. Toimitetuksi merkitty paketti antaa näyttöä kyseisestä paketista; tilauksen valmistuminen riippuu jäljellä olevista vaadituista määristä ja liiketoimintakäytännöstäsi.
Hyödyllinen oletus on merkitä tilaus kokonaan toimitetuksi vasta, kun kaikilla toimitukseen vaadituilla määrillä on kelvollinen pakettitason toimitusnäyttö eikä vaadittuja kohdistuksia ole ratkaisematta. Poissulje peruutetut määrät OMS:n peruutussääntöjen mukaisesti. Käsittele digitaaliset tuotteet, noutotilaukset ja muut ei-lähetettävät velvoitteet omien valmistumisehtojensa mukaisesti.
Korvaavat lähetykset edellyttävät yksiselitteisiä suhteita. Jos kadonnut paketti korvataan, päätä, syrjäyttääkö korvaava lähetys alkuperäisen toimitusvelvoitteen. Muuten alkuperäinen paketti voi estää valmistumisen määräämättömästi tai molemmat paketit voivat kerryttää toimitusta. Tallenna päätös sen sijaan, että johtaisit sen pelkästään seurantatilasta.
Pidä toimituksen valmistuminen erillään taloudellisesta sulkemisesta, hyvityskelpoisuudesta ja riidanratkaisusta. Kuljetusliikkeen toimitustapahtuman ei pidä automaattisesti hyväksyä hyvitystä tai ratkaista asiakkaan vaatimusta.
Palauta toiminta virheistä menettämättä auditointijälkeä
Yritä tilapäisiä virheitä uudelleen rajatulla viiveellä ja dokumentoiduilla uudelleenyritysohjeilla. Erota tilapäiset yhteysvirheet virheellisistä tunnisteista, vanhentuneista tunnistetiedoista, käyttöoikeusvirheistä ja skeemayhteensopimattomuuksista. Jälkimmäiset edellyttävät korjaavia toimia, eivät loputtomia uudelleenyrityksiä.
Ylläpidä epäonnistuneiden töiden jonoa, joka sisältää kyseisen vuokraajan, paketin, tapahtumaviitteen, yritetyn toiminnon, virheluokituksen ja seuraavan toimenpiteen. Kirjaa riittävä konteksti tutkimista varten kopioimatta tarpeettomia asiakastietoja tai tunnistetietoja lokeihin.
Suorita täsmäytys normaalin päivityspolun lisäksi. Tarkista aktiiviset lähetykset, joiden seurantatiedot ovat vanhentuneita, hyväksytyt tapahtumat, joiden OMS-kirjoitukset epäonnistuivat, yhdistämättömät havainnot sekä integraation laskeman tilan ja OMS:n väliset erot. Valitse tarkistustiheys toimitussitoumusten, API-rajoitusten ja operatiivisen riskin perusteella sen sijaan, että käyttäisit kaikille sopivaa mielivaltaista aikataulua.
Määritä omistajuus: suunnittelu vastaa tiedonkeruun ja kirjoitusvirheiden käsittelystä; toimitustoiminnot ratkaisevat puuttuvat pakettisuhteet; asiakaspalvelu tarkistaa poikkeukset, jotka edellyttävät asiakasviestintää. Jono ilman vastuullista omistajaa on vain tallennuspaikka.
Testaa yhdistäminen ja liiketoimintasäännöt ennen käyttöönottoa
Käytä hallittuja testiaineistoja ja rajattua tuotantokäyttöönottoa. Testaa seuraavat tapaukset sekä tapahtumahistoriaa että tuloksena syntyvää OMS-tietuetta vasten:
- Yhden paketin tilaus etenee normaalisti toimitukseen.
- Jaetussa tilauksessa yksi paketti on toimitettu ja toinen edelleen kuljetuksessa.
- Sama tapahtuma vastaanotetaan toistuvasti ilman kaksoiskappaleiden sivuvaikutuksia.
- Vanhempi kuljetusskannaus saapuu toimituksen jälkeen.
- Tuntematon kuljetusliike tai tila siirtyy tarkistusjonoon.
- Tarrojen vaihto ei luo uutta toimitusvelvoitetta.
- Korvaava lähetys syrjäyttää alkuperäisen paketin hyväksytyn säännön mukaisesti.
- OMS ei ole käytettävissä sen jälkeen, kun tapahtuma on hyväksytty.
- Prosessi käynnistyy uudelleen OMS-kirjoituksen ja sen kuittauksen välillä.
- Sama näkyvä tilausnumero esiintyy kahdessa myymälässä ilman vuokraajien välistä yhdistämistä.
Ota käyttöön, kun jokaisella hyväksytyllä tapahtumalla on jäljitettävä käsittelytulos, epäselvät osumat eivät voi päivittää tilauksia automaattisesti ja operaattorit voivat toistaa epäonnistuneet työt turvallisesti. Nämä ovat hyödyllisempiä hyväksymiskriteerejä kuin pelkkä API-pyynnön onnistumisen osoittaminen.
UKK
Voinko yhdistää seurantanumerot suoraan tilauksiin?
Tarkasti yhden paketin työnkulussa suora suhde voi aluksi riittää. Käytä silti sisäistä lähetysidentiteettiä tilauksen ja seurantamäärityksen välillä. Se tarjoaa siirtymäpolun jaetuille lähetyksille, uudelleentarroitukselle ja korvauksille muuttamatta tilaustietueen merkitystä.
Pitäisikö integraation käyttää webhookeja vai kyselyä?
Käytä palveluntarjoajan tukemaa ja infrastruktuurisi kanssa yhteensopivaa toimitusmenetelmää. Webhookit voivat vähentää toistuvaa hakua, kun taas kysely voi tukea hakupohjaisia työnkulkuja ja täsmäytystä silloin, kun se on saatavilla. Kumpikaan menetelmä ei poista pysyvän tallennuksen, kaksoiskappaleiden käsittelyn ja palautumisen tarvetta.
Mitä pitäisi tapahtua, kun seurantatapahtumalla ei ole vastaavaa tilausta?
Tallenna se yhdistämättömien tapahtumien jonoon ja tutki rekisteröintitietue, vuokraajakonteksti, kuljetusliikkeen identiteetti ja lähetyksen luomisen ajankohta. Älä luo tilausta tai liitä tapahtumaa automaattisesti näennäisesti sopivaan asiakkaaseen. Toista tapahtuma, kun yhdistäminen on korjattu.
Pitäisikö toimitusilmoitusten tulla OMS:stä vai seurantajärjestelmästä?
Valitse yksi omistaja kullekin ilmoitustyypille ja laukaisimelle. Jos kaksi järjestelmää voi lähettää saman viestin, poista toinen polku käytöstä tai jakakaa pysyvä ilmoitusrekisteri. Päätä myös, koskeeko viesti yhtä pakettia vai koko tilausta, erityisesti jaetussa toimituksessa.
Tarkoittaako poikkeustila, että tilaus on epäonnistunut?
Ei. Poikkeus on tulkintaa vaativa havainto, ei välttämättä pysyvä lopputulos. Säilytä syy, seuraa myöhempiä tapahtumia ja päätä eskalointikäytäntösi avulla, milloin operatiivisten toimijoiden tulee puuttua asiaan.
Lähteet
- 17TRACK Tracking API — virallinen tuoteviite API-integraation lähtökohdaksi.
- 17TRACK API documentation — toteutusviite palveluntarjoajakohtaiseen sopimukseen; varmista sovellettavat rajapinnat ja tilivaatimukset ennen käyttöönottoa.
- RFC 9110, Section 9.2.2: Idempotent Methods — HTTP-semantiikka, joka tukee metodien idempotenssin ja sovellustason kaksoiskappaleiden suojauksen erottamista.


