# 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.

URL: https://topviral.social/blog/api-smm  
Publicado em: 16/10/2026 · Atualizado em: 16/10/2026 · 7 min de leitura

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](/revenda/api). 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](/blog/o-que-e-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çã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:

```bash
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:

```json
{ "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 é:

```json
{
  "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

| 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

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](/blog/como-montar-painel-smm). Para entender como funciona a revenda, veja a página de [revenda](/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

- [Como escolher um painel SMM: 10 critérios que você consegue conferir antes de pagar](https://topviral.social/blog/como-escolher-painel-smm.md)
- [Como montar um painel SMM: o que você precisa e o passo a passo para começar](https://topviral.social/blog/como-montar-painel-smm.md)
- [Como revender seguidores pelo WhatsApp: passo a passo com painel SMM](https://topviral.social/blog/como-revender-seguidores-pelo-whatsapp.md)

## Veja também

- [Painel SMM para revenda](https://topviral.social/revenda.md)
- [Documentação da API](https://topviral.social/revenda/api.md)
- [Programa de afiliados](https://topviral.social/afiliados.md)
- [Tabela de preços completa](https://topviral.social/servicos.md)

---

Criar conta: https://painel.topviral.social/cadastro · Fazer pedido: https://painel.topviral.social/painel/novo · Índice para IAs: https://topviral.social/llms.txt

TopViral · Voga Servicos Digitais · CNPJ 46.645.884/0001-32
