Abrir o Painel
documentação pública

API Referência

Automatize compras e renovações de proxies.

Gerir chaves
Referência
pt

Introdução

Interface programática para listar planos, ver subscrições, comprar novos proxies, renovar subscrições ativas e configurar a rotação automática de IP.

A API usa um único endpoint: /api/proxy. Nas operações GET, passe op na query string; nas operações POST, passe op no JSON body.

Início rápido

Crie uma chave de API em Dashboard -> API Keys e envie-a no cabeçalho de cada pedido.

BASE="https://makeadsafe.com"
API_KEY="rk_your_long_lived_api_key"

Todos os IDs são alfanuméricos em minúsculas.

A emissão de trial via POST /api/proxy com {"op":"trial","planId":"..."} está disponível apenas para determinadas API keys. Contacta o suporte para ativar esta funcionalidade na tua chave. A utilização de trial é monitorizada e pode ser limitada ou desativada em caso de abuso.

Planos disponíveis

Devolve os planos de proxy ativos disponíveis para o proprietário da chave de API.

curl -sS 
  -H "x-api-key: $API_KEY" 
  "$BASE/api/proxy?op=plans"
{
  "ok": true,
  "plans": [
    {
      "id": "k17m3q5v7n9p1r2t4w6y8z0a",
      "connectionType": "private",
      "durationMs": 2592000000,
      "priceAmountCents": 1200,
      "popular": true,
      "remainingProxies": 20,
      "network": {
        "name": "NL-AMS",
        "city": "Amsterdam",
        "country": "NL",
        "networkType": "mobile"
      }
    }
  ]
}

Subscrições ativas

Devolve as suas subscrições, incluindo credenciais, URLs de protocolo e dados de rotação de IP.

curl -sS 
  -H "x-api-key: $API_KEY" 
  "$BASE/api/proxy?op=subscriptions"
{
  "ok": true,
  "subscriptions": [
    {
      "subscriptionId": "j97b2f6m1k4n8p3r5t7v9x0z",
      "status": "active",
      "activeUntil": 1762592000000,
      "userNote": "Client A",
      "rotationPolicy": 10,
      "label": "12001 - NL - Private",
      "networkLabel": "NL-AMS Amsterdam",
      "credentials": {
        "username": "u_6k8s9d",
        "password": "p_2n4m6q"
      },
      "protocols": {
        "http": "http://u_6k8s9d:[email protected]:12001",
        "socks5": "socks5://u_6k8s9d:[email protected]:12001",
        "vless": "vless://...",
        "shadowsocks": "ss://..."
      },
      "rotate": {
        "rotatePath": "/r/abcd1234",
        "available": true
      }
    }
  ]
}

Planos de renovação

Devolve planos elegíveis para renovar uma subscrição específica.

SUB_ID="j97b2f6m1k4n8p3r5t7v9x0z"

curl -sS 
  -H "x-api-key: $API_KEY" 
  "$BASE/api/proxy?op=renewal-plans&subscriptionId=$SUB_ID"
{
  "ok": true,
  "renewalPlans": [
    {
      "id": "k17m3q5v7n9p1r2t4w6y8z0a",
      "connectionType": "private",
      "durationMs": 2592000000,
      "priceAmountCents": 1200
    }
  ]
}

Redes disponíveis

Retorna as redes disponíveis para trocar uma subscrição específica.

SUB_ID="j97b2f6m1k4n8p3r5t7v9x0z"

curl -sS 
  -H "x-api-key: $API_KEY" 
  "$BASE/api/proxy?op=available-networks&subscriptionId=$SUB_ID"
{
  "ok": true,
  "networks": [
    {
      "id": "b1c2d3e4f5g6h7j8k9m0n1p2",
      "networkLabel": "DE-BER Berlin",
      "country": "DE"
    }
  ]
}

Use networks[].id como targetNetwork no pedido switch-network.

Comprar subscrição

Cria uma ou várias novas subscrições a partir do seu saldo com o plano selecionado.

Campos opcionais:

  • couponCode: aplica um cupão válido à compra.
  • repeatCount: inteiro positivo, valor predefinido 1; multiplica a duração e o preço de cada subscrição criada.
  • quantity: inteiro positivo, valor predefinido 1; cria várias subscrições num único pedido.
  • os: impressão digital passiva do sistema operativo aplicada a todos os proxies criados; ios, macos, android, win10 ou win11. Indisponível para planos multi.
{
  "op": "purchase",
  "planId": "k17m3q5v7n9p1r2t4w6y8z0a",
  "couponCode": "MYCODE",
  "repeatCount": 3,
  "os": "ios",
  "quantity": 2
}
curl -sS -X POST 
  -H "x-api-key: $API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"op":"purchase","planId":"k17m3q5v7n9p1r2t4w6y8z0a","repeatCount":3,"os":"ios","quantity":2}' 
  "$BASE/api/proxy"
{
  "ok": true,
  "subscriptionId": "j97b2f6m1k4n8p3r5t7v9x0z",
  "subscriptionIds": [
    "j97b2f6m1k4n8p3r5t7v9x0z",
    "n38k2f6m1k4n8p3r5t7v9x0z"
  ],
  "subscriptions": [
    {
      "subscriptionId": "j97b2f6m1k4n8p3r5t7v9x0z",
      "status": "active",
      "activeUntil": 1767776000000,
      "label": "12001 - NL - Private",
      "networkLabel": "NL-AMS Amsterdam"
    },
    {
      "subscriptionId": "n38k2f6m1k4n8p3r5t7v9x0z",
      "status": "active",
      "activeUntil": 1767776000000,
      "label": "12002 - NL - Private",
      "networkLabel": "NL-AMS Amsterdam"
    }
  ]
}

