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{"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:PASSWORDPortas 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.
| Protocolo | Porta rotativa | Porta persistente |
|---|---|---|
| HTTP / HTTPS | 9000 | 10000 |
| SOCKS5 | 11000 | 12000 |
| Gateway | Host |
|---|---|
| O mais próximo de você (padrão) | global.socksnode.com |
| Europa | fr.socksnode.com |
| Estados Unidos | us.socksnode.com |
| Singapura | sg.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.orgSegmentaçã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:
| Token | Significado |
|---|---|
| -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-androidPools
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.
| pool | Segmentação | Sticky | |
|---|---|---|---|
| 1 | Pool 1 | País, estado, cidade e ISP (ASN), combinados livremente | 1–1440 min |
| 2 | Pool 2 | País e depois um de: um estado, uma cidade ou um ISP | 1–60 min |
| 3 | Pool 3 | País; estado e cidade nos EUA | 1–1440 min |
| mix | Mix | Os locais do Pool 1; cada pool do Mix atende o que pode | 1–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.
| Escopo | Permissões |
|---|---|
| read:usage | Saldo e analytics de uso |
| read:proxies | Listar credenciais de proxy salvas |
| write:proxies | Gerar novas credenciais de proxy |
| purchase | Comprar 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_KEYErros
Os erros retornam um corpo JSON { "error": { "code", "message" } } com o status HTTP correspondente:
| Status | Significado |
|---|---|
| 400 | Corpo da solicitação inválido ou parâmetros inválidos |
| 401 | Chave de API ausente, inválida ou revogada |
| 402 | Saldo de largura de banda insuficiente para gerar proxies |
| 403 | A chave de API não tem o escopo necessário |
| 404 | Não encontrado, ou não é seu. |
| 429 | Limite de taxa excedido — consulte o cabeçalho Retry-After |
| 503 | O 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"{
"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
productstringOpcionalQual rede: residential (padrão), datacenter ou mobile_rotating.
residentialdatacentermobile_rotatingPadrão:residentialgbintegerOpcionalOpcional. 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"{
"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
productstringOpcionalQual rede: residential (padrão), datacenter ou mobile_rotating.
residentialdatacentermobile_rotatingPadrão:residentialgbintegerObrigatórioGB 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
}'{
"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
rangestringOpcionalPeríodo. Um valor desconhecido usa 24h.
1h24h7d30d90dtodaymonth12mallPadrão:24hproductstringOpcionaldatacenter 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"{
"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"{
"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órioProtocolo das credenciais.
httpsocks5countrystringObrigatórioCódigo de país de duas letras, ou ANY para o mundo todo.
statestringOpcionalEstado dos EUA, nome completo sem espaços, ex.: california.
citystringOpcionalCidade sem espaços, ex.: losangeles. Ignorado quando há asn.
asnintegerOpcionalNúmero de rede do ISP, ex.: 7922 para Comcast.
sessionModestringObrigatóriorotating dá um IP novo a cada requisição; sticky mantém um IP por stickyDurationMinutes.
rotatingstickystickyDurationMinutesintegerOpcionalQuanto tempo um IP sticky é mantido, 1–1440 minutos. Obrigatório quando sessionMode é sticky.
countintegerOpcionalQuantas credenciais criar, 1–20.
Padrão:
1labelstringOpcionalSeu nome para elas, até 80 caracteres. Com count acima de 1 cada uma recebe #n.
poolstringOpcionalPool residencial: 1 (padrão), 2, 3 ou mix. Veja Pools.
123mixPadrão:1mixPoolsstringOpcionalCom pool mix: os pools que ele usa, 12, 13, 23 ou 123 (padrão 123).
121323123Padrão:123strictbooleanOpcionaltrue: 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.
gatewaystringOpcionalGateway 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:autoosstringOpcionalImpressão digital do sistema do dispositivo: windows, android, ios ou mac. Omita para qualquer dispositivo.
windowsandroidiosmacproductstringOpcionalQual 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"
}'{
"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órioO 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"{
"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
countrystringOpcionalCódigo do país. Retorna seus estados.
statestringOpcionalCódigo do estado, junto com country. Retorna suas cidades.
productstringOpcionalQual 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:residentialpoolstringOpcionalPool 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"{
"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.