ホームブログ海上貨物追跡API：コンテナイベント、ETAデータ、選定基準

海上貨物追跡API：コンテナイベント、ETAデータ、選定基準

17TRACK

海上貨物追跡APIは、コンテナの移動、輸送マイルストーン、ETAの更新を、チームが管理する出荷に関連付けられる必要があります。貨物フォワーダー、輸入業者、統合チームにとって、選定の基準は、適切なコンテナの輸送行程を確実に特定し、実際のイベントと予測を区別し、業務上の意思決定を支える十分なコンテキストを提供できるかどうかです。一般的な出荷状況や、説明のない到着日は、海上貨物の管理には不十分です。

Ocean Freight Tracking API Container Events Eta Data and Selection

このガイドでは、要求すべきデータ、コンテナイベントと到着予測の解釈方法、本番トラフィックや調達予算を投入する前に統合を評価する方法について説明します。

追跡画面ではなく、出荷モデルから始める

海上貨物の追跡には、商業上の出荷、輸送書類、1つ以上のコンテナ、それらを運ぶ輸送区間など、複数の関連オブジェクトが関係します。1つのブッキングに複数のコンテナが含まれる場合がある一方、1つのコンテナが複数の船舶、ターミナル、内陸輸送区間を経由することもあるため、これらの関係は重要です。

有用な統合は、すべてを1つのステータスに平坦化するのではなく、これらの関係を維持する必要があります。同じ出荷に含まれる2つのコンテナが異なる動きをした場合、システムは、一見完全に見える出荷レベルのマイルストーンを表示するのではなく、オペレーターがその違いを確認できるようにすべきです。

APIを評価する前に、業務上実際に受け取る参照情報を特定してください。

  • コンテナ番号: 機器を識別しますが、コンテナは再利用されるため、関連する出荷または輸送行程と紐付ける必要があります。
  • 配送業者のブッキング参照番号: 送信元システムの検索要件に応じて、追跡リクエストをブッキングに関連付けられます。
  • 輸送書類参照番号: 海上輸送業者のレベルで出荷を識別できる場合があります。APIがチームの保有する書類参照番号を受け付けるか確認してください。
  • 内部出荷ID: 外部の追跡記録を、輸送管理システム、ERP、またはフォワーディングソフトウェアに関連付けます。

フォワーダーが発行したハウスB/L参照番号を、海上輸送業者の書類参照番号が必要な場所で常に使用できるとは限りません。ブッキングおよび書類のワークフローで利用可能な正確な識別子をテストしてください。

APIはどのコンテナイベントを公開すべきか

Digital Container Shipping AssociationのTrack & Trace標準は、海上出荷データについて議論する際の有用な参照情報です。DCSAは、出荷イベント、輸送イベント、機器イベントを区別しています。これらの分類により、管理上の進捗、輸送の移動、物理的なコンテナの取り扱いを分けて考えられます。

ベンダーは、必ずしも希望するフィールド名を使用する必要はありませんが、そのイベントモデルが必要な業務上のマイルストーンにどのように対応するかを説明できるべきです。

機器イベント：コンテナに何が起きたか

関連する機器マイルストーンには、ゲートイン、積載、荷下ろし、ゲートアウト、空コンテナの移動などがあります。利用可能性は、輸送行程、データソース、製品によって異なります。すべてのターミナルですべてのイベントが利用できると想定せず、サンプルレコードの提示を求めてください。

これらの区別は実務上重要です。船舶の到着は、特定のコンテナが荷下ろしされたことを証明しません。荷下ろしは、コンテナが引き渡し可能または集荷可能であることを証明しません。ゲートアウト記録にも場所とコンテキストが必要です。トランシップ施設からのゲートアウトは、最終輸入ターミナルからの引き取りと同じ業務上の結果ではありません。

輸送イベント：船舶または輸送区間の状況

到着イベントと出発イベントは輸送活動を表します。これらを解釈するには、関連する場所、輸送モード、輸送区間が必要です。利用可能な場合、船舶および航海識別子は、同じ港を結ぶ別の移動ではなく、予定された航海を識別するのに役立ちます。

トランシップ貨物については、中間寄港地を保持してください。経路を出発地と目的地だけに縮約すると、接続の失敗や経路変更が隠れてしまう可能性があります。業務タイムラインでは、どの区間が完了し、どの区間がまだ予測であるかを確認できるようにすべきです。

出荷イベント：管理上の進捗は物理的な移動ではない

書類および出荷処理イベントはフォワーディング業務に有用ですが、コンテナの移動とは区別して扱うべきです。書類上のマイルストーンは貨物が物理的に移動したことを示すものではなく、移動イベントもすべての商業上または規制上の要件が満たされたことを示すものではありません。

各イベントについて、イベントタイプ、対象オブジェクト、場所、イベントのタイムスタンプ、タイムゾーン情報、ソース、計画・推定・実績のいずれであるかを示す情報を要求してください。また、更新の繰り返しによって重複マイルストーンが作成されないよう、安定したイベント識別子と訂正時の動作も確認してください。

