API-ja e gjurmimit të ngarkesave: të dhënat Ltl dhe të ngarkesave, hapat e integrimit dhe kufijtë e mbulimit

Një API për gjurmimin e mallrave lidh përditësimet e dërgesave nga transportuesit, agjentët e spedicionit ose ofruesit e vizibilitetit me softuerin tuaj të logjistikës. Për dërgesat më të vogla se një kamion i plotë (LTL) dhe lëvizje të tjera mallrash, integrimi i suksesshëm varet nga më shumë se emri i transportuesit: duhet të verifikoni identifikuesit e pranuar të dërgesave, shërbimet e mbështetura, etapat e disponueshme, lejet e llogarisë dhe metodat e përditësimit të dorëzimit. Filloni me linjat e transportit dhe vendimet operacionale që duhet të mbështesni, pastaj testoni nëse API-ja ofron të dhëna të përdorshme për ato dërgesa.

Ky udhëzues është për zhvilluesit, menaxherët e logjistikës dhe përgjegjësit e integrimit që lidhin vizibilitetin e mallrave me një sistem të menaxhimit të transportit (TMS), sistem të planifikimit të burimeve të ndërmarrjes (ERP), platformë magazine ose portal klientësh. Qëllimi nuk është thjesht marrja e një statusi. Qëllimi është t'u japë ekipeve të operacioneve kontekst të mjaftueshëm për të njohur vonesat, për të koordinuar pranimin dhe për të zgjidhur përjashtimet, pa e trajtuar mungesën e të dhënave si një problem të konfirmuar të transportit.

Çfarë përfaqësojnë në të vërtetë të dhënat e gjurmimit të mallrave

Gjurmimi i mallrave është zakonisht një regjistër i ngjarjeve të raportuara të dërgesës, jo një transmetim i vazhdueshëm i vendndodhjes. Mbërritja në terminal, lirimi doganor, takimi i dorëzimit dhe dëshmia e dorëzimit përshkruajnë fakte të ndryshme operacionale. Ato mund të vijnë nga organizata të ndryshme dhe të mbërrijnë përmes sistemeve të veçanta.

Dërgesat LTL ndajnë kapacitetin e rimorkios me mallra të tjera dhe mund të kalojnë nëpër disa terminale. Lëvizjet e tjera të mallrave mund të përfshijnë transportuesin e origjinës, agjentin e spedicionit, transportuesin detar ose ajror, agjentin doganor dhe ofruesin e dorëzimit në destinacion. Një lidhje API me një pjesëmarrës nuk ekspozon automatikisht çdo segment.

Kategoria e të dhënave	Çfarë të kërkoni	Çfarë të mos supozoni
Identiteti i dërgesës	Transportuesin, llojin e identifikuesit, vlerën e identifikuesit dhe kontekstin e llogarisë kur kërkohet	Çdo numër reference funksionon si kërkim gjurmimi
Ngjarjet e lëvizjes	Marrjen, aktivitetin në terminal, nisjen, mbërritjen dhe ngjarjet e dorëzimit kur janë të disponueshme	Çdo lëvizje fizike prodhon një ngjarje
Planifikimi i dorëzimit	Mbërritjen e parashikuar, informacionin për takimin dhe rishikimet	Një datë e parashikuar është një takim i konfirmuar pranimi
Përjashtimet	Përshkrimin origjinal të përjashtimit, kategorinë e normalizuar dhe kohën e ngjarjes	Një status i përgjithshëm i përjashtimit shpjegon shkakun
Dëshmia e dorëzimit	Ngjarjen e dorëzimit, fushën e dorëzimit dhe disponueshmërinë e dokumenteve	Një status i dorëzuar përfshin një dokument të nënshkruar të dëshmisë së dorëzimit

Numrat PRO, fletëngarkesat dhe numrat e kontejnerëve nuk janë të këmbyeshëm

Për gjurmimin LTL, një numër PRO i caktuar nga transportuesi është një referencë e zakonshme e dërgesës. Fletëngarkesa (BOL) dokumenton dërgesën, por numri i saj nuk pranohet domosdoshmërisht nga i njëjti endpoint gjurmimi. Numrat e porosive të blerjes dhe referencat e dërguesit mund të kërkojnë qasje kërkimi specifike për llogarinë ose një funksion të veçantë kërkimi.

