Freight Tracking API: LTL- ja rahtitiedot, integrointivaiheet ja kattavuusrajoitukset

Rahtiseuranta-API yhdistää kuljetusliikkeiden, huolitsijoiden tai näkyvyyspalvelujen toimituspäivitykset logistiikkaohjelmistoosi. Osakuorma- (LTL) ja muiden rahtikuljetusten onnistunut integrointi riippuu muustakin kuin kuljetusliikkeen nimestä: sinun on vahvistettava hyväksytyt lähetys tunnisteet, tuetut palvelut, saatavilla olevat virstanpylväät, tilin käyttöoikeudet ja päivitysten toimitustavat. Aloita niistä rahtireiteistä ja operatiivisista päätöksistä, joita sinun on tuettava, ja testaa sitten, tarjoaako API käyttökelpoista dataa kyseisille lähetyksille.

Tämä opas on tarkoitettu kehittäjille, logistiikkapäälliköille ja integraatiovastaaville, jotka yhdistävät rahdin näkyvyystiedot kuljetustenhallintajärjestelmään (TMS), toiminnanohjausjärjestelmään (ERP), varastoalustaan tai asiakasportaaliin. Tavoitteena ei ole vain hakea tilaa. Tarkoituksena on antaa operatiivisille tiimeille riittävästi kontekstia viivästysten tunnistamiseen, vastaanoton koordinointiin ja poikkeamien ratkaisemiseen ilman, että puuttuvia tietoja pidetään vahvistettuna kuljetusongelmana.

Mitä rahtiseurantadata oikeastaan edustaa

Rahtiseuranta on yleensä raportoitujen lähetykseen liittyvien tapahtumien tallenne, ei jatkuva sijaintisyöte. Terminaaliin saapuminen, tulliselvitys, toimitusajanvaraus ja toimitustodiste kuvaavat erilaisia operatiivisia tosiasioita. Ne voivat olla peräisin eri organisaatioilta ja saapua erillisten järjestelmien kautta.

LTL-lähetykset jakavat perävaunun kapasiteetin muun rahdin kanssa ja voivat kulkea useiden terminaalien kautta. Muut rahtikuljetukset voivat sisältää lähtöpään kuljetusliikkeen, huolitsijan, meri- tai lentokuljetusliikkeen, tullimeklarin ja määränpään toimituspalvelun. Yhteys yhteen osapuoleen ei automaattisesti paljasta kaikkia kuljetusosuuksia.

Datakategoria	Mitä pyydetään	Mitä ei pidä olettaa
Lähetyksen identiteetti	Kuljetusliike, tunnisteen tyyppi, tunnisteen arvo ja tarvittaessa tilikonteksti	Jokainen viitenumero toimii seurantahaussa
Kuljetustapahtumat	Nouto-, terminaali-, lähtö-, saapumis- ja toimitustapahtumat, jos saatavilla	Jokainen fyysinen liike tuottaa tapahtuman
Toimituksen suunnittelu	Arvioitu saapuminen, ajanvaraustiedot ja muutokset	Arvioitu päivämäärä on vahvistettu vastaanottoaika
Poikkeamat	Alkuperäinen poikkeaman kuvaus, normalisoitu luokka ja tapahtuma-aika	Laaja poikkeamatila selittää syyn
Toimituksen todisteet	Toimitustapahtuma, toimituksen laajuus ja asiakirjojen saatavuus	Toimitettu-tila sisältää allekirjoitetun toimitustodisteen

PRO-numerot, konossementit ja konttinumerot eivät ole keskenään vaihtokelpoisia

LTL-seurannassa kuljetusliikkeen antama PRO-numero on yleinen lähetysviite. Konossementti (BOL) dokumentoi lähetyksen, mutta sama seurantapäätepiste ei välttämättä hyväksy sen numeroa. Ostotilausnumerot ja lähettäjän viitteet voivat edellyttää tilikohtaista hakukäyttöoikeutta tai erillistä hakutoimintoa.

