Use uma API Key pessoal para listar telefones, proxies e aplicativos e solicitar redefinição, vinculação e instalação. Os seis endpoints de clientes usam https://api.foxphone.com e /public_api/v1.
| HTTP | /public_api/v1 | Descrição |
|---|---|---|
| GET | /phones | Listar telefones |
| GET | /proxies | Listar proxies |
| POST | /phones/actions/reset | Redefinir em lote |
| POST | /proxies/{proxy_id}/bind | Vincular proxy existente |
| GET | /apps | Aplicativos e versões |
| POST | /phones/actions/install-app | Instalar em lote |
Abra Settings no avatar e API Key na área pessoal. Cada conta tem uma Key ativa. Gerar novamente invalida a anterior imediatamente; o valor completo aparece uma vez. Envie X-API-Key e Content-Type: application/json em POST. Não exige JWT do site, Cookie, Device-ID, hash ou platform. Bearer não substitui o cabeçalho.
X-API-Key: <your_api_key>Guarde Key no servidor em variáveis de ambiente ou cofre, nunca em frontend, repositório público ou cliente. Não coloque em URL, corpo, logs ou chamados. Exemplos usam API_KEY. Se vazar, rotacione/desative imediatamente e atualize os consumidores.
export API_KEY="<your_api_key>"Use HTTPS. Sucesso HTTP 200, payload em data; erros 4xx/5xx com reason em texto. Confira status, reason e itens, não só message. data de erro pode ser null; guarde request_id. As credenciais de parceiros /open_api/v1 são separadas.
A mesma Key compartilha 60 chamadas/minuto. page_num/page_size omitidos ou não positivos viram 1/20; page_size acima de 100 retorna 400. Telefones/proxies usam search, apps app_name. pod_ids deve ter 1–100 strings após remoção de espaços, vazios e duplicatas. Relacione resultados por pod_id.
pod_id é sempre string. proxy_id, total, id de versão e version_code são números JSON; use leitura sem perda para inteiros grandes, especialmente JavaScript. Zero e strings vazias são mantidos; listas vazias podem ser [] ou null.
{
"request_id": "example-request-id",
"code": 200,
"data": {
"total": 0,
"phones": []
},
"message": "success"
}Lista telefones da conta atual, search por nome ou pod_id. data.phones contém pod_id, name, online_status, operating_status, proxy_id; data.total conta. proxy_id=0 indica nenhuma associação. Associação local não confirma conclusão na nuvem.
online_status: 0 iniciando, 1 executando, 2 parado, 3 parando, 4 reiniciando, 5 transmitindo, 6 transmissão pronta. operating_status: 0 iniciando, 1 executando, 2 parado, 3 parando, 4 reiniciando, 5 redefinindo; 6 indefinido. Não confunda.
| Campo | Tipo |
|---|---|
| pod_id | string |
| name | string |
| online_status | integer |
| operating_status | integer |
| proxy_id | number |
curl --fail-with-body "https://api.foxphone.com/public_api/v1/phones?page_num=1&page_size=20&search=example" \
-H "X-API-Key: ${API_KEY}"{
"request_id": "example-request-id",
"code": 200,
"data": {
"total": 1,
"phones": [
{
"pod_id": "pod-example-001",
"name": "test-phone",
"online_status": 1,
"operating_status": 1,
"proxy_id": 42
}
]
},
"message": "success"
}Busca proxies por nome ou ID. data.proxies contém proxy_id, name, proxy_type, proxy_ip, proxy_port, check_status. Porta é string; não retorna credenciais nem URL de atualização. Estado unchecked, success ou failed; registros antigos podem estar vazios. Teste anterior não garante disponibilidade atual.
curl --fail-with-body "https://api.foxphone.com/public_api/v1/proxies?page_num=1&page_size=20&search=example" \
-H "X-API-Key: ${API_KEY}"{
"request_id": "example-request-id",
"code": 200,
"data": {
"total": 1,
"proxies": [
{
"proxy_id": 42,
"name": "example-proxy",
"proxy_type": "socks5",
"proxy_ip": "203.0.113.42",
"proxy_port": "1080",
"check_status": "success"
}
]
},
"message": "success"
}Redefinir apaga dados: faça backup e confira destinos. Envie apenas pod_ids; telefones devem estar executando, disponíveis e pertencer à conta. Parados, redefinindo ou em conflito são rejeitados. phone_template_mode, inclusive 0, e phone_template_id, inclusive vazio, retornam 400 / PHONE_TEMPLATE_PARAMETER_NOT_SUPPORTED. Modelo aleatório; sem alternativa, sem template. Preserva simulação e tenta restaurar proxy anterior após verificação; não escolhe ou compra proxy novo.
curl --fail-with-body "https://api.foxphone.com/public_api/v1/phones/actions/reset" \
-H "X-API-Key: ${API_KEY}" \
-H "Content-Type: application/json" \
--data '{"pod_ids":["pod-example-001"]}'Use proxy_id positivo da lista no caminho e só pod_ids no corpo. Recursos devem pertencer à conta e proxy estar válido, vigente e aprovado em nova verificação. Telefone parado salva configuração e permanece parado; aplica ao iniciar depois. Em execução aplica de modo assíncrono e pode reiniciar. Conflitos são rejeitados; proxy inválido: 409 / BATCH_PRECHECK_FAILED, item PRECHECK_FAILED.
curl --fail-with-body "https://api.foxphone.com/public_api/v1/proxies/42/bind" \
-H "X-API-Key: ${API_KEY}" \
-H "Content-Type: application/json" \
--data '{"pod_ids":["pod-example-001"]}'Apenas redefinição/vinculação usam successful_pod_ids/failed_items. Pré-verificação de lote falha: 409 com data.failed_items, não metadata superior. Pode haver sucesso parcial e não há reversão entre sistemas. Sucesso significa aceito ou salvo, não concluído; pode ser null. Não repita todo o lote.
{
"request_id": "example-request-id",
"code": 200,
"data": {
"successful_pod_ids": [
"pod-example-001"
],
"failed_items": [
{
"pod_id": "pod-example-002",
"code": "PROVIDER_REJECTED",
"message": "provider rejected the operation"
}
]
},
"message": "success"
}{
"request_id": "example-request-id",
"code": 409,
"data": {
"failed_items": [
{
"pod_id": "pod-example-002",
"code": "PHONE_NOT_RUNNING",
"message": "phone is not running"
}
]
},
"message": "batch precheck failed",
"reason": "BATCH_PRECHECK_FAILED"
}| Campo | Descrição |
|---|---|
| RESOURCE_NOT_OWNED | O recurso não pertence à conta atual |
| RESET_IN_PROGRESS | A redefinição do telefone está em andamento |
| OPERATION_IN_PROGRESS | Há uma operação conflitante em andamento |
| PHONE_NOT_RUNNING | O telefone não está em execução |
| RESOURCE_UNAVAILABLE | O recurso não existe ou está indisponível |
| PRECHECK_FAILED | A verificação do proxy ou outra verificação prévia falhou |
| PROVIDER_REJECTED | O provedor de nuvem rejeitou a solicitação ou o envio falhou |
source obrigatório na consulta: official ou user. Filtros app_name e app_type inteiro opcional, paginação comum. Agrupa por package_name; total conta aplicativos. Pacotes crescentes, versions por version_code decrescente. Instale por package_name/version_code, não version_id/version_name. Não lista apps instalados no telefone.
curl --fail-with-body "https://api.foxphone.com/public_api/v1/apps?source=official&page_num=1&page_size=20&app_name=example" \
-H "X-API-Key: ${API_KEY}"{
"request_id": "example-request-id",
"code": 200,
"data": {
"total": 1,
"apps": [
{
"app_id": "app-example",
"app_name": "Example App",
"package_name": "com.example.app",
"app_type": 1,
"icon_url": "",
"source": "official",
"versions": [
{
"id": 101,
"version_id": "version-example",
"version_name": "1.0.0",
"version_code": 100
}
]
}
]
},
"message": "success"
}Exige package_name não vazio, version_code inteiro positivo e pod_ids válidos; selecione seus telefones ligados. Prefira source explícito. Ausente/vazio busca pessoal e depois oficial; fonte explícita sem fallback. Sem URL APK. data.items fornece pod_id/job_id apenas como envio. Sem consulta de resultado nem contrato de pré-verificação de estado igual a redefinição/vinculação.
curl --fail-with-body "https://api.foxphone.com/public_api/v1/phones/actions/install-app" \
-H "X-API-Key: ${API_KEY}" \
-H "Content-Type: application/json" \
--data '{"source":"official","package_name":"com.example.app","version_code":100,"pod_ids":["pod-example-001"]}'{
"request_id": "example-request-id",
"code": 200,
"data": {
"items": [
{
"pod_id": "pod-example-001",
"job_id": "job-example-001"
}
]
},
"message": "success"
}400: corrija parâmetros; 401/403: confira Key/conta; 409: resolva conflito; 429: aguarde progressivamente. Consultas podem repetir dentro da quota. Escritas sem chave de idempotência publicada: após timeout/500 verifique aceitação primeiro. App inexistente, versão errada ou falha de envio também podem ser 500 / PUBLIC_API_INTERNAL_ERROR, sem provar que nada executou.
| HTTP | reason |
|---|---|
| 400 | INVALID_ARGUMENT |
| 400 | PHONE_TEMPLATE_PARAMETER_NOT_SUPPORTED |
| 401 | INVALID_API_KEY |
| 403 | API_KEY_DISABLED |
| 403 | USER_ACCOUNT_UNAVAILABLE |
| 409 | BATCH_PRECHECK_FAILED |
| 429 | RATE_LIMIT_EXCEEDED |
| 500 | PUBLIC_API_INTERNAL_ERROR |
| 500 | PUBLIC_API_AUTH_ERROR |
Guarde Key no servidor em variáveis de ambiente ou cofre, nunca em frontend, repositório público ou cliente. Não coloque em URL, corpo, logs ou chamados. Exemplos usam API_KEY. Se vazar, rotacione/desative imediatamente e atualize os consumidores.
Envie request_id, caminho, HTTP, reason, horário e parâmetros ocultando dados, nunca a Key. Valide consultas primeiro; use dispositivos de teste autorizados para escritas e confira resultados antes de aumentar o lote.