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

API SMM: o que é, como funciona o padrão API v2 e como integrar sem dor de cabeça

API SMM explicada: o que é o padrão API v2, o que faz cada ação (add, status, refill, cancel, balance), exemplos reais, erros comuns e boas práticas.

Publicado em 16/10/2026 · 7 min de leitura · Equipe TopViral

Criar conta grátis

A resposta curta: API SMM é a forma de um sistema fazer pedidos em um painel SMM sem ninguém clicar em nada. O padrão mais usado é o API v2: você envia um POST para uma única URL com a sua chave (key) e uma ação (action), como add para criar pedido ou status para consultar, e recebe a resposta em JSON.

É com a API que um painel se conecta a outro como provedor e que revendedores automatizam pedidos, status, reposição e saldo. No TopViral, a API usa os mesmos serviços, preços e saldo do painel, e a documentação técnica completa está em API de revenda. Este artigo explica o funcionamento e os cuidados de quem integra.

O que é o padrão API v2

O API v2 não é uma norma oficial: é uma convenção que a maioria dos painéis SMM adotou. Se você ainda está entendendo o que é um painel, veja o que é painel SMM. Como todos falam a mesma "língua", uma plataforma de painel consegue cadastrar qualquer provedor compatível pedindo só duas coisas: a URL e a chave.

As características do padrão:

  • Uma URL só para todas as ações. No TopViral: https://painel.topviral.social/api/v2.
  • Método POST, com os parâmetros em formulário (application/x-www-form-urlencoded). O TopViral também aceita application/json.
  • Autenticação pelo parâmetro key, sem cabeçalhos especiais.
  • Resposta em JSON. Quando algo dá errado, vem um campo error com a mensagem.

As ações e o que cada uma faz

AçãoO que fazParâmetros principais
servicesLista os serviços com preço por 1.000 (rate), mínimo, máximo e se aceitam reposição e cancelamentokey
addCria um pedido e debita o valor do saldoservice, link, quantity
statusConsulta um pedido, ou até 100 de uma vezorder ou orders
refillPede reposição de um pedido concluído em serviço com reposiçãoorder
refill_statusConsulta o andamento de uma reposiçãorefill
cancelPede cancelamento em serviços que permitem (até 100 IDs)orders
balanceMostra o saldo da contakey
scheduleExtensão TopViral: divide um pedido em 2 a 30 entregas com horárioservice, link, times, quantity
schedule_statusExtensão TopViral: consulta cada entrega programadaschedule
schedule_cancelExtensão TopViral: cancela as entregas que ainda não começaram e devolve o valorschedule

As três ações schedule são extras do TopViral. Painéis que só falam o padrão continuam funcionando normalmente com as outras.

Em add, alguns tipos de serviço usam parâmetros a mais: comments (comentários personalizados, um por linha), runs e interval (entrega em etapas), username (curtidas em comentário) e answer_number (enquete).

Exemplo real: criar um pedido

Requisição add com cURL, como na documentação:

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

Resposta de sucesso:

{ "order": 23513 }

O número em order é o ID do pedido. Guarde junto com o pedido do seu cliente: é com ele que você consulta status, pede reposição ou cancela. O valor é debitado na criação. Se o fornecedor recusar o pedido na hora, a resposta é { "error": "Order rejected, amount refunded" } e o valor volta ao saldo.

Exemplo real: consultar o status

Enviando action=status com order, a resposta é:

{
  "charge": "4.50",
  "start_count": "12840",
  "status": "In progress",
  "remains": "1850",
  "currency": "BRL"
}
  • charge: valor cobrado pelo pedido.
  • start_count: contagem no início da entrega.
  • remains: quanto falta entregar.
  • status: Pending, In progress, Processing, Completed, Partial ou Canceled.

Em Partial, a diferença já voltou ao saldo e o charge é o valor final. Em Canceled, o valor inteiro voltou ao saldo.

Erros comuns e o que significam