Merirahti tuo mukaan konttinumerot, varausviitteet ja konossementit. Lentorahti tuo mukaan lentorahtikirjan viitteet. Huolitsijan oma viite voi tunnistaa lähetyksen huolitsijan järjestelmässä ilman, että sitä voi käyttää suoraan taustalla olevan kuljetusliikkeen kanssa. Tallenna tunnisteen tyyppi ja myöntäjäarvo tunnisteen rinnalle; älä sijoita kaikkia viitteitä erottelemattomaan seurantanumerokenttään.

Määritä kattavuus lähetyksen tasolla

Kuljetusliikehakemisto on lähtökohta, ei todiste siitä, että rahtiasi voidaan seurata. Käsittele kattavuutta kuljetusliikkeen, palvelun, maantieteen, tunnisteen, käyttöoikeuksien, lähetyksen elinkaaren ja vaadittujen kenttien yhdistelmänä. Palveluntarjoaja voi tukea kuljetusliikettä, vaikka tietty palvelu tai asiakirja jäisi integraation ulkopuolelle.

• Kuljetusliike ja palvelu: Vahvista todellinen LTL- tai rahtipalvelu sen sijaan, että luottaisit emoyhtiön nimeen tai pakettipalveluluetteloon.
• Maantiede ja osuus: Varmista lähtöpaikka, määränpää, rajat ylittävä kuljetus ja viimeinen toimitusosuus erikseen.
• Hakumenetelmä: Selvitä, hyväksyykö API tunnisteen, jonka toimitusprosessisi tosiasiassa tuottaa.
• Valtuutus: Selvitä, riittääkö julkinen seuranta vai tarvitaanko kuljetusliikkeen tilin tunnistetiedot ja asiakkaan valtuutus.
• Kenttien syvyys: Tarkista, tarjoaako integraatio perustilat, terminaalitiedot, arviot, ajanvaraustiedot tai asiakirjat.
• Historia ja ajantasaisuus: Kysy historiallisista tapahtumista, passiivisista lähetyksistä, päivityskäyttäytymisestä ja dokumentoiduista säilytysrajoista.

Pidä kaksi havaintoa erillään: API:n dokumentoidut ominaisuudet ja testilähetyksissä havaitut tulokset. Onnistunut haku ei todista yleistä kattavuutta. Epäonnistunut haku ei myöskään osoita, ettei palvelua tueta; väärä tunniste, puuttuva käyttöoikeus tai se, ettei lähetystä ole vielä kirjattu lähdejärjestelmään, voi selittää tuloksen.

17TRACKin rooli arvioinnissa

Monikuljetusliikeseurantaintegraatiota arvioivalle tiimille olennainen 17TRACK-tuote on sen Tracking API. Arvioi integraatiosopimus virallisen API-dokumentaation avulla ja vahvista nimetyt rahtikuljetusliikkeet, palvelutyypit, tunnistemallit ja vaaditut kentät ennen toteutukseen sitoutumista.

Älä päättele yleisestä seurant API:n kuvauksesta täydellistä LTL-, meri-, lento- tai huolintanäkyvyyttä. Pyydä vahvistus edustavien lähetysten avulla. Jos operatiiviseen vaatimukseen kuuluu ajanvarausten hallinta, lähettäminen, rahtiasiakirjat tai sijaintitelemetria, arvioi vaatimus erikseen äläkä oleta sen kuuluvan seurantaan.

Integraation vaiheet: lähetysviitteistä operatiivisiin hälytyksiin

1. Määritä lähetysmalli ja liiketoimintatulos

Päätä, mitä toimia datan on tuettava. Vastaanottotiimi tarvitsee toimitusajan ja ajanvarauskontekstin; asiakaspalvelu tarvitsee selkeän lähetyshistorian; poikkeamatiimi tarvitsee toiminnallista viivästystietoa. Nämä vaatimukset määrittävät, mitä sinun on kerättävä ja milloin hälytyksestä on hyötyä.

Luo API-palveluntarjoajasta riippumaton sisäinen lähetysrekisteri. Yhdistä se tarvittaessa tilauksiin, rahtiviitteisiin, kuljetusliikkeisiin, käsittely-yksiköihin ja kuljetusosuuksiin. Yksi tilaus voi kulkea useissa lähetyksissä, kun taas yksi rahtilähetys voi sisältää useita tilauksia. Älä oleta yhden tilauksen ja yhden seurantanumeron välistä suhdetta.

