API JSON

Autenticación

Genere una clave personal desde Mi espacio → Claves API y envíela en la cabecera Authorization de cada llamada:

curl -H "Authorization: Bearer cpk_…" https://www.creationdeperso.com/api/v1/me

La clave lleva los derechos de su cuenta: un jugador lee el catálogo y gestiona sus personajes, un DJ además forja monstruos y objetos y redacta campañas y misiones.

Derechos de una clave

Cada clave lleva una lista de derechos elegida al crearla (y modificable después): entradas <code>familia.acción</code>, o una familia entera <code>familia.*</code>. Un derecho nunca supera los roles de la cuenta: una clave con <code>monsters.create</code> en una cuenta sin rol de DJ sigue rechazada. <code>GET /me</code> devuelve los derechos de la clave.

Una llamada fuera de los derechos de la clave responde <code>403 insufficient_scope</code> con el derecho que falta en <code>requiredScope</code>.

Convenciones

• Los elementos del catálogo se designan por su slug (<code>key</code>), nunca por un id numérico. Solo los personajes, campañas y misiones, y los recursos que usted crea, llevan un <code>id</code>.
• Una lista se envuelve en <code>{ items, total }</code> (paginada: <code>{ items, page, perPage, total }</code>, <code>perPage</code> ≤ 100).
• La cabecera <code>Accept-Language</code> (fr por defecto, en, de, es) elige el idioma de los nombres del catálogo y de los mensajes de error.
• Cada cuenta dispone de 1 000 llamadas por hora (cabeceras <code>X-RateLimit-*</code>).

Todo error responde con una envoltura única:

{
  "error": {
    "code": "validation_failed",
    "message": "…",
    "violations": [ { "path": "hitPoints", "message": "…" } ]
  }
}

Las longitudes máximas y los límites de cada campo (maxLength, minimum, maximum) están declarados en el esquema OpenAPI: son las reglas del sitio, superarlos responde 422. Un cuerpo leído con GET puede reenviarse tal cual con PUT, campos de solo lectura incluidos.

Lectura del catálogo

Empiece leyendo el catálogo para conocer los slugs que debe enviar. Las tablas «homebrew» (armas, armaduras, equipo, ataques, monstruos) se limitan a lo que su cuenta puede ver: contenido integrado, contenido público validado y sus propias creaciones (campo <code>origin</code>).

Forja: objetos y monstruos (DJ)

Las mismas reglas que la forja del sitio: cada creación descuenta su coste en créditos (no se escribe nada si el saldo es insuficiente), el contenido nace privado y pasa por moderación para hacerse público, el valor de desafío de un monstruo no puede quedar por debajo de la estimación de sus estadísticas. Las modificaciones y eliminaciones son gratuitas.

curl -X POST -H "Authorization: Bearer cpk_…" -H "Content-Type: application/json" \
     -d '{"name":"Gobelin des cendres","challengeRating":"1/4","armorClass":15,"hitPoints":7,
          "abilities":{"str":8,"dex":14,"con":10,"int":10,"wis":8,"cha":8},
          "skills":{"stealth":2},"attacks":[{"weapon":"scimitar"}]}' \
     https://www.creationdeperso.com/api/v1/monsters

Campañas y misiones (DJ)

El DJ es siempre la cuenta que llama. Los personajes se designan por <code>id</code>: un miembro del grupo debe ser público y reclamado, un PNJ vinculado debe ser una de sus fichas, un invitado debe ser público, reclamado y fuera del grupo. Una campaña o misión pública retocada vuelve a quedar pendiente de validación.

Personajes

La creación sigue exactamente las reglas del formulario del sitio: las seis puntuaciones deben ser una permutación de la tirada emitida por el servidor (obtenida en el endpoint de tirada y devuelta como el ticket <code>abilityRollToken</code>, válido cinco minutos y consumido una sola vez), el linaje es obligatorio cuando la especie tiene, el reparto del trasfondo debe ser legal, y las habilidades, dotes, conjuros y equipo se mantienen dentro de los presupuestos de nivel 1. Una regla incumplida responde 422 con la ruta del campo afectado.

El documento completo legible por máquina se sirve en OpenAPI.