Documentação da API

Visão geral

O Toplistbot expõe duas APIs HTTP. Ambas usam JSON sobre HTTPS e consomem o mesmo saldo de tokens — escolha a que combina com sua forma de integrar.

API de painel SMM

Um único endpoint compatível com Perfect Panel. Se o seu painel já fala o protocolo SMM padrão, aponte-o para cá e funciona sem alterar código.

API da plataforma

A API REST por trás do painel: navegue pelo catálogo de sites, faça login e crie e gerencie campanhas a partir do seu próprio aplicativo.

URL base

Base URL

https://backend.toplistbot.com/api

Primeiros passos

De uma conta nova a uma campanha rodando em cinco passos. Tudo abaixo usa o endpoint SMM, o caminho mais rápido; a API da plataforma funciona igual assim que você tiver um JWT.

Crie uma conta
Cadastre-se e verifique seu e-mail. A verificação credita 100 tokens grátis no seu saldo, o suficiente para rodar uma campanha real antes de gastar qualquer valor.
Copie sua chave de API
Abra o painel e gere uma chave de API. Trate-a como uma senha — ela gasta seu saldo de tokens. Você pode regenerá-la quando quiser, o que invalida a anterior na hora.
3
Encontre o serviço desejado
Liste todos os sites em que você pode fazer pedidos. Cada item tem um id numérico de serviço e uma taxa em tokens por 1.000 ações. Anote o id do site em que quer divulgar.
cURL
```
curl -X POST https://backend.toplistbot.com/api/v2 -d "key=YOUR_API_KEY" -d "action=services"
```

Faça seu primeiro pedido

Envie o id do serviço, a URL em que a campanha deve rodar e quantas ações executar. O custo é debitado na hora e a resposta traz um id de pedido.

cURL

curl -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=add" \
  -d "service=9" \
  -d "link=https://arena-top100.com/index.php?a=in&u=yourserver" \
  -d "quantity=1000"

5
Acompanhe a entrega
Consulte o id do pedido para ver quanto já foi entregue. Quando estiver satisfeito com o fluxo, conecte as mesmas chamadas ao seu painel ou aos seus scripts.
cURL
```
curl -X POST https://backend.toplistbot.com/api/v2 -d "key=YOUR_API_KEY" -d "action=status" -d "orders=184223"
```

Conectando uma instância Perfect Panel

Se você usa Perfect Panel ou software de painel SMM compatível, não precisa escrever código — adicione o Toplistbot como provedor com estas configurações e importe a lista de serviços.

URL da API: https://backend.toplistbot.com/api/v2
Chave de API: YOUR_API_KEY
Método HTTP: POST

Comece com uma quantidade pequena em um único site para confirmar que o formato do seu link é aceito antes de aumentar o volume. Um link errado também consome tokens.

Autenticação

As duas APIs autenticam de formas diferentes. O endpoint SMM usa uma chave de API de longa duração; a API da plataforma usa um JWT obtido ao fazer login.

Chave de API (endpoint SMM)

Envie sua chave como um campo `key` em toda requisição — como campo de formulário, parâmetro de consulta ou cabeçalho `Authorization: Bearer`. Gere e regenere pelo painel. Um GET no mesmo endpoint retorna o status ok e é uma forma barata de checar se a chave é válida.

Health check

curl https://backend.toplistbot.com/api/v2?key=YOUR_API_KEY

JWT (API da plataforma)

Faça login para receber um token e envie-o como bearer token nas rotas autenticadas. Os tokens expiram — chame /auth/refresh para obter um novo.

curl -X POST https://backend.toplistbot.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"..."}'

Authenticated request

curl https://backend.toplistbot.com/api/orders/getAll \
  -H "Authorization: Bearer YOUR_JWT"

Sua chave de API gasta saldo real de tokens. Mantenha-a no servidor: qualquer coisa enviada ao navegador ou commitada em um repositório deve ser considerada comprometida e regenerada pelo painel.

Tokens e preços

As campanhas são pagas em tokens, comprados antecipadamente. Cada site publica uma taxa — quantos tokens custam 1.000 ações de campanha ali — retornada como `rate` pela ação services.

Cost formula

cost_in_tokens = (rate * quantity) / 1000

Um site com taxa 13 custa 13 tokens por 1.000 ações, então um pedido de 500 custa 6,5 tokens. O custo é debitado quando o pedido é aceito, e o cancelamento devolve o restante não gasto.

As respostas de balance e status informam um campo de moeda USD por compatibilidade com o Perfect Panel, mas o valor é um saldo de tokens, não dólares. Trate o número como tokens.

API de painel SMM

Um endpoint faz tudo. Envie um campo `action` em cada POST para escolher a operação; toda requisição também leva sua `key`.

POSThttps://backend.toplistbot.com/api/v2

Ação	Parâmetros
`services`	—
`add`	service, link, quantity, interval?
`status`	orders
`balance`	—
`cancel`	orders

`action=services`

Lista todos os sites em que você pode fazer pedidos, com a taxa atual e os limites. Use o id `service` nas suas chamadas add.

cURL

curl -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=services"

Response

[
  {
    "service": 9,
    "name": "arena-top100.com 1000 upvotes",
    "type": "Default",
    "category": "Votes",
    "rate": 15,
    "min": 1,
    "max": 50000,
    "refill": false,
    "cancel": true
  }
]

`rate` é em tokens por 1.000 ações. `min` é 1 e `max` é 50000 para todos os serviços.

`action=add`

Cria uma campanha e debita o custo do seu saldo imediatamente.

