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

IPs estáticos e IP Vault

Visão geral

Compre, liste e renove IPs estáticos de datacenter e IPs ISP residenciais, e compre, liste e gerencie endereços e banda do IP Vault — as mesmas operações do painel, pelo seu código.

Chamadas que gastam dinheiro (compras e renovações) exigem uma chave de API com o escopo purchase e são pagas só com o saldo da carteira — recarregue antes. Saldo insuficiente responde 402 e nada é pedido. Pedidos estáticos são entregues em segundo plano: consulte o pedido até a entrega terminar.

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

IP estático datacenter e ISP

Catálogo de IPs estáticos

GET/static/catalog

Escopo: read:proxies

Parâmetros de consulta

  • typestringObrigatório

    dedicated_ipv4, shared_ipv4 e ipv6 são IPs de datacenter; isp é um IP ISP residencial.

    dedicated_ipv4shared_ipv4ipv6isp

curl "https://socksnode.com/api/v1/static/catalog?type=dedicated_ipv4" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
Resposta200
{
  "type": "dedicated_ipv4",
  "periodsDays": [5, 10, 20, 30, 60, 90, 120, 150, 180, 210, 240, 270, 300, 330, 360],
  "maxQuantity": 100,
  "countries": [
    { "code": "us", "name": "United States", "available": 1000, "cities": [{ "id": 3, "name": "New York", "available": 120 }] }
  ]
}

Orçar um pedido estático

GET/static/quote

Escopo: read:proxies

Parâmetros de consulta

  • typestringObrigatório

    dedicated_ipv4, shared_ipv4 e ipv6 são IPs de datacenter; isp é um IP ISP residencial.

    dedicated_ipv4shared_ipv4ipv6isp

  • countrystringObrigatório

    Código de país de duas letras do catálogo.

  • quantityintegerObrigatório

    Quantos IPs (1–100).

  • periodDaysintegerObrigatório

    Duração do aluguel em dias — um dos períodos do catálogo para este tipo.

curl "https://socksnode.com/api/v1/static/quote?type=isp&country=us&quantity=5&periodDays=30" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
Resposta200
{
  "type": "isp",
  "country": "us",
  "quantity": 5,
  "periodDays": 30,
  "unitPriceUsd": 3.4,
  "totalUsd": 17
}

Comprar IPs estáticos

POST/static/orders

Escopo: purchase

Parâmetros do corpo

  • typestringObrigatório

    dedicated_ipv4, shared_ipv4 e ipv6 são IPs de datacenter; isp é um IP ISP residencial.

    dedicated_ipv4shared_ipv4ipv6isp

  • countrystringObrigatório

    Código de país de duas letras do catálogo.

  • cityIdintegerOpcional

    Id de cidade do catálogo (só datacenter). Omita para qualquer cidade.

  • quantityintegerObrigatório

    Quantos IPs (1–100).

  • periodDaysintegerObrigatório

    Duração do aluguel em dias — um dos períodos do catálogo para este tipo.

  • couponCodestringOpcional

    Um código de desconto, se tiver.

curl -X POST "https://socksnode.com/api/v1/static/orders" \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "dedicated_ipv4",
    "country": "us",
    "quantity": 2,
    "periodDays": 30
  }'
Resposta201
{
  "id": "clx…",
  "orderNumber": "SN-…",
  "status": "paid",
  "type": "dedicated_ipv4",
  "country": "us",
  "quantity": 2,
  "periodDays": 30,
  "amountUsd": 4.6,
  "delivery": "pending"
}

Status de um pedido estático

GET/static/orders/{id}

Escopo: read:proxies

Parâmetros de caminho

  • idstringObrigatório

    O id retornado ao fazer o pedido.

curl "https://socksnode.com/api/v1/static/orders/ORDER_ID" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
Resposta200
{
  "id": "clx…",
  "status": "paid",
  "delivery": "done",
  "delivered": 2,
  "quantity": 2,
  "refundedUsd": 0,
  "ips": [ … ]
}

Listar seus IPs estáticos

GET/static

Escopo: read:proxies

Parâmetros de consulta

  • typestringOpcional

    Quais IPs estáticos listar.

    alldatacenterispPadrão: all

curl "https://socksnode.com/api/v1/static" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
Resposta200
{
  "data": [
    {
      "id": "clx…",
      "ip": "203.0.113.25",
      "host": "203.0.113.25",
      "portHttp": 50100,
      "portSocks5": 50101,
      "username": "u3k2…",
      "password": "…",
      "type": "dedicated_ipv4",
      "countryCode": "us",
      "status": "active",
      "expiresAt": "2026-11-03T10:00:00.000Z",
      "daysLeft": 30,
      "autoRenew": false
    }
  ]
}

Renovar IPs estáticos

POST/static/renew

Escopo: purchase

Parâmetros do corpo

  • idsstring[]Obrigatório

    Ids dos IPs a renovar — datacenter e ISP em chamadas separadas.

  • periodDaysintegerObrigatório

    Duração do aluguel em dias — um dos períodos do catálogo para este tipo.

