API за проследяване на морски товари: събития на контейнерите, данни за ETA и критерии за избор

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

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

Започнете с модела на пратката, а не с екрана за проследяване

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

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

Преди да оцените API, идентифицирайте референциите, които вашият бизнес действително получава:

• Номер на контейнера: Идентифицира оборудването, но трябва да бъде свързан със съответната пратка или движение, тъй като контейнерите се използват повторно.
• Референция за резервация при превозвача: Може да свърже заявката за проследяване с резервация в зависимост от изискванията за търсене на изходната система.
• Референция на транспортния документ: Може да идентифицира пратката на ниво морски превозвач. Потвърдете дали API приема референциите на документите, с които разполага вашият екип.
• Вътрешен идентификатор на пратката: Свързва външните записи за проследяване с вашата система за управление на транспорта, ERP или спедиторски софтуер.

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

Какви събития на контейнера трябва да предоставя API?

Стандартите на Digital Container Shipping Association за Track & Trace предоставят полезна отправна точка за обсъждане на данните за морски пратки. DCSA разграничава събитията на пратката, транспорта и оборудването. Тези категории помагат да се разделят административният напредък, движението на транспорта и обработката на физическия контейнер.

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

Събития на оборудването: какво се е случило с контейнера

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

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

Транспортни събития: къде се намира корабът или транспортният етап

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

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

Събития на пратката: административният напредък не е физическо движение

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

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

Данните за ETA се нуждаят от дестинация, значение и история

ETA е прогнозен час на пристигане в определена точка. Той по своята същност не е обещание, че товарът ще бъде готов за получаване. API за проследяване на морски товарни превози трябва изрично да посочва етапа на дестинацията, вместо да връща двусмислено поле, означено само като eta.

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

Разделяйте източника на прогнозата от нейния статус

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

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

Запазвайте промените на ETA, вместо да ги презаписвате

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

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

Часовите зони трябва да бъдат изрично тествани. Запазвайте времевия печат от източника и неговото отместване, когато са предоставени, нормализирайте времевите печати за изчисления и показвайте местното оперативно време, когато е уместно. Ако източникът предоставя само дата, не я превръщайте мълчаливо в обещание за точно пристигане в полунощ.

Оценявайте покритието на ниво събитие

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

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

• Директни морски движения: Можете ли да идентифицирате отпътуването от началната точка, пристигането в дестинацията и съответните събития по обработката на контейнера?
• Движения с претоварване: Виждат ли се междинните етапи и могат ли контейнерите, които се движат отделно, да останат различими?
• Сухопътни етапи: Ако услугата ви ги включва, предоставя ли API съответните етапи за железопътен, баржов или автомобилен транспорт, или видимостта приключва на пристанището?
• Изключения: Как се представят липсващи събития, променени маршрути, несъответстващи референции и прекъсвания на източника?
• Завършени пратки: Може ли екипът ви да извлече достатъчно исторически данни, за да разследва спор с клиент или да съгласува оперативен запис?

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

Поведението на API е също толкова важно, колкото и списъкът със събития

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

Периодични заявки, webhooks и възстановяване

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

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

Нормализация без загуба на доказателства

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

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

Търговски проверки и управление

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

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

Не приемайте, че общ API за проследяване отговаря на изискванията за морски товарни превози

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

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

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

Проведете доказване на концепцията около оперативните решения

Най-силното доказване на концепцията започва с решенията, които екипът ви трябва да взема, а не с демонстрация на табло. Изберете представителни пратки от собствената си дейност, включително стандартни плавания и трудните случаи, които създават ръчна работа.

1. Определете критериите за приемане. Посочете необходимите референции, събития, местоположения, семантика на времевите печати и приемливото обработване на липсващи данни преди тестването.
2. Потвърдете идентичността. Потвърдете, че всеки резултат принадлежи на планираната пратка и движение на контейнера. Включете повторно използвано оборудване и резервации с множество контейнери, когато е уместно.
3. Сравнете с изходните записи. Проверете върнатите етапи спрямо достъпните записи на превозвача или терминала, като отчетете разликите във времето на актуализация.
4. Тествайте промените и отказите. Проверете дублирани известия, събития извън ред, коригирани времеви печати, недостъпни източници и прекъсвания на крайните адреси.
5. Възпроизведете бизнес процес. Проверете дали данните подпомагат планираното действие, например преглед на забавена връзка или актуализиране на прогноза за входящи стокови запаси.
6. Прегледайте нерешените пропуски. Запишете дали всеки пропуск произлиза от основния източник, обработката от доставчика или вашата интеграция. Договорете коригиращи действия преди разширяване на използването.

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

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

Често задавани въпроси

Мога ли да проследя морска пратка само с номер на контейнер?

Това зависи от източника на данни и API. Някои работни процеси може да изискват и идентификатор на превозвача, референция за резервация или референция на транспортен документ. Тъй като оборудването се използва повторно, потвърдете, че върнатите събития принадлежат на планираното движение, вместо да разчитате само на номера на контейнера.

Означава ли действителното пристигане на кораба, че контейнерът ми е готов за получаване?

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

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

Не. AIS се отнася до идентификацията и движението на кораба; сам по себе си той не установява статуса на товарене, разтоварване, освобождаване или излизане през портала на отделен контейнер. Движението на кораба може да предостави контекст, но връзката на контейнера с плаването все още трябва да бъде потвърдена.

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

Няма един-единствен полезен интервал за всеки работен процес. Определете изискванията според това колко бързо екипът ви трябва да реагира, след като стане налична съответната информация от източника. Измервайте латентността на източника отделно от латентността на доставяне от API и потвърдете какво се случва, когато източникът не публикува ново събитие.

Могат ли събитията за проследяване да изчисляват такси за демюрейдж или задържане?

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

Източници

• DCSA: стандарти за Track & Trace — Референтна рамка за събитията на пратката, транспорта и оборудването при контейнерни превози.
• DCSA: хранилище със спецификации на OpenAPI — Техническа справка за API дефинициите и структурите на събитията на DCSA. Проверете приложимата версия на спецификацията при проектиране на интеграция.
• International Maritime Organization: Automatic Identification Systems — Основна информация за AIS и предоставяната от него информация за корабите.
• 17TRACK: Tracking API и официална документация на API — Отправни точки за проверка на съответствието на продукта; тук не са доказателство за поддръжка на събития на морски контейнери или прогнозен ETA.