MensagemCausa provávelO que fazer
Invalid API keyChave errada, gerada de novo ou conta bloqueadaConfira a chave no painel; se gerou outra, atualize no seu sistema
Incorrect requestaction ausente ou desconhecidaConfira o nome da ação
Incorrect order IDPedido inexistente ou de outra contaConfira se o ID salvo é o retornado em add
Refill not foundReposição não encontradaUse o valor retornado pela ação refill
HTTP 429Mais de 60 requisições por minutoEspere alguns segundos e reduza a frequência
Outras mensagensValidação do pedido: link, quantidade, saldo insuficienteValide antes de enviar

Um erro que não aparece como mensagem, mas é frequente: pedido cancelado pelo fornecedor porque o perfil está privado ou o post tem restrição de idade. O fornecedor abre o link sem estar logado, então o perfil ou post precisa estar público durante toda a entrega. Avise isso ao seu cliente antes do pedido.

Boas práticas de integração

Trate a chave como senha

A chave dá acesso ao seu saldo. Guarde em variável de ambiente ou cofre de segredos, nunca no código do navegador nem em aplicativo público: chame a API sempre pelo seu servidor. Se suspeitar de vazamento, gere uma nova (a anterior deixa de funcionar na hora).

Consulte status em lote, não em loop

Em vez de perguntar o status de cada pedido a cada segundo, junte os pedidos abertos e consulte em lote, com orders (até 100 IDs por chamada), a cada alguns minutos. Isso evita o limite de 60 requisições por minuto e deixa o seu sistema mais leve.

Respeite o limite e trate o 429

Se receber HTTP 429, espere alguns segundos antes de tentar de novo, aumentando a espera a cada falha. Não reenvie add às cegas depois de um erro de rede: confira em Meus pedidos se ele foi criado, para não duplicar.

Trate Partial e Canceled com o campo remains

Quando o status for Partial, use remains para saber quanto não foi entregue e devolva essa parte ao seu cliente na mesma proporção. Em Canceled, devolva o valor inteiro. Se o seu painel é uma plataforma pronta, confirme que ela faz isso sozinha.

Confira os serviços antes de vender

Chame services e verifique min, max, refill e cancel de cada serviço que você vai oferecer. Não ofereça reposição em um serviço com refill: false.

Reconcilie o saldo

Uma vez por dia, compare o balance com a soma dos depósitos menos o valor efetivamente cobrado dos pedidos (já descontando o que voltou de parciais e cancelados). Diferença inesperada costuma indicar pedido duplicado ou estorno que o seu sistema não registrou.

Como começar a usar

  1. Crie a conta no TopViral e confirme o e-mail.
  2. Gere a chave em Painel → API (não é preciso CNPJ).
  3. Coloque saldo via PIX.
  4. Teste com balance e depois com um add no mínimo de um serviço, em um perfil seu e público.
  5. Se você tem um painel, cadastre o TopViral como provedor com a URL e a chave.

Para o passo a passo do lado do painel, veja como montar um painel SMM. Para entender como funciona a revenda, veja a página de revenda.

Perguntas frequentes

Qualquer painel SMM funciona com a API do TopViral?

Painéis que aceitam provedores no padrão API v2 funcionam. Basta cadastrar a URL e a chave.

Os preços pela API são diferentes dos do painel?

Não. Pela API você usa os mesmos serviços, os mesmos preços e o mesmo saldo do painel.

Quantos pedidos posso consultar de uma vez?

Até 100 por chamada de status, enviando os IDs separados por vírgula em orders.

A API faz entrega programada?

Sim, pela extensão schedule do TopViral: de 2 a 30 entregas, com pelo menos 10 minutos entre elas e até 30 dias à frente. Vale para serviços do tipo Default.

Como peço reposição pela API?

Com action=refill e o ID do pedido, em pedidos concluídos de serviços com reposição. Acompanhe com refill_status.

Guias relacionados

Veja também