Skip to main content
ホームブログガイド配送追跡データをOmsに接続する方法:注文マッピングと同期ルール

配送追跡データをOmsに接続する方法:注文マッピングと同期ルール

17TRACK

出荷追跡データを注文管理システム(OMS)に接続するには、追跡対象の各荷物を内部の出荷レコードにマッピングし、その出荷を注文およびフルフィルメント明細に関連付けます。プロバイダーがサポートするインターフェースを通じて追跡更新を受信し、元のイベントを保持したうえで、重複、遅延更新、出荷ステータス、注文完了に関する明示的なルールを適用します。追跡番号だけを注文識別子として使用したり、複数荷物の注文を1件の配達イベントだけで自動的にクローズしたりしないでください。

OMS注文に出荷追跡データを接続する方法

このガイドは、この接続を実装するインテグレーションエンジニアおよびEコマース運用チームを対象としています。推奨設計では、配送業者の観測情報とビジネス上の判断を分離します。追跡データは荷物の移動を示し、OMSはその移動がフルフィルメント、顧客連絡、注文クローズに何を意味するかを判断します。

各レコードをどのシステムが管理するかを定義する

API接続を構築する前に、OMS管理者、フルフィルメントチーム、カスタマーサービスチームと所有権について合意してください。そうしないと、技術的には成功したインテグレーションでも、正しい業務データを上書きする可能性があります。

  • OMS: 注文、注文明細、必要数量、キャンセル、注文完了のルールを管理します。
  • フルフィルメントシステム: 梱包割り当てやラベル割り当てを含め、自ら作成した出荷または荷物のレコードを管理します。OMS自体の場合も、別の倉庫システムの場合もあります。
  • 追跡プロバイダー: 追跡情報およびプロバイダーが定義したステータス分類を提供します。
  • インテグレーション層: 識別子の相互参照、イベント処理、正規化、再試行処理、同期監査レコードを管理します。

これらは推奨される境界であり、ソフトウェアに関する前提ではありません。例外を文書化してください。たとえば、倉庫が配送ラベルを交換できる場合、インテグレーションは新しく確認された番号が古い番号に置き換わると推測するのではなく、そのシステムから明示的な更新を受け取る必要があります。

ステータスを同期する前に注文と荷物のマッピングを構築する

実用的な関係は、注文 → フルフィルメント → 荷物 → 追跡割り当てです。OMSによって名称が異なったり、一部のレコードが統合されていたりする場合があります。データベース構造が異なっていても、関係性は保持してください。

1つの注文に複数のフルフィルメントが含まれることがあり、1つのフルフィルメントに複数の荷物が含まれることもあります。また、荷物に交換後の追跡割り当てや、関連するラストマイル識別子が付与される場合があります。これらの識別子によって注文数量を追加してはなりません。

レコード推奨フィールド目的
注文テナントまたはストアID、変更不能なOMS注文ID販売者を分離し、表示用注文番号への依存を避けます。
フルフィルメントフルフィルメントID、注文ID、割り当てられた明細IDと数量購入された商品のうち、どれがフルフィルメント対象かを特定します。
荷物内部荷物ID、フルフィルメントID、利用可能な場合は荷物割り当て追跡ラベルに依存しない安定した識別情報を提供します。
追跡割り当て割り当てID、荷物ID、プロバイダーアカウント、配送業者識別子、追跡番号、有効期間受信した追跡情報を正しい荷物および割り当てのライフサイクルに関連付けます。

保存した相互参照を通じて更新を照合する

出荷を作成したら、追跡に登録する前に内部IDを保存します。文書化された登録処理によって返される、プロバイダー発行の追跡レコードIDも保存してください。プロバイダーが販売者参照をサポートしている場合は、内部の不透明な参照値を使用し、マッピングをローカルに保持します。

