TopViral · Tabela de preços · Entrar · Criar conta grátis

Documentação da API de revenda (API v2)

Documentação da API de revenda TopViral no padrão API v2: endpoint, autenticação, ações services, add, status, refill, cancel e balance, com exemplos.

Publicado em 05/10/2026 · 6 min de leitura · Equipe TopViral

Criar conta grátis

A API TopViral segue o padrão API v2 usado pelos painéis SMM. Com ela você lista os serviços, cria pedidos, consulta status, pede reposição, cancela e confere o saldo, usando os mesmos serviços, preços e saldo do painel.

Conexão

ItemValor
URLhttps://painel.topviral.social/api/v2
MétodoPOST
Formato do envioapplication/x-www-form-urlencoded ou application/json
RespostaJSON
Autenticaçãoparâmetro key com a sua chave de API
Limite60 requisições por minuto
MoedaBRL (reais)

Como obter a chave: crie a conta, confirme o e-mail e abra Painel → API para gerar a chave. Gerar uma nova chave invalida a anterior. Trate a chave como uma senha.

Se o seu painel aceita provedores no padrão API v2, cadastre o TopViral como provedor com a URL acima e a sua chave: serviços, pedidos e status passam a sincronizar sozinhos.

Listar serviços (services)

ParâmetroValor
keysua chave
actionservices

Resposta:

[
  {
    "service": 101,
    "name": "Instagram Seguidores Brasileiros",
    "type": "Default",
    "category": "Instagram Seguidores",
    "rate": "15.90",
    "min": "100",
    "max": "50000",
    "refill": true,
    "cancel": false,
    "dripfeed": false
  }
]
  • rate é o preço por 1.000 unidades (em serviços do tipo Package, é o preço do pacote). São os preços da sua conta: se ela tiver desconto, o rate já vem com ele.
  • refill, cancel e dripfeed indicam se o serviço aceita reposição, cancelamento e entrega em etapas.

Criar pedido (add)

ParâmetroObrigatórioDescrição
keysimsua chave
actionsimadd
servicesimID do serviço
linksimlink público do perfil, post ou vídeo
quantityconforme o tipoquantidade (não usada em Package e Custom Comments)
commentsCustom Commentsum comentário por linha; a quantidade é o número de linhas
runsdrip-feednúmero de etapas
intervaldrip-feedintervalo entre etapas, em minutos
usernameComment Likesusuário dono do comentário
answer_numberPollnúmero da opção da enquete

Resposta de sucesso:

{ "order": 23513 }

O valor é debitado do saldo na criação. Se o fornecedor recusar o pedido na hora, a resposta é { "error": "Order rejected, amount refunded" } e o valor volta ao saldo.

Status do pedido (status)

Um pedido:

ParâmetroValor
keysua chave
actionstatus
orderID do pedido
{
  "charge": "4.50",
  "start_count": "12840",
  "status": "In progress",
  "remains": "1850",
  "currency": "BRL"
}

Vários pedidos (até 100 por chamada): envie orders com os IDs separados por vírgula.

{
  "23513": { "charge": "4.50", "start_count": "12840", "status": "Completed", "remains": "0", "currency": "BRL" },
  "23514": { "error": "Incorrect order ID" }
}

Valores de status:

StatusSignificado
Pendingrecebido, aguardando início
In progressem entrega
Processingem processamento no fornecedor
Completedconcluído
Partialentregue em parte; a diferença voltou ao saldo (charge já é o valor final)
Canceledcancelado; o valor voltou ao saldo

Reposição (refill e refill_status)

Para pedidos concluídos de serviços com refill: true:

ParâmetroValor
keysua chave
actionrefill
orderID do pedido
{ "refill": 23513 }

Para acompanhar, use action=refill_status com refill igual ao valor retornado:

{ "status": "Completed" }

Cancelar (cancel)

Para serviços com cancel: true, envie orders com até 100 IDs separados por vírgula:

[
  { "order": 23513, "cancel": 1 },
  { "order": 23514, "cancel": { "error": "Este serviço não permite cancelamento" } }
]

O estorno acontece quando o fornecedor confirma o cancelamento; acompanhe pelo status.

Entregas programadas (schedule): extensão TopViral

