Documentación de la API

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 -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=services"

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

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"

{
  "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 -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=status" \
  -d "orders=184223"

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

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

`status` y `cancel` aceptan como máximo 100 ids de pedido por llamada. Agrupa en lugar de iterar: una llamada con 100 ids es mucho más barata para ambas partes que 100 llamadas.

action=balance

Devuelve tu saldo restante de tokens.

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

{
  "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 -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=cancel" \
  -d "orders=184223,184224"

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

Catálogo y descubrimiento#

Público, sin credencial. getAllWebsites es el endpoint por el que empezar: trae el id, el precio, el techo por hora y la tasa de aceptación que necesitas para calcular el precio y dar forma a un pedido.

• GET/orders/getAllWebsitesPúblicaEl catálogo completo: cada sitio con tarifas, límites y metadatos
• GET/orders/getAllBasicWebsitesDetailsPública20 nombres de sitio al azar, para widgets y autocompletados
• POST/orders/getWebsiteDetailsByNamePúblicaUn sitio por su nombre exacto
• POST/products/getSuggestionsPúblicaSitios relacionados con un conjunto de ids
• GET/products/demand?days=30PúblicaCuánto se ha pedido cada sitio últimamente
• GET/products/tokensPúblicaPaquetes de tokens que puedes comprar
• POST/products/suggestClave APIPídenos que añadamos un sitio nuevo
• GET/api/news/timelinePúblicaNovedades del producto

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

Pide menos

El catálogo completo pesa unos 665 KB repartidos en 396 sitios, y dos campos con los que nunca vas a pedir son la mitad de ese peso: un bloque JSON de popularidad y la descripción de marketing. Proyecta solo los campos que usas para pedir y descarta los sitios inactivos y se queda en unos 40 KB.

# The whole catalog is ~665 KB across 396 sites.
# Projected to what you actually order with: ~40 KB.
curl -s "https://backend.toplistbot.com/orders/getAllWebsites" \
  | jq '[.[]
      | select(.active == 1)
      | {id, name, price_per_1000, max_per_hour, accept_rate, subscribeable}]'

Cuenta y sesiones#

El registro necesita un navegador: está protegido por un desafío de Cloudflare. Regístrate una vez en app.toplistbot.com y automatiza todo lo demás.

• POST/api/auth/registerPúblicaCrear una cuenta: solo por navegador, protegido por captcha
• POST/api/auth/loginPúblicaCambiar credenciales por un JWT
• POST/api/auth/refreshJWTEmitir un JWT nuevo a partir de uno que caduca
• POST/api/auth/logoutJWTInvalidar el JWT actual
• GET/api/auth/user-profileJWTLa cuenta conectada, con saldo y clave API
• GET/api/userJWTEl mismo objeto de usuario, en una ruta más corta
• GET/api/api_tokenClave APIResolver una clave API a su dueño: úsalo para validar una clave
• POST/api/auth/reset-api-keyJWTRotar tu clave API; la anterior muere al instante
• POST/api/auth/fingerprintJWTRegistrar una huella de navegador en la cuenta
• POST/api/auth/ipJWTRegistrar la IP actual de la cuenta
• POST/api/auth/forgot-passwordPúblicaEnviar por correo un enlace de restablecimiento, válido 60 minutos
• POST/api/auth/reset-passwordPúblicaFijar una contraseña nueva con el token enviado por correo

Doble factor e inicio de sesión#

El doble factor protege el inicio de sesión con contraseña. No se aplica a las claves API, y por eso una clave es la mejor credencial para trabajo desatendido.

• POST/api/2fa/enableJWTIniciar el alta: devuelve el secreto, la URL del QR y los códigos de recuperación
• POST/api/2fa/verifyJWTConfirmar un código de seis dígitos y activar el doble factor
• POST/api/2fa/disableJWTDesactivar el doble factor
• POST/api/account/verification/requestJWTEnviar un enlace de verificación a la dirección conectada
• GET/api/account/verification/confirm?token=PúblicaMostrar la página de confirmación: no escribe nada
• POST/api/account/verification/confirmPúblicaConfirmar la verificación
• GET/api/auth/googlePúblicaIniciar sesión con Google
• GET/api/auth/google/callbackPúblicaRetorno del inicio de sesión con Google
• GET/api/auth/discordPúblicaIniciar sesión con Discord
• GET/api/auth/discord/callbackPúblicaRetorno del inicio de sesión con Discord

Preferencias y avisos#

Interruptores de correo y notificaciones, y el historial de avisos de la cuenta.

• GET/api/user/email-preferencesJWTEstado de suscripción a correos de marketing
• POST/api/user/email-preferencesJWTCambiarlo
• GET/api/user/notification-preferencesJWTPreferencia de avisos de voto en vivo
• POST/api/user/notification-preferencesJWTCambiarlo: debe ser un booleano JSON real
• GET/api/user/alerts?limit=20JWTAvisos de la cuenta, del más reciente al más antiguo, paginados con ?before
• POST/api/user/alerts/readJWTMarcar un aviso como leído
• POST/api/user/alerts/dismissJWTDescartar un aviso
• GET/api/email/unsubscribe?token=PúblicaBaja en un clic desde un token enviado por correo

Campañas#

Crear campañas, dirigirlas mientras corren y cerrarlas. Es el núcleo de la API de plataforma.

• GET/orders/getAllClave APITus campañas, de la más reciente a la más antigua, con su sitio incluido
• GET/orders/get/{id}Clave APIUna campaña
• POST/orders/checkoutClave APICrear campañas y cobrar del saldo
• POST/orders/updateClave APIEditar una campaña
• POST/orders/pauseClave APIPausar una campaña en marcha
• POST/orders/unpauseClave APIReanudar una campaña pausada
• POST/orders/archiveClave APIArchivar una campaña
• POST/orders/unarchiveClave APIRestaurar una campaña archivada
• PATCH/orders/updateLimitClave APIFijar o quitar el tope diario de votos

POST /orders/checkout

El cuerpo es un array JSON de líneas de carrito en el nivel superior, no un objeto. Cada línea es una campaña. Todo el carrito se valida antes de cobrar nada, y el cobro y las inserciones son una sola transacción: un pedido ocurre entero o no ocurre.

Una línea de cantidad fija

El caso habitual: entregar un número concreto de votos a una URL.

curl -X POST "https://backend.toplistbot.com/orders/checkout?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "id": 9,
      "amount": 1000,
      "ownName": "https://arena-top100.com/index.php?a=in&u=yourserver",
      "custom_max_per_hour": 60
    }
  ]'