受信した更新については、まず正しいプロバイダーアカウントとテナント内で、保存済みのプロバイダーレコードIDを解決します。その識別子を利用できない場合は、追跡番号、配送業者の識別情報、アカウントコンテキスト、割り当て履歴を組み合わせた、文書化された方法を使用します。これは検索戦略であり、その組み合わせがグローバルに一意である保証ではありません。

顧客名、メールアドレス、またはスコープが限定されていない表示用注文番号で照合しないでください。追跡番号は文字列として保持し、先頭のゼロを維持します。該当する配送業者またはプロバイダーとの契約で正規化が許可されていない限り、文字の削除や大文字・小文字の変更は避けてください。

検索結果が一致なし、または複数の候補となった場合は、調査のため更新を隔離します。未解決のイベントは、別の顧客の注文を誤って更新するより安全です。

荷物の割り当てを作り出さずに分割注文を処理する

3個の商品を含む注文を例に考えます。荷物Aには2個、荷物Bには1個が入っています。荷物Aが配達された場合、2個について配達の証拠が得られたことを意味しますが、注文全体が配達済みになったことを意味しません。

フルフィルメントシステムが、両方の荷物が同じフルフィルメントに属することだけを記録している場合、単位レベルの割り当てを推測して作成しないでください。必要なすべての荷物が配達されたかどうかは計算できますが、割り当てデータが存在するまで、商品単位の配達状況は利用不可または明示的に不確実な状態にしてください。

永続的な取り込み層を通じて追跡APIに接続する

プロバイダーとの通信とOMSへの書き込みを分離するパイプラインを使用します。

出荷作成 → 追跡登録 → 受信更新またはスケジュール取得 → 永続的なイベント保存 → マッピングと正規化 → OMS更新 → 突合

17TRACKを実装する場合、Tracking API product pageとofficial API documentationが関連する出発点です。アダプターを実装する前に、適用される登録インターフェース、配送業者識別子、更新配信オプション、認証要件、ステータス定義、アカウント上限を確認してください。このガイドのデータモデルはインテグレーションに関する推奨であり、17TRACKがこれらのフィールド名を使用していることや、OMS用のネイティブコネクターを提供していることを示すものではありません。

選択したプロバイダーがWebhookをサポートしている場合は、文書化された仕組みで受信リクエストを認証し、受理したメッセージを応答前に永続的に保存します。時間のかかるOMS処理はリクエスト処理の外で行ってください。特定のレスポンス本文やタイムアウトを前提とせず、プロバイダーの実際の応答確認および再試行契約に従います。

ポーリングが必要な場合は、APIがサポートしている取得進捗を保存し、同時実行数を制御し、文書化されたレート制限に従います。Webhookの受信もポーリングリクエストの成功も、OMSが更新されたことを証明するものではありません。これらの結果は別々に記録してください。

再試行と遅延イベントに耐えられる同期ルールを定義する

1. 処理を冪等にする

同じ観測情報を2回処理しても、出荷が重複したり、数量が2回進んだり、同じ顧客通知が再送されたりしてはなりません。HTTPは任意のPOST操作を冪等にはしません。インテグレーション側で重複防止を実装する必要があります。RFC 9110ではHTTPメソッドの冪等性が説明されています。

文書化され、利用可能な場合は、安定したプロバイダーイベントIDを使用します。それ以外の場合は、割り当てIDと、イベントタイムスタンプ、元のステータス、場所などの関連イベントフィールドからフィンガープリントを定義します。衝突やイベント説明の変更が起こり得ることを文書化してください。別のOMSアクションを発生させない場合でも、元の観測情報は保持します。

各副作用を個別に保護します。たとえば、OMSステータスの書き込みとメール通知には、それぞれ独自の重複排除制御が必要です。トランザクショナルアウトボックスまたは同等の永続的な作業レコードを使用し、プロセスがクラッシュしても、受理済みイベントが更新予定なしの状態にならないようにします。

2. イベント時刻と受信時刻を分けて保存する

