API Pública

API v2 – Documentação

Integração para revendedores — compatível com a especificação “v2” usada por vários painéis.

Visão geral

Esta API permite consultar saldo, listar serviços, criar pedidos, acompanhar status, solicitar cancelamento e refills.

Versão: v2
Base URL: (sempre use com a barra / ao final)
Protocolo: HTTPS obrigatório
Formato: application/x-www-form-urlencoded (recomendado) ou application/json
Autenticação: Envie sua chave de três formas:
- Parâmetro key no body
- Header X-API-Key: <KEY>
- Header Authorization: Bearer <KEY>
Moeda: Todas as respostas incluem currency (BRL, USD, etc)
Timeout: 30 segundos para todas as requisições

Importante: para serviços do tipo Custom Comments, envie os comentários no parâmetro comments, um por linha. Se não informar quantity, usamos o número de linhas.

Autenticação

Parâmetro via key

POST {{BASE_URL}}
action=balance&key=SUA_CHAVE_AQUI

Header via X-API-Key ou Bearer

POST {{BASE_URL}}
Headers:
  X-API-Key: SUA_CHAVE_AQUI
Body:
  action=balance

// ou
Authorization: Bearer SUA_CHAVE_AQUI

JSON Exemplo

curl -X POST "{{BASE_URL}}" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "balance",
    "key": "SUA_CHAVE"
  }'

Endpoints

POST action=balance

Retorna seu saldo atual e a moeda.

cURL

curl -X POST "{{BASE_URL}}" \
  -d "action=balance" \
  -d "key=SUA_CHAVE"

Resposta

{
  "balance": "123.45000",
  "currency": "BRL"
}

POST action=services

Lista serviços ativos.

curl -X POST "{{BASE_URL}}" -d "action=services" -d "key=SUA_CHAVE"

Exemplo de resposta

[
  {
    "service": 101,
    "name": "Seguidores HQ",
    "type": "Default",
    "category": "Instagram",
    "rate": "12.50000",      // preço / 1000 na moeda da API
    "min": "100",
    "max": "100000",
    "refill": false,
    "cancel": true
  },
  {
    "service": 202,
    "name": "Comentários personalizados",
    "type": "Custom Comments",
    "category": "Instagram",
    "rate": "35.00000",
    "min": "10",
    "max": "5000",
    "refill": false,
    "cancel": true
  }
]

POST action=add

Cria um pedido.

Parâmetros

service (obrigatório)
link (obrigatório)
quantity (obrigatório, exceto Custom Comments quando enviar comments)
comments (apenas para Custom Comments, um por linha; se não enviar quantity, usamos o número de linhas)

Exemplo (Default)

curl -X POST "{{BASE_URL}}" \
  -d "action=add" \
  -d "key=SUA_CHAVE" \
  -d "service=101" \
  -d "link=https://instagram.com/p/XXXX" \
  -d "quantity=1000"

Exemplo (Custom Comments)

curl -X POST "{{BASE_URL}}" \
  -d "action=add" \
  -d "key=SUA_CHAVE" \
  -d "service=202" \
  -d "link=https://instagram.com/p/XXXX" \
  --data-urlencode "comments=Primeiro comentário
Segundo comentário
Terceiro comentário"

Resposta

{ "order": 789 }

POST action=status

Consulta status de um pedido (order) ou de vários (orders = IDs separados por vírgula).

Um pedido

curl -X POST "{{BASE_URL}}" -d "action=status" -d "key=SUA_CHAVE" -d "order=789"

Resposta

{
  "charge": "12.50000",
  "start_count": "0",
  "status": "In progress",
  "remains": "250",
  "currency": "BRL"
}

Múltiplos

curl -X POST "{{BASE_URL}}" -d "action=status" -d "key=SUA_CHAVE" -d "orders=789,790,791"

Resposta

{
  "789": { "charge":"12.50000", "start_count":"0", "status":"Completed", "remains":"0", "currency":"BRL" },
  "790": { "charge":"7.00000",  "start_count":"0", "status":"In progress", "remains":"120", "currency":"BRL" },
  "791": { "error":"Incorrect order ID" }
}

POST action=cancel

Solicita cancelamento de múltiplos pedidos (orders).

curl -X POST "{{BASE_URL}}" \
  -d "action=cancel" \
  -d "key=SUA_CHAVE" \
  -d "orders=789,790"

Resposta

[
  {"order":789,"cancel":1},
  {"order":790,"cancel":{"error":"Unable to cancel"}}
]

Regras: só é possível cancelar quando o pedido está Pending ou In progress. Quando aprovado, o valor é reembolsado integralmente.

POST action=refill / refill_status

Refill abre um ticket interno; consulte o status com refill_status.

Refill (um ou múltiplos)

curl -X POST "{{BASE_URL}}" -d "action=refill" -d "key=SUA_CHAVE" -d "order=789"

curl -X POST "{{BASE_URL}}" -d "action=refill" -d "key=SUA_CHAVE" -d "orders=789,790"

Resposta

{"refill":"15"}

[
  {"order":789,"refill":"15"},
  {"order":790,"refill":"16"}
]

Status do refill

curl -X POST "{{BASE_URL}}" -d "action=refill_status" -d "key=SUA_CHAVE" -d "refill=15"

curl -X POST "{{BASE_URL}}" -d "action=refill_status" -d "key=SUA_CHAVE" -d "refills=15,16"

Resposta

{"status":"Pending"}

[
  {"refill":15,"status":"Pending"},
  {"refill":16,"status":"Completed"}
]