curl -X POST "https://socksnode.com/api/v1/static/renew" \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "STATIC_ID"
    ],
    "periodDays": 30
  }'
Resposta201
{
  "jobId": "clx…",
  "renewed": 1,
  "chargedUsd": 2.3,
  "delivery": "pending"
}

Atualizar um IP estático

PATCH/static/{id}

Escopo: write:proxies

Parâmetros de caminho

  • idstringObrigatório

    O id do IP estático.

Parâmetros do corpo

  • autoRenewbooleanOpcional

    Renovar automaticamente com o saldo antes de expirar.

  • namestringOpcional

    Um rótulo para o IP.

  • notestringOpcional

    Uma nota privada.

curl -X PATCH "https://socksnode.com/api/v1/static/STATIC_ID" \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "autoRenew": true
  }'
Resposta200
{
  "id": "clx…",
  "autoRenew": true,
  …
}

IP residencial dedicado 24 horas

IPs residenciais de 24 horas (/day-ip): liste o que está à venda por país, estado, cidade ou provedor, compre endereços exatos pelo ref ou quaisquer correspondentes por quantidade, e depois liste, anote, favorite, cheque fraude e meça a velocidade do que você tem. Cada endereço funciona por até 24 horas sem limite de GB; um que não funciona nos 10 minutos após a compra pode ser reembolsado.

IPs de 24 horas: países e preço

GET/day-ip/countries

Escopo: read:proxies

Parâmetros de consulta

  • poolstringOpcional

    Catálogo de qual rede: a (padrão) ou b. As duas cobrem países diferentes, por isso cada uma responde a sua própria lista.

    abPadrão: a

curl "https://socksnode.com/api/v1/day-ip/countries" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
Resposta200
{
  "priceUsd": 0.09,
  "count": 219,
  "data": [{ "code": "US", "name": "United States" }]
}

IPs de 24 horas: estados, cidades e provedores

GET/day-ip/places

Escopo: read:proxies

Parâmetros de consulta

  • levelstringObrigatório

    O que listar: state, city ou asn (as redes de provedor); na rede b, isp em vez de asn.

    statecityasnisp

  • countrystringObrigatório

    Código de país de duas letras, ex. US.

  • statestringOpcional

    Um estado ou região, como /day-ip/places lista.

  • poolstringOpcional

    Catálogo de qual rede: a (padrão) ou b. As duas cobrem países diferentes, por isso cada uma responde a sua própria lista.

    abPadrão: a

curl "https://socksnode.com/api/v1/day-ip/places?level=city&country=US&state=Texas" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
Resposta200
{
  "level": "city",
  "country": "US",
  "data": [{ "value": "Dallas", "label": "Dallas" }]
}

IPs de 24 horas: endereços à venda

GET/day-ip/shop

Escopo: read:proxies

Parâmetros de consulta

  • countrystringObrigatório

    Código de país de duas letras, ex. US.

  • statestringOpcional

    Um estado ou região, como /day-ip/places lista.

  • citystringOpcional

    Uma cidade, como /day-ip/places lista; sem precisar do estado.

  • asnintegerOpcional

    Um número de rede (ASN), ex. 7922.

  • freshbooleanOpcional

    true lista de novo em vez de usar a cópia dos últimos 90 segundos.

  • morebooleanOpcional

    true adiciona um novo lote à lista (até 500). Cada consulta retorna no máximo 100 endereços e a loja não busca por faixa de IP, então amplie a lista para encontrá-lo.

  • ispstringOpcional

    Uma rede pelo nome, exatamente como /day-ip/places a lista (rede b).

  • zipstringOpcional

    Um código postal (ZIP), correspondência exata (rede b).

  • poolstringOpcional

    Qual rede: a (padrão) ou b. A rede b exige um country, filtra por isp e zip em vez de asn, e cada endereço traz um ping; fresh e more não se aplicam a ela.

    abPadrão: a

curl "https://socksnode.com/api/v1/day-ip/shop?country=US&state=Texas" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
Resposta200
{
  "priceUsd": 0.09,
  "walletUsd": 12.4,
  "count": 98,
  "data": [
    { "ref": "DO7fs76WkECuwM", "ip": "73.12.148.*", "cc": "US", "state": "Texas", "city": "Dallas", "isp": "Comcast Cable Communications, LLC", "asn": 7922 }
  ]
}

IPs de 24 horas: comprar

POST/day-ip/ips

Escopo: purchase

Parâmetros do corpo

  • refsstring[]Opcional

    Endereços exatos a comprar: o ref de cada um, de /day-ip/shop. Um ref pode ser comprado por cerca de 5 minutos. Até 50.

  • countrystringOpcional

    Em vez de refs: compre endereços que correspondam neste país (com state, city ou asn para restringir).

  • statestringOpcional

    Um estado ou região, como /day-ip/places lista.

  • citystringOpcional

    Uma cidade, como /day-ip/places lista; sem precisar do estado.

  • asnintegerOpcional

    Um número de rede (ASN), ex. 7922.

  • countintegerOpcional

    Com country: quantos endereços, de 1 a 50.

  • ispstringOpcional

    Uma rede pelo nome, exatamente como /day-ip/places a lista (rede b).

  • poolstringOpcional

    Qual rede: a (padrão) ou b. A rede b vende apenas endereços exatos — envie refs junto com o country, nunca count.

    abPadrão: a

