UPS Tracking API：初心者向けの始め方ガイド

UPS Tracking APIを使用すると、企業は配送状況を取得し、自社のウェブサイト、アプリ、注文管理システム、またはカスタマーサービスツール内に配送更新情報を表示できます。通常、利用を開始するには、UPS開発者アカウントを作成し、アプリケーションを登録し、認証情報を取得し、追跡リクエストを送信して、そのレスポンスを顧客向けの有用なイベントに変換します。このガイドでは、APIの経験がないことを前提にプロセスを説明します。

例では、ラベル作成、料金計算、住所検証ではなく、追跡に重点を置いています。UPSはAPI製品とドキュメントを個別に提供しているため、本番ワークフローを構築する前に、登録するアプリケーションが必要な追跡機能にアクセスできることを確認してください。

UPS Tracking APIでできること

APIとは、あるソフトウェアシステムが別のシステムに情報を要求するための構造化された方法です。追跡ワークフローでは、システムが追跡番号などの配送識別子を配送業者または追跡プラットフォームに送信します。サービスは、リクエスト時点で利用可能なサービス、配送内容、レスポンスフィールドに応じて、現在のステータス、ステータスの説明、位置情報、日付、荷物のマイルストーンなどを含む配送データを返します。

このデータは、次のような実用的な機能を支援できます。

• ECストアに埋め込まれた追跡ページ。
• 注文管理システムまたはエンタープライズリソースプランニングシステム内での配送可視化。
• 配送業者のウェブサイトを手動で確認する必要を減らすカスタマーサービス画面。
• 配送例外、遅延、配達完了に関する社内アラート。
• 配送イベントに基づく購入後メッセージ。

APIがアプリケーションのロジックに取って代わるわけではありません。更新をどのくらいの頻度でリクエストするか、レスポンスをどのように保存するか、不完全なデータをどう扱うか、配送業者のステータスを顧客にどう説明するかは、引き続き自分で決める必要があります。

UPS Tracking APIとUPSウェブサイトの違い

UPSウェブサイトは、ユーザーが追跡番号を入力して結果を読むために設計されています。APIはソフトウェア向けに設計されています。追跡情報を別のシステムに自動的に表示したり、社内プロセスを開始したりする必要がある場合に役立ちます。

この違いが重要なのは、API統合には手動検索にはない責任が伴うためです。チームは認証情報を保護し、ユーザー入力を検証し、リクエストとレスポンスを適切に記録し、一時的な障害に対処し、配送業者のプラットフォーム変更後も統合が機能し続けているかを監視する必要があります。

現在の登録方法と技術要件を確認するには、UPS開発者プラットフォームから始めるのが適切です。認証方式、APIバージョン、必須ヘッダー、製品アクセスルールは変更される可能性があるため、古いチュートリアル、コードサンプル、フォーラム投稿よりも公式ドキュメントを優先してください。

リクエストを行う前に必要なもの

統合を作成する前に、次の項目を準備してください。

1. UPS開発者アカウント。公式のUPS Developer Portalを使用して、利用可能なAPIを確認し、アプリケーションを作成します。
2. アプリケーション認証情報。正確な認証情報の名称と認証フローは、現在のUPSドキュメントから確認してください。クライアントシークレットをブラウザコード、モバイルアプリケーション、公開リポジトリ、顧客から見えるページに配置しないでください。
3. テスト用の有効な追跡番号。組織がアクセスを許可されている配送物でテストし、ログに個人情報や商用配送データを公開しないでください。
4. サーバー側の統合ポイント。バックエンドサービスは、認証情報を非公開に保ち、リクエスト量を制御できるため、通常は公開ウェブページから配送業者を直接呼び出すより安全です。
5. レスポンス保存計画。必要なフィールド、保持期間、配送業者のイベントと社内注文を関連付ける方法を決めます。

初心者向けの統合ワークフロー

1. ビジネス要件を確認する

まず、製品における「追跡」の意味を定義します。顧客向けページでは、現在のステータスと配達予定情報だけが必要な場合があります。倉庫またはサポート用ダッシュボードでは、スキャン履歴、タイムスタンプ、例外の説明、元の追跡番号も必要になる場合があります。