イベントが発生した時刻と、インテグレーションが受信した時刻は異なる問いに答えます。元のタイムスタンプ表現および提供されたタイムゾーンオフセットとともに、両方を保存してください。タイムゾーンが不明なイベントに、倉庫のタイムゾーンを黙って割り当てないでください。

遅れて到着した輸送中スキャンは、通常、新しい配達済み状態を置き換えずに履歴を補足する必要があります。ただし、タイムスタンプだけでは不十分です。プロバイダーが訂正を発行する場合があり、イベントの時刻情報が不完全なこともあります。利用可能な場合は文書化された連番または改訂フィールドを使用し、明示的な訂正ポリシーも定めてください。

3. 元の詳細を消さずにステータスを正規化する

OMSが理解できる小規模な内部語彙を作成します。たとえば、配送業者の受け入れ待ち、輸送中、配達中、配達済み、例外、返送中などです。プロバイダーが文書化しているステータスをそこにマッピングします。これらは推奨される内部カテゴリであり、すべての配送業者に共通する定義ではありません。

元のステータスコード、説明、イベント場所、プロバイダーレコード参照、マッピングルールのバージョンを保存します。未マッピングの値は、配達済みや失敗にデフォルト設定するのではなく、確認可能な状態を作成する必要があります。ラベル作成は、元のイベントが明示的にその解釈を裏付けていない限り、配送業者が実際に受け入れた証拠として扱わないでください。

4.単純な数値ランキングではなく遷移ルールを使用する

出荷状態が常に一直線に進むとは限りません。例外の後に通常の輸送が続くことがあり、配達試行は配達そのものではありません。以前に配達イベントがあった後に返送が始まる場合もあります。

  • その後の証拠が輸送再開を示す場合、例外を解消できるようにします。
  • 通常の過去スキャンによって、配達済み状態が黙って置き換えられないようにします。
  • 文書化された訂正を、管理された改訂経路で許可します。
  • OMSがサポートする場合、返送の移動を出荷完了とは別に追跡します。
  • 曖昧または矛盾する証拠を運用キューに送ります。

これらのルールにはバージョンを付けます。マッピングを変更した場合、新しいイベントだけに適用するのか、履歴レコードにも管理された再計算が必要なのかを決定してください。

必要なフルフィルメント義務から注文ステータスを計算する

荷物ステータスと注文ステータスは別のフィールドにしてください。配達済みとマークされた荷物はその荷物の証拠を提供しますが、注文完了は残りの必要数量と業務ポリシーに依存します。

有用なデフォルトは、配達が必要なすべての数量について有効な荷物単位の配達証拠があり、未解決の必要な割り当てがない場合にのみ、注文を完全配達済みとすることです。キャンセル数量はOMSのキャンセルルールに従って除外します。デジタル商品、店舗受取、その他の非配送義務は、それぞれ独自の完了条件で処理してください。

交換出荷には明示的な関係が必要です。紛失した荷物を交換する場合、交換品が元の配達義務に取って代わるかどうかを決定します。そうしないと、元の荷物が注文完了を無期限に妨げたり、両方の荷物がフルフィルメントに算入されたりする可能性があります。追跡ステータスだけから導出せず、判断を記録してください。

配達完了を、決済上のクローズ、返金資格、紛争解決とは分けて管理します。配送業者の配達イベントだけで、返金を自動的に承認したり、顧客の請求を解決したりしてはなりません。

監査証跡を失わずに障害から復旧する

一時的な障害は、上限付きバックオフと文書化された再試行指針を使用して再試行します。一時的な接続障害を、無効な識別子、期限切れの認証情報、権限エラー、スキーマ非互換と分けてください。後者には無限の再試行ではなく、是正措置が必要です。

影響を受けたテナント、荷物、イベント参照、試行した操作、エラー分類、次のアクションを含む失敗作業キューを保持します。不要な顧客データや認証情報をログにコピーせず、調査に必要な十分なコンテキストを記録してください。

