Documentación de la API

Descripción general

Toplistbot expone dos API HTTP. Ambas usan JSON sobre HTTPS y consumen el mismo saldo de tokens: elige la que encaje con tu forma de integrar.

API de panel SMM

Un único endpoint compatible con Perfect Panel. Si tu panel ya habla el protocolo SMM estándar, apúntalo aquí y funciona sin cambiar código.

API de la plataforma

La API REST que hay detrás del panel: recorre el catálogo de sitios, inicia sesión y crea y gestiona campañas desde tu propia aplicación.

URL base

Base URL

https://backend.toplistbot.com/api

Primeros pasos

De una cuenta nueva a una campaña en marcha en cinco pasos. Todo lo de abajo usa el endpoint SMM, la vía más rápida; la API de la plataforma funciona igual una vez que tengas un JWT.

Crea una cuenta
Regístrate y verifica tu correo. La verificación abona 100 tokens gratis en tu saldo, suficiente para lanzar una campaña real antes de gastar nada.
Copia tu clave de API
Abre tu panel y genera una clave de API. Trátala como una contraseña: gasta tu saldo de tokens. Puedes regenerarla cuando quieras, lo que invalida la anterior al instante.
3
Encuentra el servicio que quieres
Lista todos los sitios en los que puedes hacer pedidos. Cada entrada tiene un id numérico de servicio y una tarifa en tokens por cada 1.000 acciones. Anota el id del sitio en el que quieres promocionar.
cURL
```
curl -X POST https://backend.toplistbot.com/api/v2 -d "key=YOUR_API_KEY" -d "action=services"
```

Haz tu primer pedido

Envía el id del servicio, la URL sobre la que se ejecuta la campaña y cuántas acciones lanzar. El coste se descuenta al momento y la respuesta te da un 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
Sigue la entrega
Consulta el id del pedido para ver cuánto se ha entregado. Cuando el flujo te convenza, conecta las mismas llamadas a tu propio panel o a tus scripts.
cURL
```
curl -X POST https://backend.toplistbot.com/api/v2 -d "key=YOUR_API_KEY" -d "action=status" -d "orders=184223"
```

Conectar una instancia de Perfect Panel

Si usas Perfect Panel o software de panel SMM compatible, no necesitas escribir código: añade Toplistbot como proveedor con estos ajustes e importa la lista de servicios.

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

Empieza con una cantidad pequeña en un solo sitio para confirmar que se acepta el formato de tu enlace antes de aumentar el volumen. Un enlace incorrecto también consume tokens.

Autenticación

Las dos API se autentican de forma distinta. El endpoint SMM usa una clave de API de larga duración; la API de la plataforma usa un JWT que obtienes al iniciar sesión.

Clave de API (endpoint SMM)

Envía tu clave como campo `key` en cada petición: como campo de formulario, parámetro de consulta o cabecera `Authorization: Bearer`. Puedes generarla y regenerarla desde tu panel. Un GET al mismo endpoint devuelve el estado ok y es una forma barata de comprobar que una clave es válida.

Health check

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

JWT (API de la plataforma)

Inicia sesión para recibir un token y envíalo como bearer token en las rutas autenticadas. Los tokens caducan: llama a /auth/refresh para obtener uno nuevo.

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"

Tu clave de API gasta saldo real de tokens. Mantenla en el servidor: cualquier cosa que llegue al navegador o se suba a un repositorio debe considerarse comprometida y regenerarse desde el panel.

Tokens y precios

Las campañas se pagan en tokens, comprados por adelantado. Cada sitio publica una tarifa —cuántos tokens cuesta lanzar 1.000 acciones de campaña allí— que la acción services devuelve como `rate`.

Cost formula

cost_in_tokens = (rate * quantity) / 1000

Un sitio con tarifa 13 cuesta 13 tokens por 1.000 acciones, así que un pedido de 500 cuesta 6,5 tokens. El coste se descuenta al aceptar el pedido, y cancelar devuelve el resto no gastado.

Las respuestas de balance y status indican un campo de moneda USD por compatibilidad con Perfect Panel, pero el valor es un saldo de tokens, no dólares. Trata el número como tokens.

API de panel SMM

Un solo endpoint lo hace todo. Envía un campo `action` en cada POST para elegir la operación; toda petición lleva además tu `key`.

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

Acción	Parámetros
`services`	—
`add`	service, link, quantity, interval?
`status`	orders
`balance`	—
`cancel`	orders

`action=services`