Transporti detar sjell numrat e kontejnerëve, referencat e rezervimit dhe fletëngarkesat. Transporti ajror sjell referenca të fletëngarkesave ajrore. Referenca e brendshme e një agjenti spedicioneri mund të identifikojë një dërgesë brenda sistemit të tij pa qenë drejtpërdrejt e përdorshme me transportuesin bazë. Ruani llojin e identifikuesit dhe palën lëshuese së bashku me vlerën; mos i vendosni të gjitha referencat në një fushë të padiferencuar të numrit të gjurmimit.

Përcaktoni mbulimin në nivelin e dërgesës

Një direktori transportuesish është pikënisje, jo provë se mallrat tuaja mund të gjurmohen. Trajtojeni mbulimin si kombinim të transportuesit, shërbimit, gjeografisë, identifikuesit, të drejtave të qasjes, ciklit jetësor të dërgesës dhe fushave të kërkuara. Një ofrues mund të mbështesë një transportues, ndërsa një shërbim ose dokument i caktuar mund të mbetet jashtë fushës së integrimit.

• Transportuesi dhe shërbimi: Konfirmoni shërbimin aktual LTL ose të mallrave, në vend që të mbështeteni te emri i kompanisë mëmë ose te listimi i shërbimit të parcelave.
• Gjeografia dhe segmenti: Verifikoni veçmas origjinën, destinacionin, lëvizjen ndërkufitare dhe segmentin përfundimtar të dorëzimit.
• Metoda e kërkimit: Përcaktoni nëse API-ja pranon identifikuesin që prodhon realisht rrjedha juaj e transportit.
• Autorizimi: Përcaktoni nëse gjurmimi publik është i mjaftueshëm apo kërkohen kredenciale të llogarisë së transportuesit dhe autorizimi i klientit.
• Thellësia e fushave: Kontrolloni nëse integrimi ofron statuse bazë, detaje terminali, vlerësime, informacion takimesh ose dokumente.
• Historiku dhe freskia: Pyesni për ngjarjet historike, dërgesat joaktive, sjelljen e rifreskimit dhe çdo kufizim të dokumentuar të ruajtjes.

Mbani të ndara dy gjetje: aftësitë e dokumentuara të API-së dhe rezultatet e vërejtura në dërgesat tuaja të testimit. Një kërkim i suksesshëm nuk provon mbulim universal. Një kërkim i pasuksesshëm gjithashtu nuk vërteton se një shërbim nuk mbështetet; një identifikues i pasaktë, leje që mungojnë ose një dërgesë që ende nuk është futur në sistemin burimor mund ta shpjegojnë rezultatin.

Roli i 17TRACK në vlerësim

Për një ekip që vlerëson një integrim gjurmimi me shumë transportues, produkti përkatës i 17TRACK është Tracking API. Përdorni dokumentacionin zyrtar të API-së për të vlerësuar kontratën e integrimit dhe konfirmoni transportuesit tuaj të emërtuar të mallrave, llojet e shërbimeve, formatet e identifikuesve dhe fushat e kërkuara përpara se të angazhoheni në zbatim.

Mos nxirrni përfundimin për vizibilitet të plotë LTL, detar, ajror ose të spedicionit të mallrave nga një përshkrim i përgjithshëm i API-së së gjurmimit. Kërkoni konfirmim duke përdorur dërgesa përfaqësuese. Nëse një kërkesë operacionale përfshin planifikimin e takimeve, dispeçerimin, dokumentet e mallrave ose telemetrinë e vendndodhjes, vlerësojeni atë veçmas në vend që të supozoni se është pjesë e gjurmimit.

Hapat e integrimit: nga referencat e dërgesës te sinjalizimet operacionale

1. Përcaktoni modelin e dërgesës dhe rezultatin e biznesit

Vendosni se cilat veprime duhet të mbështesin të dhënat. Ekipi i pranimit ka nevojë për kohën e dorëzimit dhe kontekstin e takimit; shërbimi ndaj klientit ka nevojë për një historik të qartë të dërgesës; një ekip përjashtimesh ka nevojë për informacion të zbatueshëm mbi vonesat. Këto kërkesa përcaktojnë çfarë duhet të mblidhni dhe kur një sinjalizim është i dobishëm.

