UPS Tracking APIの使い方：ステップごとの設定ガイド
UPS Tracking APIを使用するには、UPS Developerアカウントを作成し、アプリケーションを登録して、OAuth 2.0認証情報を取得し、有効なUPS追跡番号を使用してアクセストークンをリクエストし、認証済みの追跡リクエストを送信します。ポータル上の正確なラベル、承認手順、API要件は変更される可能性があるため、本番環境の統合を稼働させる前に、公式UPS Developer Portalで最新の手順を確認してください。
このガイドは、オンラインストア、注文管理システム、倉庫業務、カスタマーサービスツール、社内ダッシュボードなどで、配送状況を必要とする開発者およびEC運用チーム向けです。統合の手順、信頼性に影響する判断、一般的な追跡エラーを防ぐための確認事項に焦点を当てています。
UPS Tracking APIでできること
API統合を利用すると、従業員や顧客が配送業者の追跡ページを手動で開かなくても、ソフトウェアからUPSに配送情報をリクエストできます。アプリケーションは、レスポンスを使用して最新の既知のステータスを表示したり、配達イベントを特定したり、カスタマーサービスでの調査を支援したり、社内ワークフローを開始したりできます。
APIは追跡ページと同じものではありません。追跡ページは人が読むために設計されています。一方、APIレスポンスは、ソフトウェアが解析、保存、表示する必要がある構造化データです。認証、エラー処理、ポーリングまたはイベント収集、データ保持、ユーザーインターフェースの設計、配達イベントに基づくビジネスルールについては、引き続きシステム側で対応する必要があります。
開始前の準備
Developer Portalを開く前に、次の項目を準備してください。
- UPS Developerアカウント、または現在のUPSオンボーディングプロセスで必要とされるアカウント種別。
- 登録済みのアプリケーションと、そのアプリケーションに発行された認証情報。
- テスト用追跡番号、または承認された別のテスト方法。UPSのドキュメントに個別のテスト環境やテスト手順が記載されている場合は、実際の顧客データから始めないでください。
- 配送記録、追跡イベント、顧客向けステータスメッセージをどのシステムが管理するかについての明確な決定。
- クライアント認証情報とアクセストークンを安全に保存する場所。シークレットをブラウザコード、公開リポジトリ、スクリーンショット、またはユーザーが検査できるモバイルアプリケーションに決して含めないでください。
アプリケーションに必要なのが追跡のみか、それともより広範なUPS統合かについても決定しておく必要があります。追跡、料金計算、発送、住所検証、書類サービスでは、製品、権限、リクエスト形式、運用要件が異なる場合があります。
ステップ1：UPS Developer Portalを開く
公式UPS Developer Portalから開始します。現在のAPIカタログ、認証ガイダンス、オンボーディング要件、利用規約、環境情報を確認してください。別のUPSサービス向けの手順も追跡に適用できると決めつけず、Tracking APIのドキュメントを具体的に探してください。
現在のリクエストフィールド、認可スコープ、レスポンス定義、レート制限、エラーコード、環境の詳細については、ポータルが適切な情報源です。これらの詳細は変更される可能性があり、第三者のコード例では古いUPSインターフェースや旧式の認証方式が使用されている場合があります。
ステップ2：アプリケーションを登録する
Developer Portalでアプリケーションを作成し、実際に必要なUPS APIを選択します。追跡のみのプロジェクトでは、ワークフローで追加サービスが必要な場合を除き、追跡機能のみをリクエストしてください。権限を限定すると、設定の複雑さが軽減され、後のトラブルシューティングが容易になります。
アプリケーション識別子とシークレットは、サーバー側のシークレットマネージャーまたは保護された環境変数システムに保存します。シークレットはパスワードと同じように扱ってください。公開された場合は、UPSが提供する手順でローテーションし、不正使用がないかログを確認してください。
ポータルでアカウント、請求、事業、またはアプリケーションに関する情報を求められた場合は、正確な情報を提供してください。テストを完了するためだけに本番での利用目的を偽ったり、他人のアカウント情報を使用したりしないでください。サービスへのアクセスは、アカウント設定や現在のUPSの承認プロセスに左右される場合があります。
ステップ3：OAuth 2.0認証を実装する
現在のUPS開発者向けドキュメントでは、APIにOAuthベースの認証を使用しています。通常、サーバーは文書化されたトークンフローを通じてアプリケーション認証情報を交換し、アクセストークンを受け取ります。その後、APIリクエストの認証ヘッダーにそのトークンを含めます。
認証と追跡ロジックは分離してください。実用的な設計では、有効なトークンを取得してキャッシュするコンポーネントと、追跡エンドポイントを呼び出すコンポーネントを分けます。トークンコンポーネントは次の処理を行う必要があります。
- 認証情報を、文書化されたUPS認証エンドポイントにのみ送信する。
- 現在のUPSドキュメントで指定されているコンテンツタイプと付与パラメーターを使用する。
- トークンを一時的に保存し、追跡番号ごとに新しいトークンをリクエストするのではなく、期限切れまで再利用する。
- 文書化された有効期限の条件に達したときに、トークンを更新または再取得する。
- アプリケーションログ、エラーレポート、サポートチケットから認証情報とトークンをマスキングする。
ブラウザーセッションからトークンをコピーして、永続的な統合に使用しないでください。バックエンドサービスは、シークレットを公開クライアントコードから分離できるため、一般に認証情報を管理するより安全な場所です。
ステップ4：追跡リクエストを構築する
公式Tracking APIリファレンスに示されているリクエスト形式を使用します。一般的なリクエストには、パスまたはリクエストパラメーター内の追跡番号、認証ヘッダー内のアクセストークン、UPS APIで必要とされるヘッダーが含まれます。追跡番号だけが必要な値だと決めつけないでください。現在のリファレンスでは、バージョン、トランザクション、コンテンツタイプ、相関ヘッダーなどが指定されている場合があります。
簡略化したリクエストのパターンは次のようになります。
GET [UPS tracking endpoint]/[tracking-number]
Authorization: Bearer [access-token]
Accept: application/jsonこれは構造上の例であり、そのままコピーして使用するエンドポイントではありません。アプリケーションについてUPSドキュメントに公開されているエンドポイント、バージョン、ヘッダー、パラメーター名を使用してください。追跡番号は独自の注文データルールに従って正規化しますが、配送業者のドキュメントで安全であることが確認されていない限り、文字を削除しないでください。
ステップ5：イベントをデータモデルに取り込む
配送業者のレスポンスには、単一のステータスラベルよりも多くの情報が含まれることがよくあります。顧客向けページをコーディングする前に、レスポンスを配送識別子、配送業者、最新ステータス、イベントコード、イベントの説明、イベント日時、場所、配達予定情報、利用可能な場合は配達完了日時などの内部モデルにマッピングします。
保持およびプライバシーポリシーで許可される場合は、配送業者の元のレスポンスを保持してください。生のレスポンスは、マッピングエラーの診断や、正規化されたステータスが配送業者の表現と異なる理由の説明に役立ちます。同時に、読みやすい説明なしに技術的なイベントコードを顧客に表示することは避けてください。
すべてのステータスを最終的な配達結果として扱わないでください。たとえば、輸送中のイベント、例外、配達試行、配達完了イベントを同じ顧客向けメッセージにまとめるべきではありません。明示的なマッピングを作成し、UPSがコードで認識できないイベント値を追加した場合の処理を定義してください。
ステップ6：リトライ、検証、監視を追加する
本番環境の統合には、開発コンソールでリクエストが成功すること以上の対応が必要です。検証と運用上の保護策を追加してください。
- 入力検証：リクエストを送信する前に、空白、形式不正、明らかに不完全な追跡番号を拒否する。
- タイムアウト：配送業者からの遅いレスポンスによって、チェックアウト、サポート、倉庫業務全体がブロックされるのを防ぐ。
- リトライルール：一時的なネットワークまたはサービス障害は、バックオフを使用して慎重に再試行する。認証エラーや無効な追跡番号を繰り返し再試行しない。
- レートの把握：UPSドキュメントの制限と利用ルールに従う。業務プロセスで許可される場合は、最近の結果をキャッシュする。
- 不明な状態：認識されないイベントを、配達済みまたは紛失と誤って表示するのではなく、確認のために保持する。
- 可観測性：シークレットや不要な個人データをログに記録せず、リクエスト時間、レスポンス区分、相関情報を記録する。
追跡システムでは、配送の更新頻度も定義する必要があります。頻繁すぎるポーリングは不要な負荷を生み、新しい情報を取得できない場合があります。頻度が低すぎると、顧客向けページが古く見える可能性があります。配送量、運用上の緊急性、配送業者のルール、ユーザーが実際に必要とする鮮度に基づいて間隔を選択してください。
ステップ7：現実的なシナリオでテストする
配達完了した配送の成功だけをテストしてはいけません。不明な追跡番号、輸送中の配送、例外、複数のイベントを含む配送、期限切れトークン、タイムアウト、認証失敗、パーサーが想定していないフィールドを含むレスポンスをテストしてください。UPSが個別のテスト環境またはテスト認証情報を提供している場合は、まずその手順に従ってください。
リクエストからユーザーインターフェースまでの完全な経路を確認してください。正しい注文に正しい配送が割り当てられていること、日時が意図したタイムゾーンで表示されること、重複イベントによって顧客向けメッセージが重複作成されないこと、配送業者の障害によって以前の有効なステータスが誤解を招くテキストで上書きされないことを確認します。
マルチキャリア追跡APIが適している場合
業務で主にUPSを利用し、配送業者のワークフローを細かく管理する必要がある場合は、UPSとの直接統合が適しています。注文が複数の配送業者、マーケットプレイス、郵便事業者、地域配送会社を経由する可能性がある場合は、利便性が低下します。そのような状況では、個別の認証情報、レスポンス形式、ステータス用語、リトライルールによって保守作業が増える可能性があります。
17TRACK Tracking APIのようなマルチキャリアサービスは、複数の配送業者にまたがる追跡を必要とするアプリケーションに、別の統合モデルを提供できます。対応配送業者、リクエスト形式、認証、利用規約、利用可能な機能については、開発者向けドキュメントを直接確認してください。これは、直接UPSに接続するより自動的に優れているという意味ではありません。適切な選択は、配送業者の構成、データ要件、統合の管理範囲、商業上またはコンプライアンス上の制約によって異なります。
開発者向け統合ではなく消費者向けの検索が必要な場合は、API接続を構築するよりも17TRACKの追跡ページの方が適している可能性があります。ブランド化された購入後の更新を必要とするオンラインストアでは、ストアが必要としていないAPI作業を追加するのではなく、関連するプラットフォーム統合を個別に確認してください。
一般的な実装ミス
- 古い例を使用する：コードサンプルが廃止されたバージョン、古い認証方式、または別のUPSサービスを参照している場合があります。
- フロントエンドコードにシークレットを配置する：ブラウザーに配信されるものは、検査可能なものとして扱う必要があります。
- 空の結果は配送がないことを意味すると考える：業務上の結論を出す前に、追跡番号、アカウント権限、環境、レスポンスメッセージを確認してください。
- テキストだけをマッピングする：ステータスの説明は変わる可能性があります。文書化されたコードを使用し、不明な値は確認のために保持してください。
- アカウントと利用要件を無視する：技術的なコードが正しくても、アプリケーションが要求されたサービス向けに設定されていない場合があります。
- 業務ルールなしに更新する：不要なポーリングは、顧客体験を改善しないまま、コスト、負荷、運用上のノイズを増加させる可能性があります。
実用的な本番稼働チェックリスト
- アプリケーションが最新のUPSドキュメントと承認済み環境を使用していることを確認する。
- 認証情報がサーバー側に保存され、ローテーション可能であることを確認する。
- 認証失敗、配送業者エラー、不正な入力、タイムアウトをテストする。
- 代表的な配送について、正規化されたステータスと元のレスポンスを比較する。
- 更新ポリシーを設定し、リクエスト量を監視する。
- 識別できないイベント、更新遅延、顧客からのエスカレーションの担当を定義する。
- 別の開発者が認証情報、エンドポイントのバージョン、ステータスマッピングを安全に更新できるよう、統合内容を文書化する。
FAQ
Tracking APIを使用するにはUPSアカウントが必要ですか？
現在のUPSオンボーディングおよびアクセス要件をDeveloper Portalで確認してください。APIアクセスは、アプリケーション登録、認証情報、アカウント設定、リクエストする特定のサービスによって異なる場合があります。公開追跡ページのログイン情報がDeveloper APIへのアクセスにも使えると決めつけないでください。
UPS Tracking APIは無料ですか？
APIアクセスに商用条件や利用条件がないと決めつけないでください。UPSは公式チャネルを通じて最新のサービスおよびアカウント情報を公開しており、一部の要件は製品、アカウント、契約によって異なる場合があります。本番環境の予算を計画する前に、適用される条件を直接確認してください。
ブラウザーのJavaScriptからUPS APIを直接呼び出せますか？
ブラウザーからの呼び出しでは、アプリケーション認証情報が公開され、クロスオリジン、セキュリティ、利用制御に関する問題が発生する可能性があります。シークレットの保存、トークンの取得、リトライルールの適用、配送データへのアクセス制限を行うには、一般にサーバー側統合の方が安全なパターンです。
アプリケーションはどのくらいの頻度で追跡情報をリクエストすべきですか？
配送業者が文書化している制限、配送量、運用上の緊急性、ユーザーに必要な鮮度に基づいて更新ポリシーを設定してください。適切な場合は最近の結果をキャッシュし、一時的な障害の後はバックオフを使用し、文書化されたイベント機能や通知機能の代わりに繰り返しポーリングを行わないでください。
UPSとの直接統合とマルチキャリアAPIのどちらを使用すべきですか？
配送業者固有の制御が必要なUPS中心のワークフローには、UPSとの直接統合が適している場合があります。配送に複数の配送業者を利用する場合は、マルチキャリアAPIによって統合数を減らせる可能性があります。選択する前に、対応配送業者、認証、データフィールド、信頼性要件、利用規約、実装作業を比較してください。
情報源
- UPS Developer Portal — 公式APIカタログ、アプリケーションアクセス、認証、開発者向けドキュメント。
- UPS Technology Integration — UPSテクノロジーと業務システムの統合に関する公式情報。
- 17TRACK Tracking API — マルチキャリア追跡向けの公式製品および開発者向け入口。
- 17TRACK API Documentation — 認証、リクエスト、レスポンス処理に関する公式APIドキュメント。
