Da de alta una institución y su sandbox

Estado honesto

El procedimiento de alta ya levantó una celda de demostración con datos ficticios; ninguna institución real tiene celda todavía. El script está en la rama de trabajo de la infraestructura SaaS y forma parte del material interno de implementación: las rutas, servidores e imágenes reales se entregan por ese canal. En esta guía todo lo variable va entre <…>.

Si todavía no lo has hecho, lee antes SaaS en nube propia: la arquitectura de celdas y Suscripción y licencias por módulo.

Lo que necesitas

Qué	Para qué
Acceso de operador al servidor de celdas, con Docker, jq, curl y openssl	Levantar la celda
Un token de servicio de la consola emisora con los alcances lic:read, lic:write y lic:emitir, en un archivo con permisos 600	Crear la instalación, la suscripción y emitir las llaves
El código del plan que contrató la institución (por ejemplo CORE_BASICO)	La suscripción
La imagen del core con una etiqueta fija del corte (nunca latest)	El core de la celda
La ruta del registro de instituciones del gateway (y, si quieres, su archivo de entorno)	Enrutar a la institución
La base de referencia del instalador	Poblar una base vacía

El identificador de la institución va en minúsculas, dígitos y guiones, entre 2 y 40 caracteres: será también su subdominio en el gateway. En esta guía usamos banco-demo.

Da de alta la institución

1. Mira el plan sin tocar nada. Ejecuta el alta sin --aplicar. Por defecto el script corre en modo de prueba: imprime los cinco pasos con lo que haría y termina sin tocar la red, Docker ni archivos.

   saas/alta-tenant.sh --tenant banco-demo --nombre "Banco Demo, C.A." \
     --plan CORE_BASICO --periodicidad ANUAL \
     --imagen-core <imagen-del-core>:<corte> \
     --licencias-url https://<su-emisor> \
     --token-emisor-archivo <ruta-segura>/token-emisor \
     --tenants-yaml <ruta-del-gateway>/tenants.yaml \
     --gateway-env <ruta-del-gateway>/.env

   Verás un resumen como este, que termina en «Modo —dry-run: no se ha tocado nada»:

   Plan de alta del tenant banco-demo (Banco Demo, C.A.)
     a) celda          <celdas>/banco-demo  (proyecto finora-celda-banco-demo, .env 600, secretos generados si faltan)
     b) licencias      https://<su-emisor>/api/v1/admin
                       instalación banco-demo: GET → si 404, POST
                       suscripción ACTIVA del plan CORE_BASICO (ANUAL desde <hoy>)
                       emitir con Idempotency-Key alta-banco-demo-<suscripcionId>
     c) docker compose up -d en la red finora-celdas; espera healthy (máx. 900 s)
     d) tba_api_keys: socio finora-core-gateway, sha256 de la clave en <celdas>/banco-demo/secretos/…
     e) <ruta-del-gateway>/tenants.yaml: tenant banco-demo → http://banco-demo-core:8087

2. Revisa el plan con calma. Comprueba el identificador, el plan, la periodicidad y la imagen. Si la institución contrató módulos fuera del plan, agrégalos con --modulos-adicionales GL_API,GATEWAY. Si debe ver solo algunos dominios del gateway, usa --gateway-modulos CLIENTS,DEPOSITS,GL. Para un ambiente que no es productivo (demo, pruebas, sandbox) agrega --no-productivo: sin esa opción, un core productivo exige las integraciones regulatorias reales y no arranca con las simuladas.

3. Aplica. Repite la misma orden con --aplicar. El script recorre los cinco pasos:

   Paso	Qué hace	Qué escribe
   a) Celda	Crea la carpeta de la celda desde la plantilla y genera los secretos que falten	El archivo de entorno de la celda, con permisos 600
   b) Licencias	Crea la instalación (si no existe), su clave de sincronización, la suscripción del plan y emite las llaves	La respuesta de la emisión y las claves públicas para el core
   c) Arranque	Levanta la base y la caché; si la base está vacía, restaura la base de referencia sin datos de demostración, cambia la clave del administrador y desactiva las demás cuentas semilla; levanta el core y espera a que esté sano	La clave nueva del administrador, en un archivo 600
   d) Credencial del gateway	Crea la credencial del gateway ante el core de la celda, guardando en el core solo su huella	El valor, en un archivo 600 para el gateway
   e) Registro del gateway	Agrega la institución al registro, con respaldo previo y verificación	El registro actualizado; el gateway lo relee solo

4. Completa lo manual. Al terminar, el resumen recuerda lo que el script no hace: crear los clientes OAuth de la institución en el gateway y entregarle sus credenciales por el canal seguro. Si no usaste --gateway-env, copia la variable de la credencial del core al entorno del gateway y reinícialo.