2. Vahvista käyttöoikeudet ja tunnisteiden käsittely

Hanki tarvittavat tunnistetiedot ja vahvista palveluntarjoajan todennusmenetelmä. Säilytä salaisuudet palvelinpuolen asetuksissa tai salaisuuksien hallintajärjestelmässä, älä selainkoodissa. Jos käyttöoikeus on tilikohtainen, yhdistä jokainen asiakas tai liiketoimintayksikkö oikeaan valtuutuskontekstiin.

Säilytä tunnistearvot merkkijonoina, jotta alkunollat eivät katoa. Käytä vain dokumentoituja muotoilusääntöjä. Käytä sisäistä hakutunnistetta, joka sisältää kuljetusliikkeen, tunnisteen tyypin, tunnisteen arvon ja olennaisen tilikontekstin. Tämä vähentää eri organisaatioiden myöntämien viitteiden tahattomia törmäyksiä.

3. Rekisteröi tai hae lähetykset dokumentoidun työnkulun avulla

Jotkin seurannan integraatiot edellyttävät lähetyksen rekisteröintiä ennen päivitysten saatavuutta; toiset tukevat suoria hakuja. Noudata valitun API:n dokumentoitua elinkaarta sen sijaan, että olettaisit tietyn päätepisteen, hyötykuorman tai vastausmuodon. Tallenna eräajoissa tulokset lähetyskohtaisesti, jotta osittain onnistunut pyyntö ei peitä hylättyjä tietueita.

Erota virheellinen syöte, käyttöoikeuden epääminen, tilapäinen lähdevirhe ja kelvollinen haku ilman tapahtumia. Jokainen vaatii erilaisen vastauksen. Virheellisen tunnisteen jatkuva toistaminen lisää liikennettä parantamatta näkyvyyttä.

4. Normalisoi tapahtumat hävittämättä niiden merkitystä

Rakenna logistiikanhallinnan työnkulkuasi varten yhteinen tapahtumamalli, mutta säilytä alkuperäinen lähteen tila ja kuvaus. Hyödyllisiä kenttiä ovat sisäinen lähetys-ID, kuljetusosuus, lähteen kuljetusliike, lähteen tapahtumatunniste, jos se annetaan, tapahtuma-aika, vastaanottoaika, sijainti, normalisoitu tila ja raaka kuvaus.

Tallenna tapahtuma-aika erillään käsittelyyn saapumisesta. Äskettäin vastaanotettu päivitys voi kuvata vanhempaa terminaalitapahtumaa. Säilytä aikavyöhykesiirtymät, kun ne annetaan, ja merkitse aikaleimat, joiden aikavyöhyke on tuntematon. Saapuminen määränpään terminaaliin ei saa muuttua lopulliseksi toimitukseksi vain siksi, että molemmat tapahtumat sisältävät sanan ”saapuminen”.

5. Toteuta luotettava päivitysten vastaanotto

Kun webhookit ovat saatavilla, validoi saapuvat pyynnöt palveluntarjoajan dokumentoidulla suojausmenetelmällä. Tallenna tai jonota hyväksytyt viestit pysyvästi ennen kuittausta ja käsittele jatkotoimet asynkronisesti. Suunnittele kaksoistoimitusten ja väärässä järjestyksessä saapuvien tapahtumien varalle, ellei integraatiosopimus nimenomaisesti takaa muuta.

Noudata kyselyissä dokumentoituja pyyntörajoja ja säädä aikataulu lähetyksen tilan ja operatiivisen kiireellisyyden mukaan. Käytä tilapäisissä virheissä hallittuja uudelleenyrityksiä viiveellä. Noudata palvelimen uudelleenyritysohjeita, kun ne annetaan. HTTP-uudelleenyritysten turvallisuus riippuu pyynnön semantiikasta, joten älä oleta, että jokainen epäonnistunut kirjoitus voidaan toistaa luomatta päällekkäistä työtä.

6. Yhdistä tilat toimiin, ei vain koontinäyttöihin

