API para bots

La API deja que otros bots usen a Catita en un servidor: leer y sumar XP, dar o quitar dinero, crear llaves de roles propios o generar capturas FakeSS. Discord no deja que un bot use los comandos de otro, así que se hace por HTTP en https://api.catita.gg/v1.

Crear una llave

En /settings > API > Crear llave (hace falta Gestionar servidor).

• La llave es así: ctk_1a2b3c4d_…. Se ve una sola vez: cópiala al crearla. Catita solo guarda su huella cifrada, así que no puede volver a enseñártela.
• Cada llave sirve solo en su servidor: ninguna ruta lleva el ID del servidor, sale de la llave.
• Hasta 5 llaves por servidor, cada una con su nombre, permisos, topes y caducidad.
• Rotar da un secreto nuevo y el anterior deja de valer al momento. Revocar la borra.
• Cada llave creada, rotada o revocada se avisa en el canal de registros de moderación.

Guárdala como un secreto: en una variable de entorno, nunca en el código ni en un mensaje.

Permisos

Las llaves nuevas solo leen. Marca en /settings lo que necesite tu bot:

Permiso	Deja
keys:read	Ver las llaves de roles propios
keys:write	Crear llaves de roles propios (hasta 100 al día por llave)
levels:read	Leer niveles y el ranking
levels:write	Sumar o quitar XP
economy:read	Leer saldos
economy:write	Dar o quitar dinero de la cartera
fakess	Generar capturas

Autenticación

Manda la llave en la cabecera Authorization:

curl https://api.catita.gg/v1/me \
  -H "Authorization: Bearer $CATITA_KEY"

const res = await fetch('https://api.catita.gg/v1/me', {
    headers: { Authorization: `Bearer ${process.env.CATITA_KEY}` }
});
console.log(await res.json());

Límites

• 60 peticiones por minuto por llave (las capturas, 10). Cada respuesta trae X-RateLimit-Remaining; al pasarte, 429 con Retry-After.
• Topes diarios por llave: por defecto 50 000 de XP y 1 000 000 de dinero, sumado o quitado. Se cambian en /settings > API > la llave > Topes y se reinician a las 00:00 UTC. Así, una llave filtrada no puede romper la economía.
• Muchas llaves incorrectas desde la misma IP la bloquean 10 minutos.
• Cuerpos JSON de 16 KB como mucho, con Content-Type: application/json. Los campos que no existen se rechazan.

Reintentos sin duplicar

Las escrituras aceptan la cabecera Idempotency-Key (de 1 a 64 letras, números, - o _). Si tu bot repite la misma petición con la misma clave en 24 horas, recibe la misma respuesta (con Idempotent-Replayed: true) y no se suma dos veces.

curl -X POST "https://api.catita.gg/v1/levels/123456789012345678/xp" \
  -H "Authorization: Bearer $CATITA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: premio-evento-42" \
  -d '{"amount": 500}'

Endpoints

Todos los IDs de personas tienen que ser de miembros del servidor de la llave (no bots). ?instance= elige la instancia de niveles o de economía; sin él, la principal.

Método y ruta	Permiso	Qué hace
GET /v1/me	—	El servidor, la llave, sus permisos y cuánto queda hoy de cada tope
GET /v1/levels/leaderboard?limit=&offset=	levels:read	Ranking (hasta 100 por página)
GET /v1/levels/{userId}	levels:read	Nivel, XP, rebirths y puesto
POST /v1/levels/{userId}/xp	levels:write	{ "amount": 500 } suma; un número negativo resta
GET /v1/economy/{userId}	economy:read	Cartera, banco y patrimonio
POST /v1/economy/{userId}/wallet	economy:write	{ "amount": 1000 } da; negativo quita (nunca deja saldo negativo)
GET /v1/customroles/keys	keys:read	Las últimas 100 llaves de roles propios
POST /v1/customroles/keys	keys:write	{ "days": 30, "count": 5 } crea llaves (1 a 365 días, 1 a 20 llaves)
POST /v1/fakess	fakess	Captura PNG de un mensaje

Sumar XP funciona como darla desde /settings: sube de nivel, da las recompensas y hace el anuncio. Cada cambio de dinero queda en el libro contable del servidor como api:<nombre de la llave>.

Ejemplo: premiar a alguien con dinero

const res = await fetch(`https://api.catita.gg/v1/economy/${userId}/wallet`, {
    method: 'POST',
    headers: {
        Authorization: `Bearer ${process.env.CATITA_KEY}`,
        'Content-Type': 'application/json',
        'Idempotency-Key': `premio-${interaction.id}`
    },
    body: JSON.stringify({ amount: 1000 })
});
const data = await res.json();
if (!res.ok) throw new Error(data.error.message);
console.log(`Ahora tiene ${data.wallet}`);

Capturas FakeSS

{
  "authorId": "123456789012345678",
  "content": "hola **a todos**",
  "reply": { "authorId": "234567890123456789", "content": "¿qué tal?" },
  "image": "https://cdn.discordapp.com/attachments/…/foto.png",
  "theme": "dark"
}

• El autor tiene que ser miembro del servidor: el nombre, el avatar y el color salen de Discord, no se pueden inventar.
• content hasta 2000 caracteres y 10 menciones; theme es dark, darker o light.
• image solo del CDN de Discord (cdn.discordapp.com o media.discordapp.net).
• Devuelve un PNG. Si hay muchas a la vez, 503 con Retry-After.

Errores

Siempre con el mismo formato:

{ "error": { "code": "missing_scope", "message": "This key needs the \"levels:write\" scope." } }

Estado	Cuándo
400	Cuerpo o parámetro inválido
401	Llave que falta, es incorrecta, caducó o se revocó
403	La llave no tiene ese permiso, o Catita ya no está en el servidor
404	La persona no es miembro, o la instancia no existe
409	No se puede hacer ahora (niveles apagados, saldo insuficiente…)
422	Idempotency-Key repetida con otra petición, o una imagen que no se pudo leer
429	Límite por minuto o tope diario
503	Ocupado: reintenta tras Retry-After

La especificación completa está en openapi.json. Para recibir avisos cuando pasa algo, mira Eventos.