Krijoni një regjistër të brendshëm të dërgesës, të pavarur nga ofruesi i API-së. Lidheni atë me porositë, referencat e mallrave, transportuesit, njësitë e trajtimit dhe segmentet e transportit kur është e përshtatshme. Një porosi mund të lëvizë në disa dërgesa, ndërsa një dërgesë mallrash mund të përmbajë disa porosi. Shmangni supozimin për një marrëdhënie një-porosi-me-një-numër-gjurmimi.

2. Vërtetoni qasjen dhe trajtimin e identifikuesve

Merrni kredencialet e kërkuara dhe konfirmoni metodën e autentikimit të ofruesit. Mbajini sekretet në konfigurimin e serverit ose në një menaxher sekretesh, jo në kodin e shfletuesit. Nëse qasja është specifike për llogarinë, lidhni çdo klient ose njësi biznesi me kontekstin e saktë të autorizimit.

Ruajini vlerat e identifikuesve si vargje që të mos humbasin zerot në fillim. Zbatoni vetëm rregullat e dokumentuara të formatimit. Përdorni një çelës të brendshëm kërkimi që përfshin transportuesin, llojin e identifikuesit, vlerën e identifikuesit dhe kontekstin përkatës të llogarisë. Kjo redukton përplasjet aksidentale midis referencave të lëshuara nga organizata të ndryshme.

3. Regjistroni ose kërkoni dërgesat duke përdorur rrjedhën e dokumentuar

Disa integrime gjurmimi kërkojnë regjistrimin e dërgesës përpara se të bëhen të disponueshme përditësimet; të tjera mbështesin kërkime të drejtpërdrejta. Ndiqni ciklin jetësor të dokumentuar të API-së së zgjedhur, në vend që të supozoni një endpoint, payload ose format përgjigjeje të caktuar. Kapni rezultatet për çdo dërgesë gjatë dërgimit të grupeve, në mënyrë që një kërkesë pjesërisht e suksesshme të mos fshehë regjistrimet e refuzuara.

Ndani hyrjen e pavlefshme, refuzimin e qasjes, dështimin e përkohshëm të burimit dhe një kërkim të vlefshëm pa ngjarje. Secila kërkon përgjigje të ndryshme. Përsëritja e pafundme e një identifikuesi të formatuar gabim krijon trafik pa përmirësuar vizibilitetin.

4. Normalizoni ngjarjet pa humbur kuptimin e tyre

Ndërtoni një model të përbashkët ngjarjesh për rrjedhën tuaj të menaxhimit të logjistikës, por ruani statusin dhe përshkrimin origjinal të burimit. Fushat e dobishme përfshijnë ID-në e brendshme të dërgesës, segmentin e transportit, transportuesin burimor, identifikuesin e ngjarjes burimore kur ofrohet, kohën e ngjarjes, kohën e pranimit, vendndodhjen, statusin e normalizuar dhe përshkrimin e papërpunuar.

Ruajeni kohën e ngjarjes veçmas nga koha e futjes. Një përditësim i marrë së fundmi mund të përshkruajë një ngjarje më të vjetër terminali. Ruani zhvendosjet e zonës kohore kur ofrohen dhe identifikoni vulat kohore, zona kohore e të cilave është e panjohur. Mbërritja në një terminal destinacioni nuk duhet të shndërrohet në dorëzim përfundimtar vetëm sepse të dyja ngjarjet përmbajnë fjalën “mbërritje”.

5. Zbatoni marrje të besueshme të përditësimeve

Kur webhooks janë të disponueshme, vërtetoni kërkesat hyrëse duke përdorur mekanizmin e sigurisë të dokumentuar nga ofruesi. Ruani në mënyrë të qëndrueshme ose vendosni në radhë mesazhet e pranuara përpara se t'i konfirmoni dhe përpunoni punët pasuese në mënyrë asinkrone. Dizenjoni sistemin për dërgesa të dyfishta dhe ngjarje jashtë rendit, përveçse kur kontrata e integrimit garanton shprehimisht të kundërtën.

Për polling, ndiqni kufijtë e dokumentuar të kërkesave dhe përshtatni orarin sipas gjendjes së dërgesës dhe urgjencës operacionale. Përdorni riprovime të kontrolluara me rritje graduale të intervalit për dështimet kalimtare. Respektoni udhëzimet e serverit për riprovim kur ofrohen. Siguria e riprovimit HTTP varet nga semantika e kërkesës, ndaj mos supozoni se çdo shkrim i dështuar mund të përsëritet pa krijuar punë të dyfishtë.