200 OK
Successfully purchased with token balance

Una línea de suscripción

Para sitios cuyo indicador `subscribeable` vale 1. Se cobra a partir de subscription_price_1d del sitio multiplicado por los días y por el descuento del nivel: Weekly es 0,90, Monthly es 0,80 y cualquier otro es 1,00. La cantidad entregada se deriva en el servidor a partir del propio subscription_speed del sitio, así que nada de lo que envíes la cambia.

[
  {
    "type": "subscription",
    "website": { "id": 9 },
    "subscription_days": 30,
    "tier": { "name": "Monthly" },
    "url": "https://arena-top100.com/index.php?a=in&u=yourserver"
  }
]

Respuestas

• 200Todas las líneas se crearon y se cobró del saldo. El cuerpo es texto plano.
• 400El cuerpo no era JSON válido.
• 402Saldo insuficiente. El mensaje indica cuántos tokens faltan y no se cobró nada.
• 422Una o más líneas están mal. No se cobró nada.
• 429El mismo carrito se envió en los últimos 60 segundos. Reintenta tras la espera indicada.

Un 422 señala la línea culpable: los errores se indexan como items.[index].[field], así que un carrito con tres líneas malas se arregla en un viaje y no en tres.

{
  "errors": {
    "items.2.amount": ["Enter 0 or more votes; a negative amount is not allowed."]
  }
}

POST /orders/update

`id` es obligatorio; envía solo los campos que cambias. Los pedidos de suscripción no se pueden modificar.

curl -X POST "https://backend.toplistbot.com/orders/update?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":184223,"amount_to_do":2000,"custom_name":"EU launch"}'

Tope diario

`type: "delete"` quita el tope. En ese caso el validador sigue exigiendo `max_votes_per_day`: envía cualquier entero.

curl -X PATCH "https://backend.toplistbot.com/orders/updateLimit?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":184223,"max_votes_per_day":500,"type":"set"}'

Registros y analíticas#

Datos de entrega, voto a voto y agregados. Leen una base de datos de registros aparte y son más lentos que el resto de la API: consúltalos cada minutos, no cada segundos.

• GET/orders/logs/{id}Clave APIRegistro de entrega voto a voto de una campaña
• GET/orders/graph/{id}Clave APISerie temporal de una campaña, lista para graficar
• GET/api/orders/graph/summaryJWTUna serie que agrupa todas tus campañas
• GET/orders/grouped/usernames/{id}Clave APIEntregas agrupadas por el usuario que votó
• POST/orders/averageClave APIEntrega media de varias campañas
• GET/api/logs/{id}/filtered-graphJWTSerie temporal filtrada

Perfiles de voto y proxy#

Un perfil de voto es una lista con nombre de usuarios con los que vota una campaña. Un perfil de proxy es una lista de países permitidos para las IP que usa. Asocia cualquiera de los dos a una campaña con username_profile_id o proxy_profile_id en /orders/update.