Parâmetro	Tipo	Descrição
`key`obrigatório	string	Sua chave de API.
`action`obrigatório	string	Deve ser `add`.
`service`obrigatório	integer	Id do serviço vindo da ação services.
`link`obrigatório	url	A URL em que a campanha vai rodar. Precisa ser uma URL válida.
`quantity`obrigatório	integer	Número de ações a executar, entre 1 e 50000.
`interval`	integer	Ações por hora. Padrão 15, limite de 4000, e não pode ultrapassar o máximo do próprio site.

cURL

curl -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=add" \
  -d "service=9" \
  -d "link=https://arena-top100.com/index.php?a=in&u=yourserver" \
  -d "quantity=1000" \
  -d "interval=60"

Response

{
  "order_id": 184223
}

`action=status`

Retorna o progresso de um ou mais pedidos. Passe um único id para um objeto simples, ou uma lista separada por vírgulas.

cURL

curl -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=status" \
  -d "orders=184223"

Response — single order

{
  "charge": 13.5,
  "start_count": 0,
  "status": "Completed",
  "remains": 1000,
  "currency": "USD"
}

Com vários ids, a resposta é indexada pelo id do pedido, e pedidos desconhecidos ou de outra conta retornam uma entrada de erro em vez de derrubar a requisição inteira.

Response — multiple orders

{
  "184223": { "charge": 13.5, "start_count": 0, "status": "Completed", "remains": 1000, "currency": "USD" },
  "184224": { "error": "Incorrect order ID" }
}

`action=balance`

Retorna seu saldo restante de tokens.

cURL

curl -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=balance"

Response

{
  "balance": 528.41,
  "currency": "USD"
}

`action=cancel`

Interrompe um pedido e devolve o restante não gasto ao seu saldo. Pedidos concluídos não podem ser cancelados.

cURL

curl -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=cancel" \
  -d "orders=184223,184224"

Response

[
  { "order": "184223", "cancel": 1, "refund": 4.5 },
  { "order": "184224", "cancel": { "error": "Incorrect order ID" } }
]

API da plataforma

A mesma API REST que o painel usa. Os endpoints de catálogo são públicos; todo o resto exige um JWT.

Catálogo

Público, sem autenticação. Útil para montar seu próprio diretório ou página de preços.

GET/orders/getAllWebsitesTodos os sites listados, com taxas e metadados
POST/orders/getWebsiteDetailsByNameUm site pelo nome exato
GET/orders/getAllBasicWebsitesDetails20 nomes de sites aleatórios
POST/products/getSuggestionsSites relacionados a um conjunto de ids
GET/products/tokensPacotes de tokens disponíveis
POST/products/suggestSugira um site para adicionarmos
GET/news/timelineChangelog do produto

cURL

curl https://backend.toplistbot.com/api/orders/getAllWebsites

Conta

Cadastro, sessões e histórico de cobrança.

POST/auth/registerCriar uma conta
POST/auth/loginTrocar credenciais por um JWT
POST/auth/refreshEmitir um novo JWT JWT
POST/auth/logoutInvalidar o JWT atual JWT
GET/auth/user-profilePerfil do usuário atual JWT
POST/auth/reset-api-keyRegenerar sua chave de API JWT
GET/invoices/getHistórico de cobrança JWT

Campanhas

Crie e gerencie campanhas e leia seus logs de entrega.

GET/orders/getAllSuas campanhas, mais recentes primeiro
POST/orders/checkoutCriar uma ou mais campanhas
POST/orders/updateEditar uma campanha
POST/orders/pausePausar uma campanha em execução
POST/orders/unpauseRetomar uma campanha pausada
POST/orders/archiveArquivar uma campanha
PATCH/orders/updateLimitAlterar o limite diário
GET/orders/logs/{id}Log de entrega de uma campanha
GET/orders/graph/{id}Série temporal para gráficos

Erros

Os erros vêm com o status HTTP correspondente. Falhas de validação retornam um objeto `errors` indexado pelo nome do campo.

400Ação inválida, parâmetros malformados ou um id de serviço inexistente.
401Credenciais ausentes ou inválidas.
403Autenticado, mas seu saldo de tokens é insuficiente para o pedido.
422A requisição foi entendida, mas não passou na validação.

Validation error

{
  "errors": {
    "quantity": ["The quantity must be at least 1."]
  }
}

Limites e observações

A quantidade do pedido deve ficar entre 1 e 50000 ações.
O intervalo é 15 por hora por padrão e tem teto de 4000. Pedir mais que o máximo do próprio site é rejeitado com um 400 informando o limite.
As ações `refill` e `refill_status` não estão implementadas — crie um novo pedido em vez disso.
O campo `status` ainda não é um sinal de progresso em tempo real; use `remains` e `start_count` para acompanhar a entrega.
Os sites de listagem definem suas próprias regras e as mudam com o tempo. Você é responsável por garantir que seu uso esteja de acordo com os termos de qualquer site em que divulgar. Não prometemos nenhuma colocação ou posição específica.

Fale conosco no Discord

Visão geral

API de painel SMM

API da plataforma

URL base

Primeiros passos

Crie uma conta

Copie sua chave de API

Encontre o serviço desejado

Faça seu primeiro pedido

Acompanhe a entrega

Conectando uma instância Perfect Panel

Autenticação

Chave de API (endpoint SMM)

JWT (API da plataforma)

Tokens e preços

API de painel SMM

action=services

action=add

action=status

action=balance

action=cancel

API da plataforma

Catálogo

Conta

Campanhas

Erros

Limites e observações

Comece a divulgar agora!

`action=services`

`action=add`

`action=status`

`action=balance`

`action=cancel`