curl -X POST "https://socksnode.com/api/v1/day-ip/ips" \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "refs": [
      "SHOP_REF_1",
      "SHOP_REF_2"
    ]
  }'
Resposta201
{
  "bought": [
    { "id": "cmv…", "proxy": "vault.socksnode.com:27311:user-ip:pass", "ip": "73.12.148.20", "country": "US", "city": "Dallas", "isp": "Comcast Cable Communications, LLC", "asn": 7922, "expiresAt": "2026-10-12T15:36:40Z" }
  ],
  "chargedUsd": 0.18,
  "refundedUsd": 0
}

IPs de 24 horas: listar os seus

GET/day-ip/ips

Escopo: read:proxies

Parâmetros de consulta

  • viewstringOpcional

    active: endereços dentro das 24 horas; all: também os dos últimos 7 dias.

    activeallPadrão: active

curl "https://socksnode.com/api/v1/day-ip/ips" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
Resposta200
{
  "view": "active",
  "count": 1,
  "data": [
    { "id": "cmv…", "proxy": "vault.socksnode.com:27311:user-ip:pass", "ip": "73.12.148.20", "country": "US", "status": "active", "expiresAt": "2026-10-12T15:36:40Z", "fraud": { "score": 12, "risk": "low", "listed": false }, "speedMs": 1840, "note": "shop #3", "favorite": true }
  ]
}

IPs de 24 horas: nota e favorito

PATCH/day-ip/ips/{id}

Escopo: write:proxies

Parâmetros de caminho

  • idstringObrigatório

    O id de um dos seus IPs de 24 horas.

Parâmetros do corpo

  • notestringOpcional

    Sua nota para o endereço, até 200 caracteres.

  • favoritebooleanOpcional

    Marcar ou desmarcar como favorito.

curl -X PATCH "https://socksnode.com/api/v1/day-ip/ips/DAY_IP_ID" \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "note": "shop #3",
    "favorite": true
  }'
Resposta200
{
  "id": "cmv…",
  "ok": true
}

IPs de 24 horas: reembolsar um IP morto

POST/day-ip/ips/{id}/refund

Escopo: write:proxies

Parâmetros de caminho

  • idstringObrigatório

    O id de um dos seus IPs de 24 horas.

curl -X POST "https://socksnode.com/api/v1/day-ip/ips/DAY_IP_ID/refund" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
Resposta200
{
  "id": "cmv…",
  "result": "refunded",
  "windowMinutes": 10
}

IPs de 24 horas: reembolsar vários IPs mortos

POST/day-ip/ips/refund

Escopo: write:proxies

Parâmetros do corpo

  • idsstring[]Obrigatório

    Ids dos seus IPs de 24 horas a reembolsar, até 50. Cada um é testado de novo primeiro, e a resposta diz o que aconteceu com cada um: refunded, still_online ou expired.

curl -X POST "https://socksnode.com/api/v1/day-ip/ips/refund" \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "DAY_IP_ID_1",
      "DAY_IP_ID_2"
    ]
  }'
Resposta200
{
  "refunded": 1,
  "stillOnline": 1,
  "expired": 0,
  "windowMinutes": 10,
  "data": [
    { "id": "cmv…", "result": "refunded", "why": "dead", "usd": 0.09 },
    { "id": "cmw…", "result": "still_online", "usd": 0 }
  ]
}

IPs de 24 horas: checagem de fraude

POST/day-ip/ips/fraud

Escopo: purchase

Parâmetros do corpo

  • idsstring[]Obrigatório

    Ids dos seus IPs de 24 horas, até 50. $0.003 cada, do saldo.

curl -X POST "https://socksnode.com/api/v1/day-ip/ips/fraud" \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "DAY_IP_ID"
    ]
  }'
Resposta200
{
  "checked": 1,
  "failed": 0,
  "chargedUsd": 0.003,
  "data": [{ "id": "cmv…", "ip": "73.12.148.20", "fraud": { "score": 12, "risk": "low", "listed": false } }]
}

IPs de 24 horas: verificar se está online

POST/day-ip/ips/speed

Escopo: read:proxies

Parâmetros do corpo

  • idsstring[]Obrigatório

    Ids dos seus IPs de 24 horas, até 20.

curl -X POST "https://socksnode.com/api/v1/day-ip/ips/speed" \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "DAY_IP_ID"
    ]
  }'
Resposta200
{
  "data": [{ "id": "cmv…", "ip": "73.12.148.20", "online": true, "speedMs": 1840 }]
}

Pronto para começar?

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