このページは英語から翻訳されています。英語版が正式な情報源です。翻訳内容に不一致がある場合は、英語版を参照してください。
環境
Flex Forward APIは、本番運用と開発テストのために2つの環境を提供しています。利用可能な環境
すべてのリクエストはHTTPSを使用する必要があります。HTTPでのリクエストは拒否されます。
開発環境
開発環境は配送業者のサンドボックスサービス（例：YunExpressサンドボックス）に接続されます。以下の用途にご利用ください：- 実際の配送を作成せずにインテグレーションをテスト
- リクエスト形式とレスポンス処理の検証
- エラーハンドリングとリトライロジックの開発
サンドボックスの配送業者サービスは、シミュレートされた追跡データとラベル文書を返す場合があります。レスポンスのタイミングや利用可能な追跡ステータスが本番と異なる場合があります。
サンドボックステストデータ
開発環境は、予測可能な追跡レスポンスを生成するテスト値をサポートしています。これらを使用して、インテグレーションがさまざまな配送結果を正しく処理することを確認してください：テスト値とシミュレートされたレスポンスは変更される場合があります。最新のサンドボックステストデータについては、Flex Forwardチームにお問い合わせください。
認証情報の分離
各環境には個別のAPIトークンをご使用ください。本番の認証情報を開発で使用したり、その逆を行ったりしないでください。どちらのペアもユーザーポータルでお客様自身が作成・管理します。Flex Forward が発行やローテーションを行うことはありません。認証情報のベストプラクティス
- APIキーとトークンを環境変数またはシークレットマネージャーに保存する
- ソースコードに認証情報をハードコードしたり、バージョン管理にコミットしたりしない
- 開発中の本番への誤ったリクエストを防ぐため、環境ごとに個別のトークンを使用する
- ご自身のセキュリティ方針で必要になった時点で、ユーザーポータルで認証情報を再生成する。Flex Forward がお客様に代わってローテーションや失効を行うことはありません
レート制限
レート制限は現在適用されていません。目安として、アカウントごとに 1秒あたり10リクエスト 以下に抑えてください。レート制限ヘッダー（X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset）は現在レスポンスに含まれていません。
すべてのエンドポイントは、すでに Retry-After ヘッダー（待機秒数）付きの HTTP 429 Too Many Requests レスポンスを宣言しています。制限が適用されても統合に影響が出ないよう、今のうちにこの処理を実装してください。429 を受け取ったら Retry-After 秒待機し、同じリクエストをリトライします。エラーハンドリングを参照してください。
将来レート制限が導入される場合は、事前通知とともに変更履歴を通じてお知らせします。高スループットのインテグレーションに関するキャパシティプランニングについては、Flex Forwardチームに [email protected] までご連絡ください。
本番移行チェックリスト
開発環境から本番環境に切り替える前に：- 推奨：まずサンドボックスでインテグレーションをテストする（開発用の認証情報は User Portal から取得）
- 本番のAPIキーとトークンをUser Portal（Settings → Signing Key and API Token）から取得済み
- 本番の配送業者用にシッパーアカウントが設定済み
- 開発環境でラベル作成が正常にテスト済み
- ラベル文書の取得がテスト済み
- 追跡の取得がテスト済み
- 冪等性の動作を検証済み（同じキーと本文はリプレイされ、本文を変更すると
IDEMPOTENCY_CONFLICTが返る） - すべてのステータスコードに対するエラーハンドリングが実装済み
- 必要な配送業者と配送ルートの設定が確認済み