Public API 사용 가이드

FoxPhone Public API를 사용하면 현재 계정의 클라우드폰과 프록시를 조회하고 기기 초기화 및 프록시 바인딩 작업을 일괄 요청할 수 있습니다. 현재 버전은 다음 네 가지 엔드포인트를 제공합니다.

1. API Key 준비

오른쪽 상단의 프로필 이미지를 클릭하고 Settings를 선택한 다음 계정 프로필에서 API Key 페이지를 여세요.

API Key 페이지에서 Key를 생성하세요. 계정당 활성 Key는 하나만 허용됩니다:

• Key를 다시 생성하면 이전 Key는 즉시 무효화됩니다.
• Key를 비활성화하면 모든 Public API 요청이 즉시 거부됩니다.
• 전체 Key는 생성 시 한 번만 표시됩니다. 통제된 비밀 관리 시스템에 보관하세요.

요청 헤더에 Key를 전달하세요:

X-API-Key: <your_api_key>

보안 안내: API Key를 URL, 요청 본문, 소스 코드, 로그 또는 지원 티켓에 넣지 마세요. 이 가이드의 리소스 ID와 Key는 예시용 값입니다.

2. 일반 규칙

• 운영 환경 기본 URL: https://api.foxphone.com/public_api/v1
• 네 엔드포인트는 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 을 참고해 리소스 상태를 해결하고 같은 요청을 바로 다시 제출하지 마세요.