通常の更新経路に加えて突合を実行します。追跡情報が古いアクティブな出荷、OMSへの書き込みに失敗した受理済みイベント、一致しない観測情報、インテグレーションが計算した状態とOMSの差異を確認します。確認頻度は、配送上の約束、API制限、運用リスクに基づいて決め、任意の共通スケジュールを適用しないでください。

所有者を割り当てます。エンジニアリングは取り込みと書き込みの失敗を処理し、フルフィルメント運用は不足している荷物関係を解決し、カスタマーサービスは顧客への連絡が必要な例外を確認します。責任者のいないキューは、単なる保存場所にすぎません。

リリース前にマッピングと業務ルールをテストする

管理されたテストデータと限定的な本番展開を使用します。以下のケースを、イベント履歴と結果として生成されるOMSレコードの両方に対してテストしてください。

  • 単一荷物の注文が正常に配達まで進む。
  • 分割注文で、1つの荷物が配達済み、もう1つが輸送中である。
  • 同じイベントを繰り返し受信しても、副作用が重複しない。
  • 配達後に古い輸送スキャンが到着する。
  • 不明な配送業者またはステータスが確認キューに入る。
  • 別のフルフィルメント義務を作成せずにラベルが交換される。
  • 承認済みのルールにより、交換出荷が元の荷物に取って代わる。
  • イベント受理後にOMSが利用できなくなる。
  • OMSへの書き込みとその応答確認の間にプロセスが再起動する。
  • 同じ表示用注文番号が2つのストアに存在しても、テナントをまたいで照合されない。

すべての受理済みイベントに追跡可能な処理結果があり、曖昧な照合では注文を自動更新できず、オペレーターが失敗した作業を安全に再実行できる状態でリリースします。これらは、APIリクエストが成功することを示すだけよりも有用な受け入れ基準です。

FAQ

追跡番号を注文に直接接続できますか?

厳密に単一荷物のワークフローであれば、初期段階では直接の関係で十分な場合があります。それでも、注文と追跡割り当ての間に内部出荷IDを使用してください。これにより、注文レコードの意味を変更せずに、分割出荷、ラベル変更、交換に対応する移行経路が得られます。

インテグレーションではWebhookとポーリングのどちらを使うべきですか?

プロバイダーがサポートし、インフラと互換性のある配信方式を使用します。Webhookは繰り返し取得を減らせる一方、ポーリングは取得ベースのワークフローや、利用可能な場合の突合をサポートできます。どちらの方式でも、永続的な保存、重複処理、復旧は必要です。

追跡イベントに一致する注文がない場合、どうすべきですか?

一致しないイベントのキューに保存し、登録レコード、テナントコンテキスト、配送業者の識別情報、出荷作成時刻を調査します。注文を作成したり、もっともらしい顧客にイベントを自動的に関連付けたりしないでください。マッピングを修正した後に再実行します。

配達通知はOMSと追跡システムのどちらから送るべきですか?

通知の種類とトリガーごとに1つの所有者を選びます。2つのシステムが同じメッセージを送信できる場合は、一方の経路を無効にするか、永続的な通知台帳を共有します。また、特に分割フルフィルメントでは、メッセージが1つの荷物を指すのか、注文全体を指すのかも決定してください。

例外ステータスは注文が失敗したことを意味しますか?

いいえ。例外は解釈が必要な観測情報であり、必ずしも恒久的な結果ではありません。理由を保持し、その後のイベントを監視し、運用チームが介入すべき時期をエスカレーションポリシーで決定します。

出典

  • 17TRACK Tracking API — APIインテグレーションの出発点となる公式製品リファレンス。
  • 17TRACK API documentation — プロバイダー固有の契約に関する実装リファレンス。導入前に適用されるインターフェースとアカウント要件を確認してください。
  • RFC 9110, Section 9.2.2: Idempotent Methods — メソッドの冪等性とアプリケーションレベルの重複防止を区別するためのHTTPセマンティクス。