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 rotativos (residencial, datacenter, móvel)

Início rápido

Aponte qualquer cliente HTTP(S) ou SOCKS5 para o gateway e autentique com seu nome de usuário e senha do proxy. A segmentação é definida dentro do nome de usuário.

Proxy rotativo dos EUA via HTTP. Substitua USERNAME e PASSWORD pelas suas credenciais.

O gateway de entrada é escolhido para onde você está — a porta mais próxima costuma ser a mais rápida. Você pode trocar.

Prefere um passo a passo completo para a sua stack? Cada guia cobre configuração, sessões rotativas e persistentes, e segmentação por país.

curl -x http://global.socksnode.com:9000 \
  -U "USERNAME-country-us:PASSWORD" \
  https://api.ipify.org?format=json
Resposta200
{"ip": "104.28.219.14"}

Conexão do proxy

Cada proxy usa as mesmas quatro partes — host:port:username:password. Seu nome de usuário e senha vêm de o gerador de proxy no seu painel. Segmentação por país, cidade e sessão é adicionada ao nome de usuário como tokens (veja abaixo).

global.socksnode.com:9000:USERNAME-country-us:PASSWORD

Portas e gateways

O gateway de entrada afeta a latência — o mais próximo de você costuma ser o mais rápido, então escolhemos automaticamente. Se um proxy parecer lento, troque o gateway. O país de saída é escolhido com o token country, independentemente do gateway.

ProtocoloPorta rotativaPorta persistente
HTTP / HTTPS900010000
SOCKS51100012000
GatewayHost
O mais próximo de você (padrão)global.socksnode.com
Europafr.socksnode.com
Estados Unidosus.socksnode.com
Singapurasg.socksnode.com
# 9000: a new exit IP on every request
curl -x http://global.socksnode.com:9000 \
  -U "USERNAME-country-us:PASSWORD" \
  https://api.ipify.org

Segmentação e sessões

Acrescente tokens ao seu nome de usuário, separados por hífens, para controlar o local de saída e o comportamento da sessão:

TokenSignificado
-country-<cc>Código ISO do país, ex.: -country-us
-state-<name>Estado dos EUA, ex.: state-california (nome completo, sem espaços). Funciona com uma cidade ou um ISP.
-city-<name>Cidade, ex.: city-losangeles (nome, sem espaços ou sublinhados).
-asn-<number>Segmente um ISP específico por ASN, ex.: asn-7922 (Comcast). Combina com um estado ou uma cidade.
-os-<name>Retorne IPs apenas em um sistema operacional do dispositivo: windows, android, ios ou mac. Isso reduz o pool, então espere menos IPs.
-session-<id>Mantenha o mesmo IP entre as solicitações (persistente)
-lifetime-<min>Duração da sessão persistente, 1–1440 minutos
# Rotating: a fresh IP on every request
USERNAME-country-us

# Sticky: the same IP for 30 minutes
USERNAME-country-us-session-a1b2c3d4-lifetime-30

# State + city
USERNAME-country-us-state-california-city-losangeles

# City + ISP (ASN)
USERNAME-country-us-city-chicago-asn-7922

# Device OS
USERNAME-country-us-os-android

Pools

A banda residencial funciona nos três pools pelo mesmo preço. Envie pool no POST /proxies para escolher um; sem ele é o Pool 1, como antes. Um Mix distribui as requisições entre os pools de mixPools, em partes iguais. Um pool que não atende o alvo fica de fora, e um alvo que só um pool atende roda no Pool 1: pool, mixPools e poolNote de cada linha dizem onde ela roda.

poolSegmentaçãoSticky
1Pool 1País, estado, cidade e ISP (ASN), combinados livremente1–1440 min
2Pool 2País e depois um de: um estado, uma cidade ou um ISP1–60 min
3Pool 3País; estado e cidade nos EUA1–1440 min
mixMixOs locais do Pool 1; cada pool do Mix atende o que pode1–1440 min com Pools 1 + 3 (Pool 2 fica de fora após 60); 1–60 min nos demais casos

Locais do Pool 2 e do Pool 3: GET /locations?pool=2 (ou 3). Nomes e códigos funcionam: "Los Angeles", "losangeles" e "los_angeles" são a mesma cidade.

# Pool 3, Los Angeles, the same IP for 30 minutes
curl -X POST "https://socksnode.com/api/v1/proxies" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pool": "3", "protocol": "http", "country": "us",
       "state": "california", "city": "losangeles",
       "sessionMode": "sticky", "stickyDurationMinutes": 30}'

