FedEx API統合のベストプラクティス

このクイックリファレンスガイドは、フェデックスとの統合体験を向上させ、デザイン、スピード、セキュリティの面で統合ソリューションの品質を確保する方法をAPIの利用者が理解できるようにすることを目的としています。

FedEx APIと効率的に統合するために、開発者は以下の統合のベストプラクティスに従う必要があります。

API URI

• テスト用と実稼働用のAPI URIは分かれています。
• 開発者は開発と統合テストにはテスト用のURIを、実稼働用には実稼働用のURIを使用する必要があります。

API URIの一覧：

テスト：https://apis-sandbox.fedex.com/

実稼働：https://apis.fedex.com/

認証の管理

• APIキーと秘密キー

• APIキーと秘密キーはアプリケーションを識別するために使用され、OAuthトークンリクエストで使用する必要があります。

1. APIキーとシークレットキーは非常に安全に取り扱う必要があります。APIキーや秘密キーをEメールで配布したり、クライアントサイドのJavaScriptを含む配布コードで配布したりしないでください。
2. APIキーや秘密キーが盗まれるとアプリケーションが危険にさらされます。認証情報が盗まれた、または漏洩したと思われる場合は直ちに秘密キーを再作成してください。
3. 秘密キーなどの機密情報のログを取らないようにしてください。

• コード内でAPIキーと秘密キーをハードコーディングしないでください。
• アプリケーションはAPIキーと秘密キーを動的に更新できるようにする必要があります。
• クライアントの認証情報は侵害されないように保管場所/安全な場所に保管する必要があります。

• OAuthトークン

• アクセストークンはウェブアプリケーションのサーバーにのみ保存されるようにし、ブラウザに公開することはできません。
• アプリケーションでトークンをハードコーディングしないでください。
• アクセストークンの安全性を確保して、侵害されないようにします。
• 新しいアクセストークンのためにOAuthトークンAPIを何度も呼び出すことは避けてください。HTTPエラーコード401が発生するまでアクセストークンをキャッシュすることをお勧めします。エラー401が発生したらOAuthトークンを再生成します。
• トークンをエンドユーザーやアプリケーションに公開しないでください。
• すべてのAPIトランザクションでHTTPSを使用します。

コーディングのプラクティス

• 最新かつ最も安全なデータ暗号化通信プロトコルへの準拠を維持するためにはTLS（Transport Layer Security）バージョン1.2以上の使用を推奨します。
• 各APIリクエストに必要な正しいAPIヘッダを設定することを忘れないでください。各APIドキュメントページの下にヘッダー情報があります。
• HTTP POSTの'Content-Type'は'application/json'である必要があります。
• サンプルコードを参考にして各APIを使ってみてください。各APIのエンドポイントには必要な要素やフォーマットなどの詳細を理解するのに役立つサンプルがいくつか添付されています。
• ユーザーや開発者が値の中に多くの小数を送信すると、奇妙なエラーが発生することがあります。重量と通貨値/金額については明示的な小数点以下2桁のみが許可されます。寸法 – 長さ、幅、高さなど – は少数をサポートしていません。

例:重量:45.26、通貨の価額/金額:100.52、長さ:10、幅:25、高さ:15

• 空の要素を送信しないようにします。

例: “Streetlines”:””

• リクエストを処理するために必要なデータのみを送信してください。

例えば、米国国内出荷の場合、国際出荷の場合のみ必要となる可能性のあるコマーシャル・インボイスや品目データの送付は避けるようにします。

• 開発時に料金などの必須ではない返信要素が返ってこなかった場合の対応を決めておきます。データを使用する前に欠落している要素がないかトランザクションの返信を評価します。

例えば、料金見積もりが機能していない場合はパッケージを出荷することができます。データを使用する前に欠落している要素がないかトランザクションの返信をテストします。

• 一般的にはFedEx APIの統合が必要な場合、ハードな依存関係を避けるようにしてください。
• 通信の遅延を低減し正確な結果を得るには以下のステップを踏んでいただく必要がございます。
  
  • フィルタリング - これを使用して探しているパラメーターで検索を絞り込みます。
  • ソート - これを使用すると特定のパラメータで結果を昇順または降順にソートできます。
• 必須フィールドの検証 – 受信者の郵便番号やパッケージの重量などトランザクションを送信する前にデータを取得しておきます。データが該当するフィールドに対して適切であることを確認します。これによりトランザクションエラーを最小限に抑えることができます。

例えば、米国の郵便番号の場合、フィールドがすべて数字であり、5桁またはZIP+4の郵便番号形式であることを確認します。

• フェデックスのシステムの有効性と信頼性への悪影響を回避するには：
  
  • テスト環境または実稼働環境でパフォーマンステストを実行しないでください。
  • 同じトランザクションが何度も失敗しないようにコーディングロジックを実行します。
• 制限値は10秒間で1400件のトランザクションに設定されています。最初の数秒でこの制限に達した場合、HTTPエラーコード「429 Too many requests」が返され、10秒に達するまでトランザクションが制限されますが、その後、トランザクションは再開されます。
  

