Desenvolvedores

Documentação da API e de integração

Duas formas de integrar o SocksNode: conecte-se diretamente ao gateway do proxy por HTTP(S) ou SOCKS5, ou gerencie largura de banda, uso e proxies programaticamente por meio da API REST.

Nesta página

Proxies móveis

REST API 4G/5G

Compre e gerencie proxies móveis 4G/5G programaticamente. Cada IP Móvel é um IP de operadora rotativo com até 3 conexões para uma duração escolhida. Aluguéis e renovações são cobrados do crédito pré-pago da sua conta (USD). Usa os escopos read:proxies / write:proxies.

https://socksnode.com/api/v1

Autenticação

URL base https://socksnode.com/api/v1. Crie uma chave em Dashboard → API access e envie-a como um token Bearer. As chaves têm escopo — solicite apenas o que você precisa.

EscopoPermissões
read:usageSaldo e analytics de uso
read:proxiesListar credenciais de proxy salvas
write:proxiesGerar novas credenciais de proxy
purchaseComprar GB para proxies rotativos residenciais, de datacenter e móveis, comprar e renovar IPs estáticos e ISP, alugar e renovar portas 4G/5G, ativar a renovação automática, comprar IPs de 24 horas e endereços e banda do IP Vault, cobrados do seu saldo.

Limite de taxa: 120 solicitações por minuto por chave (a geração de proxy é ainda mais limitada). Mantenha sua chave em segredo e no lado do servidor.

GET /api/v1/account HTTP/1.1
Host: socksnode.com
Authorization: Bearer sk_YOUR_API_KEY

Erros

Os erros retornam um corpo JSON { "error": { "code", "message" } } com o status HTTP correspondente:

StatusSignificado
400Corpo da solicitação inválido ou parâmetros inválidos
401Chave de API ausente, inválida ou revogada
402Saldo de largura de banda insuficiente para gerar proxies
403A chave de API não tem o escopo necessário
404Não encontrado, ou não é seu.
409O estado da porta não permite isso agora, ex.: ela expirou.
429Limite de taxa excedido — consulte o cabeçalho Retry-After
502A rede de origem falhou. Você não foi cobrado.
503O produto está em manutenção. Tente de novo em instantes.
HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "error": {
    "code": "no_bandwidth",
    "message": "…"
  }
}

Endpoints da API

durações, países, estados e operadoras

GET/mobile/catalog

Escopo: read:proxies

Parâmetros de consulta

  • countryintegerOpcional

    Id do país. Retorna seus estados.

  • stateintegerOpcional

    Id do estado. Retorna suas operadoras.

  • availabilitystringOpcional

    Use 1 para incluir quanto de cada opção está livre agora.

    1

  • tierstringOpcional

    De qual plano mostrar o estoque.

    economybasicturboPadrão: basic

  • modemsstringOpcional

    Use 1 junto com state para listar todos os modems do estado, livres e ocupados, com quanto tempo cada um mantém o IP. Mesmos campos de /mobile/proxies/PROXY_ID/modems.

    1

  • carrierintegerOpcional

    Id da operadora. Com modems=1, lista só os modems dessa operadora.

curl "https://socksnode.com/api/v1/mobile/catalog?state=12&availability=1" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
Resposta200
{
  "data": {
    "carriers": [
      { "id": 34, "name": "5G AT&T", "status": "ok", "pct": 82 },
      { "id": 35, "name": "5G T-Mobile", "status": "low", "pct": 11 },
      { "id": 36, "name": "5G Verizon", "status": "none", "pct": 0 }
    ]
  }
}
// status: "ok" | "low" | "none" | "unknown"
// Country and state stock is refreshed every ~15 min;
// carrier stock is checked live, right before you choose.

liste seus proxies móveis (com credenciais)

GET/mobile/proxies

Escopo: read:proxies

Sem parâmetros.

curl "https://socksnode.com/api/v1/mobile/proxies" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
Resposta200
{
  "data": [
    {
      "id": "clx…",
      "name": "Port 1",
      "host": "mobile.socksnode.com",
      "port": 9094,
      "protocol": "socks5",
      "username": "sn_a1b2c3d4",
      "password": "…",
      "authMode": "userpass",
      "allowedIps": [],
      "country": "UNITED STATES",
      "state": "FLORIDA",
      "carrier": "5G AT&T",
      "rotationMinutes": 15,
      "modem": { "id": "3f9c0a1b2d4e5f607182", "code": "K7QM" },
      "status": "active",
      "paused": false,
      "bytesUsed": 0,
      "lastExitIp": null,
      "expiresAt": "2026-10-30T04:46:53.000Z"
    }
  ]
}

um proxy

GET/mobile/proxies/{id}

