help-icon
icon

Guia da API pública

helpDetails-time-icon2026-09-23T15:37:56+08:00

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.

Endpoints

HTTP/public_api/v1Descrição
GET/phonesListar telefones
GET/proxiesListar proxies
POST/phones/actions/resetRedefinir em lote
POST/proxies/{proxy_id}/bindVincular proxy existente
GET/appsAplicativos e versões
POST/phones/actions/install-appInstalar em lote

Preparar API Key

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>"

Convenções e respostas

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"
}

Listar telefones

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.

CampoTipo
pod_idstring
namestring
online_statusinteger
operating_statusinteger
proxy_idnumber
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"
}

Listar proxies

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 em lote

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"]}'

Vincular proxy existente

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"]}'

Resultados e erros do lote

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"
}
CampoDescrição
RESOURCE_NOT_OWNEDO recurso não pertence à conta atual
RESET_IN_PROGRESSA redefinição do telefone está em andamento
OPERATION_IN_PROGRESSHá uma operação conflitante em andamento
PHONE_NOT_RUNNINGO telefone não está em execução
RESOURCE_UNAVAILABLEO recurso não existe ou está indisponível
PRECHECK_FAILEDA verificação do proxy ou outra verificação prévia falhou
PROVIDER_REJECTEDO provedor de nuvem rejeitou a solicitação ou o envio falhou

Aplicativos e versões

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"
}

Instalar em lote

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"
}

Erros e novas tentativas

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.

HTTPreason
400INVALID_ARGUMENT
400PHONE_TEMPLATE_PARAMETER_NOT_SUPPORTED
401INVALID_API_KEY
403API_KEY_DISABLED
403USER_ACCOUNT_UNAVAILABLE
409BATCH_PRECHECK_FAILED
429RATE_LIMIT_EXCEEDED
500PUBLIC_API_INTERNAL_ERROR
500PUBLIC_API_AUTH_ERROR

Segurança da 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.

Validação e suporte

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.

Artigos relacionados

Email contact
Cookie notification iconAviso de Cookie
Este site usa cookies para melhorar a experiência do usuário. Para saber mais sobre nossa política de cookies ou retirar seu consentimento, consulte nossa Política de Privacidade e Política de Cookies.