API de revenda
Provisione proxies para seus clientes de forma programática — crie subcontas, aloque largura de banda, gere credenciais e consulte o uso.
Nesta página
API de revenda
Visão geral
Obtendo acesso. A API de revenda é habilitada assim que sua conta de revendedor é ativada. Depois disso, você cria uma chave de API e chama os endpoints abaixo com ela.
- Pool de largura de banda
- Seu saldo pré-pago. Ao alocar para uma subconta, ele é consumido; ao recuperar, é devolvido.
- Subcontas
- Cada um dos seus clientes finais é uma subconta com sua própria largura de banda, credenciais de proxy e uso.
https://socksnode.com/api/v1/resellerProdutos
Você pode vender três produtos. Cada um tem seu próprio pool, seu próprio preço de atacado e seu próprio saldo em cada subconta, então um GB de um nunca é gasto como outro. Escolha com o campo product em allocate, proxies, usage e locations.
| product | Produto | Segmentação | IP sticky |
|---|---|---|---|
| residential | Residencial rotativo | País, estado, cidade, ASN | 1–1440 min |
| datacenter | Datacenter rotativo | País, cidade, ASN | 1–1440 min |
| mobile_rotating | Móvel rotativo (IPs de operadoras 4G/5G) | País; estado, cidade e ASN contam o tráfego em dobro | 1–120 min |
Sem product, toda chamada significa residencial, exatamente como antes. Datacenter e móvel rotativo ficam disponíveis quando ativados na sua conta; até lá essas chamadas respondem 403 product_not_enabled.
# Allocate 10 GB of DATACENTER to a sub-account
curl -X POST "https://socksnode.com/api/v1/reseller/subaccounts/SUB_ID/allocate" \
-H "Authorization: Bearer sk_live_xxx" \
-H "Content-Type: application/json" \
-d '{"gb": 10, "product": "datacenter"}'
# Generate a ROTATING MOBILE proxy for it
curl -X POST "https://socksnode.com/api/v1/reseller/subaccounts/SUB_ID/proxies" \
-H "Authorization: Bearer sk_live_xxx" \
-H "Content-Type: application/json" \
-d '{"product": "mobile_rotating", "country": "us",
"protocol": "http", "sessionMode": "rotating"}'
# No "product" = residential, exactly as beforePools
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/reseller/subaccounts/SUB_ID/proxies" \
-H "Authorization: Bearer sk_live_xxx" \
-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/reseller/subaccounts/SUB_ID/proxies" \
-H "Authorization: Bearer sk_live_xxx" \
-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/reseller/locations/GB?pool=2" \
-H "Authorization: Bearer sk_live_xxx"Autenticação
Cada solicitação é autenticada com sua chave de API como um Bearer token. Mantenha-a em segredo — ela pode provisionar largura de banda do seu pool.
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/reseller/pool HTTP/1.1
Host: socksnode.com
Authorization: Bearer sk_live_xxxErros
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. |
| 422 | Limite de subcontas atingido. |
| 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": "insufficient_pool",
"message": "…"
}
}IDs de sessão autogerenciados
Cada nome de usuário de credencial é apenas uma string de token, e a senha permanece a mesma durante toda a vida da subconta. Depois de gerar uma, crie quantas sessões rotativas ou persistentes quiser localmente — sem chamadas extras à API, sem limite de lote de 20 por solicitação.
As sessões criadas dessa forma não são rastreadas como credenciais individuais — elas não aparecem na lista de proxies de uma subconta e não podem ser revogadas uma a uma. A largura de banda ainda é aplicada corretamente em relação à sua alocação em ambos os casos, e o uso agregado ainda é exibido pelo endpoint de uso.
# Base credential, from any POST …/proxies call
username: acme-country-us
password: 3f9c2a1b-7e4d-4a2c-9f1a-8b6c5d4e3f2a
# Rotating: no session token, a fresh IP every request
acme-country-us
# Sticky: append your own session id + lifetime (1-1440 minutes).
# Build as many as you want locally, no API call needed:
acme-country-us-session-req0001-lifetime-30
acme-country-us-session-req0002-lifetime-30
acme-country-us-session-req0003-lifetime-30
# State and city targeting work the same way (see /locations):
acme-country-us-state-california-session-req0004-lifetime-30Personalização da marca do seu gateway
Roteie os proxies pelo seu próprio domínio em vez do nosso. gatewayId escolhe a região de entrada (fr/us/sg) — isso não afeta o país de saída, que você define separadamente no campo country.
| Region | gatewayId | CNAME target |
|---|---|---|
| Nearest (default) | auto | global.socksnode.com |
| France | fr | fr.socksnode.com |
| United States | us | us.socksnode.com |
| Singapore | sg | sg.socksnode.com |
- 1
Add a DNS record.
For each region you want branded, create a
CNAMEfrom your own subdomain (e.g.us.yourbrand.com) to that region's target above. Only set up the regions you'll use; anything left blank falls back to your default host. If your DNS provider can't do a CNAME there, use anArecord and ask us for the current IPs. A CNAME follows automatically if they change; an A record won't. - 2
Wait for DNS to propagate.
Usually a few minutes, sometimes a few hours, depending on your provider and TTL.
- 3
Set it in your dashboard.
Go to Reseller → White-label gateway. With more than one region you'll see a field per region plus a Default field. Enter the domain you set up and save.
- 4
Verify.
Generate a test proxy for that region, check that the
hostin the response is your domain, then connect through it once.
gatewayId picks your customer's entry point, not their exit country; the exit country is the country field. A DNS lookup on your CNAME still shows it resolves to socksnode.com. To hide that from your own customers, run your own relay (nginx or HAProxy stream) in front instead of a plain CNAME, and ask us if you need help.
; One CNAME per region you brand
proxy.yourbrand.com. CNAME global.socksnode.com.
fr.yourbrand.com. CNAME fr.socksnode.com.
us.yourbrand.com. CNAME us.socksnode.com.
sg.yourbrand.com. CNAME sg.socksnode.com.Endpoints
Consulte o saldo do seu pool de largura de banda
GET/pool
Escopo: reseller:read
Sem parâmetros.
curl "https://socksnode.com/api/v1/reseller/pool" \
-H "Authorization: Bearer sk_live_xxx"{
"poolGb": 812.5,
"allocatedGb": 187.5,
"subAccounts": 42,
"products": {
"residential": { "poolGb": 812.5, "allocatedGb": 187.5, "ratePerGb": 0.54, "pricing": "wholesale" },
"datacenter": { "poolGb": 300, "allocatedGb": 23.2, "ratePerGb": null, "pricing": "site" }
}
}Crie uma subconta para um dos seus clientes
POST/subaccounts
Escopo: reseller:manage
Parâmetros do corpo
labelstringOpcionalSeu nome para este cliente, até 80 caracteres.
curl -X POST "https://socksnode.com/api/v1/reseller/subaccounts" \
-H "Authorization: Bearer sk_live_xxx" \
-H "Content-Type: application/json" \
-d '{
"label": "customer-acme"
}'{
"id": "sub_9f2a…",
"label": "customer-acme",
"balanceGb": 0,
"usedGb": 0,
"status": "active",
"createdAt": "2026-09-30T08:12:44.000Z",
"products": {
"residential": { "balanceGb": 8.4, "usedGb": 1.6 },
"datacenter": { "balanceGb": 20, "usedGb": 3.2 },
"mobile_rotating": { "balanceGb": 0, "usedGb": 0 }
}
}Liste suas subcontas com saldo e uso
GET/subaccounts
Escopo: reseller:read
Sem parâmetros.
curl "https://socksnode.com/api/v1/reseller/subaccounts" \
-H "Authorization: Bearer sk_live_xxx"{
"data": [
{
"id": "sub_9f2a…",
"label": "customer-acme",
"balanceGb": 8.4,
"usedGb": 1.6,
"status": "active",
"createdAt": "2026-09-30T08:12:44.000Z",
"products": {
"residential": { "balanceGb": 8.4, "usedGb": 1.6 },
"datacenter": { "balanceGb": 20, "usedGb": 3.2 },
"mobile_rotating": { "balanceGb": 0, "usedGb": 0 }
}
}
]
}Obter uma subconta
GET/subaccounts/{id}
Escopo: reseller:read
Parâmetros de caminho
idstringObrigatórioO id da subconta.
curl "https://socksnode.com/api/v1/reseller/subaccounts/SUB_ID" \
-H "Authorization: Bearer sk_live_xxx"{
"id": "sub_9f2a…",
"label": "customer-acme",
"balanceGb": 8.4,
"usedGb": 1.6,
"status": "active",
"createdAt": "2026-09-30T08:12:44.000Z",
"products": {
"residential": { "balanceGb": 8.4, "usedGb": 1.6 },
"datacenter": { "balanceGb": 20, "usedGb": 3.2 },
"mobile_rotating": { "balanceGb": 0, "usedGb": 0 }
}
}Renomear ou reativar uma subconta
PATCH/subaccounts/{id}
Escopo: reseller:manage
Parâmetros de caminho
idstringObrigatórioO id da subconta.
Parâmetros do corpo
labelstring | nullOpcionalSeu nome para este cliente, até 80 caracteres.
reactivatebooleanOpcionaltrue reativa os proxies da subconta. A banda não é restaurada.
curl -X PATCH "https://socksnode.com/api/v1/reseller/subaccounts/SUB_ID" \
-H "Authorization: Bearer sk_live_xxx" \
-H "Content-Type: application/json" \
-d '{
"label": "customer-acme-eu"
}'{
"id": "sub_9f2a…",
"label": "customer-acme-eu",
"balanceGb": 8.4,
"usedGb": 1.6,
"status": "active",
"createdAt": "2026-09-30T08:12:44.000Z",
"products": {
"residential": { "balanceGb": 8.4, "usedGb": 1.6 },
"datacenter": { "balanceGb": 20, "usedGb": 3.2 },
"mobile_rotating": { "balanceGb": 0, "usedGb": 0 }
}
}Aloque largura de banda para uma subconta a partir do seu pool
POST/subaccounts/{id}/allocate
ou envie um gb negativo para recuperá-la.
Escopo: reseller:manage
Parâmetros de caminho
idstringObrigatórioO id da subconta.
Parâmetros do corpo
gbnumberObrigatórioGB a mover do seu pool. Um número negativo devolve GB, até o saldo da subconta.
productstringOpcionalQual produto: residential (padrão), datacenter ou mobile_rotating. Cada um tem seu próprio pool, preço de atacado e saldo de subconta, e fica disponível quando ativado na sua conta.
residentialdatacentermobile_rotatingPadrão:residential
curl -X POST "https://socksnode.com/api/v1/reseller/subaccounts/SUB_ID/allocate" \
-H "Authorization: Bearer sk_live_xxx" \
-H "Content-Type: application/json" \
-d '{
"gb": 10,
"product": "datacenter"
}'{
"id": "sub_9f2a…",
"product": "datacenter",
"balanceGb": 10,
"poolGb": 290
}
// With a negative gb:
// { "id": "sub_9f2a…", "product": "datacenter", "reclaimedGb": 4, "balanceGb": 6, "poolGb": 294 }Gere credenciais de proxy para uma subconta
POST/subaccounts/{id}/proxies
rotativo (novo IP por solicitação) ou persistente (o mesmo IP por 1–1440 minutos via stickyDurationMinutes).
Escopo: reseller:manage
Parâmetros de caminho
idstringObrigatórioO id da subconta.
Parâmetros do corpo
productstringOpcionalQual produto: residential (padrão), datacenter ou mobile_rotating. Cada um tem seu próprio pool, preço de atacado e saldo de subconta, e fica disponível quando ativado na sua conta. 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:residentialprotocolstringObrigató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.
gatewayIdstringOpcionalRegião de entrada: fr, us ou sg. Define qual dos seus hosts white-label é retornado.
frussgpoolstringOpcionalPool 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.
curl -X POST "https://socksnode.com/api/v1/reseller/subaccounts/SUB_ID/proxies" \
-H "Authorization: Bearer sk_live_xxx" \
-H "Content-Type: application/json" \
-d '{
"country": "us",
"protocol": "http",
"sessionMode": "rotating",
"gatewayId": "us"
}'{
"data": [
{
"id": "clx…",
"host": "gw.your-brand.com",
"port": 9000,
"username": "acme-country-us",
"password": "…",
"protocol": "http",
"country": "us",
"state": null,
"city": null,
"sessionMode": "rotating",
"stickyDurationMinutes": null,
"label": "customer-acme",
"product": "residential",
"pool": "1",
"mixPools": null,
"poolNote": null
}
]
}Listar as credenciais de proxy de uma subconta, com senhas
GET/subaccounts/{id}/proxies
Escopo: reseller:read
Parâmetros de caminho
idstringObrigatórioO id da subconta.
curl "https://socksnode.com/api/v1/reseller/subaccounts/SUB_ID/proxies" \
-H "Authorization: Bearer sk_live_xxx"{
"data": [
{
"id": "clx…",
"host": "gw.your-brand.com",
"port": 9000,
"username": "acme-country-us",
"password": "…",
"protocol": "http",
"country": "us",
"state": null,
"city": null,
"sessionMode": "rotating",
"stickyDurationMinutes": null,
"label": "customer-acme",
"status": "active",
"createdAt": "2026-09-30T08:12:44.000Z",
"lastUsedAt": null,
"product": "residential",
"pool": "1",
"mixPools": null,
"poolNote": null
}
]
}Consulte o uso de uma subconta em um intervalo de datas
GET/subaccounts/{id}/usage
Escopo: reseller:read
Parâmetros de caminho
idstringObrigatórioO id da subconta.
Parâmetros de consulta
rangestringOpcionalPeríodo. Um valor desconhecido usa 24h.
1h24h7d30d90dtodaymonth12mallPadrão:24hproductstringOpcionalQual produto: residential (padrão), datacenter ou mobile_rotating. Cada um tem seu próprio pool, preço de atacado e saldo de subconta, e fica disponível quando ativado na sua conta.
residentialdatacentermobile_rotatingPadrão:residential
curl "https://socksnode.com/api/v1/reseller/subaccounts/SUB_ID/usage?range=30d" \
-H "Authorization: Bearer sk_live_xxx"{
"product": "residential",
"range": "30d",
"totalGb": 6.8,
"totalRequests": 91240,
"successRate": 98.7,
"series": [{ "period": "2026-09-01", "gb": 0.4 }],
"requestSeries": [ … ]
}Desative uma subconta e recupere a largura de banda restante
DELETE/subaccounts/{id}
Escopo: reseller:manage
Parâmetros de caminho
idstringObrigatórioO id da subconta.
curl -X DELETE "https://socksnode.com/api/v1/reseller/subaccounts/SUB_ID" \
-H "Authorization: Bearer sk_live_xxx"{
"id": "sub_9f2a…",
"status": "deactivated",
"reclaimedGb": 8.4,
"reclaimed": { "residential": 8.4, "datacenter": 20, "mobile_rotating": 0 }
}Liste todos os países disponíveis para segmentação
GET/locations
Escopo: reseller:read
Parâmetros de consulta
productstringOpcionalQual produto: residential (padrão), datacenter ou mobile_rotating. Cada um tem seu próprio pool, preço de atacado e saldo de subconta, e fica disponível quando ativado na sua conta.
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/reseller/locations" \
-H "Authorization: Bearer sk_live_xxx"{
"product": "residential",
"data": [
{ "code": "US", "name": "United States" },
{ "code": "GB", "name": "United Kingdom" }
]
}Obtenha os estados, cidades e ISPs/ASNs de um país
GET/locations/{country}
Escopo: reseller:read
Parâmetros de caminho
countrystringObrigatórioCódigo de país de duas letras.
Parâmetros de consulta
productstringOpcionalQual produto: residential (padrão), datacenter ou mobile_rotating. Cada um tem seu próprio pool, preço de atacado e saldo de subconta, e fica disponível quando ativado na sua conta.
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/reseller/locations/US" \
-H "Authorization: Bearer sk_live_xxx"{
"product": "residential",
"data": {
"states": [
{
"code": "california",
"name": "California",
"cities": [{ "code": "losangeles", "name": "Los Angeles" }]
}
],
"asns": [{ "code": "7922", "name": "Comcast Cable Communications, LLC" }]
}
}Venda proxies residenciais sob sua própria marca
O acesso à API de revendedor está sendo disponibilizado gradualmente com o programa.