Emite las llaves de una institución

Estado honesto

La consola emisora está implementada y en operación en el entorno de demostración, sin bancos reales: hoy emite solo para la instalación piloto y para una celda de demostración. Esta guía describe sus pantallas tal como están en el código; no lleva capturas porque la consola no tiene todavía un ambiente de demostración con datos ficticios.

Si dar de alta la institución lo hace el procedimiento automatizado (Da de alta una institución y su sandbox), estos pasos ya ocurrieron por la API de administración. Esta guía es el mismo recorrido hecho a mano, y sirve para entender qué hizo el script, para atender a una institución instalada en su propio centro de datos o para renovar y revocar.

Necesitas un usuario de la consola con el rol Licencias: administración. Con Licencias: lectura ves todo, pero no puedes emitir ni revocar.

Emite las llaves

El menú de la consola tiene cuatro grupos: Clientes (Instalaciones, Suscripciones), Emisión (Concesiones, Listas de revocación, Claves de firma), Catálogo (Módulos, Planes) y Administración (Usuarios).

1. Registra la instalación. Abre Clientes → Instalaciones y crea una. El ID de instalación es el identificador que el core de la institución tendrá configurado (por ejemplo, banco-demo): debe coincidir exactamente, porque va dentro de cada llave. Completa la razón social («Banco Demo, C.A.»), el contacto y el correo. La instalación nace en estado ACTIVA.

2. Genera la clave de sincronización. En la lista de instalaciones, selecciona la nueva y pulsa Generar clave de sincronización. La consola te avisa que la clave se mostrará una sola vez: cópiala en ese momento y entrégala por el canal seguro a quien configura el core. La consola guarda solo su huella SHA-256. Si la instalación ya tenía clave, la nueva la reemplaza y el core deja de sincronizar hasta que se configure la nueva.

3. Elige o crea el plan. En Catálogo → Planes revisa si ya existe el paquete contratado. Un plan tiene un código, sus módulos, sus precios mensual y anual y unos límites por defecto en JSON. El catálogo de Módulos trae sembrados los 21 módulos del core.

4. Crea la suscripción. En Clientes → Suscripciones, crea una para la instalación con:

   Campo	Qué poner
   Plan	El plan contratado
   Módulos adicionales	Los módulos fuera del plan, si los hay
   Periodicidad	Mensual, trimestral o anual
   Inicio	Desde cuándo valen las llaves
   Fin	El último día de vigencia (inclusive); vacío = perpetua
   Límites	JSON que sobrescribe los límites del plan; {} si no hay
   Renovación automática	Si el cierre diario debe renovarla al vencer

   El fin no puede ser anterior al inicio.

5. Emite las llaves. En la lista de suscripciones, selecciona la nueva y pulsa Emitir llaves. La consola firma una llave FNM1 por módulo (del plan más los adicionales activos) y te informa, por ejemplo, «Emitidas: 7 · sin cambios: 0 · revocadas: 0».

6. Comprueba las concesiones. Abre Emisión → Concesiones: verás una fila por módulo con su Grant ID, Válida desde, Válida hasta, Clave (kid) y estado VIGENTE.

Emitir dos veces no duplica

Emitir es idempotente: si ya hay una concesión vigente con las mismas condiciones, no se vuelve a firmar y cuenta como «sin cambios». Si las condiciones cambiaron, la concesión anterior se revoca y se emite la nueva.

Entrega las llaves al core

Lo normal es que el core las pida solo: con su ID de instalación, la URL de la consola emisora, la clave de sincronización y las claves públicas configuradas, las recibe al arrancar, cada seis horas o cuando alguien pulsa «Sincronizar ahora». Las claves públicas que el core necesita las da Emisión → Claves de firma → Copiar para el core.

Si el core de la institución no puede alcanzar la consola emisora (por ejemplo, en un centro de datos sin salida), usa Concesiones → Exportar vigentes: entrega todas las llaves vigentes de la instalación, una por línea, y al final la última lista de revocación, para importarlas a mano en el core.

Sigue en Sincroniza y verifica las licencias en el core.

Renueva, revoca y rota

Tarea	Dónde	Qué pasa
Renovar	Suscripciones → Renovar	El fin se extiende un periodo (1, 3 o 12 meses según la periodicidad) y se emiten llaves nuevas; las anteriores quedan revocadas
Revocar una concesión	Concesiones → Revocar	Exige un motivo. Se publica una lista de revocación FNR1 con la secuencia siguiente; el core la aplica en su próxima sincronización
Re-emitir	Concesiones → Re-emitir	Firma de nuevo la concesión, por ejemplo después de rotar la clave de firma
Suspender la instalación	Instalaciones → abre la instalación y cambia su Estado a SUSPENDIDA	La sincronización responde 423: el core no recibe concesiones nuevas, pero lo ya importado sigue valiendo hasta su fin
Rotar la clave de firma	Claves de firma	Con la clave nueva desplegada, re-emite y usa Copiar todas (rotación): el core debe listar la clave nueva y las anteriores mientras queden llaves vigentes firmadas con ellas

Cada noche, el cierre de la consola renueva las suscripciones con renovación automática que vencieron y marca como vencidas las demás y sus concesiones. El Tablero muestra lo que está por vencer.

Lo mismo, por API

La consola expone la misma secuencia en https://<su-emisor>/api/v1/admin, con un token de servicio (Authorization: Bearer <token>) y alcances lic:read, lic:write, lic:emitir y lic:revocar. Emitir y revocar exigen la cabecera Idempotency-Key: repetir la misma petición devuelve la misma respuesta con Idempotent-Replayed: true.

Paso	Petición
Instalación	POST /instalaciones
Clave de sincronización	POST /instalaciones/{installationId}:generarClaveSync
Suscripción	POST /suscripciones
Emisión	POST /suscripciones/{id}:emitir
Claves públicas para el core	GET /firma/claves
Revocación	POST /concesiones/{grantId}:revocar

Errores frecuentes

Qué pasa	Por qué	Qué hacer
El core rechaza las llaves con INSTALLATION_MISMATCH	El ID de instalación de la consola no coincide con el del core	Corrige el ID en el core (o crea la instalación con el ID correcto) y vuelve a emitir
El core rechaza con UNKNOWN_KID	El core no tiene la clave pública con la que se firmó	Copia las claves de firma al core, incluidas las anteriores durante una rotación
Emitir responde que la firma no está disponible	La consola arrancó sin su clave de firma	La pantalla Claves de firma muestra el motivo; corrige la configuración y reinicia
El core dejó de sincronizar tras generar la clave	La nueva clave anuló la anterior	Configura la clave nueva en el core