# A Mix of all three pools, a new IP on every request
curl -X POST "https://socksnode.com/api/v1/proxies" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pool": "mix", "mixPools": "123", "protocol": "http",
       "country": "gb", "sessionMode": "rotating", "count": 5}'

# Pool 2's own states, cities and ISPs in one country
curl "https://socksnode.com/api/v1/locations?pool=2&country=gb" \
  -H "Authorization: Bearer YOUR_API_KEY"

API REST

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.
429Limite de taxa excedido — consulte o cabeçalho Retry-After
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": "…"
  }
}

saldo de largura de banda

GET/account

Escopo: read:usage

Sem parâmetros.

curl "https://socksnode.com/api/v1/account" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
Resposta200
{
  "balance": {
    "purchasedGb": 50,
    "usedGb": 12.34,
    "remainingGb": 37.66
  },
  "datacenterBalance": {
    "purchasedGb": 0,
    "usedGb": 0,
    "remainingGb": 0
  },
  "mobileRotatingBalance": {
    "purchasedGb": 10,
    "usedGb": 1.2,
    "remainingGb": 8.8
  },
  "creditUsd": 40
}

Tabela de preços e cotação de GB rotativo

GET/pricing

Escopo: read:usage

Parâmetros de consulta

  • productstringOpcional

    Qual rede: residential (padrão), datacenter ou mobile_rotating.

    residentialdatacentermobile_rotatingPadrão: residential

  • gbintegerOpcional

    Opcional. Um número inteiro de GB, de 5 a 10.240, para receber uma cotação.

curl "https://socksnode.com/api/v1/pricing?product=datacenter&gb=100" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
Resposta200
{
  "product": "datacenter",
  "currency": "USD",
  "minGb": 5,
  "maxGb": 10240,
  "bandwidthExpires": false,
  "tiers": [
    { "gb": 5, "priceUsd": 3.05, "perGbUsd": 0.61 },
    { "gb": 100, "priceUsd": 49, "perGbUsd": 0.49 },
    { "gb": 10240, "priceUsd": 2969.6, "perGbUsd": 0.29 }
  ],
  "quote": { "gb": 100, "totalUsd": 49, "perGbUsd": 0.49 }
}

Comprar GB rotativo com o seu saldo

POST/orders

Escopo: purchase

Parâmetros do corpo

  • productstringOpcional

    Qual rede: residential (padrão), datacenter ou mobile_rotating.

    residentialdatacentermobile_rotatingPadrão: residential

  • gbintegerObrigatório

    GB a comprar, de 5 a 10.240. Cobrado do seu saldo pelo preço da tabela, com o desconto do seu nível; os GB são creditados na hora e nunca expiram.

curl -X POST "https://socksnode.com/api/v1/orders" \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "datacenter",
    "gb": 100
  }'
Resposta201
{
  "order": {
    "id": "cmv…",
    "orderNumber": "SN-MVFRMPRO-B26F94",
    "product": "datacenter",
    "gb": 100,
    "amountUsd": 49,
    "discountUsd": 0,
    "status": "paid"
  },
  "balanceUsd": 51
}

análises

GET/usage

Escopo: read:usage

Parâmetros de consulta

  • rangestringOpcional

    Período. Um valor desconhecido usa 24h.

    1h24h7d30d90dtodaymonth12mallPadrão: 24h

  • productstringOpcional

    datacenter lê o uso de datacenter; qualquer outro valor lê residencial.

    residentialdatacentermobile_rotatingPadrão: residential

curl "https://socksnode.com/api/v1/usage?range=30d" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
Resposta200
{
  "range": "30d",
  "product": "residential",
  "granularity": "day",
  "totalGb": 12.34,
  "series": [{ "period": "2026-09-01", "gb": 1.2 }],
  "requests": {
    "total": 10420,
    "successful": 10310,
    "failed": 110,
    "successRate": 98.9,
    "avgLatencyMs": 280
  },
  "byCountry": [{ "country": "us", "requests": 8200, "gb": 9.1 }],
  "truncated": false
}

listar credenciais salvas

GET/proxies

Escopo: read:proxies

Sem parâmetros.

curl "https://socksnode.com/api/v1/proxies" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
Resposta200
{
  "data": [
    {
      "id": "clx…",
      "product": "residential",
      "label": "scraper",
      "protocol": "http",
      "country": "us",
      "sessionMode": "rotating",
      "host": "global.socksnode.com",
      "port": 9000,
      "username": "USERNAME-country-us",
      "pool": "1",
      "status": "active",
      "createdAt": "2026-09-30T08:12:44.000Z"
    }
  ]
}

