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

URL: https://topviral.social/revenda/api  
Publicado em: 05/10/2026 · Atualizado em: 05/10/2026 · 4 min de leitura

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

| Item | Valor |
|---|---|
| URL | `https://painel.topviral.social/api/v2` |
| Método | `POST` |
| Formato do envio | `application/x-www-form-urlencoded` ou `application/json` |
| Resposta | JSON |
| Autenticação | parâmetro `key` com a sua chave de API |
| Limite | 60 requisições por minuto |
| Moeda | BRL (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âmetro | Valor |
|---|---|
| `key` | sua chave |
| `action` | `services` |

Resposta:

```json
[
  {
    "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).
- `refill`, `cancel` e `dripfeed` indicam se o serviço aceita reposição, cancelamento e entrega em etapas.

## Criar pedido (`add`)

| Parâmetro | Obrigatório | Descrição |
|---|---|---|
| `key` | sim | sua chave |
| `action` | sim | `add` |
| `service` | sim | ID do serviço |
| `link` | sim | link público do perfil, post ou vídeo |
| `quantity` | conforme o tipo | quantidade (não usada em `Package` e `Custom Comments`) |
| `comments` | `Custom Comments` | um comentário por linha; a quantidade é o número de linhas |
| `runs` | drip-feed | número de etapas |
| `interval` | drip-feed | intervalo entre etapas, em minutos |
| `username` | `Comment Likes` | usuário dono do comentário |
| `answer_number` | `Poll` | número da opção da enquete |

Resposta de sucesso:

```json
{ "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âmetro | Valor |
|---|---|
| `key` | sua chave |
| `action` | `status` |
| `order` | ID do pedido |

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

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

Valores de `status`:

| Status | Significado |
|---|---|
| `Pending` | recebido, aguardando início |
| `In progress` | em entrega |
| `Processing` | em processamento no fornecedor |
| `Completed` | concluído |
| `Partial` | entregue em parte; a diferença voltou ao saldo (`charge` já é o valor final) |
| `Canceled` | cancelado; o valor voltou ao saldo |

## Reposição (`refill` e `refill_status`)

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

| Parâmetro | Valor |
|---|---|
| `key` | sua chave |
| `action` | `refill` |
| `order` | ID do pedido |

```json
{ "refill": 23513 }
```

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

```json
{ "status": "Completed" }
```

## Cancelar (`cancel`)

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

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

## Saldo (`balance`)

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

| Mensagem | Causa |
|---|---|
| `Invalid API key` | chave errada, gerada de novo ou conta bloqueada |
| `Incorrect request` | `action` ausente ou desconhecida |
| `Incorrect order ID` | pedido inexistente ou de outra conta |
| `Refill not found` | reposição não encontrada |
| outras mensagens | validaçã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:

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

PHP:

```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+):

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

```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](/revenda) e o guia [como revender seguidores](/blog/como-revender-seguidores-painel-smm).

## Guias relacionados

- [Como revender seguidores e serviços de redes sociais: guia para começar](https://topviral.social/blog/como-revender-seguidores-painel-smm.md)
- [O que é painel SMM, como funciona e como escolher um bom](https://topviral.social/blog/o-que-e-painel-smm.md)

## Veja também

- [Revenda TopViral](https://topviral.social/revenda.md)
- [Tabela de preços](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