API за проследяване на товарни пратки: LTL и данни за товарни превози, стъпки за интеграция и ограничения на покритието

API за проследяване на товарни пратки свързва актуализациите за пратките от превозвачи, спедитори или доставчици на услуги за видимост с вашия логистичен софтуер. За частични товарни пратки (LTL) и други товарни превози успешната интеграция зависи от повече от името на превозвача: трябва да проверите приеманите идентификатори на пратките, поддържаните услуги, наличните етапи, правата за достъп до акаунта и методите за получаване на актуализации. Започнете с товарните направления и оперативните решения, които трябва да поддържате, след което проверете дали API предоставя използваеми данни за тези пратки.

Това ръководство е предназначено за разработчици, логистични мениджъри и отговорници по интеграциите, които свързват видимостта на товарите със система за управление на транспорта (TMS), система за планиране на ресурсите на предприятието (ERP), складова платформа или клиентски портал. Целта не е просто да се извлече статус. Тя е да се предостави на оперативните екипи достатъчно контекст, за да разпознават закъснения, да координират приемането и да разрешават изключения, без да приемат липсващите данни като потвърден проблем с превоза.

Какво всъщност представляват данните за проследяване на товарни пратки

Проследяването на товари обикновено представлява запис на съобщени събития по пратката, а не непрекъснат поток от данни за местоположението. Пристигане на терминал, освобождаване от митница, час за доставка и доказателство за доставка описват различни оперативни факти. Те могат да произхождат от различни организации и да постъпват чрез отделни системи.

LTL пратките споделят капацитета на ремаркето с други товари и могат да преминават през множество терминали. Другите товарни превози могат да включват камионен превозвач в началната точка, спедитор, морски или въздушен превозвач, митнически посредник и доставчик в крайната точка. API връзката с един участник не разкрива автоматично всеки етап.

Категория данни	Какво да поискате	Какво да не приемате за даденост
Идентичност на пратката	Превозвач, тип идентификатор, стойност на идентификатора и контекст на акаунта, когато е необходим	Всеки референтен номер работи като заявка за проследяване
Събития по движението	Вземане, дейности на терминала, отпътуване, пристигане и събития при доставка, когато са налични	Всяко физическо преместване създава събитие
Планиране на доставката	Очаквано пристигане, информация за час на доставка и промени	Очакваната дата е потвърден час за приемане
Изключения	Оригинално описание на изключението, нормализирана категория и час на събитието	Общият статус на изключението обяснява причината
Доказателства за доставката	Събитие за доставена пратка, обхват на доставката и наличност на документи	Статусът „доставено“ включва подписан документ за доказателство за доставка

PRO номерата, товарителниците и номерата на контейнерите не са взаимозаменяеми

При проследяване на LTL пратки присвоеният от превозвача PRO номер е често използван референтен номер. Товарителницата (BOL) документира пратката, но нейният номер не се приема непременно от същата крайна точка за проследяване. Номерата на поръчките за покупка и референциите на изпращача може да изискват достъп за търсене, специфичен за акаунта, или отделна функция за търсене.

Морският транспорт добавя номера на контейнери, референции за резервации и товарителници. Въздушният транспорт добавя референции за въздушни товарителници. Вътрешната референция на спедитора може да идентифицира пратка в системата на спедитора, без да може да се използва директно с основния превозвач. Съхранявайте типа идентификатор и издаващата страна заедно със стойността; не поставяйте всяка референция в недиференцирано поле за номер за проследяване.

Определете покритието на ниво пратка

Директорията на превозвачите е начална точка, а не доказателство, че товарът ви може да бъде проследен. Разглеждайте покритието като комбинация от превозвач, услуга, география, идентификатор, права за достъп, жизнен цикъл на пратката и задължителни полета. Доставчикът може да поддържа даден превозвач, докато конкретна услуга или документ остава извън обхвата на интеграцията.

