Krovinių siuntų sekimo API: LTL ir krovinių duomenys, integravimo etapai bei aprėpties apribojimai

Krovinių sekimo API perduoda vežėjų, ekspeditorių ar matomumo paslaugų teikėjų siuntų atnaujinimus į jūsų logistikos programinę įrangą. Dalinių krovinių (LTL) ir kitų krovinių pervežimų atveju sėkminga integracija priklauso ne tik nuo vežėjo pavadinimo: turite patikrinti priimamus siuntų identifikatorius, palaikomas paslaugas, galimus etapus, paskyros teises ir atnaujinimų pristatymo būdus. Pradėkite nuo krovinių maršrutų ir veiklos sprendimų, kuriuos turite palaikyti, tada patikrinkite, ar API pateikia tinkamus duomenis apie šias siuntas.

Šis vadovas skirtas kūrėjams, logistikos vadovams ir už integraciją atsakingiems asmenims, kurie krovinių matomumą jungia su transporto valdymo sistema (TMS), įmonės išteklių planavimo sistema (ERP), sandėlio platforma ar klientų portalu. Tikslas nėra vien gauti būseną. Siekiama suteikti veiklos komandoms pakankamai konteksto, kad jos galėtų atpažinti vėlavimus, koordinuoti priėmimą ir spręsti išimtis, nelaikydamos trūkstamų duomenų patvirtinta siuntimo problema.

Ką iš tikrųjų reiškia krovinių sekimo duomenys

Krovinių sekimas paprastai yra praneštų siuntos įvykių įrašas, o ne nuolatinis vietos duomenų srautas. Atvykimas į terminalą, muitinės išleidimas, pristatymo susitikimas ir pristatymo patvirtinimas apibūdina skirtingus veiklos faktus. Jie gali būti gauti iš skirtingų organizacijų ir per atskiras sistemas.

LTL siuntos dalijasi priekabos talpa su kitais kroviniais ir gali būti vežamos per kelis terminalus. Kiti krovinių pervežimai gali apimti siuntėjo vietos vežėją, ekspeditorių, jūrų ar oro vežėją, muitinės tarpininką ir paskirties vietos pristatymo paslaugų teikėją. API ryšys su vienu dalyviu automatiškai neatskleidžia visų etapų.

Duomenų kategorija	Ko prašyti	Ko nereikėtų manyti
Siuntos tapatybė	Vežėjas, identifikatoriaus tipas, identifikatoriaus reikšmė ir, jei reikia, paskyros kontekstas	Kiekvienas nuorodos numeris tinka sekimo paieškai
Judėjimo įvykiai	Paėmimo, terminalo veiklos, išvykimo, atvykimo ir pristatymo įvykiai, jei jie prieinami	Kiekvienas fizinis judėjimas sukuria įvykį
Pristatymo planavimas	Numatomas atvykimas, susitikimo informacija ir pakeitimai	Numatyta data yra patvirtintas priėmimo susitikimas
Išimtys	Pradinis išimties aprašymas, normalizuota kategorija ir įvykio laikas	Bendra išimties būsena paaiškina priežastį
Pristatymo įrodymai	Pristatymo įvykis, pristatymo apimtis ir dokumentų prieinamumas	Pristatymo būsena apima pasirašytą pristatymo patvirtinimo dokumentą

PRO numeriai, važtaraščiai ir konteinerių numeriai nėra tarpusavyje keičiami

LTL sekime vežėjo priskirtas PRO numeris yra įprasta siuntos nuoroda. Važtaraštis (BOL) dokumentuoja siuntą, tačiau jo numeris nebūtinai priimamas tame pačiame sekimo taške. Pirkimo užsakymo numeriams ir siuntėjo nuorodoms gali reikėti konkrečiai paskyrai pritaikytos paieškos prieigos arba atskiros paieškos funkcijos.