inclui dados usados + último IP de saída

Escopo: read:proxies

Parâmetros de caminho

  • idstringObrigatório

    O id do proxy móvel.

curl "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
Resposta200
{
  "data": {
    "id": "clx…",
    "name": "Port 1",
    "host": "mobile.socksnode.com",
    "port": 9094,
    "protocol": "socks5",
    "username": "sn_a1b2c3d4",
    "password": "…",
    "authMode": "userpass",
    "allowedIps": [],
    "country": "UNITED STATES",
    "state": "FLORIDA",
    "carrier": "5G AT&T",
    "rotationMinutes": 15,
    "modem": { "id": "3f9c0a1b2d4e5f607182", "code": "K7QM" },
    "status": "active",
    "paused": false,
    "bytesUsed": 0,
    "lastExitIp": null,
    "expiresAt": "2026-10-30T04:46:53.000Z"
  }
}

compre N portas (cobrado do crédito; 402 se estiver baixo demais)

POST/mobile/proxies

Escopo: purchase

Parâmetros do corpo

  • tierKeystringOpcional

    Plano a alugar.

    economybasicturboPadrão: basic

  • durationKeystringObrigatório

    Duração do aluguel. Precisa ser uma que o plano vende.

    2h12h1d3d7d15d30d

  • quantityintegerOpcional

    Portas a alugar, 1–50. Se alguma não puder ser criada, você paga só o restante.

    Padrão: 1

  • countryIdintegerOpcional

    Id do país no catálogo. Omita para pegar qualquer local disponível.

  • cityIdintegerOpcional

    Id do estado no catálogo.

  • spIdintegerOpcional

    Id da operadora no catálogo.

  • modemIdstringOpcional

    Um id de modem de /mobile/catalog?modems=1 (mesmo plano). Exige cityId e quantity 1. 409 modem_taken se não houver vaga; você não é cobrado.

  • protocolstringOpcional

    Protocolo da porta.

    sockshttpPadrão: socks

curl -X POST "https://socksnode.com/api/v1/mobile/proxies" \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "durationKey": "30d",
    "quantity": 1,
    "countryId": 1,
    "cityId": 12,
    "spId": 34,
    "protocol": "socks"
  }'
Resposta201
{
  "data": [
    {
      "id": "clx…",
      "name": "Port 1",
      "host": "mobile.socksnode.com",
      "port": 9094,
      "protocol": "socks5",
      "username": "sn_a1b2c3d4",
      "password": "…",
      "authMode": "userpass",
      "allowedIps": [],
      "country": "UNITED STATES",
      "state": "FLORIDA",
      "carrier": "5G AT&T",
      "rotationMinutes": 15,
      "modem": { "id": "3f9c0a1b2d4e5f607182", "code": "K7QM" },
      "status": "active",
      "paused": false,
      "bytesUsed": 0,
      "lastExitIp": null,
      "expiresAt": "2026-10-30T04:46:53.000Z"
    }
  ],
  "charged": 40
}

alterar país/estado/operadora (gratuito)

POST/mobile/proxies/{id}/switch

Escopo: write:proxies

Parâmetros de caminho

  • idstringObrigatório

    O id do proxy móvel.

Parâmetros do corpo

  • countryIdintegerObrigatório

    Id do país no catálogo.

  • cityIdintegerOpcional

    Id do estado no catálogo.

  • spIdintegerOpcional

    Id da operadora no catálogo.

  • modemIdstringOpcional

    Um id de modem da lista de modems. Exige cityId. A porta vai só para esse modem: 409 modem_taken se estiver cheio, 404 modem_gone se saiu da lista.

  • protocolstringOpcional

    Por padrão, o protocolo atual da porta.

    sockshttp

curl -X POST "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID/switch" \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "countryId": 3,
    "cityId": 12,
    "spId": 34,
    "modemId": "8d21e7c40b9a6f5e3c12"
  }'
Resposta200
{
  "data": {
    "id": "clx…",
    "host": "mobile.socksnode.com",
    "port": 9095,
    "protocol": "socks5",
    "country": "UNITED STATES",
    "state": "FLORIDA",
    "carrier": "5G AT&T",
    "status": "active"
  }
}
// + every other field of GET /mobile/proxies/{id}

lista os modems de um estado para uma porta (livres e ocupados, tempo de IP)

GET/mobile/proxies/{id}/modems

Escopo: read:proxies

Parâmetros de caminho

  • idstringObrigatório

    O id do proxy móvel.

Parâmetros de consulta

  • stateintegerObrigatório

    Id do estado no catálogo. Lista os modems desse estado para o plano desta porta.

  • carrierintegerOpcional

    Id da operadora. Com modems=1, lista só os modems dessa operadora.