• Превозвач и услуга: Потвърдете действителната LTL или товарна услуга, вместо да разчитате на името на компанията майка или на списък с куриерски услуги.
• География и етап: Проверете отделно началната точка, дестинацията, трансграничното движение и последния етап на доставката.
• Метод за търсене: Установете дали API приема идентификатора, който действително се създава от работния процес за изпращане.
• Упълномощаване: Определете дали публичното проследяване е достатъчно или са необходими идентификационни данни за акаунта на превозвача и разрешение от клиента.
• Дълбочина на полетата: Проверете дали интеграцията предоставя основни статуси, подробности за терминала, оценки, информация за часове за доставка или документи.
• История и актуалност: Попитайте за исторически събития, неактивни пратки, поведението при обновяване и всички документирани ограничения за съхранение.

Разделяйте две констатации: документираните възможности на API и резултатите, наблюдавани при тестовите ви пратки. Успешната заявка не доказва универсално покритие. Неуспешната заявка също не доказва, че дадена услуга не се поддържа; неправилен идентификатор, липсващо разрешение или пратка, която още не е въведена в изходната система, могат да обяснят резултата.

Какво е мястото на 17TRACK в оценката

За екип, който оценява интеграция за проследяване на множество превозвачи, подходящият продукт на 17TRACK е неговият Tracking API. Използвайте официалната документация на API, за да оцените договора за интеграция, и потвърдете посочените от вас товарни превозвачи, типовете услуги, форматите на идентификаторите и задължителните полета, преди да започнете реализация.

Не правете извод за пълна видимост на LTL, морски, въздушни или спедиторски превози от общото описание на API за проследяване. Поискайте потвърждение чрез представителни пратки. Ако оперативното изискване включва планиране на часове за доставка, диспечиране, товарни документи или телеметрия за местоположението, оценете това изискване отделно, вместо да приемате, че е част от проследяването.

Стъпки за интеграция: от референции на пратките до оперативни сигнали

1. Определете модела на пратката и бизнес резултата

Решете кои действия трябва да поддържат данните. Екипът по приемане се нуждае от времето на доставката и контекста на часа за приемане; обслужването на клиенти се нуждае от ясна история на пратката; екипът за изключения се нуждае от приложима информация за закъсненията. Тези изисквания определят какво трябва да събирате и кога даден сигнал е полезен.

Създайте вътрешен запис за пратката, независим от доставчика на API. Свържете го с поръчки, товарни референции, превозвачи, товарни единици и транспортни етапи, когато е необходимо. Една поръчка може да се движи в няколко пратки, а една товарна пратка може да съдържа няколко поръчки. Избягвайте да приемате връзка „една поръчка към един номер за проследяване“.

2. Валидирайте достъпа и обработката на идентификаторите

Получете необходимите идентификационни данни и потвърдете метода за удостоверяване на доставчика. Съхранявайте тайните в конфигурация от страна на сървъра или в мениджър на тайни, а не в код на браузъра. Ако достъпът е специфичен за акаунта, свържете всеки клиент или бизнес звено с правилния контекст за упълномощаване.

Запазвайте стойностите на идентификаторите като низове, за да не се губят водещите нули. Прилагайте само документирани правила за форматиране. Използвайте вътрешен ключ за търсене, който включва превозвача, типа идентификатор, стойността на идентификатора и съответния контекст на акаунта. Това намалява случайните съвпадения между референции, издадени от различни организации.

3. Регистрирайте или заявявайте пратките според документирания работен процес

Някои интеграции за проследяване изискват регистрация на пратката, преди актуализациите да станат налични; други поддържат директни заявки. Следвайте документирания жизнен цикъл на избрания API, вместо да приемате конкретна крайна точка, структура на заявката или формат на отговора. При изпращане на пакетни заявки събирайте резултатите за всяка пратка, така че частично успешната заявка да не скрива отхвърлените записи.

Разделяйте невалидните входни данни, отказа на достъп, временната повреда на източника и валидната заявка без събития. Всеки от тези случаи изисква различна реакция. Безкрайното повтаряне на неправилно форматиран идентификатор създава трафик, без да подобрява видимостта.