例えば、最初の4秒間に1400件のリクエストを受信した場合、HTTPエラーコード429 Too many requests -「短い期間にあまりにも多くのリクエストを受信しました。しばらくしてからやり直してください。」というメッセージが返され、トランザクションは次の6秒間制限され、その後、再開されます。

• サービスの種類、パッケージの種類、重量制限などのビジネスルールは変更されることがありますのでハードコーディングしないようにします。

エラー処理

各APIのレスポンスにはHTTPステータスコードとレスポンスペイロードが含まれます。レスポンスの中にはエラーや警告、注意事項などが含まれているものもあります。警告や注意事項は障害の兆候ではありませんが、エラーや警告メッセージはログに記録して調べる必要があります。適切なエラー処理を行うことでフェデックスとの統合がスムーズに進み、障害を回避することができます。

HTTPステータスコード

料金

• 料金見積もりを取得するには2つの方法があります。
  
  • 特定のサービスタイプの料金 - 表示されたサービスタイプの値によって結果がフィルタリングされます。これによりリプライのサイズが小さくなり、トランザクションの応答時間が短縮されます。
    

    Example: STANDARD_OVERNIGHT

  • レート・ショップ – サービスタイプが指定されていない場合は該当するすべてのサービスとそれに対応する料金が返されます。
• 利用可能サービスAPIを使用して、指定された出荷地-仕向地の組み合わせで利用可能なサービス、パッケージオプション、および特別サービスを決定し、料金リクエストでserviceTypeとパッケージオプションを渡します。
  

  例えば、STANDARD_OVERNIGHTは特にすべての郵便番号間で利用できるわけではありません。

• 貨物に特別サービスを適用する場合は特別サービスの種類とその内容を記載する必要があります。
  
  • 注: 詳細が記載されていない特別サービスもあります。
• Rate APIドキュメンテーションを参照してください。

出荷

• 利用可能サービスAPIを使用して、特定の出荷地と仕向地の組み合わせで利用可能なサービスを判別し、出荷リクエストでserviceTypeおよびパッケージオプションを渡します。
• 貨物に特別サービスを適用する場合は特別サービスの種類とその内容を記載する必要があります。
  • 注: 詳細が記載されていない特別サービスもあります。
• 貨物の集荷前の出荷日の終わりにFedEx Groundのクローズを実行します。
• 出荷APIドキュメンテーションを参照してください。
  

追跡

• 1回の追跡リクエストの追跡番号の数を30に制限します。これにより、リプライのサイズが小さくなり、トランザクションの応答時間が短縮されます。
  
• パッケージを追跡する回数を、ビジネスに必要な回数に制限します。
• バッチ追跡の場合、バッチから「配達済み」という追跡ステータスを返したパッケージをすべて削除します。
• 「追跡API書類」を参照してください。

住所の検証

• 住所の検証はフェデックスがご提案するものであり、最終判断されたものではありません。エンドユーザーは、提供されたデータとそのビジネスニーズから、住所が使用可能かどうかを最終的に判断する必要があります。発注を処理できるように、有効性を確認できない住所を処理するためのプロセスを用意する必要があります。
• より良い配達体験を実現するために、配達プロセスを住所検証などのオプションサービスに依存させないでください。
  
  

例えば、注文入力時や出荷時に住所検証APIが利用できない場合は、出荷を完了させるために例外処理を設定しておく必要があります。

• 住所検証APIドキュメンテーションを参照してください
  

フェデックス営業所の検索

• 特定の属性（場所の種類、提供されるサービスなど）を指定して検索を絞り込むことで、適切な場所のオプションと迅速なレスポンスを得ることができます。
• 「フェデックス営業所検索API書類」を参照してください。
  

集荷予約

• 集荷のスケジュールを設定する場合は、過去の準備完了時刻、過去の日付、または未来の日付を入力しないでください。
• 匿名の集荷は許可されていません。
• Pickup Request APIドキュメンテーションを参照してください。
  

利用可能なサービス

• FedEx Express（FDXE）、FedEx Ground（FDXG）、FedEx Freight（FXFR）、FedEx Ground® Economyなどの複数の事業会社の結果を取得するには、複数の運送業者コードを指定することはできないため、carrierCodes要素を省略するか個別のサービス可用性リクエストを送信してください。
• 個々のスキッドが151ポンド以上、スキッド合計が2,200ポンドを超える場合は事前承認を取得済みであることを確認してください。
• 可変オプションにSATURDAY_DELIVERYを指定すると土曜日配達がオプションになっているすべてのサービスで土曜日配達オプションと通常のオプションの両方を取得します。特別サービスに SATURDAY_DELIVERY を指定しないでください。指定すると該当する土曜日の配達オプションのみが返されます。
• 利用可能サービスAPIドキュメンテーションを参照してください。

カスタマーサポート

さらにサポートが必要な場合は、支援をご提供します。リソースとお問い合わせ方法に関する情報についてはサポートページを参照してください。