Jūrų transportas apima konteinerių numerius, rezervacijos nuorodas ir važtaraščius. Oro transportas apima oro važtaraščio nuorodas. Ekspeditoriaus vidinė nuoroda gali identifikuoti siuntą ekspeditoriaus sistemoje, tačiau nebūti tiesiogiai naudojama su faktiniu vežėju. Kartu su reikšme saugokite identifikatoriaus tipą ir jį išdavusią šalį; nedėkite kiekvienos nuorodos į vieną neatskirtą sekimo numerio lauką.

Apibrėžkite aprėptį siuntos lygiu

Vežėjų katalogas yra pradinis taškas, o ne įrodymas, kad jūsų krovinį galima sekti. Aprėptį vertinkite kaip vežėjo, paslaugos, geografijos, identifikatoriaus, prieigos teisių, siuntos gyvavimo ciklo ir privalomų laukų derinį. Teikėjas gali palaikyti vežėją, tačiau konkreti paslauga ar dokumentas gali nepatekti į integracijos apimtį.

• Vežėjas ir paslauga: patvirtinkite konkrečią LTL ar krovinių paslaugą, o ne remkitės patronuojančiosios įmonės pavadinimu ar siuntų paslaugų sąrašu.
• Geografija ir etapas: atskirai patikrinkite kilmės vietą, paskirties vietą, tarpvalstybinį pervežimą ir galutinio pristatymo etapą.
• Paieškos būdas: nustatykite, ar API priima identifikatorių, kurį iš tikrųjų sukuria jūsų siuntimo procesas.
• Autorizacija: nustatykite, ar pakanka viešo sekimo, ar reikia vežėjo paskyros prisijungimo duomenų ir kliento autorizacijos.
• Laukų išsamumas: patikrinkite, ar integracija pateikia pagrindines būsenas, terminalo informaciją, prognozes, susitikimų informaciją ar dokumentus.
• Istorija ir naujumas: pasiteiraukite apie istorinius įvykius, neaktyvias siuntas, atnaujinimo elgseną ir dokumentais pagrįstus saugojimo apribojimus.

Atskirkite du dalykus: API dokumentuotas galimybes ir bandymo siuntose pastebėtus rezultatus. Sėkminga paieška neįrodo visuotinės aprėpties. Nesėkminga paieška taip pat neįrodo, kad paslauga nepalaikoma; rezultatą gali paaiškinti neteisingas identifikatorius, trūkstama teisė arba tai, kad siunta dar neįvesta į šaltinio sistemą.

17TRACK vieta vertinime

Komandai, vertinančiai kelių vežėjų sekimo integraciją, tinkamas 17TRACK produktas yra jo Tracking API. Naudokite official API documentation, kad įvertintumėte integracijos sutartį, ir prieš įsipareigodami įgyvendinti sprendimą patvirtinkite konkrečius krovinių vežėjus, paslaugų tipus, identifikatorių formatus ir privalomus laukus.

Nedarykite išvados apie visišką LTL, jūrų, oro ar krovinių ekspedijavimo matomumą remdamiesi bendru sekimo API aprašu. Prašykite patvirtinimo naudodami tipines siuntas. Jei veiklos reikalavimas apima susitikimų planavimą, dispečerizavimą, krovinių dokumentus ar vietos telemetriją, vertinkite šį reikalavimą atskirai, nemanydami, kad jis yra sekimo dalis.

Integracijos etapai: nuo siuntų nuorodų iki veiklos įspėjimų

1. Nustatykite siuntos modelį ir verslo rezultatą

Nuspręskite, kokius veiksmus turi palaikyti duomenys. Priėmimo komandai reikia pristatymo laiko ir susitikimo konteksto; klientų aptarnavimui reikia aiškios siuntos istorijos; išimčių komandai reikia praktiškai panaudojamos informacijos apie vėlavimą. Šie reikalavimai nulemia, ką turite rinkti ir kada įspėjimas yra naudingas.

