Salud y readiness
GET /health responde liveness. GET /readyz ejecuta cada sonda de dependencia y responde un solo estado.
GET /readyz/tenant/{id} responde el mismo detalle para una institución. READYZ_PROBE_TIMEOUT_SEC limita cada sonda a 5 segundos. READYZ_DEP_SLOW_THRESHOLD_MS marca una dependencia lenta a los 500 milisegundos.
Un Reporter inalcanzable retira la instancia de servicio. Inicia primero el Reporter.
Configuración en tiempo de ejecución
Un pequeño conjunto de perillas cambia sin un reinicio. Configura
SYSTEMPLANE_ENABLED=true para montar el plano de tiempo de ejecución.
Cada grupo es un espacio de nombres bajo el prefijo de configuración de este servicio.
Lee un espacio de nombres con
GET /system/{namespace} y una clave con GET /system/{namespace}/{key}. Escribe una clave con PUT /system/{namespace}/{key}. Solo un administrador de la plataforma puede llamar a estas rutas.
Todo lo demás proviene del entorno y necesita un reinicio: cadenas de conexión, pools, material TLS, listeners, y la puerta de autenticación. Consulta Systemplane para el contrato del plano de tiempo de ejecución.
Credenciales y claves
Configura
PLUGIN_AUTH_ENABLED=true y PLUGIN_AUTH_HOST para activar la puerta de la API. El mismo par impulsa la autenticación saliente.
Cada upstream lleva su propia credencial. Lerian STA usa STA_CLIENT_ID y STA_CLIENT_SECRET. Lerian Reporter usa REPORTER_CLIENT_ID y REPORTER_CLIENT_SECRET. No hay credencial compartida ni alternativa.
Con la puerta activa, un par faltante detiene el arranque y nombra la variable exacta. Lerian CCS genera cada token mediante OAuth2 client credentials y lo almacena en caché durante M2M_CREDENTIAL_CACHE_TTL_SEC segundos, 300 por defecto. Los despliegues multi-institución leen en cambio las credenciales por institución desde AWS Secrets Manager.
CCS_CRYPTO_MASTER_KEY contiene la clave maestra AES-256-GCM para los datos cifrados en reposo. Toma 64 caracteres hexadecimales. Un valor vacío detiene el arranque.
Lerian CCS puede verificar una firma en cada evento entrante de Lerian STA. Configura STA_EVENT_HMAC_VERIFY_ENABLED=true, carga el catálogo de claves en STA_EVENT_HMAC_MASTER_KEYS, y nombra la versión activa en STA_EVENT_HMAC_MASTER_KEY_VERSION. Carga primero el catálogo. STA_EVENT_HMAC_TOLERANCE_SECONDS limita el desfase de reloj a 300 segundos.
Almacenamiento, outbox y retención
Dos buckets de almacenamiento de objetos contienen el XML regulatorio:
OBJECT_STORAGE_STA_BUCKET de entrada y OBJECT_STORAGE_CCS_BUCKET de salida. Solo las referencias de archivo viajan por la red.
El trabajo de salida sale a través de una tabla outbox transaccional. El despachador la lee cada OUTBOX_DISPATCH_INTERVAL_SEC segundos, 2 por defecto, en lotes de OUTBOX_BATCH_SIZE, 50 por defecto, y abandona un evento después de OUTBOX_MAX_DISPATCH_ATTEMPTS intentos, 10 por defecto. Configura CCS_OUTBOX_OVERRIDES_ENABLED=true para mover el despachador al intervalo, tamaño de lote y presupuesto de intentos de CCS_OUTBOX_*. Un mensaje que agota su presupuesto de intentos pasa a la cola dead-letter bajo CCS_OUTBOX_DLQ_ROUTING_KEY, y esa clave se aplica en ambos casos.
CCS_OUTBOUND_RETENTION_DAYS y CCS_ACCS009_RETENTION_DAYS tienen ambos un valor por defecto de 30 días. Un monitor busca una remesa faltante cada CCS_NON_SUBMISSION_SCAN_INTERVAL_SEC segundos, 3600 por defecto.
El servicio nunca aplica su propio esquema de base de datos. Un job de migración separado lo aplica antes del arranque.
Respuestas de STA en espera
Un archivo de entrada que Lerian CCS no puede aplicar queda en espera en una cola dead-letter con su payload intacto. Una espera mantiene una pendencia abierta. El archivo en espera suele ser la única copia de un hecho de BACEN, así que necesita una alerta y una decisión humana.
POST /v1/batches/{id}/drain-parked-response aplica un ACCS003 tardío a un lote que ya alcanzó un estado terminal. Quien llama solo aporta identificadores. Lerian CCS vuelve a obtener el archivo, vuelve a derivar los veredictos, y rechaza cuando el lote nombrado no coincide. Escribe una entrada de auditoría en la misma transacción.
No liberes la respuesta en espera cuando dos lotes coinciden con un archivo, o cuando la correlación se contradice. Establece primero qué lote produjo el archivo. Trata el desacuerdo como el hallazgo.
Métricas y trazas
GET /metrics sirve las métricas de readiness en formato de texto Prometheus. Configura ENABLE_TELEMETRY=true para exportar trazas y métricas por OTLP a OTEL_EXPORTER_OTLP_ENDPOINT. Consulta Observabilidad para la vista de la plataforma.
Postura de despliegue
DEPLOYMENT_MODE toma local, byoc, saas u onprem. En saas, el servicio exige TLS en cada dependencia. CCS_RUN_MODE toma manager, worker o all, y selecciona qué subsistemas se ejecutan.
Producción agrega estos requisitos.
PLUGIN_AUTH_ENABLED=trueconPLUGIN_AUTH_HOST.LICENSE_KEYyORGANIZATION_IDS.CIRCUIT_BREAKER_ENABLED=true, que necesita la integración con Reporter.REPORTER_URLyCCS_CRYPTO_MASTER_KEY, ambos siempre obligatorios.