curl "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID/modems?state=12&carrier=34" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
Resposta200
{
  "data": {
    "modems": [
      {
        "id": "3f9c0a1b2d4e5f607182",
        "code": "K7QM",
        "carrier": "5G AT&T",
        "free": true,
        "current": true,
        "yours": 0,
        "yourPorts": [],
        "rotationMinutes": 30,
        "lastIp": "174.208.161.27",
        "lastOkAt": "2026-10-28T03:12:40.000Z",
        "failing": false
      },
      {
        "id": "8d21e7c40b9a6f5e3c12",
        "code": "R4XB",
        "carrier": "5G AT&T",
        "free": false,
        "current": false,
        "yours": 0,
        "yourPorts": [],
        "rotationMinutes": 60,
        "lastIp": null,
        "lastOkAt": null,
        "failing": false
      }
    ],
    "free": 1,
    "total": 2
  }
}
// free: has a slot for one more port. current: this port is on it.
// yours: your other live ports on it (they share its IP); yourPorts: their port numbers.
// rotationMinutes: how long the modem keeps one IP.

novo IP de saída (gratuito)

POST/mobile/proxies/{id}/rotate

Escopo: write:proxies

Parâmetros de caminho

  • idstringObrigatório

    O id do proxy móvel.

curl -X POST "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID/rotate" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
Resposta200
{
  "data": {
    "id": "clx…",
    "host": "mobile.socksnode.com",
    "port": 9095,
    "protocol": "socks5",
    "country": "UNITED STATES",
    "state": "FLORIDA",
    "carrier": "5G AT&T",
    "status": "active"
  }
}
// + every other field of GET /mobile/proxies/{id}

leia o IP de saída em tempo real

GET/mobile/proxies/{id}/check-ip

Escopo: read:proxies

Parâmetros de caminho

  • idstringObrigatório

    O id do proxy móvel.

curl "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID/check-ip" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
Resposta200
{
  "data": { "ip": "174.208.161.27" }
}

alternar SOCKS5 ↔ HTTP(S)

POST/mobile/proxies/{id}/protocol

Escopo: write:proxies

Parâmetros de caminho

  • idstringObrigatório

    O id do proxy móvel.

Parâmetros do corpo

  • protocolstringObrigatório

    Protocolo da porta.

    sockshttp

curl -X POST "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID/protocol" \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "protocol": "http"
  }'
Resposta200
{
  "data": {
    "id": "clx…",
    "host": "mobile.socksnode.com",
    "port": 9095,
    "protocol": "socks5",
    "country": "UNITED STATES",
    "state": "FLORIDA",
    "carrier": "5G AT&T",
    "status": "active"
  }
}
// + every other field of GET /mobile/proxies/{id}

alternar modo de autenticação

POST/mobile/proxies/{id}/auth

Escopo: write:proxies

Parâmetros de caminho

  • idstringObrigatório

    O id do proxy móvel.

Parâmetros do corpo

  • modestringObrigatório

    userpass entra com usuário e senha; whitelist deixa os IPs da lista conectarem sem senha.

    userpasswhitelist

  • allowedIpsstring[]Opcional

    Até 3 endereços IPv4 ou IPv6 públicos, sem faixas. Necessário para whitelist.

    Padrão: []

curl -X POST "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID/auth" \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "whitelist",
    "allowedIps": [
      "203.0.113.7"
    ]
  }'
Resposta200
{
  "data": {
    "id": "clx…",
    "host": "mobile.socksnode.com",
    "port": 9095,
    "protocol": "socks5",
    "country": "UNITED STATES",
    "state": "FLORIDA",
    "carrier": "5G AT&T",
    "status": "active"
  }
}
// + every other field of GET /mobile/proxies/{id}

estenda a porta (cobrado do crédito)

POST/mobile/proxies/{id}/renew

Escopo: purchase

Parâmetros de caminho

  • idstringObrigatório

    O id do proxy móvel.

Parâmetros do corpo

  • durationKeystringObrigatório

    Duração do aluguel. Precisa ser uma que o plano da porta vende.

    2h12h1d3d7d15d30d

curl -X POST "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID/renew" \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "durationKey": "30d"
  }'
Resposta200
{
  "data": {
    "id": "clx…",
    "host": "mobile.socksnode.com",
    "port": 9095,
    "protocol": "socks5",
    "country": "UNITED STATES",
    "state": "FLORIDA",
    "carrier": "5G AT&T",
    "status": "active"
  },
  "charged": 40
}
// + every other field of GET /mobile/proxies/{id}

Pronto para começar?

Gere credenciais no painel ou crie uma chave de API para automatizar isso.