6. Lidhini statuset me veprimet, jo vetëm me panelet

Përcaktoni se kush është përgjegjës për çdo përjashtim. Një marrje e humbur mund t'i përkasë operacioneve të transportit, një mospërputhje takimi ekipit të pranimit dhe një referencë e munguar e gjurmimit pronarit të sistemit të transportit. Përfshini në sinjalizim ngjarjen burimore dhe kontekstin e dërgesës, në mënyrë që marrësi të mund të veprojë pa rindërtuar historikun e dërgesës.

Mbani të ndara mesazhet e brendshme dhe ato për klientët. Operacionet mund të kenë nevojë për një kod burimor të pazgjidhur; klienti ka nevojë për një përshkrim në gjuhë të thjeshtë që nuk pretendon më shumë siguri sesa mbështesin të dhënat. Mos e shndërroni kurrë një vlerësim që mungon në një datë të premtuar dorëzimi.

Kufijtë e mbulimit që ndryshojnë vendimet operacionale

Mungesa e një ngjarjeje nuk do të thotë domosdoshmërisht mungesë lëvizjeje. Mallrat mund të lëvizin midis etapave të raportuara. Dalloni “asnjë përditësim të fundit” nga “vonesë e raportuar nga transportuesi”. Një sinjalizim për të dhëna të vjetruara duhet të nxisë hetim, jo t'i tregojë automatikisht klientit se mallrat kanë humbur ose janë vonuar.

Etapat e gjurmimit nuk janë GPS i vazhdueshëm. Nëse rrjedha juaj kërkon pozicionin e automjetit, gjeofencing ose përditësime të shpeshta të vendndodhjes, kërkoni konfirmim të qartë për burimin e vendndodhjes, sjelljen e rifreskimit dhe lidhjen midis dërgesës dhe automjetit. Një ngjarje terminali me vulë kohore nuk është telemetri e drejtpërdrejtë e automjetit.

Përfundimi i transportit mund të vlejë vetëm për një segment. Dorëzimi në një magazinë, terminal ose pikë konsolidimi mund të përfundojë përgjegjësinë e një ofruesi, ndërsa udhëtimi i dërgesës drejt klientit vazhdon. Modeloni shprehimisht kalimet, në mënyrë që një ngjarje e ndërmjetme dorëzimi të mos mbyllë para kohe të gjithë dërgesën.

Dokumentet dhe rezultatet në nivel copëzash kërkojnë kontrolle të veçanta. Një ngjarje dorëzimi mund të mos përfshijë dokument të nënshkruar, shënim mungese, regjistrim dëmtimi ose ndarje të njësive të trajtimit. Për rrjedhat e dorëzimit të pjesshëm, konfirmoni çfarë raporton burimi dhe ruani sasitë e pazgjidhura derisa operacionet t'i rakordojnë.

Qasja dhe standardet e të dhënave janë probleme të ndryshme. Standardet si standardet DCSA Track & Trace ofrojnë një referencë për terminologjinë dhe ndërfaqet e ngjarjeve të transportit me kontejnerë. Ato nuk përcaktojnë vetë se një API e caktuar ofron qasje në dërgesën tuaj ose mbështet lidhjen e kërkuar me transportuesin.

Testoni mbulimin dhe monitoroni cilësinë e të dhënave përpara zgjerimit

Ndërtoni një provë koncepti rreth përzierjes suaj reale të mallrave. Përfshini dorëzime normale, dërgesa aktive në transit, lëvizje ndërkufitare kur është e përshtatshme, kalime, referenca që mungojnë dhe raste përjashtimesh. Zgjidhni shembuj nga transportuesit dhe shërbimet që kanë rëndësi për operacionin tuaj, në vend që të përdorni vetëm kërkimet më të lehta dhe të suksesshme.

