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 aceitaapplication/json. - Autenticação pelo parâmetro
key, sem cabeçalhos especiais. - Resposta em JSON. Quando algo dá errado, vem um campo
errorcom a mensagem.
As ações e o que cada uma faz
| Ação | O que faz | Parâmetros principais |
|---|---|---|
services | Lista os serviços com preço por 1.000 (rate), mínimo, máximo e se aceitam reposição e cancelamento | key |
add | Cria um pedido e debita o valor do saldo | service, link, quantity |
status | Consulta um pedido, ou até 100 de uma vez | order ou orders |
refill | Pede reposição de um pedido concluído em serviço com reposição | order |
refill_status | Consulta o andamento de uma reposição | refill |
cancel | Pede cancelamento em serviços que permitem (até 100 IDs) | orders |
balance | Mostra o saldo da conta | key |
schedule | Extensão TopViral: divide um pedido em 2 a 30 entregas com horário | service, link, times, quantity |
schedule_status | Extensão TopViral: consulta cada entrega programada | schedule |
schedule_cancel | Extensão TopViral: cancela as entregas que ainda não começaram e devolve o valor | schedule |
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,PartialouCanceled.
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
| Mensagem | Causa provável | O que fazer |
|---|---|---|
Invalid API key | Chave errada, gerada de novo ou conta bloqueada | Confira a chave no painel; se gerou outra, atualize no seu sistema |
Incorrect request | action ausente ou desconhecida | Confira o nome da ação |
Incorrect order ID | Pedido inexistente ou de outra conta | Confira se o ID salvo é o retornado em add |
Refill not found | Reposição não encontrada | Use o valor retornado pela ação refill |
| HTTP 429 | Mais de 60 requisições por minuto | Espere alguns segundos e reduza a frequência |
| Outras mensagens | Validação do pedido: link, quantidade, saldo insuficiente | Valide 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
- Crie a conta no TopViral e confirme o e-mail.
- Gere a chave em Painel → API (não é preciso CNPJ).
- Coloque saldo via PIX.
- Teste com
balancee depois com umaddno mínimo de um serviço, em um perfil seu e público. - 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.