Public API 利用ガイド

FoxPhone Public API では、現在のアカウントに属するクラウドフォンとプロキシを一覧表示し、デバイスのリセットやプロキシのバインドを一括で送信できます。現在のバージョンでは次の4つのエンドポイントを利用できます。

1. API Key の準備

右上のプロフィール画像をクリックして Settings を選び、アカウントプロフィールで API Key ページを開きます。

API Key ページで Key を生成します。各アカウントで有効にできる Key は1つだけです。

• Key を再生成すると、以前の Key は直ちに無効になります。
• Key を無効にすると、すべての Public API リクエストが直ちに拒否されます。
• 完全な Key が表示されるのは生成時の1回だけです。管理されたシークレット管理システムに保存してください。

リクエストヘッダーで Key を渡します。

X-API-Key: <your_api_key>

セキュリティ上の注意: API Key を URL、リクエスト本文、ソースコード、ログ、サポートチケットに含めないでください。本ガイドのリソース ID と Key はすべてサンプルです。

2. 共通ルール

• 本番環境のベース URL: https://api.foxphone.com/public_api/v1
• 4つのエンドポイントで、API Key ごとに毎分60リクエストのレート制限を共有します。
• 一覧パラメーターでは、page_num のデフォルト値は 1。page_size のデフォルト値は 20、 の最大値は 100。search は任意です。
• 一括リクエストでは1～100個の pod_ids を指定できます。サーバーが重複を自動で除外します。
• アクセスできるのは API Key を所有するアカウントのリソースだけです。パラメーターで別のアカウントを指定することはできません。
• 事前チェックで無効なリソースまたは競合する操作が見つかった場合、バッチ全体は送信されません。
• リモート送信の開始後に一部が失敗しても、受理済みの操作はロールバックされません。レスポンスには成功項目と失敗項目が別々に表示されます。

3. クラウドフォンの一覧

次のエンドポイントで、現在のアカウントのクラウドフォンをページ単位で取得します。

GET /public_api/v1/phones?page_num=1&page_size=20&search=pod-example

search では、クラウドフォン名または pod_id で検索できます。

リクエスト例:

curl --fail-with-body 
  -H "X-API-Key: $API_KEY" 
  "https://api.foxphone.com/public_api/v1/phones?page_num=1&page_size=20&search=pod-example"

レスポンス例:

{
  "total": 1,
  "phones": [
    {
      "pod_id": "pod-example-001",
      "name": "automation-phone",
      "online_status": 1,
      "operating_status": 0,
      "proxy_id": "42"
    }
  ]
}

proxy_id が 0 の場合、そのクラウドフォンにはプロキシが現在バインドされていません。

4. プロキシの一覧

次のエンドポイントで、現在のアカウントに登録済みのプロキシをページ単位で取得します。

GET /public_api/v1/proxies?page_num=1&page_size=20&search=42

search では、プロキシ名または proxy_id で検索できます。エンドポイントはプロキシのユーザー名やパスワードを返しません。

リクエスト例:

curl --fail-with-body 
  -H "X-API-Key: $API_KEY" 
  "https://api.foxphone.com/public_api/v1/proxies?page_num=1&page_size=20&search=42"

レスポンス例:

{
  "total": 1,
  "proxies": [
    {
      "proxy_id": "42",
      "name": "us-residential",
      "proxy_type": "http",
      "proxy_ip": "203.0.113.42",
      "proxy_port": "10000",
      "check_status": "available"
    }
  ]
}

5. デバイスの一括リセット

次のエンドポイントで複数デバイスのリセットタスクを送信します。

POST /public_api/v1/phones/actions/reset
Content-Type: application/json

リクエスト本文:

{
  "pod_ids": ["pod-example-001", "pod-example-002"]
}

現在の制限: リセットエンドポイントでは、リクエスト本文で proxy_id やその他のプロキシパラメーターを指定できません。プロキシを変更する場合は、リセット完了後に既存プロキシの一括バインドエンドポイントを呼び出してください。

リクエスト例:

curl --fail-with-body 
  -X POST 
  -H "Content-Type: application/json" 
  -H "X-API-Key: $API_KEY" 
  --data '{"pod_ids":["pod-example-001","pod-example-002"]}' 
  "https://api.foxphone.com/public_api/v1/phones/actions/reset"

対象のクラウドフォンでリセットが進行中の場合、新しいリクエストは事前チェックで RESET_IN_PROGRESS を返し、重複タスクは送信されません。

6. 既存プロキシの一括バインド

まずプロキシ一覧エンドポイントから proxy_id を取得し、次のエンドポイントを呼び出します。

POST /public_api/v1/proxies/{proxy_id}/bind
Content-Type: application/json

リクエスト本文:

{
  "pod_ids": ["pod-example-001", "pod-example-002"]
}

リクエスト例:

curl --fail-with-body 
  -X POST 
  -H "Content-Type: application/json" 
  -H "X-API-Key: $API_KEY" 
  --data '{"pod_ids":["pod-example-001","pod-example-002"]}' 
  "https://api.foxphone.com/public_api/v1/proxies/42/bind"

プロキシとすべてのクラウドフォンは現在のアカウントに属している必要があります。電源オフのフォンにもプロキシをバインドできます。リセット、電源操作、再起動、その他のプロキシ操作中のフォンは事前チェックで拒否されます。

7. 一括操作のレスポンス

デバイスリセットとプロキシバインドでは同じレスポンス構造を使用します。

{
  "successful_pod_ids": ["pod-example-001"],
  "failed_items": [
    {
      "pod_id": "pod-example-002",
      "code": "PROVIDER_REJECTED",
      "message": "provider rejected the operation"
    }
  ]
}

事前チェックに失敗すると、HTTP 409 とエラーコード BATCH_PRECHECK_FAILED が返されます。エラーメタデータの failed_items には対象の pod_id、code と message が一覧表示され、この場合バッチは送信されません。

リモートでの受け付け開始後に発生した失敗は、業務レスポンスの successful_pod_ids と failed_items で実際の結果を示します。

8. よくあるエラー

HTTP 429 の場合はバックオフ方式で後から再試行してください。HTTP 409 の場合は、まず failed_items に従ってリソース状態を修正し、同じリクエストをすぐに再送しないでください。