Sukurkite vidinį siuntos įrašą, nepriklausomą nuo API teikėjo. Susiekite jį su užsakymais, krovinių nuorodomis, vežėjais, krovos vienetais ir transportavimo etapais, kai tai svarbu. Vienas užsakymas gali būti gabenamas keliomis siuntomis, o vienoje krovinių siuntoje gali būti keli užsakymai. Nemanykite, kad vienas užsakymas visada atitinka vieną sekimo numerį.

2. Patikrinkite prieigą ir identifikatorių tvarkymą

Gaukite reikalingus prisijungimo duomenis ir patvirtinkite teikėjo autentifikavimo būdą. Paslaptis laikykite serverio konfigūracijoje arba paslapčių tvarkyklėje, o ne naršyklės kode. Jei prieiga priklauso nuo paskyros, susiekite kiekvieną klientą ar padalinį su tinkamu autorizacijos kontekstu.

Identifikatorių reikšmes saugokite kaip eilutes, kad nebūtų prarasti pradiniai nuliai. Taikykite tik dokumentuotas formatavimo taisykles. Naudokite vidinį paieškos raktą, apimantį vežėją, identifikatoriaus tipą, identifikatoriaus reikšmę ir atitinkamą paskyros kontekstą. Tai mažina atsitiktinių sutapimų tarp skirtingų organizacijų išduotų nuorodų riziką.

3. Registruokite arba ieškokite siuntų pagal dokumentuotą procesą

Kai kurios sekimo integracijos reikalauja užregistruoti siuntą prieš tampant prieinamiems atnaujinimams; kitos palaiko tiesiogines užklausas. Laikykitės pasirinktos API dokumentuoto gyvavimo ciklo ir nemanykite, kad konkretus galinis taškas, duomenų paketas ar atsakymo formatas yra savaime suprantami. Pateikdami paketus fiksuokite kiekvienos siuntos rezultatą, kad iš dalies sėkminga užklausa nepaslėptų atmestų įrašų.

Atskirkite netinkamą įvestį, prieigos atsisakymą, laikiną šaltinio gedimą ir galiojančią paiešką, kurioje nėra įvykių. Kiekvienai situacijai reikia kitokio atsako. Neribotas netinkamo identifikatoriaus kartojimas tik didina srautą, bet nepagerina matomumo.

4. Normalizuokite įvykius neprarasdami jų prasmės

Sukurkite bendrą įvykių modelį savo logistikos valdymo procesui, tačiau išsaugokite pradinę šaltinio būseną ir aprašą. Naudingi laukai: vidinis siuntos ID, transportavimo etapas, šaltinio vežėjas, jei pateikiamas, šaltinio įvykio identifikatorius, įvykio laikas, gavimo laikas, vieta, normalizuota būsena ir neapdorotas aprašas.

Įvykio laiką saugokite atskirai nuo įvedimo laiko. Neseniai gautas atnaujinimas gali apibūdinti senesnį terminalo įvykį. Jei pateikiamos laiko juostos poslinkio reikšmės, jas išsaugokite, o laiko žymas, kurių laiko juosta nežinoma, pažymėkite. Atvykimas į paskirties terminalą neturėtų tapti galutiniu pristatymu vien todėl, kad abiejuose įvykiuose yra žodis „atvykimas“.

5. Įdiekite patikimą atnaujinimų priėmimą

Jei prieinami webhook, patikrinkite gaunamas užklausas naudodami teikėjo dokumentuotą saugumo mechanizmą. Prieš patvirtindami priimtas žinutes patikimai jas išsaugokite arba įdėkite į eilę, o tolesnį apdorojimą vykdykite asinchroniškai. Numatyti pasikartojantį pristatymą ir įvykius ne eilės tvarka, nebent integracijos sutartis aiškiai garantuoja kitaip.

Naudodami apklausą laikykitės dokumentuotų užklausų limitų ir pritaikykite grafiką prie siuntos būsenos bei veiklos skubumo. Laikinų gedimų atveju naudokite kontroliuojamus pakartojimus su didėjančiais intervalais. Jei pateikiamos serverio pakartojimo instrukcijos, jų laikykitės. HTTP pakartojimo saugumas priklauso nuo užklausos semantikos, todėl nemanykite, kad kiekvieną nesėkmingą įrašymo veiksmą galima kartoti nesukuriant pasikartojančio darbo.