Lista todos los sitios en los que puedes hacer pedidos, con su tarifa actual y sus límites. Usa el id `service` en tus llamadas 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` va en tokens por cada 1.000 acciones. `min` es 1 y `max` es 50000 en todos los servicios.

`action=add`

Crea una campaña y descuenta su coste de tu saldo de inmediato.

Parámetro	Tipo	Descripción
`key`obligatorio	string	Tu clave de API.
`action`obligatorio	string	Debe ser `add`.
`service`obligatorio	integer	Id de servicio de la acción services.
`link`obligatorio	url	La URL sobre la que se ejecuta la campaña. Debe ser una URL válida.
`quantity`obligatorio	integer	Número de acciones a lanzar, entre 1 y 50000.
`interval`	integer	Acciones por hora. Por defecto 15, con tope de 4000, y no puede superar el máximo propio del sitio.

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`

Devuelve el progreso de uno o varios pedidos. Pasa un solo id para obtener un objeto simple, o una lista separada por comas.

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"
}

Con varios ids la respuesta se indexa por id de pedido, y los pedidos desconocidos o ajenos devuelven una entrada de error en lugar de hacer fallar toda la petición.

Response — multiple orders

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

`action=balance`

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

Detiene un pedido y devuelve el resto no gastado a tu saldo. Los pedidos completados no se pueden cancelar.

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 de la plataforma

La misma API REST que usa el panel. Los endpoints de catálogo son públicos; todo lo demás necesita un JWT.

Catálogo

Público, sin autenticación. Útil para montar tu propio directorio o página de precios.

GET/orders/getAllWebsitesTodos los sitios listados, con tarifas y metadatos
POST/orders/getWebsiteDetailsByNameUn sitio por nombre exacto
GET/orders/getAllBasicWebsitesDetails20 nombres de sitios al azar
POST/products/getSuggestionsSitios relacionados para un conjunto de ids
GET/products/tokensPaquetes de tokens disponibles
POST/products/suggestPropón un sitio para que lo añadamos
GET/news/timelineRegistro de cambios del producto

cURL

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

Cuenta

Registro, sesiones e historial de facturación.

POST/auth/registerCrear una cuenta
POST/auth/loginCanjear credenciales por un JWT
POST/auth/refreshEmitir un JWT nuevo JWT
POST/auth/logoutInvalidar el JWT actual JWT
GET/auth/user-profilePerfil del usuario actual JWT
POST/auth/reset-api-keyRegenerar tu clave de API JWT
GET/invoices/getHistorial de facturación JWT

Campañas

Crea y gestiona campañas y consulta sus registros de entrega.

GET/orders/getAllTus campañas, las más recientes primero
POST/orders/checkoutCrear una o varias campañas
POST/orders/updateEditar una campaña
POST/orders/pausePausar una campaña activa
POST/orders/unpauseReanudar una campaña pausada
POST/orders/archiveArchivar una campaña
PATCH/orders/updateLimitCambiar el tope diario
GET/orders/logs/{id}Registro de entrega de una campaña
GET/orders/graph/{id}Serie temporal para gráficas

Errores

Los errores llegan con su código HTTP correspondiente. Los fallos de validación devuelven un objeto `errors` indexado por nombre de campo.

400Acción no válida, parámetros mal formados o un id de servicio que no existe.
401Credenciales ausentes o no válidas.
403Autenticado, pero tu saldo de tokens es insuficiente para el pedido.
422La petición se entendió pero no pasó la validación.

Validation error

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

Límites y notas

La cantidad del pedido debe estar entre 1 y 50000 acciones.
El intervalo es 15 por hora por defecto y tiene un tope de 4000. Pedir más que el máximo del propio sitio se rechaza con un 400 que indica el límite.
Las acciones `refill` y `refill_status` no están implementadas: crea un pedido nuevo en su lugar.
El campo `status` todavía no es una señal de progreso en vivo; usa `remains` y `start_count` para seguir la entrega.
Los sitios de listados fijan sus propias reglas y las cambian con el tiempo. Eres responsable de asegurarte de que tu uso cumple los términos de cualquier sitio en el que promociones. No prometemos ninguna posición ni clasificación concreta.

Escríbenos en Discord

Descripción general

API de panel SMM

API de la plataforma

URL base

Primeros pasos

Crea una cuenta

Copia tu clave de API

Encuentra el servicio que quieres

Haz tu primer pedido

Sigue la entrega

Conectar una instancia de Perfect Panel

Autenticación

Clave de API (endpoint SMM)

JWT (API de la plataforma)

Tokens y precios

API de panel SMM

action=services

action=add

action=status

action=balance

action=cancel

API de la plataforma

Catálogo

Cuenta

Campañas

Errores

Límites y notas

Empieza a promocionar ¡ahora!

`action=services`

`action=add`

`action=status`

`action=balance`

`action=cancel`