Desenvolvedores

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/reseller

Produtos

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.

productProdutoSegmentaçãoIP sticky
residentialResidencial rotativoPaís, estado, cidade, ASN1–1440 min
datacenterDatacenter rotativoPaís, cidade, ASN1–1440 min
mobile_rotatingMóvel rotativo (IPs de operadoras 4G/5G)País; estado, cidade e ASN contam o tráfego em dobro1–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 before

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/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_xxx

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.
422Limite de subcontas atingido.
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": "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-30

Personalizaçã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.

RegiongatewayIdCNAME target
Nearest (default)autoglobal.socksnode.com
Francefrfr.socksnode.com
United Statesusus.socksnode.com
Singaporesgsg.socksnode.com
  1. 1

    Add a DNS record.

    For each region you want branded, create a CNAME from 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 an A record and ask us for the current IPs. A CNAME follows automatically if they change; an A record won't.

  2. 2

    Wait for DNS to propagate.

    Usually a few minutes, sometimes a few hours, depending on your provider and TTL.

  3. 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. 4

    Verify.

    Generate a test proxy for that region, check that the host in 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"
Resposta200
{
  "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

  • labelstringOpcional

    Seu 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"
  }'
Resposta201
{
  "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"
Resposta200
{
  "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ório

    O id da subconta.

curl "https://socksnode.com/api/v1/reseller/subaccounts/SUB_ID" \
  -H "Authorization: Bearer sk_live_xxx"
Resposta200
{
  "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ório

    O id da subconta.

Parâmetros do corpo

  • labelstring | nullOpcional

    Seu nome para este cliente, até 80 caracteres.

  • reactivatebooleanOpcional

    true 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"
  }'
Resposta200
{
  "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ório

    O id da subconta.

Parâmetros do corpo

  • gbnumberObrigatório

    GB a mover do seu pool. Um número negativo devolve GB, até o saldo da subconta.

  • productstringOpcional

    Qual 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"
  }'
Resposta200
{
  "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ório

    O id da subconta.

Parâmetros do corpo

  • productstringOpcional

    Qual 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: residential

  • 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.

  • gatewayIdstringOpcional

    Região de entrada: fr, us ou sg. Define qual dos seus hosts white-label é retornado.

    frussg

  • 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.

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"
  }'
Resposta201
{
  "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ório

    O id da subconta.

curl "https://socksnode.com/api/v1/reseller/subaccounts/SUB_ID/proxies" \
  -H "Authorization: Bearer sk_live_xxx"
Resposta200
{
  "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ório

    O id da subconta.

Parâmetros de consulta

  • rangestringOpcional

    Período. Um valor desconhecido usa 24h.

    1h24h7d30d90dtodaymonth12mallPadrão: 24h

  • productstringOpcional

    Qual 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"
Resposta200
{
  "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ório

    O id da subconta.

curl -X DELETE "https://socksnode.com/api/v1/reseller/subaccounts/SUB_ID" \
  -H "Authorization: Bearer sk_live_xxx"
Resposta200
{
  "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

  • productstringOpcional

    Qual 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

  • 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/reseller/locations" \
  -H "Authorization: Bearer sk_live_xxx"
Resposta200
{
  "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ório

    Código de país de duas letras.

Parâmetros de consulta

  • productstringOpcional

    Qual 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

  • 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/reseller/locations/US" \
  -H "Authorization: Bearer sk_live_xxx"
Resposta200
{
  "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.