ETAには目的地、意味、履歴が必要

ETAとは、指定された地点への到着予定時刻です。これは本質的に、貨物を引き取れることを約束するものではありません。海上貨物追跡APIは、単にetaとだけ表示された曖昧なフィールドを返すのではなく、目的地のマイルストーンを明示すべきです。

たとえば到着予測は、港への寄港、ターミナル、内陸施設、または別に定義された目的地を指す場合があります。トラックを手配したり、在庫の利用可能性を約束したりする前に、そのタイムスタンプが正確に何を表しているのかを明確にしてください。

予測のソースとステータスを分ける

輸送業者が提供する予測と、プロバイダーが生成する予測は異なるデータ製品です。いずれも実際の到着として提示すべきではありません。レスポンスに予測の出所、計算または公開時刻、予測対象の場所またはイベントが含まれるか確認してください。

プロバイダーが予測ETAを提供する場合は、その方法論と検証方法を要求してください。どのマイルストーンを予測するのか、到着のどのくらい前に精度を測定するのか、利用する航路によって結果が異なるのかなどが有用な質問です。対象イベントと測定期間が明確でない場合、広範な精度の主張を適用するのは困難です。

ETAの改訂を上書きせず保持する

最新のETAは今日の計画を支え、改訂履歴は何が変わったかを説明します。以前の予測、新しい予測、関連するマイルストーン、ソース、システムが変更を受信した時刻を保存してください。

この履歴により、運用チームは重大な遅延と、書式の訂正や無関係な寄港地の変更を区別できます。また、最終的な予測が輸送行程の早い段階で分かっていたかのように扱うことなく、事後評価を行えます。

タイムゾーンは明示的にテストする必要があります。提供されている場合はソースのタイムスタンプとオフセットを保持し、計算用にタイムスタンプを正規化し、適切な場合は現地の業務時間を表示してください。ソースが日付のみを提供する場合、正確な午前0時の到着予定に暗黙的に変換しないでください。

イベントレベルでカバレッジを評価する

カバレッジリストに輸送業者が掲載されているだけでは、すべてのコンテナマイルストーンが利用可能であることにはなりません。カバレッジは、自社にとって重要な輸送業者、航路、出荷参照番号、業務イベントに対してテストする必要があります。

実際の要件を用いて評価マトリックスを作成してください。代表的な各出荷について、APIが参照番号を解決し、正しい経路を返し、必要なマイルストーンを公開し、管理対象の輸送行程の範囲で更新を維持できるか確認します。

  • 直行海上輸送: 出発地の出港、目的地への到着、関連するコンテナ取り扱いイベントを特定できますか。
  • トランシップ輸送: 中間区間が表示され、別々に移動するコンテナを区別できますか。
  • 内陸輸送区間: サービスに含まれる場合、APIは鉄道、はしけ、トラックに関する関連マイルストーンを提供しますか。それとも港で可視性が終了しますか。
  • 例外: 欠落イベント、経路変更、照合できない参照番号、ソースの中断はどのように表現されますか。
  • 完了済み出荷: 顧客との紛争を調査したり、業務記録を照合したりするのに十分な履歴データをチームが取得できますか。

利用できないデータと否定的なイベントを分けて扱ってください。荷下ろし記録がないことは、荷下ろしが発生していないことを証明しません。有用な統合は、明示的な業務ステータスと可視性の欠落を区別します。

APIの動作はイベントリストと同じくらい重要

イベントフィードが豊富でも、配信動作が不明確であれば運用は困難になります。アプリケーションが更新を受け取り、訂正を処理し、障害後に復旧する方法を評価してください。

ポーリング、Webhook、復旧

ポーリングでは、アプリケーションが独自のスケジュールで更新を要求できます。Webhookでは、プロバイダーが運用するエンドポイントに更新を送信できます。どちらの仕組みだけでも鮮度は保証されません。即座に配信されたWebhookであっても、ソースイベントの受信が遅れている可能性があります。

利用可能な場合は、ソースイベント時刻、プロバイダー受信時刻、通知時刻を別々に定義するよう求めてください。Webhookについては、認証または署名検証、リトライ、重複配信の動作、失敗した通知を再送できるかを確認してください。ポーリングについては、ページネーション、レート制限、差分取得、履歴訂正の扱いを確認します。

証拠を失わない正規化

正規化されたステータスは複数の輸送業者にまたがる業務を容易にしますが、過度な単純化は有用なコンテキストを失わせます。利用可能な場合は、正規化されたイベントと元のソース説明またはコードを併せて保持できるモデルを優先してください。

受信した生データの記録を、ダッシュボードのステータスに変換する業務ルールとは別に保存してください。これにより、元の証拠を失わずにマッピングを修正できます。また、顧客向けステータスが運用チームの解釈と異なる場合にも、調査しやすくなります。

商業面およびガバナンスの確認

