Saltar al contenido principal
Tres realidades del hub de archivos de BACEN dan forma a Lerian STA. Las credenciales por institución expiran, cada transferencia saliente tiene una vida útil acotada, y BACEN no hace idempotente el paso de creación de protocolo. Lerian STA concilia al nivel de granularidad del número de protocolo de BACEN.

Sondeadores

Cuando SCHEDULER_ENABLED es true, el scheduler ejecuta el sondeador de estado saliente. El sondeador se autoencola con un backoff por clave de estado. Lerian STA somete todas las credenciales de una institución a un único presupuesto de 10 transferencias de archivo simultáneas y 10 comandos por minuto, que la rotación de contraseña comparte. Reserva 20 consultas por minuto para el descubrimiento entrante de forma predeterminada.

Credenciales

Cada credencial es una contraseña de operador de BACEN. Lerian STA la identifica por código de institución e ID de operador. Lerian STA la almacena cifrada con cifrado envelope. Los operadores pueden crear, actualizar, probar la conectividad de, rotar y revocar una credencial. Una actualización cambia solo el ID de operador o la descripción.

Qué credencial usa una transferencia

Una solicitud de creación de transferencia selecciona su credencial de BACEN de una de tres formas. Lerian STA aplica la primera que la solicitud lleva:
  1. credentialId: Lerian STA usa esa credencial.
  2. institutionCode sin credentialId: Lerian STA usa la única credencial no revocada de esa institución.
  3. Ninguno de los dos campos: Lerian STA usa la única credencial no revocada que tiene.
La respuesta 201 lleva el credentialId que Lerian STA usó. Para dejar un campo sin valor, omítelo o envía null. Una cadena vacía devuelve 400 con STA-0014. La solicitud solo exige que la credencial exista. Una transferencia en una credencial en rotación o rechazada se crea y queda retenida, sin envío, hasta que la contraseña se resuelva o hasta que el plazo de envío de BACEN la cierre.

Rotación de contraseña

La rotación es un protocolo de tres fases que conserva la contraseña anterior y la nueva hasta que BACEN confirma una de ellas:
  1. Prepara la nueva contraseña de forma local.
  2. Cámbiala en BACEN.
  3. Promuévela de forma local.
Un barrido de recuperación resuelve las rotaciones que quedaron en curso. Se ejecuta una vez al arrancar el worker cuando CREDENTIALS_RECOVERY_ON_BOOT es true, y cada 5 minutos cuando SCHEDULER_ENABLED es true. Resuelve solo una rotación cuyo último cambio tiene al menos 15 minutos. Hasta que una rotación se resuelva, las cargas de esa credencial quedan retenidas, y una prueba de conectividad o una nueva rotación responde 409 con STA-0102. Si BACEN no acepta ni la contraseña anterior ni la nueva, Lerian STA marca la credencial como rechazada.

Credencial rechazada

Cuando BACEN rechaza la contraseña de una credencial, Lerian STA marca la credencial como rechazada, con el estado error. Una credencial rechazada no inicia sesión en nada. Las cargas en ella quedan retenidas con CREDENTIAL_REFUSED, y una prueba de conectividad o una rotación responde 409 con STA-0102. Lerian STA aún acepta nuevas transferencias en ella y las retiene. Un operador libera la credencial con PUT /v1/credentials/{id}/current-password, que exige el permiso credentials:rotate. El cuerpo lleva la contraseña que BACEN tiene ahora. Lerian STA inicia sesión en BACEN una vez con ella:
  • Si BACEN la acepta, Lerian STA guarda la contraseña, la credencial vuelve a estar activa y los archivos retenidos salen de inmediato.
  • Si BACEN la rechaza, la solicitud responde 422 y no se guarda nada. Cada inicio de sesión rechazado cuenta para el bloqueo del operador en BACEN.
  • Si el usuario de Sisbacen no tiene acceso a STA, la solicitud responde 422 y no se guarda nada. La respuesta indica que este caso no cuenta para el bloqueo.
  • Si BACEN no responde, la solicitud responde 503 y no se guarda nada.
  • Una credencial que no está rechazada responde 409.

Monitoreo de expiración de contraseña

BACEN exige cambios periódicos de contraseña. Lerian STA rastrea la expiración reportada por BACEN de cada credencial mediante una cache read-through. Proyecta una banda de salud con los días restantes. Las bandas son saludable por encima de 15 días, de advertencia de 6 a 15, crítica de 1 a 5 y vencida en 0 o menos. Un operador puede entonces rotar la contraseña antes de que BACEN le bloquee el acceso.

Retención y TTL de protocolo

  • Plazo de envío saliente. BACEN cancela un protocolo cuyo archivo no se envió por completo en 48 horas. En ese plazo, Lerian STA cancela una carga retenida que aún no se envió.
  • TTL de protocolo saliente. Después de que el archivo se envía, cada paso de BACEN tiene una vida útil de reloj de pared, contada desde el último cambio de estado. El valor predeterminado es 44 horas (TRANSFER_TTL_HOURS).
  • Transferencias canceladas e inconsistentes. Cuando SCHEDULER_ENABLED es true, Lerian STA las elimina cuando su último cambio de estado tiene más de 7 días (SCHEDULER_QUARANTINE_RETENTION_DAYS).
  • Retención entrante. Una política de ciclo de vida en el bucket controla cuánto tiempo permanecen los archivos entrantes.

Conciliación y contingencia

Lerian STA concilia al nivel de granularidad de una transferencia por número de protocolo de BACEN. En el descubrimiento, el número de protocolo es la clave de idempotencia: un protocolo ya registrado no crea una segunda transferencia. BACEN no ofrece una creación de protocolo idempotente. Una segunda creación puede duplicar el archivo en BACEN. Cuando una transferencia tiene una marca persistente de intento de creación, pero no tiene número de protocolo, Lerian STA la pone en Creación de protocolo no confirmada. Un operador debe conciliar ese intento. Lerian STA no repite la creación marcada.