配送追跡APIを使用してプロアクティブな配送通知を送信する方法
Shipment tracking APIでプロアクティブな配送通知を送信するには、各荷物を注文に関連付け、追跡情報の更新を取り込み、それらの更新を顧客に関連するイベントへ変換し、メール、SMS、またはアプリ通知サービスを通じてメッセージを送信します。受信する追跡データと送信するメッセージの間に、永続的なキューと重複チェックを配置し、繰り返し発生する更新や遅延した更新によって混乱を招くアラートが生成されないようにします。
このガイドは、このワークフローを構築する開発者およびEコマース運用チームを対象としています。目的は、配送業者のすべてのスキャン情報を転送することではありません。重要な変化がいつ起きたのか、その変化が何を意味するのか、顧客が対応する必要があるのかを伝えることです。
APIに接続する前に通知ワークフローを設計する
Shipment tracking APIは追跡情報を提供しますが、その情報をどのように使用するかはアプリケーションが決定します。選択したサービスが両方を提供している場合でも、配送状況の可視化と顧客コミュニケーションは別々の責任として扱ってください。
実用的なアーキテクチャは6つの段階で構成されます。
- 注文の関連付け: 必要に応じて、追跡番号と配送業者識別子を社内の配送記録に関連付けます。
- 追跡の登録: プロバイダーの統合要件に従って、配送を送信または登録します。
- 更新情報の取り込み: Webhookコールバックを受信するか、APIリクエストを通じて更新情報を取得するか、両方の方法を組み合わせます。
- イベント処理: 受信イベントを検証、正規化、重複排除し、評価します。
- 通知の判断: 通知するかどうか、誰に連絡するか、どのチャネルとテンプレートを使用するかを決定します。
- メッセージ配信: 通知を送信し、メッセージングサービスの応答を記録します。
統合上どうしても共有する必要がない限り、顧客の連絡先情報は自社の注文システムまたはメッセージングシステムで管理してください。通常、追跡サービスが、アプリケーションで追跡イベントと注文を関連付けるためだけに顧客のメールアドレスを必要とすることはありません。
1. 統合契約を確認する
受信処理を作成する前に、プロバイダーのドキュメントで、認証、配送登録、配送業者の識別、対応する更新方法、レスポンス形式、リクエスト制限、エラー処理を確認してください。Webhook統合の場合は、コールバックの認証方法、受信を確認するレスポンス、配信に失敗した場合の処理方法も確認します。
17TRACKを実装する場合は、17TRACK Tracking APIページと公式APIドキュメントから始めてください。このガイドに記載されている例示的なフィールド名を17TRACKのリクエストまたはレスポンスフィールドとして扱うのではなく、統合にはドキュメント化された契約を使用してください。実装前に、コールバック設定、セキュリティ要件、アカウント固有の制限を確認します。
統合契約に従って更新方法を選択します。
- Webhooks: インフラストラクチャに適しており、サポートされている場合はコールバックを使用します。プロバイダーが更新を送信した時点でアプリケーションが更新を処理できるため、同じ配送を繰り返しリクエストする必要がありません。
- Polling: コールバックが利用できない、または適していない場合は、スケジュールに従って追跡情報を取得します。スケジュールは文書化されたリクエスト制限内に収めてください。
- 組み合わせた方法: 通常の処理にはコールバックを使用し、プロバイダーがそのワークフローをサポートしている場合は、更新が古く見える配送を照合するために選択的なAPI取得を行います。
Webhookを使用しているという理由だけで、顧客に即時通知を約束しないでください。上流の追跡データで利用可能になる前に、アプリケーションが配送業者のイベントを報告することはできません。
2. 実際の注文に耐えられる配送記録を構築する
主な参照には追跡番号だけでなく、社内配送IDを使用してください。1つの注文に複数の荷物が含まれる場合があり、追跡番号が永続的にグローバルで一意であるとは限りません。
有用な社内記録には次の情報が含まれます。
- 社内注文IDと配送ID。
- 判明している場合は、追跡番号と配送業者識別子。
- 提供されている場合は、プロバイダーの配送参照番号。
- 現在の正規化されたステータスと最新の重要イベント。
- 利用可能な場合は、タイムゾーンまたはオフセットを含む配送業者のイベント時刻。
- システムが更新を受信した時刻。
- 顧客のコミュニケーション設定への参照。
- 通知履歴と有効な例外処理ワークフロー。
イベント時刻と受信時刻は別々に保存してください。以前に発生したスキャンが、新しいスキャンの後に到着する場合があります。アプリケーションが到着順だけで並べ替えると、配達済みの配送を誤って輸送中に戻してしまう可能性があります。
分割注文の場合は、通知を対象の荷物に関連付けてください。別の荷物がまだ輸送中である場合、「ご注文の商品が到着しました」よりも「ご注文の荷物の1つが到着しました」のほうが正確です。
3. 追跡イベントを顧客の判断にマッピングする
配送業者の説明は運用データであり、そのまま顧客向けメッセージとして使用できるものではありません。元のイベントを保持しながら、通知ルールが理解できる社内カテゴリを割り当てる正規化レイヤーを構築してください。
以下のカテゴリは、推奨されるアプリケーション上の概念であり、普遍的なAPIステータスの語彙ではありません。
| 社内カテゴリ | 通知の判断 | メッセージ上の境界 |
|---|---|---|
| 配送情報を受信 | 役立つ場合に限り、準備状況の更新を送信します。 | ラベルの作成だけで、配送業者が実際に荷物を保有していることを示唆しないでください。 |
| 輸送中 | 最初の重要な移動時に通知することを検討します。 | 顧客の次の行動が変わらない通常の施設スキャンは抑制します。 |
| 配達中 | サポート対象のイベントがこのステータスを示した時点で通知します。 | ステータスを確実な到着時刻に変換しないでください。 |
| 配達試行または受け取りが必要 | 対応が必要な通知を送信します。 | 確認済みの場合に限り、期限や受け取り方法を記載します。 |
| 配送例外 | 原因と顧客が対応する必要があるかどうかを評価します。 | すべての例外を荷物の紛失として説明しないでください。 |
| 配達済み | 荷物単位の確認を送信します。 | 受取人、配達場所、配達証明を勝手に作成しないでください。 |
不確実性を保持してください。認識できないイベントは、よく似たカテゴリに無理に分類するのではなく、確認またはフォールバック処理に送ります。トラブルシューティングを行うサポート担当者が利用できるよう、元の説明を保持してください。
4. 作業を失ったり重複させたりせずに更新を受信する
Webhookエンドポイントでは、リクエストを検証し、受け入れた更新を永続的に保存してから、プロバイダーが要求する確認応答を返す必要があります。コールバックリクエスト中にメールまたはSMSサービスを待機するのではなく、メッセージ生成を非同期で実行してください。
プロバイダーが文書化しているコールバック検証方法を実装してください。署名ヘッダーを勝手に作成したり、すべてのプロバイダーが同じ認証方式を使用すると想定したりしないでください。また、HTTPS、リクエストサイズの制限、ペイロード検証、適切なアクセス制御を適用します。
簡略化した処理フローは次のようになります。これはアプリケーションレベルの処理であり、動作するSDKの例ではありません。
コールバックを受信
文書化されたプロバイダーの仕組みでリクエストを検証
ペイロードを検証
受け入れたペイロードを永続化し、処理キューにアトミックに追加
文書化された確認応答を返す
キューに入った更新を処理
社内配送を検索
関連するイベントを正規化
処理済みのイベントを無視
時系列と状態遷移を評価
ポリシーで許可されている場合は通知ジョブを作成
状態とジョブを同時にコミット
通知ジョブを送信
受信者の設定と抑制ルールを確認
メッセージングサービスにメッセージを送信
結果を記録し、適切な場合のみ再試行
アトミックな処理が重要です。アプリケーションがステータス変更を保存した後、通知ジョブを作成する前にクラッシュすると、顧客が通知を受け取れない可能性があります。トランザクショナルアウトボックスは設計の選択肢の1つです。同じデータベーストランザクションで状態変更と保留中のジョブを保存し、その後ワーカーにジョブを送信させます。
不明な配送参照番号は明示的に処理してください。どの顧客に通知すべきかを推測するのではなく、調査または照合のために隔離します。
5. 重複防止と時系列チェックを追加する
受信処理は、繰り返し送信されるコールバックやワーカーの再試行に耐えられるように設計してください。文書化された安定したプロバイダーイベント識別子がある場合は、それを優先します。ない場合は、社内配送ID、イベントコード、イベント時刻、場所などの適切なフィールドから決定論的なイベントフィンガープリントを作成します。依存する前に、実際のペイロードに対してそのフィンガープリントをテストしてください。
イベントの重複排除と通知の抑制は、異なる問題を解決します。重複排除は同じイベントが2回処理されるのを防ぎます。抑制は、複数の異なるスキャンによって本質的に同じ顧客向けメッセージが生成されるのを防ぎます。
ビジネスイベントを中心に通知の識別子を定義します。配達確認には、配送IDと配達マイルストーンを使用できます。配達試行には、後の試行が本当に新しいイベントである可能性があるため、試行固有の識別子が必要になる場合があります。
順序が前後する更新については、イベントのタイムスタンプを比較し、許可された状態遷移を評価します。コールバックに新しいスキャンだけが含まれると想定せず、文書化された構造が個別のイベント、スナップショット、履歴のいずれを表すのかを確認してください。矛盾する更新は、すべての修正を黙って破棄するのではなく、照合処理に送ります。
6. 次に何が起こるかを説明するメッセージを書く
各通知では、対象となる荷物、確認された変更、顧客が次に取るべき行動を記載してください。安全な追跡リンクと、識別しやすい注文参照番号を含めます。SMSメッセージやロック画面のプレビューでは、完全な住所や不要な個人情報を表示しないでください。
例:
- 配達中: 「注文 {order_reference} の荷物は配達中です。こちらで配送状況を確認できます: {tracking_link}」
- 配達を試行: 「配送業者から、お荷物の配達を試みたとの報告がありました。次に利用できる手順は追跡ページでご確認ください: {tracking_link}」
- 配達済み: 「配送業者により、注文 {order_reference} の荷物は配達済みと記録されています。利用可能な配達詳細を確認してください: {tracking_link}」
プレースホルダーは検証済みのデータからのみ表示してください。配送予定が利用可能で表示に適している場合は、予定であることを明記します。情報がない場合は、日付を勝手に作成せず省略してください。
例外については、配送上の問題と顧客が行うべき作業を区別してください。混乱には説明だけが必要な場合がありますが、確認済みの住所問題には対応が必要な場合があります。信頼できない自由記述の追跡コンテンツだけを根拠に、顧客を支払いページや書類アップロードページへ誘導しないでください。
顧客の設定、チャネルの許可、緊急性、適用される規則に基づいてチャネルを選択します。利用する地域とメッセージングチャネルについて、同意、オプトアウト、静穏時間の要件を確認してください。配送サービスの通知はプロモーションキャンペーンと分け、同じ許可が両方を対象にすると想定しないでください。
7. 追跡情報の更新が途絶えた場合の処理を定義する
プロアクティブなコミュニケーションでは、新しいイベントだけでなく進捗がない場合も扱う必要があります。ただし、沈黙だけで配送の遅延や紛失が証明されるわけではありません。
サービスレベル、経路、最後の重要イベント、サポートされている配送予定を使用して、追跡が古くなった場合のルールを作成します。すべての配送に一律の待機期間を適用するのではなく、運用データとサポートプロセスに基づいてしきい値を設定してください。
そのルールが発動したら、処理漏れがないか確認し、サポートされている場合は追跡元と照合し、社内サポートタスクを開始するかどうかを判断します。顧客に通知する場合は、把握している事実を反映した表現を使用してください。「新しい追跡情報を受信していません」は、「荷物を紛失しました」とは異なります。
未解決の例外には担当者を割り当ててください。解決への道筋を作らずに問題を繰り返し知らせるだけの通知システムは、顧客の不満を増大させる可能性があります。
8. 自動送信を有効にする前に全経路をテストする
まずシャドーモードでワークフローを実行します。実際のイベントまたは承認済みのテストイベントを取り込み、通知案を生成し、顧客に連絡せずに結果を確認します。
- 同一のコールバックを再生し、別のメッセージが作成されないことを確認します。
- 配達済みイベントの後に、より古い輸送中イベントを処理し、結果の状態を確認します。
- タイムスタンプの欠落、不明なステータス、不正なペイロードをテストします。
- 確認応答前のデータベース障害と、永続化後のワーカー障害をシミュレーションします。
- サービスがすでにメッセージを受け入れている可能性がある不確実な応答を含め、メッセージングのタイムアウトをテストします。
- 分割配送で荷物ごとの文言が生成されることを確認します。
- オプトアウトした受信者、無効な連絡先情報、静穏時間の処理を確認します。
- 追跡リンクから他の顧客の注文情報が漏洩しないことを検証します。
受け入れたコールバック、処理エラー、キューの経過時間、通知ジョブ、重複抑制、メッセージング結果を監視します。処理遅延は、配送業者イベントの経過時間とは別に、システムの受信時刻から測定してください。この区別により、通知の遅延が上流のデータ提供によるものか、自社のパイプラインによるものかを特定しやすくなります。
まずは、十分に理解された少数のマイルストーンから始めてください。サポートチームと運用チームが、メッセージが正確で、対応可能で、受け取る価値があると合意してからルールを拡張します。
FAQ
Shipment tracking APIはメールやSMSを自動的に送信しますか?
必ずしもそうではありません。追跡データへのアクセスと顧客へのメッセージ送信は別の機能です。サービスの文書化された範囲を確認してください。カスタム統合では、アプリケーションが追跡情報を処理し、別のメッセージングサービスを通じて通知を送信できます。
すべての追跡スキャンについて顧客に通知すべきですか?
通常は必要ありません。重要なマイルストーンと対応が必要なイベントを優先してください。複数の施設スキャンは、顧客が知るべき内容を変えない通常の輸送を示している場合があります。詳細な履歴は追跡ページに残してください。
リアルタイムの配達通知を保証できますか?
システムが更新を受信した後の処理目標を設定し、監視することはできます。配送業者がスキャンを記録または公開する時期を保証することはできません。この依存関係を反映した表現でサービスを説明してください。
配達メッセージの重複を防ぐにはどうすればよいですか?
永続的なイベント重複排除、各ビジネスマイルストーンに固有の通知識別子、トランザクショナルなジョブ作成を使用してください。メッセージングサービスが冪等性をサポートしている場合は、追加の保護策として使用します。メモリ内の重複チェックだけでは、再起動や複数ワーカーに耐えられません。
配送業者が配達済みステータスを訂正した場合、どうすべきですか?
両方のイベントを保持し、配送の状態を照合してください。訂正が顧客に実質的な影響を与える場合は、ポリシーに従って明確な訂正通知を送信するか、サポートへ送ります。コードを簡略化するためだけに、配達済みステータスを永久に変更不能にしないでください。
Sources
以下の公式リソースは、上記で説明した17TRACK統合の実装リファレンスです。このガイドの社内スキーマ、通知ルール、処理フローはアーキテクチャ上の推奨事項であり、引用されたAPI契約ではありません。
- 17TRACK Tracking API — API統合を評価するための公式の出発点。
- 17TRACK API documentation — プロバイダー固有のリクエスト形式、認証、追跡操作、統合要件のリファレンス。