Määritä jokaiselle poikkeamalle vastuuhenkilö. Väliin jäänyt nouto voi kuulua kuljetusoperaatioille, ajanvarausristiriita vastaanottotiimille ja puuttuva seurantaviite lähetysjärjestelmän omistajalle. Sisällytä hälytykseen lähdetapahtuma ja lähetyskonteksti, jotta vastaanottaja voi toimia muodostamatta lähetyshistoriaa uudelleen.

Pidä sisäiset ja asiakasviestit erillään. Operatiivinen tiimi voi tarvita ratkaisemattoman lähdekoodin; asiakas tarvitsee selkokielisen kuvauksen, joka ei väitä datan tukemaa suurempaa varmuutta. Älä koskaan muuta puuttuvaa arviota luvatuksi toimituspäiväksi.

Kattavuusrajoitukset, jotka muuttavat operatiivisia päätöksiä

Tapahtuman puuttuminen ei välttämättä tarkoita liikkumattomuutta. Rahti voi liikkua raportoitujen virstanpylväiden välillä. Erota ”ei viimeaikaista päivitystä” ja ”kuljetusliikkeen raportoima viivästys”. Vanhentuneen datan hälytyksen pitäisi käynnistää selvitys, ei ilmoittaa asiakkaalle automaattisesti, että rahti on kadonnut tai viivästynyt.

Seurannan virstanpylväät eivät ole jatkuvaa GPS:ää. Jos työnkulkusi edellyttää ajoneuvon sijaintia, geoaidausta tai tiheitä sijaintipäivityksiä, pyydä nimenomainen vahvistus sijainnin lähteestä, päivityskäyttäytymisestä ja lähetyksen ja ajoneuvon yhdistämisestä. Aikaleimattu terminaalitapahtuma ei ole reaaliaikaista ajoneuvotelemetriaa.

Kuljetuksen valmistuminen voi koskea vain yhtä osuutta. Toimitus varastoon, terminaaliin tai yhdistämispisteeseen voi päättää yhden palveluntarjoajan vastuun samalla, kun asiakkaalle näkyvä matka jatkuu. Mallinna luovutukset eksplisiittisesti, jotta välivaiheen toimitustapahtuma ei sulje koko lähetystä ennenaikaisesti.

Asiakirjat ja kappaletason tulokset edellyttävät erillisiä tarkistuksia. Toimitustapahtuma ei välttämättä sisällä allekirjoitettua asiakirjaa, puutosmerkintää, vahinkotietuetta tai käsittely-yksiköiden erittelyä. Vahvista osatoimitusten työnkuluissa, mitä lähde raportoi, ja säilytä ratkaisemattomat määrät, kunnes operatiivinen tiimi täsmäyttää ne.

Käyttöoikeudet ja datastandardit ovat eri ongelmia. Standardit, kuten DCSA Track & Trace -standardit, tarjoavat viitteen konttikuljetusten tapahtumaterminologialle ja rajapinnoille. Ne eivät yksinään osoita, että tietty API tarjoaa pääsyn lähetykseesi tai tukee tarvitsemaasi kuljetusliikeyhteyttä.

Testaa kattavuus ja valvo datan laatua ennen laajentamista

Rakenna konseptitodistus todellisen rahtijakaumasi ympärille. Sisällytä normaalit toimitukset, aktiiviset kuljetuksessa olevat lähetykset, tarvittaessa rajat ylittävät kuljetukset, luovutukset, puuttuvat viitteet ja poikkeustapaukset. Valitse esimerkkejä toiminnallesi tärkeistä kuljetusliikkeistä ja palveluista sen sijaan, että käyttäisit vain helpoimpia onnistuneita hakuja.

• Haun oikeellisuus: Tunnistaako vastaus tarkoitetun lähetyksen eikä samankaltaista tai uudelleen käytettyä viitettä?
• Virstanpylväiden kattavuus: Mitkä operatiivisesti hyödylliset tapahtumat näkyvät ja mitkä edellyttävät toista lähdettä?
• Aikaleimojen laatu: Ovatko tapahtuma-aika, vastaanottoaika ja aikavyöhykkeen tulkinta yhdenmukaisia?
• Arvioiden käsittely: Pystyykö järjestelmä erottamaan arvion, muutoksen ja ajanvarauksen?
• Virhekäyttäytyminen: Tuottavatko virheellinen syöte, valtuutusvirheet ja tilapäiset käyttökatkot erotettavat tulokset?
• Palautuminen: Pystyykö integraatio täsmäyttämään väliin jääneet viestit tai palautumaan keskeytyksen jälkeen?