Divide um pedido em 2 a 30 entregas, em horários escolhidos (por exemplo, 100 seguidores agora, 100 às 15h e mais 100 amanhã às 9h). É uma extensão do padrão API v2: painéis que só falam o padrão continuam funcionando com as ações acima.

  • O valor de todas as entregas é debitado na hora.
  • Cada entrega vai ao fornecedor no horário marcado, sempre depois que a anterior terminar.
  • Regras: de 2 a 30 entregas, pelo menos 10 minutos entre elas, até 30 dias à frente; cada entrega respeita o min e o max do serviço. Vale para serviços do tipo Default.
ParâmetroObrigatórioDescrição
keysimsua chave
actionsimschedule
servicesimID do serviço
linksimlink público do perfil, post ou vídeo
timessim (form)horários separados por vírgula: ISO 8601 (sem fuso = horário de Brasília), timestamp Unix ou now
quantitysim (form)quantidade de cada entrega
quantitiesnãoquantidade de cada entrega, separadas por vírgula (mesma ordem de times)
partssim (JSON)alternativa em JSON: lista de { "quantity": 100, "at": "2026-10-07T09:00:00-03:00" }

Resposta:

{ "schedule": 12, "orders": [23514, 23515, 23516], "charge": "2.70", "currency": "BRL" }

Exemplo (form):

curl -X POST https://painel.topviral.social/api/v2 \
  -d key=SUA_CHAVE \
  -d action=schedule \
  -d service=101 \
  -d link=https://instagram.com/perfil \
  -d quantity=100 \
  --data-urlencode "times=now,2026-10-07 15:00,2026-10-08 09:00"

Acompanhar (schedule_status, com schedule): devolve cada entrega com order, part, scheduled_at e os mesmos campos de status. Entregas que ainda não começaram aparecem como Pending com scheduled_at.

{
  "schedule": 12,
  "parts": [
    { "order": 23514, "part": 1, "scheduled_at": "2026-10-06T12:00:00.000Z", "status": "Completed", "charge": "0.90", "remains": "0", "start_count": "1520", "currency": "BRL" },
    { "order": 23515, "part": 2, "scheduled_at": "2026-10-07T18:00:00.000Z", "status": "Pending", "charge": "0.90", "remains": "100", "start_count": "0", "currency": "BRL" }
  ]
}

Cancelar (schedule_cancel, com schedule e, opcionalmente, from_part): cancela as entregas que ainda não começaram e devolve o valor ao saldo na hora.

{ "schedule": 12, "canceled": 2, "balance": "248.30", "currency": "BRL" }

Uma entrega específica também pode ser cancelada pela ação cancel, com o ID do pedido.

Saldo (balance)

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

O saldo é o mesmo do painel e é recarregado via PIX.

Erros

Os erros voltam como JSON com o campo error:

MensagemCausa
Invalid API keychave errada, gerada de novo ou conta bloqueada
Incorrect requestaction ausente ou desconhecida
Incorrect order IDpedido inexistente ou de outra conta
Refill not foundreposição não encontrada
outras mensagensvalidação do pedido (link, quantidade, saldo insuficiente etc.)

Acima do limite de requisições, a API responde com HTTP 429. Aguarde alguns segundos e tente de novo.

Exemplos

cURL:

curl -X POST https://painel.topviral.social/api/v2 \
  -d key=SUA_CHAVE \
  -d action=add \
  -d service=101 \
  -d link=https://instagram.com/perfil \
  -d quantity=1000

PHP:

$ch = curl_init('https://painel.topviral.social/api/v2');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POSTFIELDS => http_build_query([
    'key' => 'SUA_CHAVE',
    'action' => 'status',
    'order' => 23513,
  ]),
]);
$status = json_decode(curl_exec($ch), true);

JavaScript (Node.js 18+):

const res = await fetch('https://painel.topviral.social/api/v2', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ key: process.env.TOPVIRAL_KEY, action: 'balance' }),
});
console.log(await res.json()); // { balance: '248.30', currency: 'BRL' }

Python:

import requests

r = requests.post('https://painel.topviral.social/api/v2', data={
    'key': 'SUA_CHAVE',
    'action': 'services',
})
print(r.json()[:3])

Boas práticas

  • Consulte o status em lote (orders) a cada poucos minutos, em vez de um pedido por vez.
  • Guarde o ID do pedido retornado em add junto com o pedido do seu cliente.
  • Antes de vender um serviço, confira min, max, refill e cancel em services.
  • Nunca exponha a sua chave no navegador ou em aplicativos públicos: chame a API pelo seu servidor.

Dúvidas sobre a integração? Fale com o suporte pelo WhatsApp. Veja também a página de revenda e o guia como revender seguidores.

Guias relacionados

Veja também