6. Susiekite būsenas su veiksmais, ne tik su skydeliais

Nustatykite, kas atsakingas už kiekvieną išimtį. Neįvykęs paėmimas gali priklausyti transporto operacijoms, neatitikimas dėl susitikimo – priėmimo komandai, o trūkstama sekimo nuoroda – siuntimo sistemos savininkui. Įspėjime pateikite šaltinio įvykį ir siuntos kontekstą, kad gavėjas galėtų imtis veiksmų neatkurdamas visos siuntos istorijos.

Atskirkite vidinius ir klientams skirtus pranešimus. Operacijoms gali reikėti neišspręsto šaltinio kodo, o klientui reikia paprasto aprašymo, kuris neteiktų daugiau tikrumo, nei leidžia duomenys. Niekada nepaverskite trūkstamos prognozės pažadėta pristatymo data.

Aprėpties ribos, keičiančios veiklos sprendimus

Nesamas įvykis nebūtinai reiškia, kad nėra judėjimo. Krovinys gali judėti tarp praneštų etapų. Atskirkite „nėra naujausio atnaujinimo“ nuo „vežėjas pranešė apie vėlavimą“. Įspėjimas apie pasenusius duomenis turėtų paskatinti tyrimą, o ne automatiškai informuoti klientą, kad krovinys prarastas ar vėluoja.

Sekimo etapai nėra nuolatinis GPS. Jei jūsų procesui reikia transporto priemonės vietos, geografinio aptvėrimo ar dažnų vietos atnaujinimų, aiškiai patvirtinkite vietos šaltinį, atnaujinimo elgseną ir siuntos susiejimą su transporto priemone. Laiko žyma pažymėtas terminalo įvykis nėra tiesioginė transporto priemonės telemetrija.

Transportavimo užbaigimas gali būti taikomas tik vienam etapui. Pristatymas į sandėlį, terminalą ar konsolidavimo punktą gali užbaigti vieno teikėjo atsakomybę, kol klientui matoma kelionė tęsiasi. Aiškiai modeliuokite perdavimus, kad tarpinis pristatymo įvykis per anksti neuždarytų visos siuntos.

Dokumentus ir vienetų lygio rezultatus reikia tikrinti atskirai. Pristatymo įvykyje gali nebūti pasirašyto dokumento, trūkumo žymos, žalos įrašo ar krovos vienetų išskaidymo. Jei procesas apima dalinį pristatymą, patvirtinkite, ką praneša šaltinis, ir išsaugokite neišspręstus kiekius, kol operacijos juos suderins.

Prieiga ir duomenų standartai yra skirtingos problemos. Tokie standartai kaip DCSA Track & Trace standards pateikia konteinerių laivybos įvykių terminijos ir sąsajų nuorodas. Jie savaime nenustato, kad konkreti API suteikia prieigą prie jūsų siuntos ar palaiko reikiamą vežėjo ryšį.

Prieš plečiant išbandykite aprėptį ir stebėkite duomenų kokybę

Sukurkite koncepcijos patikrą pagal faktinį jūsų krovinių derinį. Įtraukite įprastus pristatymus, aktyvias gabenamas siuntas, kai aktualu – tarpvalstybinius pervežimus, perdavimus, trūkstamas nuorodas ir išimtinius atvejus. Rinkitės pavyzdžius iš jūsų veiklai svarbių vežėjų ir paslaugų, o ne tik lengviausiai sėkmingai randamas siuntas.

• Paieškos teisingumas: ar atsakymas identifikuoja numatytą siuntą, o ne panašią ar pakartotinai panaudotą nuorodą?
• Etapų išsamumas: kurie veiklai naudingi įvykiai rodomi, o kuriems reikia kito šaltinio?
• Laiko žymų kokybė: ar įvykio laikas, gavimo laikas ir laiko juostos interpretacija yra nuoseklūs?
• Prognozių tvarkymas: ar sistema gali atskirti prognozę, jos pakeitimą ir susitikimą?
• Gedimų elgsena: ar netinkama įvestis, autorizacijos gedimai ir laikini sutrikimai sukuria atskiriamus rezultatus?
• Atkūrimas: ar integracija gali suderinti praleistas žinutes arba atsikurti po pertrūkio?