• GET/advanced/profile/getClave APITus perfiles de voto
• GET/advanced/profile/get/{id}Clave APIUn perfil de voto
• POST/advanced/profile/createClave APICrear un perfil de voto, o sobrescribir uno por id
• DELETE/advanced/profile/delete/{id}Clave APIBorrar un perfil de voto
• GET/advanced/profile/proxy/getClave APITus perfiles de proxy
• GET/advanced/profile/proxy/get/{id}Clave APIUn perfil de proxy
• POST/advanced/profile/proxy/createClave APICrear un perfil de proxy, o sobrescribir uno por id
• DELETE/advanced/profile/proxy/delete/{id}Clave APIBorrar un perfil de proxy

Tokens de Discord#

Para listas que autentican a los votantes a través de Discord. Añadir el mismo token dos veces se rechaza como duplicado.

• GET/api/discord-tokensJWTTus tokens de Discord
• POST/api/discord-tokensJWTAñadir un token
• GET/api/discord-tokens/statsJWTUso acumulado de tus tokens
• GET/api/discord-tokens/{id}JWTUn token
• PATCH/api/discord-tokens/{id}JWTCambiar un token o su estado activo
• DELETE/api/discord-tokens/{id}JWTEliminar un token
• PUT/api/discord-tokens/{id}/toggleJWTAlternar un token entre activo e inactivo

Facturación y pagos#

Comprar tokens siempre termina en una página de pago alojada, así que recargar no puede ser totalmente automático. Todo lo posterior a la recarga sí.

• GET/invoices/getClave APIHistorial de facturación
• GET/api/subscriptions/subscriptionsJWTSuscripciones activas
• GET/products/tokensByUserClave APIPaquetes de tokens con el precio de tu cuenta
• POST/company/getClave APITu dirección de facturación
• POST/company/createClave APIFijarla: country, region, city, address, postalCode
• GET/api/stripe/checkout?product_id=JWTUna URL de Stripe Checkout para un paquete de tokens
• GET/api/stripe/subscription?plan=JWTUna URL de Stripe Checkout para un plan
• GET/api/stripe/portalJWTUna URL del portal de facturación de Stripe
• GET/api/stripe/documentsJWTFacturas y recibos de Stripe
• GET/coinpayments/checkoutClave APIUna URL de pago con criptomonedas

Carrito guardado#

El carrito del panel, guardado en el servidor para que sobreviva a un cambio de dispositivo. No lo necesitas para crear pedidos: /orders/checkout acepta el carrito en la propia petición.

• GET/api/cartJWTEl carrito guardado
• PUT/api/cartJWTReemplazarlo
• POST/api/cartJWTReemplazarlo, igual que PUT
• DELETE/api/cartJWTVaciarlo

Superficies internas#

Existen para Stripe, el planificador de tareas y el desafío antiabuso del registro. Se autentican con secretos compartidos o firmas y no forman parte de la superficie de integración: se listan aquí solo para que el inventario esté completo.

• POST/api/stripe/webhookEventos de pago de Stripe, autenticados por firma
• POST/api/jobs/tickEjecuta las tareas pendientes, autenticado por secreto compartido
• POST/api/pow/challengeDesafío de prueba de trabajo del registro
• POST/api/logs/updateSeguimiento de actividad de correo
• POST/api/order/{email}Crea un pedido en otra cuenta: solo lista blanca de administradores
• GET/reset-password/{token}La antigua página de restablecimiento renderizada en servidor, mantenida por los enlaces ya enviados
• GET/PúblicaComprobación de estado

El objeto sitio#

Lo devuelven /orders/getAllWebsites y /orders/getWebsiteDetailsByName, y viene incrustado en cada campaña como `website`.

Los campos que no aparecen aquí alimentan la propia interfaz del panel. Léelos si quieres, pero no forman parte del contrato de integración y pueden cambiar sin aviso.

El objeto campaña#

Lo devuelven /orders/getAll y /orders/get/. Fíjate en lo que falta: no hay campo de estado.

Los campos que no aparecen aquí alimentan la propia interfaz del panel. Léelos si quieres, pero no forman parte del contrato de integración y pueden cambiar sin aviso.

¿Está corriendo? ¿Ha terminado?#

Una campaña no tiene campo de estado, así que lo deduces de cuatro columnas. Evalúa estas condiciones en orden y quédate con la primera que se cumpla.

Progreso y reembolsos#

amount_to_do cuenta votos aceptados; amount_done cuenta envíos. Solo se acepta accept_rate por ciento de los envíos, así que están en unidades distintas y restar uno del otro directamente es un error.

// accept_rate arrives as a STRING, and it is per-site, not global.
const rate = Number(order.website.accept_rate)

// amount_done counts SUBMISSIONS; amount_to_do counts ACCEPTED votes.
// Convert before comparing them.
const delivered = order.amount_done * rate / 100
const remaining = Math.max(order.amount_to_do - delivered, 0)
const percent   = 100 * delivered / order.amount_to_do

// What cancelling right now would put back on your balance:
const refund    = (remaining / 1000) * order.website.price_per_1000

La misma cuenta pone precio a una cancelación: el reembolso es el resto no gastado al precio de lista del sitio, así que puedes saber cuánto vale parar una campaña antes de decidirte.