課金単位について書面による説明を求めてください。サブスクリプション、追跡対象の出荷、コンテナ、APIリクエスト、通知は、同じ意味の指標ではありません。特定の料金モデルを想定せず、リトライ、重複登録、履歴検索、再有効化された出荷が料金にどう影響するかを明確にしてください。

さらに、データ保持、アクセス制御、認証情報のローテーション、許可された下流利用、サポートへのエスカレーション、サービスコミットメントを確認してください。契約上の保証は、製品デモやマーケティング上の説明とは分けて扱います。

一般的な追跡APIが海上貨物の要件を満たすと想定しない

追跡APIは、カテゴリ名ではなく、検証済みのデータモデルに基づいて選定すべきです。小口配送の更新と海上コンテナの可視性は、どちらも出荷追跡と呼ばれていても、異なる業務を支える場合があります。

17TRACKがすでに統合候補のリストにある場合は、要件確認の出発点として公式Tracking APIページとAPIドキュメントを利用してください。一般的な追跡統合を海上貨物ソリューションとして扱う前に、アプリケーションに必要な正確な海上参照番号、コンテナイベント、輸送区間、ETAフィールドを確認してください。このガイドは、17TRACKの海上貨物固有の機能を確立するものではありません。

同じ受け入れ基準をすべての候補に適用してください。代表的な出荷で必要なデータを実証し、制限事項を説明できることが必要です。より広範な輸送業者追跡ワークフローはサプライチェーンの別の場所で役立つ場合がありますが、専門的なコンテナイベントフィードの代替にはなりません。

業務上の意思決定を中心に概念実証を行う

最も有効な概念実証は、ダッシュボードのデモではなく、チームが必要とする意思決定から始まります。単純な航海だけでなく、手作業を生む難しいケースも含め、自社業務を代表する出荷を選択してください。

  1. 受け入れ基準を定義する。テスト前に、必要な参照番号、イベント、場所、タイムスタンプの意味、欠落データの許容される扱いを明確にします。
  2. 身元を検証する。すべての結果が意図した出荷およびコンテナの輸送行程に属することを確認します。該当する場合は、再利用された機器や複数コンテナのブッキングを含めます。
  3. ソース記録と比較する。更新時刻の違いを考慮しながら、返されたマイルストーンをアクセス可能な輸送業者またはターミナルの記録と照合します。
  4. 改訂と障害をテストする。重複通知、順不同イベント、訂正されたタイムスタンプ、利用できないソース、エンドポイント障害を試します。
  5. 業務ワークフローを再現する。遅延した接続の確認や入荷在庫予測の更新など、意図したアクションをデータが支えられるか検証します。
  6. 未解決のギャップを確認する。各ギャップが基盤となるソース、プロバイダーの処理、統合のいずれに起因するか記録します。利用範囲を拡大する前に、是正策について合意します。

ETAのテストでは、各予測を到着時点で保存し、同じマイルストーンの最終的な実績イベントと比較してください。港への到着予測を倉庫受け入れと比較したり、リードタイムが大きく異なる予測を1つの説明のないスコアにまとめたりしないでください。

選定ルールは明確です。追跡可能なイベント、理解しやすい予測、復旧可能な配信動作により、必要な意思決定を実証的に支援できる統合を選択してください。集荷計画にターミナルの利用可能性、リリース状況、予約も必要な場合は、船舶の到着から推測せず、それらの入力を個別に確認してください。

FAQ

コンテナ番号だけで海上出荷を追跡できますか。

データソースとAPIによります。ワークフローによっては、輸送業者識別子、ブッキング参照番号、輸送書類参照番号も必要になる場合があります。機器は再利用されるため、コンテナ番号だけに頼らず、返されたイベントが意図した輸送行程に属することを確認してください。

船舶の実際の到着は、コンテナが集荷可能であることを意味しますか。

いいえ。船舶の到着、コンテナの荷下ろし、貨物の利用可能性、集荷の許可は、それぞれ別の業務上の事実です。出荷によっては、集荷にリリース情報やターミナル予約も必要です。関連する条件を担当者に確認してください。

AIS船舶追跡はコンテナ追跡の代わりになりますか。

いいえ。AISは船舶の識別情報と移動情報に関するものであり、個々のコンテナの積載、荷下ろし、リリース、ゲートアウトの状況をそれ自体で証明するものではありません。船舶の移動はコンテキストを提供できますが、コンテナと航海との関連付けは確認する必要があります。

海上追跡APIはどのくらいの頻度で更新すべきですか。

すべての業務に有効な単一の間隔はありません。関連するソース情報が利用可能になってから、チームがどれだけ早く行動する必要があるかを基準に要件を設定してください。ソースの遅延とAPIの配信遅延を分けて測定し、ソースが新しいイベントを公開しない場合に何が起こるか確認してください。

追跡イベントからデマレージまたはディテンション料金を計算できますか。

イベントはタイムラインを支援できますが、完全な料金計算を確定するものではありません。適用される契約条件、フリータイム規則、暦日の扱い、権威ある開始条件と終了条件も必要です。一般的なマイルストーンだけから支払額を算出しないでください。

出典

Loading