Stebėdami API, atskirkite techninę būklę nuo siuntų matomumo. Kartu su siuntomis, neturinčiomis pirmojo įvykio, pasenusiomis istorijomis ar neišspręstais identifikatoriais, stebėkite užklausų gedimus, apdorojimo delsą, atmestus webhook ir eilės atsilikimą. Sėkmingas HTTP atsakymas vis tiek gali nepateikti naudingos informacijos apie siuntą.

Apibrėžkite kiekvieno rodiklio vardiklį. „Sėkminga paieška“ gali reikšti priimtą užklausą, atpažintą siuntą arba siuntą su tinkamais etapais; tai skirtingi matavimai. Prieš bandomąjį etapą nustatykite priėmimo kriterijus ir dokumentuokite rezultatus pagal vežėją, paslaugą ir maršrutą. Plėskite tik tada, kai ryšys palaiko numatytus veiklos sprendimus ir yra įvardytas atsarginis būdas neaprėptiems atvejams.

DUK

Ar galiu sekti LTL krovinį naudodamas tik BOL numerį?

Kartais, tačiau priimtinumas priklauso nuo vežėjo ir integracijos. Paslaugai gali reikėti PRO numerio, paskyros prisijungimo duomenų ar kitos nuorodos. Prieš kurdami tik BOL pagrįstą procesą patvirtinkite paieškos būdą.

Ar krovinių sekimo API pakeičia TMS?

Ne pati savaime. Sekimas suteikia matomumo duomenis. Transportavimo planavimas, pasiūlymų teikimas, tarifų nustatymas, susitikimų valdymas ir atsiskaitymas yra atskiros funkcijos, kurios gali likti jūsų TMS ar kitose veiklos sistemose.

Kodėl vežėjo svetainėje atnaujinimas rodomas anksčiau nei mano sistemoje?

Galimos priežastys: šaltinio sinchronizavimas, API atnaujinimo laikas, webhook pristatymas arba jūsų pačių apdorojimo eilė. Palyginkite šaltinio įvykio laiką su gavimo ir apdorojimo laikais, kad nustatytumėte spragą. Nemanykite, kad vežėjo svetainė ir API naudoja identiškus atnaujinimo kelius.

Ar viena API gali sekti tarptautinę krovinių siuntą nuo pradžios iki pabaigos?

Gali, jei prijungti reikalingi dalyviai ir siuntų nuorodos. Atskirai patikrinkite paėmimą kilmės vietoje, pagrindinį vežimą, su muitine susijusius etapus ir pristatymą paskirties vietoje. Ryšys, apimantis pagrindinį transportavimo etapą, automatiškai neapima kitų etapų.

Kas turėtų įvykti, kai sekimo duomenys pasensta?

Nustatykite paslaugai ir siuntos etapui tinkamą ribą, tada sukurkite duomenų kokybės arba veiklos peržiūros užduotį. Rodykite paskutinį žinomą įvykį ir jo laiką. Jei reikia, kreipkitės į vežėją ar ekspeditorių, tačiau nepateikite trūkstamų atnaujinimų kaip patvirtinto vėlavimo.

Šaltiniai

• 17TRACK Tracking API — oficialus atspirties taškas vertinant sekimo API pasiūlymą.
• 17TRACK API documentation — nuoroda, skirta įgyvendinimo sutarčiai ir integracijos reikalavimams tikrinti.
• DCSA Track & Trace standards — konteinerių laivybos sekimo standartai ir įvykių modelio kontekstas.
• RFC 9110: HTTP Semantics — HTTP metodų semantika, idempotentiškumas ir su pakartojimais susiję protokolo aspektai.