Se for criada apenas uma subscrição, o gateway pode devolver subscription em vez de subscriptions. Os itens em subscription/subscriptions usam a mesma estrutura de GET /api/proxy?op=subscriptions.

Renovar subscrição

Renova uma subscrição existente com um plano de renovação elegível.

Campos opcionais:

  • couponCode: aplica um cupão válido à renovação.
  • repeatCount: inteiro positivo, valor predefinido 1; multiplica tanto a duração como o preço da renovação.
{
  "op": "renew",
  "subscriptionId": "j97b2f6m1k4n8p3r5t7v9x0z",
  "planId": "q2w4e6r8t0y2u4i6o8p0a2s4",
  "couponCode": "MYCODE",
  "repeatCount": 3
}
curl -sS -X POST 
  -H "x-api-key: $API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"op":"renew","subscriptionId":"j97b2f6m1k4n8p3r5t7v9x0z","planId":"q2w4e6r8t0y2u4i6o8p0a2s4","repeatCount":3}' 
  "$BASE/api/proxy"
{
  "ok": true,
  "subscriptionId": "j97b2f6m1k4n8p3r5t7v9x0z",
  "endAt": 1770368000000
}

Alterar credenciais de ligação

Regenera as credenciais de ligação para uma subscrição ativa do utilizador autenticado (JWT) ou do proprietário da chave de API.

{
  "op": "change-credentials",
  "subscriptionId": "j97b2f6m1k4n8p3r5t7v9x0z"
}
curl -sS -X POST 
  -H "x-api-key: $API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"op":"change-credentials","subscriptionId":"j97b2f6m1k4n8p3r5t7v9x0z"}' 
  "$BASE/api/proxy"
{
  "ok": true,
  "password": "q7N3x9Lp",
  "vpn": "7f3d9d4a-8b9f-4a93-9f55-2d5e3b7f1c24"
}

Definir política de rotação automática

Configura a rotação automática de IP para uma subscrição ativa. Disponível apenas para ligações com "rotate": { "available": true }.

Valores permitidos para rotationPolicy: 0, 5, 10, 15, 30, 60 minutos. Usa 0 para desativar a rotação automática.

{
  "op": "set-rotation-policy",
  "subscriptionId": "j97b2f6m1k4n8p3r5t7v9x0z",
  "rotationPolicy": 10
}
curl -sS -X POST 
  -H "x-api-key: $API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"op":"set-rotation-policy","subscriptionId":"j97b2f6m1k4n8p3r5t7v9x0z","rotationPolicy":10}' 
  "$BASE/api/proxy"
{
  "ok": true
}

Alterar rede de conexão

Move uma assinatura ativa para outra rede disponível.

{
  "op": "switch-network",
  "subscriptionId": "j97b2f6m1k4n8p3r5t7v9x0z",
  "targetNetwork": "b1c2d3e4f5g6h7j8k9m0n1p2"
}
curl -sS -X POST 
  -H "x-api-key: $API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"op":"switch-network","subscriptionId":"j97b2f6m1k4n8p3r5t7v9x0z","targetNetwork":"b1c2d3e4f5g6h7j8k9m0n1p2"}' 
  "$BASE/api/proxy"
{
  "ok": true,
  "subscription": {
    "subscriptionId": "j97b2f6m1k4n8p3r5t7v9x0z",
    "status": "active",
    "activeUntil": 1762592000000,
    "userNote": "Client A",
    "rotationPolicy": 10,
    "label": "12001 - DE - Private",
    "networkLabel": "DE-BER Berlin",
    "credentials": {
      "username": "u_6k8s9d",
      "password": "p_2n4m6q"
    },
    "protocols": {
      "http": "http://u_6k8s9d:[email protected]:12001",
      "socks5": "socks5://u_6k8s9d:[email protected]:12001",
      "vless": "vless://...",
      "shadowsocks": "ss://..."
    },
    "rotate": {
      "rotatePath": "/r/abcd1234",
      "available": true
    }
  }
}

Erros de gateway

  • 400 JSON body inválido
  • 400 O body deve ser um objeto
  • 400 op em falta ou desconhecido
  • 400 planId/subscriptionId/targetNetwork/rotationPolicy em falta ou inválido
  • 400 repeatCount ou quantity inválido
  • 400 os inválido
  • 401 Unauthorized
  • 402 Saldo insuficiente
  • 403 Forbidden
  • 404 Subscrição não encontrada
  • 409 Política de rotação indisponível para esta subscrição
  • 409 Esgotado, plano/rede inativos ou estado de subscrição inválido
  • 409 A seleção do sistema operativo não está disponível para planos multi
  • 429 Rate limited
  • 500 Internal error