Tokens de API

Pásale el .md directo a tu IA para que integre la API (incluye automatización de cartas y reporte de anomalías).

1. Autenticación

Toda petición lleva tu token en la cabecera:

Authorization: Bearer ctcg_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Base URL: https://codicetcg.org/api/v1

Cada token puede tener vigencia (la eliges al crearlo). Un token expirado responde 401 y debes generar uno nuevo.

2. Permisos (scopes)

• cards:read — leer cartas y datos de referencia (todos los planes).
• decks:public — leer mazos públicos de usuarios vinculados (todos los planes).
• decks:private — leer también mazos privados de usuarios que vincularon su cuenta con tu app (plan Partner).
• anomaly:read / anomaly:write — reportar y revisar anomalías de datos (plan Partner).
• automation:read / automation:write — cartas automatizadas. Solo el equipo de Códice lo concede, previa revisión.

Los permisos se ajustan solos a tu plan: al subir a Partner tus tokens reciben los nuevos permisos sin regenerarlos. Si el plan vence, la API responde 403 hasta que renueves. Si superas las consultas por minuto de tu plan, responde 429 con el header Retry-After.

3. Vincular un usuario

El usuario de Códice copia su ID de conexión (public_id) desde su página de Configuración y lo pega en tu app. Con ese ID consultas sus mazos.

4. Endpoints

5. Campos de una carta

Tanto /catalog/:bloque como /cards y /cards/:uuid devuelven cada carta con estos campos:

{
  "uuid": "abc123",
  "nombre": "Nombre de la carta",
  "master_slug": "espada-sagrada",  // identifica la misma carta en distintas ediciones
  "edicion": "Nombre de la edición",
  "tipo": "Aliado",                 // nombre ya resuelto ("Aliado", "Talismán", "Arma"…)
  "coste": 3,                        // número | null
  "fuerza": 2,                       // número | null
  "habilidad": "Texto de la habilidad…",
  "frecuencia": "UR",               // código de rareza tal cual ("C", "UR", "MR", "SP"…)
  "razas": ["Caballero", "Real"],    // lista: una carta multi-raza trae varias
  "familias": ["Helenica"],          // lista: familias (edición base) de la carta
  "imagen": "https://…"
}

tipo, razas y familias vienen ya resueltos a su nombre. razas y familias son siempre listas (una carta puede ser multi-raza o pertenecer a varias familias). master_slug es el mismo para todas las reimpresiones de una carta → sirve para identificar cartas iguales entre ediciones. El catálogo de IMP incluye además temporada. Los campos sin dato devuelven null (o lista vacía).

Si prefieres trabajar con IDs, las tablas de referencia (/reference/types, /reference/races, /reference/editions, /reference/seasons) devuelven el mapeo id → nombre de cada taxonomía.

6. Reconstruir un mazo

Un mazo trae solo UUIDs y cantidades. Dos formas de resolver las cartas reales:

1. Lee el mazo → obtienes datos_json.main/side (uuid → cantidad) y el bloque.
2. Opción A (recomendada, offline): descarga el catálogo del bloque una vez con /catalog/:bloque y cruza cada UUID localmente. Ya trae todos los campos, sin llamadas extra.
3. Opción B (puntual): pasa los UUIDs del mazo a /cards?uuids=a,b,c (hasta 300) y recibes las cartas resueltas en una sola petición.

Usa /catalog (manifiesto) para cachear y solo re-descargar el catálogo cuando su updated_at cambie.

7. Ejemplo (curl)

TOKEN="ctcg_..."
BASE="https://codicetcg.org/api/v1"

# Mazos del usuario
curl -H "Authorization: Bearer $TOKEN" "$BASE/users/$PUBLIC_ID/decks"

# Un mazo completo
curl -H "Authorization: Bearer $TOKEN" "$BASE/users/$PUBLIC_ID/decks/mi-mazo"

# Catálogo del bloque para resolver los UUIDs (offline)
curl -H "Authorization: Bearer $TOKEN" "$BASE/catalog/IMP"

# Resolver varias cartas puntuales en una sola petición
curl -H "Authorization: Bearer $TOKEN" "$BASE/cards?uuids=abc123,def456,ghi789"

8. Escritura: cartas automatizadas y anomalías

anomaly:write viene incluido en el plan Partner; automation:write lo concede solo el equipo de Códice. Ambos están pensados para uso servidor a servidor. Tienen límite de tasa y validación de tamaño. Solo escriben registros ligados a tu propio partner; no tocan cartas, mazos ni usuarios.

FX se declara por master_slug (cubre todas las reimpresiones); IMP por uuid. Ejemplo:

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  "$BASE/automation/cards" -d '[
    { "match_type": "master_slug", "match_value": "walkirias-fx", "bloque": "FX",
      "nombre": "Walkirias", "automated_since": "2026-09-22" }
  ]'

El detalle completo de bodies y respuestas está en el .md descargable arriba.

Errores

401 token ausente/inválido/revocado · 403 falta el permiso requerido · 404 no encontrado · 429 límite de tasa (reintenta según Retry-After).