gerar credenciais (senha retornada uma única vez)

POST/proxies

Escopo: write:proxies

Parâmetros do corpo

  • protocolstringObrigatório

    Protocolo das credenciais.

    httpsocks5

  • countrystringObrigatório

    Código de país de duas letras, ou ANY para o mundo todo.

  • statestringOpcional

    Estado dos EUA, nome completo sem espaços, ex.: california.

  • citystringOpcional

    Cidade sem espaços, ex.: losangeles. Ignorado quando há asn.

  • asnintegerOpcional

    Número de rede do ISP, ex.: 7922 para Comcast.

  • sessionModestringObrigatório

    rotating dá um IP novo a cada requisição; sticky mantém um IP por stickyDurationMinutes.

    rotatingsticky

  • stickyDurationMinutesintegerOpcional

    Quanto tempo um IP sticky é mantido, 1–1440 minutos. Obrigatório quando sessionMode é sticky.

  • countintegerOpcional

    Quantas credenciais criar, 1–20.

    Padrão: 1

  • labelstringOpcional

    Seu nome para elas, até 80 caracteres. Com count acima de 1 cada uma recebe #n.

  • poolstringOpcional

    Pool residencial: 1 (padrão), 2, 3 ou mix. Veja Pools.

    123mixPadrão: 1

  • mixPoolsstringOpcional

    Com pool mix: os pools que ele usa, 12, 13, 23 ou 123 (padrão 123).

    121323123Padrão: 123

  • strictbooleanOpcional

    true: só o estado, a cidade ou o ISP exatos; false: recorre ao país quando não há IP livre. Padrão true no Pool 1 e false num Mix; um Mix estrito roda no Pool 1.

  • gatewaystringOpcional

    Gateway de entrada que a linha usa: fr, us ou sg — ou auto (padrão), que devolve o host roteado por geolocalização e deixa o DNS escolher o mais próximo. Só residencial.

    autofrussgPadrão: auto

  • osstringOpcional

    Impressão digital do sistema do dispositivo: windows, android, ios ou mac. Omita para qualquer dispositivo.

    windowsandroidiosmac

  • productstringOpcional

    Qual saldo paga e de qual rede vêm os proxies: residential (padrão), datacenter ou mobile_rotating. Para mobile_rotating, a segmentação por país é o padrão; estado, cidade e ASN contam o tráfego em dobro, e um IP sticky é mantido por no máximo 120 minutos.

    residentialdatacentermobile_rotatingPadrão: residential

curl -X POST "https://socksnode.com/api/v1/proxies" \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "protocol": "http",
    "country": "us",
    "sessionMode": "rotating",
    "count": 2,
    "label": "scraper"
  }'
Resposta201
{
  "data": [
    {
      "id": "clx…",
      "host": "global.socksnode.com",
      "port": 9000,
      "username": "USERNAME-country-us",
      "password": "shown once",
      "protocol": "http",
      "country": "us",
      "state": null,
      "city": null,
      "sessionMode": "rotating",
      "stickyDurationMinutes": null,
      "label": "scraper #1",
      "product": "residential",
      "pool": "1",
      "mixPools": null,
      "poolNote": null
    }
  ]
}

excluir uma credencial salva

DELETE/proxies/{id}

Escopo: write:proxies

Parâmetros de caminho

  • idstringObrigatório

    O id do proxy salvo, como o GET /proxies devolve.

curl -X DELETE "https://socksnode.com/api/v1/proxies/PROXY_ID" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
Resposta200
{
  "data": { "id": "clx…", "deleted": true }
}

Catálogo de segmentação: países, seus estados e cidades

GET/locations

Escopo: read:proxies

Parâmetros de consulta

  • countrystringOpcional

    Código do país. Retorna seus estados.

  • statestringOpcional

    Código do estado, junto com country. Retorna suas cidades.

  • productstringOpcional

    Qual catálogo ler: residential (padrão), datacenter ou mobile_rotating. Datacenter e móvel rotativo também listam os ASNs do país.

    residentialdatacentermobile_rotatingPadrão: residential

  • poolstringOpcional

    Pool residencial cujos locais listar: 1 (padrão), 2 ou 3. Um Mix usa a lista do Pool 1.

    123Padrão: 1

curl "https://socksnode.com/api/v1/locations?country=us" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
Resposta200
{
  "data": {
    "country": "us",
    "states": [
      { "code": "california", "name": "California", "cities": 212 },
      { "code": "texas", "name": "Texas", "cities": 187 }
    ]
  }
}

Pronto para começar?

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