4. Нормализирайте събитията, без да губите значението им

Изградете общ модел на събитията за работния процес по управление на логистиката, но запазете оригиналния статус и описание от източника. Полезните полета включват вътрешен идентификатор на пратката, транспортен етап, превозвач от източника, идентификатор на събитието от източника, когато е предоставен, час на събитието, час на получаване, местоположение, нормализиран статус и необработено описание.

Съхранявайте отделно часа на събитието и часа на приемане. Наскоро получена актуализация може да описва по-старо събитие на терминал. Запазвайте отместванията на часовата зона, когато са предоставени, и обозначавайте времевите маркери, чиято часова зона е неизвестна. Пристигането на терминал в дестинацията не трябва да се превръща във финална доставка само защото и двете събития съдържат думата „пристигане“.

5. Реализирайте надеждно получаване на актуализации

Когато са налични уебкуки, валидирайте входящите заявки чрез документирания механизъм за сигурност на доставчика. Надеждно съхранявайте или поставяйте в опашка приетите съобщения, преди да ги потвърдите, и обработвайте последващата работа асинхронно. Проектирайте системата за дублирани и несортирани събития, освен ако договорът за интеграция изрично не гарантира друго.

При периодично извличане следвайте документираните ограничения за заявките и адаптирайте графика към състоянието на пратката и оперативната спешност. Използвайте контролирани повторни опити с постепенно увеличаване на интервала при временни повреди. Спазвайте инструкциите на сървъра за повторен опит, когато са предоставени. Безопасността при повторение на HTTP зависи от семантиката на заявката, затова не приемайте, че всяка неуспешна операция за запис може да бъде повторена без създаване на дублирана работа.

6. Свържете статусите с действия, а не само с табла

Определете кой отговаря за всяко изключение. Пропуснатото вземане може да принадлежи на транспортните операции, несъответствието в часа за доставка — на екипа по приемане, а липсващата референция за проследяване — на собственика на системата за изпращане. Включвайте изходното събитие и контекста на пратката в сигнала, така че получателят да може да действа, без да възстановява историята на пратката.

Поддържайте отделни вътрешни и клиентски съобщения. Оперативният екип може да има нужда от неразрешен код от източника; клиентът се нуждае от описание на разбираем език, което не претендира за по-голяма сигурност, отколкото данните позволяват. Никога не превръщайте липсващата оценка в обещана дата за доставка.

Ограничения на покритието, които променят оперативните решения

Липсата на събитие не означава непременно липса на движение. Товарът може да се движи между съобщените етапи. Разграничавайте „няма скорошна актуализация“ от „съобщено от превозвача закъснение“. Сигналът за остарели данни трябва да предизвика проверка, а не автоматично да съобщава на клиента, че товарът е изгубен или закъснява.

Етапите на проследяване не са непрекъснат GPS. Ако работният ви процес изисква позиция на превозното средство, геозониране или чести актуализации на местоположението, поискайте изрично потвърждение на източника на местоположението, поведението при обновяване и връзката между пратката и превозното средство. Събитие на терминал с времеви маркер не е телеметрия на превозното средство в реално време.

Завършването на транспорта може да се отнася само до един етап. Доставката до склад, терминал или консолидационен пункт може да приключи отговорността на един доставчик, докато пътуването към клиента продължава. Моделирайте изрично предаването, така че междинно събитие „доставено“ да не приключва преждевременно цялата пратка.

Документите и резултатите на ниво отделна товарна единица изискват отделни проверки. Събитието за доставка може да не включва подписан документ, отбелязване за липса, запис за повреда или разбивка на товарните единици. При работни процеси за частична доставка потвърдете какво съобщава източникът и запазвайте неразрешените количества, докато операциите не ги съгласуват.

Достъпът и стандартите за данни са различни проблеми. Стандарти като DCSA Track & Trace standards предоставят референция за терминологията и интерфейсите при събитията в контейнерния транспорт. Те сами по себе си не доказват, че конкретен API предлага достъп до вашата пратка или поддържа необходимата връзка с превозвача.