Status possíveis de um pedido

Status	Descrição	Ação possível
Pending	Pedido aguardando processamento / fila	Cancelar ✓ \| Refill ✓
In progress	Pedido sendo processado	Cancelar ✓ \| Refill ✓
Completed	Pedido finalizado com sucesso	Cancelar ✗ \| Refill ✓
Canceled	Pedido cancelado (reembolso integral)	Cancelar ✗ \| Refill ✗
Error	Erro no processamento (contate suporte)	Cancelar ✗ \| Refill ✓

Rate Limiting e Limites

Requisições: máximo 100 requisições por minuto
Pedidos simultâneos: máximo 10 pedidos por minuto (ação add)
Saldo mínimo: R$ 1,00 para criar pedidos
Resposta de rate limit: HTTP 429 com header X-RateLimit-Remaining
Retry sugerido: aguarde 60 segundos antes de tentar novamente

Erros comuns e soluções

Erro	Causa	Solução
`Missing "key"`	Chave de autenticação não enviada	Adicione o parâmetro `key` ou header `X-API-Key`
`Invalid "key"`	Chave incorreta ou expirada	Verifique a chave na sua conta ou gere uma nova
`Account disabled`	API desabilitada na sua conta	Entre em contato com o suporte para ativar
`IP not allowed`	Seu IP está na lista de bloqueio	Adicione seu IP à whitelist nas configurações
`Insufficient balance`	Saldo insuficiente para o pedido	Aumente seu saldo na plataforma
`Quantity out of range`	Quantidade fora dos limites do serviço	Verifique min/max usando `action=services`
`Incorrect order ID`	Pedido não existe ou não pertence a você	Verifique o ID do pedido e tente novamente
HTTP 429	Limite de requisições excedido	Aguarde 60 segundos antes de fazer novas requisições
HTTP 503	Servidor em manutenção	Implemente retry exponencial e tente novamente

Dica: se sua ferramenta reclama de redirecionamento, use sempre a Base URL com barra no final (ex.: .../api/v2/).

Exemplos rápidos (PHP)

<?php
$base = '{{BASE_URL}}';
$key  = 'SUA_CHAVE';

// 1. Consultar saldo
$data = http_build_query(['action' => 'balance', 'key' => $key]);
$ctx = stream_context_create(['http' => [
  'method' => 'POST',
  'header' => "Content-Type: application/x-www-form-urlencoded\r\n",
  'content' => $data
]]);
$resp = json_decode(file_get_contents($base, false, $ctx), true);
echo "Saldo: {$resp['balance']} {$resp['currency']}\n";

// 2. Listar serviços
$data = http_build_query(['action' => 'services', 'key' => $key]);
$resp = json_decode(file_get_contents($base, false, stream_context_create(['http' => [
  'method' => 'POST',
  'header' => "Content-Type: application/x-www-form-urlencoded\r\n",
  'content' => $data
]])), true);
foreach($resp as $srv) {
  echo "{$srv['name']}: R\$ {$srv['rate']} por 1000\n";
}

// 3. Criar pedido
$data = http_build_query([
  'action' => 'add',
  'key' => $key,
  'service' => 101,
  'link' => 'https://instagram.com/p/XXXX',
  'quantity' => 1000
]);
$resp = json_decode(file_get_contents($base, false, stream_context_create(['http' => [
  'method' => 'POST',
  'header' => "Content-Type: application/x-www-form-urlencoded\r\n",
  'content' => $data
]])), true);
echo "Pedido criado: #{$resp['order']}\n";

// 4. Consultar status
$data = http_build_query(['action' => 'status', 'key' => $key, 'order' => $resp['order']]);
$resp = json_decode(file_get_contents($base, false, stream_context_create(['http' => [
  'method' => 'POST',
  'header' => "Content-Type: application/x-www-form-urlencoded\r\n",
  'content' => $data
]])), true);
echo "Status: {$resp['status']} ({$resp['remains']} restante)\n";
?>

JavaScript / Node.js (com fetch)

// Balance
fetch('{{BASE_URL}}', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({ action: 'balance', key: 'SUA_CHAVE' })
})
.then(r => r.json())
.then(d => console.log('Saldo:', d.balance, d.currency));

// Add order
fetch('{{BASE_URL}}', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    action: 'add',
    key: 'SUA_CHAVE',
    service: 101,
    link: 'https://instagram.com/p/XXXX',
    quantity: 1000
  })
})
.then(r => r.json())
.then(d => console.log('Pedido:', d.order));

// Status
fetch('{{BASE_URL}}', {
  method: 'POST',
  headers: { 'X-API-Key': 'SUA_CHAVE', 'Content-Type': 'application/json' },
  body: JSON.stringify({ action: 'status', order: 789 })
})
.then(r => r.json())
.then(d => console.log('Status:', d.status, '| Restante:', d.remains));

Boas Práticas de Integração

✅ Faça

Implemente retry com backoff exponencial
Armazene order IDs no seu banco de dados
Respeite o rate limit (100 req/min)
Use HTTPS sempre
Valide a chave antes de usar em produção
Monitore o saldo regularmente
Use timeouts apropriados (30s)

❌ Evite

Compartilhar sua chave de API publicamente
Fazer requisições síncronas em loops grandes
Usar HTTP em vez de HTTPS
Criar múltiplos pedidos para o mesmo link
Guardar responses em cache por muito tempo
Fazer requisições sem tratamento de erro
Enviar dados sensíveis em plaintext