API-valvonnassa erota tekninen terveys lähetysnäkyvyydestä. Seuraa pyyntövirheitä, käsittelyviivettä, webhook-hylkäyksiä ja jonon kertymää sekä lähetyksiä, joilla ei ole ensimmäistä tapahtumaa, vanhentuneita historioita tai ratkaisemattomia tunnisteita. Onnistunut HTTP-vastaus voi silti sisältää hyödyttömästi lähetys tietoja.

Määritä jokaisen mittarin nimittäjä. ”Onnistunut haku” voi tarkoittaa hyväksyttyä pyyntöä, tunnistettua lähetystä tai lähetystä, jolla on käyttökelpoiset virstanpylväät; nämä ovat eri mittareita. Aseta hyväksymiskriteerit ennen pilottia ja dokumentoi tulokset kuljetusliikkeen, palvelun ja reitin mukaan. Laajenna vasta, kun yhteys tukee aiottuja operatiivisia päätöksiä ja kattamattomille tapauksille on nimetty varamenettely.

UKK

Voinko seurata LTL-rahtia pelkällä BOL-numerolla?

Joskus, mutta hyväksyntä riippuu kuljetusliikkeestä ja integraatiosta. Palvelu voi edellyttää PRO-numeroa, tilitunnuksia tai muuta viitettä. Vahvista hakumenetelmä ennen kuin rakennat työnkulun, joka perustuu vain BOL-seurantaan.

Korvaako rahtiseuranta-API TMS:n?

Ei yksinään. Seuranta tarjoaa näkyvyysdataa. Kuljetusten suunnittelu, tarjouspyynnöt, hinnoittelu, ajanvarausten hallinta ja tilitys ovat erillisiä toimintoja, jotka voivat jäädä TMS:ään tai muihin operatiivisiin järjestelmiin.

Miksi kuljetusliikkeen verkkosivusto näyttää päivityksen ennen järjestelmääni?

Mahdollisia syitä ovat lähteen synkronointi, API:n päivitysajankohta, webhook-toimitus tai oman järjestelmäsi käsittelyjono. Vertaa lähdetapahtuman aikaa vastaanotto- ja käsittelyaikoihin aukon paikantamiseksi. Älä oleta, että kuljetusliikkeen verkkosivusto ja API käyttävät samoja päivitysreittejä.

Voiko yksi API seurata kansainvälistä rahtilähetystä alusta loppuun?

Se voi olla mahdollista, jos tarvittavat osallistujat ja lähetysviitteet ovat yhteydessä toisiinsa. Vahvista lähtöpään nouto, pääkuljetus, tulliin liittyvät virstanpylväät ja määränpään toimitus erikseen. Pääkuljetusosuuden kattava yhteys ei automaattisesti sisällä muita osuuksia.

Mitä pitäisi tapahtua, kun seurantadata vanhenee?

Sovella palvelulle ja lähetysvaiheelle sopivaa kynnysarvoa ja luo sitten datan laadun tai operatiivisen tarkastelun tehtävä. Näytä viimeisin tunnettu tapahtuma ja sen aika. Eskaloi tarvittaessa kuljetusliikkeelle tai huolitsijalle esittämättä puuttuvia päivityksiä vahvistettuna viivästyksenä.

Lähteet

• 17TRACK Tracking API — virallinen lähtöpiste seurantatarjonnan arviointiin.
• 17TRACK API documentation — viite toteutussopimuksen ja integraatiovaatimusten tarkistamiseen.
• DCSA Track & Trace standards — konttikuljetusten seurantastandardit ja tapahtumamallin konteksti.
• RFC 9110: HTTP Semantics — HTTP-metodien semantiikka, idempotenssi ja uudelleenyrityksiin liittyvät protokollanäkökohdat.