A Public API da FoxPhone permite listar os cloud phones e proxies da conta atual e enviar tarefas de redefinição e vinculação de proxy em lote. A versão atual oferece estes quatro endpoints.
1. Preparar uma API Key
Clique no avatar no canto superior direito, selecione Settings e abra a página API Key no perfil da sua conta.
Gere uma chave na página API Key. Cada conta pode ter apenas uma chave ativa:
- Ao gerar uma nova chave, a anterior é invalidada imediatamente.
- Ao desativar uma chave, todas as solicitações à Public API são recusadas imediatamente.
- A chave completa é exibida apenas uma vez, no momento da criação. Guarde-a em um gerenciador de segredos controlado.
Envie a chave em um cabeçalho da solicitação:
X-API-Key: <your_api_key>Aviso de segurança: Nunca inclua a API Key na URL, no corpo da solicitação, no código-fonte, em logs ou chamados de suporte. Os IDs de recursos e chaves deste guia são exemplos.
2. Regras gerais
- URL base de produção:
https://api.foxphone.com/public_api/v1 - Os quatro endpoints compartilham o limite de 60 solicitações por minuto para cada API Key.
- Para os parâmetros de lista,
page_numtem valor padrão1;page_sizetem valor padrão20, tem valor máximo100;searché opcional. - As solicitações em lote aceitam de 1 a 100
pod_ids; o servidor remove duplicatas automaticamente. - Você só pode acessar recursos da conta proprietária da API Key. Não é possível especificar outra conta por parâmetro.
- Se a validação prévia encontrar um recurso inválido ou uma operação conflitante, nenhuma solicitação do lote será enviada.
- Se ocorrerem falhas parciais após o início do envio remoto, as operações já aceitas não serão revertidas. A resposta lista separadamente os itens concluídos e com falha.
3. Listar cloud phones
Use este endpoint para listar os cloud phones da conta atual com paginação:
GET /public_api/v1/phones?page_num=1&page_size=20&search=pod-exampleUse search para localizar um cloud phone pelo nome ou pelo pod_id.
Exemplo de solicitação:
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"Exemplo de resposta:
{
"total": 1,
"phones": [
{
"pod_id": "pod-example-001",
"name": "automation-phone",
"online_status": 1,
"operating_status": 0,
"proxy_id": "42"
}
]
}proxy_id é 0 quando o cloud phone não tem proxy vinculado.
4. Listar proxies
Use este endpoint para listar os proxies existentes na conta atual com paginação:
GET /public_api/v1/proxies?page_num=1&page_size=20&search=42Use search para localizar um proxy pelo nome ou pelo proxy_id. O endpoint não retorna nomes de usuário nem senhas do proxy.
Exemplo de solicitação:
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"Exemplo de resposta:
{
"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. Enviar redefinições de dispositivos em lote
Use este endpoint para enviar tarefas de redefinição de vários dispositivos:
POST /public_api/v1/phones/actions/reset
Content-Type: application/jsonCorpo da solicitação:
{
"pod_ids": ["pod-example-001", "pod-example-002"]
}Limitação atual: O endpoint de redefinição não permite especificar proxy_id nem outros parâmetros de proxy no corpo da solicitação. Para trocar o proxy, aguarde a conclusão da redefinição e depois chame o endpoint de vinculação em lote de proxies existentes.
Exemplo de solicitação:
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"Se já houver uma redefinição em andamento para o cloud phone, uma nova solicitação retornará RESET_IN_PROGRESS durante a validação prévia e não enviará uma tarefa duplicada.
6. Vincular proxies existentes em lote
Primeiro obtenha o proxy_id pelo endpoint de lista de proxies e, em seguida, chame este endpoint:
POST /public_api/v1/proxies/{proxy_id}/bind
Content-Type: application/jsonCorpo da solicitação:
{
"pod_ids": ["pod-example-001", "pod-example-002"]
}Exemplo de solicitação:
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"O proxy e todos os cloud phones devem pertencer à conta atual. Também é possível vincular um proxy a um phone desligado. Phones em redefinição, operação de energia, reinicialização ou outra operação de proxy são recusados na validação prévia.
7. Respostas em lote
A redefinição de dispositivos e a vinculação de proxies usam a mesma estrutura de resposta:
{
"successful_pod_ids": ["pod-example-001"],
"failed_items": [
{
"pod_id": "pod-example-002",
"code": "PROVIDER_REJECTED",
"message": "provider rejected the operation"
}
]
}Uma falha na validação prévia retorna HTTP 409 e o código de erro BATCH_PRECHECK_FAILED. Nos metadados do erro, failed_items lista os respectivos pod_id, code e message; nesse caso, nada do lote é enviado.
Falhas após o início do processamento remoto são informadas na resposta da operação por meio de successful_pod_ids e failed_items para mostrar o resultado real.
8. Erros comuns
| Status HTTP | Código de erro | Descrição |
|---|---|---|
| 400 | INVALID_ARGUMENT | Formato de parâmetro, quantidade de itens ou valor de paginação inválido |
| 401 | INVALID_API_KEY | API Key ausente, malformada ou inválida |
| 403 | API_KEY_DISABLED | API Key desativada |
| 403 | USER_ACCOUNT_UNAVAILABLE | A conta proprietária da API Key não está disponível |
| 409 | BATCH_PRECHECK_FAILED | Falha na validação em lote; nada foi enviado |
| 429 | RATE_LIMIT_EXCEEDED | Limite de solicitações por minuto excedido |
Ao receber HTTP 429, tente novamente mais tarde usando backoff. Para HTTP 409, primeiro use failed_items para corrigir o estado do recurso; não reenvie imediatamente a mesma solicitação.