Puedes repetirlo

El alta es idempotente. Si un paso falla (por ejemplo, el core tarda más de lo esperado en quedar sano), corrige la causa y vuelve a ejecutar la misma orden con --aplicar: no se regeneran secretos, no se crea otra suscripción, la emisión repite su clave de idempotencia y el registro del gateway no se duplica.

Comprueba el resultado

• Core sano. El paso c) solo termina cuando el contenedor del core informa que está sano.
• Licencias. La emisión informa cuántas llaves emitió y para qué módulos. Las concesiones llegan al core en su sincronización al arrancar o en la siguiente programada; para no esperar, sigue Sincroniza y verifica las licencias en el core.
• Gateway. Pide un token con el cliente de la institución y haz una lectura (por ejemplo GET /v1/glaccounts). Luego prueba el aislamiento: un token de otra institución contra banco-demo debe responder 403 TENANT_CRUZADO.

Clona su sandbox

El sandbox es otra celda, con su propia instalación de licencias, poblada con una copia anonimizada de la base de producción.

1. Da de alta la celda del sandbox con el mismo procedimiento, marcándola como sandbox y no productiva:

   saas/alta-tenant.sh --tenant banco-demo-sandbox --sandbox-de banco-demo \
     --nombre "Banco Demo, C.A. (sandbox)" --plan CORE_BASICO --no-productivo \
     --imagen-core <imagen-del-core>:<corte> --licencias-url https://<su-emisor> \
     --token-emisor-archivo <ruta-segura>/token-emisor \
     --tenants-yaml <ruta-del-gateway>/tenants.yaml --aplicar

   La institución de producción ya debe estar en el registro del gateway: si no, el script se detiene.

2. Mira el plan del clonado. Sin --aplicar, el script de clonado muestra origen, destino y sus cuatro pasos:

   saas/sandbox-clonar.sh --contenedor <postgres-de-banco-demo> \
     --contenedor-destino <postgres-de-banco-demo-sandbox> \
     --db finora --db-destino finora_sandbox \
     --semilla-archivo <celdas>/banco-demo/secretos/semilla-sandbox

   El destino debe contener la palabra sandbox en su nombre y no puede ser la base de origen: es una salvaguarda, porque el destino se puede reemplazar.

3. Clona. Repite con --aplicar. Verás 1/4 (copia a una base temporal), 2/4 y 3/4 (anonimización y purga de credenciales en una sola transacción) y 4/4 (publicación). Si el sandbox ya existe, el script se niega; para refrescarlo, agrega --reemplazar.

4. Apunta el sandbox a su base y crea su credencial. En el entorno de la celda del sandbox, indica que su base es finora_sandbox y vuelve a ejecutar el alta del sandbox con --aplicar: la copia no trae ninguna credencial, así que el paso d) crea la del gateway.

La semilla es un secreto

La anonimización es determinista: con la misma semilla y la misma base, da el mismo resultado. Por eso quien conozca la semilla podría confirmar un dato original probando valores. No la compartas con los usuarios del sandbox.

Retira una institución

Retirar es el camino inverso y no tiene marcha atrás: haz antes un respaldo de la base de la celda.

1. Quita la institución del registro del gateway y la variable de su credencial del entorno del gateway. Desde ese momento el gateway responde 403 TENANT_DESCONOCIDO a sus peticiones.

2. En la consola emisora, suspende la instalación (o dala de baja). Su core deja de recibir concesiones nuevas.

3. Detén la celda y elimina sus volúmenes desde la carpeta de la celda, con el nombre de su proyecto:

   docker compose -p finora-celda-banco-demo down -v

Errores frecuentes

Qué pasa	Por qué	Qué hacer
«falta —imagen-core (la celda aún no tiene imagen)»	Primera alta sin imagen	Indica una imagen con etiqueta fija
«—imagen-core debe llevar un tag inmutable»	Usaste latest	Usa la etiqueta del corte
El core no queda sano y reinicia en bucle	Una base vacía sin base de referencia, o un core productivo con integraciones simuladas	Revisa que exista la base de referencia; en demo o sandbox usa --no-productivo
«—sandbox-de …: ese tenant no está en tenants.yaml»	Intentaste el sandbox antes que producción	Da de alta primero la institución de producción
El clonado sale con código 3	El sandbox ya existe	Agrega --reemplazar si de verdad quieres refrescarlo
La emisión responde 409 REGLA_DE_LICENCIA	La suscripción no cumple una regla de la consola emisora	Lee el detalle en la consola; el mensaje es el mismo que ve un operador