Тествайте покритието и наблюдавайте качеството на данните, преди да разширите мащаба

Изградете доказателство за концепция около действителния си товарен микс. Включете нормални доставки, активни пратки в транзит, трансгранични движения, когато е необходимо, предавания, липсващи референции и случаи с изключения. Изберете примери от превозвачите и услугите, които са важни за вашата дейност, вместо да използвате само най-лесните успешни заявки.

• Коректност на заявката: Отговорът идентифицира ли търсената пратка, а не сходна или повторно използвана референция?
• Пълнота на етапите: Кои оперативно полезни събития се появяват и кои изискват друг източник?
• Качество на времевите маркери: Последователни ли са часът на събитието, часът на получаване и тълкуването на часовата зона?
• Обработка на оценките: Може ли системата да различи оценка, промяна и час за доставка?
• Поведение при грешки: Невалидните входни данни, грешките при упълномощаване и временните прекъсвания водят ли до различими резултати?
• Възстановяване: Може ли интеграцията да съгласува пропуснати съобщения или да се възстанови след прекъсване?

При наблюдение на API отделяйте техническото здраве от видимостта на пратките. Следете неуспешните заявки, забавянето при обработката, отхвърлянето на уебкуки и натрупването в опашките заедно с пратките без първо събитие, остарелите истории или неразрешените идентификатори. Успешният HTTP отговор все пак може да не съдържа полезна информация за пратката.

Определете знаменателя на всяка метрика. „Успешна заявка“ може да означава приета заявка, разпозната пратка или пратка с използваеми етапи; това са различни измервания. Определете критериите за приемане преди пилотния проект и документирайте резултатите по превозвач, услуга и направление. Разширявайте само когато връзката поддържа предвидените оперативни решения, като посочите резервен вариант за непокритите случаи.

ЧЗВ

Мога ли да проследявам LTL товар само с номер на BOL?

Понякога, но приемането зависи от превозвача и интеграцията. Услугата може да изисква PRO номер, идентификационни данни за акаунта или друга референция. Потвърдете метода за търсене, преди да изградите работен процес само около проследяване по BOL.

Заменя ли API за проследяване на товари TMS?

Не самостоятелно. Проследяването предоставя данни за видимост. Транспортното планиране, възлагането, тарифирането, управлението на часовете за доставка и сетълментът са отделни функции, които могат да останат във вашата TMS или други оперативни системи.

Защо уебсайтът на превозвача показва актуализация преди моята система?

Възможните причини включват синхронизация с източника, времето за обновяване на API, доставката на уебкуки или натрупване на изоставане при собствената ви обработка. Сравнете часа на събитието от източника с часовете на получаване и обработка, за да откриете разликата. Не приемайте, че уебсайтът на превозвача и API използват идентични пътища за актуализация.

Може ли един API да проследява международна товарна пратка от край до край?

Възможно е, ако необходимите участници и референции на пратката са свързани. Проверете отделно вземането в началната точка, основния превоз, етапите, свързани с митницата, и доставката в дестинацията. Връзката, която покрива основния транспортен етап, не включва автоматично останалите.

Какво трябва да се случи, когато данните за проследяване остареят?

Приложете праг, подходящ за услугата и етапа на пратката, след което създайте задача за преглед на качеството на данните или на оперативния процес. Показвайте последното известно събитие и неговия час. При необходимост ескалирайте към превозвача или спедитора, без да представяте липсващите актуализации като потвърдено закъснение.

Източници

• 17TRACK Tracking API — официална отправна точка за оценка на предложението за API за проследяване.
• 17TRACK API documentation — справочник за проверка на договора за реализация и изискванията за интеграция.
• DCSA Track & Trace standards — стандарти за проследяване на контейнерни превози и контекст на модела на събитията.
• RFC 9110: HTTP Semantics — семантика на HTTP методите, идемпотентност и протоколни съображения, свързани с повторните опити.