理由なく利用可能なすべてのフィールドを要求することは避けてください。データモデルが小さいほど保守しやすく、ユーザーが必要としない情報を公開する可能性も低くなります。

2. アプリケーションを登録する

UPS開発環境でアプリケーションを作成し、現在のポータルの指示に従って関連する追跡製品を選択します。アプリケーション識別子は安全に記録してください。UPSが本番アクセスに承認、アカウント連携、または追加設定を要求する場合は、稼働開始日を約束する前にその手続きを完了してください。

プラットフォームがそのモデルをサポートしている場合は、テスト用と本番用で認証情報と設定を分けてください。これにより、テストスクリプトが稼働中のワークフローに影響を与える可能性を減らせます。

3. 認証を実装する

認証により、アプリケーションがサービスを呼び出すことを許可されていると証明できます。現在のUPSドキュメントに記載された認証方式、トークンエンドポイント、スコープ要件、ヘッダー形式に従ってください。アクセストークンは一時的な秘密情報として扱い、アプリケーションログに書き込まないでください。

適切な実装では、必要なときだけトークンを取得し、許可された有効期間中は再利用し、期限切れ後に新しいトークンを取得します。また、コードでは認証失敗と追跡番号エラーを区別する必要があります。対処方法が異なるためです。前者では認証情報または設定の確認が必要ですが、後者では入力検証が必要になる場合があります。

4. 追跡リクエストを送信する

認証後、UPSが指定する追跡操作と識別子形式を使用してリクエストを送信します。正確なURL、HTTPメソッド、ヘッダー、レスポンススキーマは、選択したAPIバージョンの公式ドキュメントに従ってください。

概念的なリクエストは次のようになります。

POST /tracking-operation
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "trackingNumber": "YOUR_TRACKING_NUMBER"
}

これは学習用の例であり、そのまま本番リクエストにコピーして使用するものではありません。操作名、エンドポイント、ヘッダー、本文は、現在のUPS APIリファレンスに記載された値に置き換えてください。APIによってはパスパラメータや異なるリクエスト構造を使用します。

5. レスポンスを正規化する

配送業者のレスポンスは、必ずしも顧客が期待する言語で記述されているとは限りません。次のような安定したフィールドを持つ社内イベントモデルを作成してください。

• 社内注文または配送ID。
• 配送業者名と追跡番号。
• 最新の配送業者ステータスコードと生の説明。
• アプリケーションで使用する正規化済みステータス。
• イベントのタイムスタンプ、および提供される場合は位置情報。
• 最後に正常に更新された時刻。

可能な限り、元の配送業者ステータスを保持してください。「輸送中」のような正規化ラベルは顧客インターフェースに便利ですが、生の説明はサポート担当者が通常とは異なるイベントを調査する際に役立ちます。

6. 更新情報の取得方法を決める

一部のシステムではスケジュールポーリングを使用します。バックエンドが対象となる配送物を指定した間隔で確認し、変更を保存する方式です。関連プラットフォームが対応している場合は、イベント通知を使用するシステムもあります。すべてのUPS追跡製品が同じ通知メカニズムを提供しているとは限りません。Webhookベースのワークフローを設計する前に、現在のドキュメントと商用条件を確認してください。

ポーリングは選択的に行うべきです。発送直後または配送中の荷物は、配達済みまたはキャンセル済みの配送物より頻繁な確認が必要になる場合があります。一時的な障害にはバックオフ付きの再試行を適用し、文書化された制限を守り、ビジネスプロセスで後続確認が必要でない限り、終端状態になった後の不要なリクエストを停止してください。

よくあるエラーと対処方法

ユーザー体験における最も重要なルールは、欠落データを確定的な結論に変換しないことです。「新しいスキャンがない」は自動的に「紛失」を意味せず、「ラベル作成済み」は必ずしも「輸送中」を意味しません。ステータスを慎重にマッピングし、例外処理をサポートチームから見えるようにしてください。

マルチキャリアAPIの方が適している場合