• Saktësia e kërkimit: A identifikon përgjigjja dërgesën e synuar dhe jo një referencë të ngjashme ose të ripërdorur?
• Plotësia e etapave: Cilat ngjarje të dobishme operacionale shfaqen dhe cilat kërkojnë një burim tjetër?
• Cilësia e vulave kohore: A janë të qëndrueshme koha e ngjarjes, koha e pranimit dhe interpretimi i zonës kohore?
• Trajtimi i vlerësimeve: A mund të dallojë sistemi një vlerësim, një rishikim dhe një takim?
• Sjellja në rast dështimi: A prodhojnë hyrja e pavlefshme, dështimet e autorizimit dhe ndërprerjet e përkohshme rezultate të dallueshme?
• Rikuperimi: A mund të rakordojë integrimi mesazhet e humbura ose të rikuperohet pas një ndërprerjeje?

Për monitorimin e API-së, ndani shëndetin teknik nga vizibiliteti i dërgesës. Ndiqni dështimet e kërkesave, vonesën e përpunimit, refuzimet e webhook-eve dhe grumbullimin në radhë, krahas dërgesave pa ngjarje të parë, historikëve të vjetëruar ose identifikuesve të pazgjidhur. Një përgjigje e suksesshme HTTP mund të mos përmbajë informacion të dobishëm për dërgesën.

Përcaktoni emëruesin e çdo metrike. “Kërkim i suksesshëm” mund të nënkuptojë kërkesë të pranuar, dërgesë të njohur ose dërgesë me etapa të përdorshme; këto janë matje të ndryshme. Vendosni kriteret e pranimit përpara pilotimit dhe dokumentoni rezultatet sipas transportuesit, shërbimit dhe linjës. Zgjerohuni vetëm kur lidhja mbështet vendimet e synuara operacionale, me një alternativë të emërtuar për rastet e pambuluara.

FAQ

A mund të gjurmoj mallrat LTL duke përdorur vetëm një numër BOL?

Ndonjëherë, por pranimi varet nga transportuesi dhe integrimi. Një shërbim mund të kërkojë numër PRO, kredenciale llogarie ose një referencë tjetër. Konfirmoni metodën e kërkimit përpara se të ndërtoni një rrjedhë pune që mbështetet vetëm në gjurmimin me BOL.

A e zëvendëson një API për gjurmimin e mallrave një TMS?

Jo, jo vetë. Gjurmimi ofron të dhëna vizibiliteti. Planifikimi i transportit, tenderimi, tarifimi, menaxhimi i takimeve dhe shlyerja janë funksione të veçanta që mund të mbeten në TMS-në tuaj ose në sisteme të tjera operacionale.

Pse faqja e transportuesit shfaq një përditësim përpara sistemit tim?

Shkaqet e mundshme përfshijnë sinkronizimin e burimit, kohën e rifreskimit të API-së, dorëzimin e webhook-ut ose grumbullimin në procesimin tuaj. Krahasoni kohën e ngjarjes burimore me kohën e pranimit dhe përpunimit për të gjetur boshllëkun. Mos supozoni se faqja e transportuesit dhe API-ja përdorin rrugë identike për përditësimet.

A mund të ndjekë një API një dërgesë ndërkombëtare mallrash nga fillimi në fund?

Mund ta bëjë, nëse pjesëmarrësit dhe referencat e kërkuara të dërgesës janë të lidhura. Verifikoni veçmas marrjen në origjinë, transportin kryesor, etapat doganore dhe dorëzimin në destinacion. Një lidhje që mbulon segmentin kryesor të transportit nuk i përfshin automatikisht të tjerat.

Çfarë duhet të ndodhë kur të dhënat e gjurmimit vjetrohen?

Zbatoni një prag të përshtatshëm për shërbimin dhe fazën e dërgesës, pastaj krijoni një detyrë për rishikim të cilësisë së të dhënave ose të operacioneve. Shfaqni ngjarjen e fundit të njohur dhe kohën e saj. Përshkallëzojeni te transportuesi ose agjenti i spedicionit kur është e nevojshme, pa i paraqitur përditësimet që mungojnë si vonesë të konfirmuar.

Burimet

• 17TRACK Tracking API — pikënisja zyrtare për vlerësimin e ofertës së API-së së gjurmimit.
• Dokumentacioni i API-së 17TRACK — referencë për kontrollin e kontratës së zbatimit dhe kërkesave të integrimit.
• Standardet DCSA Track & Trace — standardet e gjurmimit të transportit me kontejnerë dhe konteksti i modelit të ngjarjeve.
• RFC 9110: HTTP Semantics — semantika e metodave HTTP, idempotenca dhe konsideratat e protokollit lidhur me riprovimet.