配送の大部分をUPSが担当しており、チームが配送業者との接続を直接管理したい場合は、UPSとの直接統合が合理的な選択となる可能性があります。ただし、配送業者が増えるたびに、別の認証モデル、データスキーマ、エラーポリシー、保守プロセスが必要になる場合があります。

複数の配送業者を利用している場合、マルチキャリアサービスによって個別統合の数を減らせます。17TRACK's Tracking APIはアプリケーションベースの配送追跡向けに設計されており、公式開発者ドキュメントで利用可能な統合モデルを説明しています。実際の要件がUPS追跡だけでなく、配送業者間で一貫した追跡レイヤーを構築することである場合は、評価する価値があります。

これは、直接的なUPS接続を自動的に置き換える理由にはなりません。必要な配送業者の対応範囲、イベントの詳細、データ保持要件、認証モデル、運用上の制限、サポートプロセス、実装全体の労力を比較してください。プロバイダーの公開ドキュメントは、技術的な概念実証の出発点として扱うべきであり、自社の配送パターンをテストする代替手段ではありません。

本番運用準備チェックリスト

• 認証情報はシークレットマネージャーに保存され、ブラウザに公開されていない。
• テスト環境と本番環境が明確に分離されている。
• リクエストにタイムアウト、制御された再試行、有用なエラーログが設定されている。
• 送信前に追跡番号が検証されている。
• 最後に正常に更新された情報が保存され、空のレスポンスで上書きされない。
• 配送業者の生メッセージと顧客向けラベルが分けて扱われている。
• ポーリング頻度がプロバイダーの公開制限と運用上の必要性に従っている。
• 認証失敗、エラー率の上昇、更新が滞っている配送物を監視で検知できる。
• サポート担当者が顧客からの問い合わせを調査するのに十分な詳細を確認できる。
• UPSがドキュメント、認証情報、エンドポイント、レスポンスフィールドを変更した際に統合を再テストする。

まずは、認証、テスト配送物1件の追跡、レスポンスの保存、簡単なステータスの表示、障害処理という1つの完全な経路から始めてください。その経路が信頼できるようになってから拡張します。基盤となるデータとエラー動作を理解する前に大規模な顧客向け追跡体験を構築するよりも、この方法の方が通常は安全です。

FAQ

少数の荷物しか追跡しない場合でもAPIは必要ですか？

通常は必要ありません。たまに検索するだけなら、配送業者のウェブサイトで手動追跡する方が実用的です。追跡が繰り返し行うワークフローの一部になる場合や、別のアプリケーション内に表示する必要がある場合に、APIの価値が高まります。

ShopifyテーマやブラウザからUPS Tracking APIを呼び出せますか？

ブラウザから直接呼び出すと認証情報が露出し、リクエスト制御が難しくなる可能性があります。通常は、サーバー側サービスまたは確立された追跡統合の方が安全です。現在のUPSドキュメントで技術要件と許可されるアーキテクチャを確認してください。

追跡APIで配送ラベルを作成できますか？

必ずしもできるとは限りません。追跡、ラベル作成、料金計算、住所検証、その他の物流機能は、別々のAPI製品である場合があります。必要な操作に合った製品を選択してください。

有効な追跡番号なのに情報がほとんど返らないのはなぜですか？

荷物がまだ最初のスキャンを受けていない、データがまだ利用可能になっていない、またはリクエストがAPIの必須形式やアクセス権限に適合していない可能性があります。空または限定的なレスポンスは、配送物が紛失した証拠ではなく、調査が必要な状態として扱ってください。

UPSを直接選ぶべきですか、それともマルチキャリア追跡APIを選ぶべきですか？

UPSが主要な配送業者で、焦点を絞った統合を望む場合は、直接接続を選択してください。複数の配送業者にまたがる1つの追跡ワークフローが運用上の目標である場合は、マルチキャリアサービスを検討してください。最終決定を下す前に、必要な配送業者とイベントシナリオをテストしてください。

出典

• UPS Developer Portal
• UPS Tracking APIのドキュメントと製品リソース
• 17TRACK Tracking API
• 17TRACK APIドキュメント