Saltar al contenido principal
Esta página describe cómo operar la Mensageria. Operar Lerian SISBAJUD executor describe el executor.

​
Instituciones

POST /v1/institutions registra una institución en la Mensageria. El cuerpo tiene estos campos: La solicitud crea el keyset de tokenización y el keyset de auditoría de la institución. Una segunda solicitud con el mismo institutionId devuelve 409. PATCH /v1/institutions/{institutionId} cambia institutionCode, retryPolicyConfig o enabled.

​
Registra la institución en los dos componentes

Registra cada institución en la Mensageria y en el executor:
  1. Envía POST /v1/institutions a la Mensageria con el institutionId de la institución y "enabled": true.
  2. Envía POST /v1/institutions al executor con el mismo institutionId y "enabled": true. El cuerpo del executor también lleva la configuración de su conector de Midaz y acepta los campos opcionales branchFormat y accountFormat. Operar Lerian SISBAJUD executor describe esta solicitud.
El executor se registra como dueño de la institución, a partir de su propia identidad M2M (EXECUTOR_M2M_SUBJECT). Ningún campo de la solicitud define el dueño, y un PATCH no lo cambia. El executor escribe en el ledger solo para las instituciones de las que es dueño.

​
Un cliente por instalación

Cada instalación de la Mensageria atiende a un cliente. Una instalación puede tener muchas instituciones.

​
Órdenes que necesitan atención

GET /v1/institutions/{institutionId}/orders y GET /v1/institutions/{institutionId}/files listan las órdenes y los archivos. Las operaciones de detalle devuelven una orden o un archivo.

​
Ventanas de respuesta

SISBAJUD define el plazo de la respuesta de bloqueo según la hora de envío de cada remesa. Una remesa enviada hasta las 13:00 BRT vence a las 19:00 BRT del mismo día. Una remesa enviada después de las 13:00 BRT vence a las 12:00 BRT del siguiente día hábil. La Mensageria genera archivos de respuesta en intervalos, no en horarios fijos. Configura RETURN_FILE_GENERATION_SCAN_INTERVAL e INFORMATION_RETURN_FILE_GENERATION_SCAN_INTERVAL para que cada ciclo termine dentro de la ventana de BACEN. Los dos valores son en segundos, y los dos tienen un valor predeterminado de una hora.

​
Correcciones de archivos de respuesta

  • POST /v1/institutions/{institutionId}/return-file/generate ejecuta una generación de archivo de respuesta ahora.
  • POST /v1/institutions/{institutionId}/return-file/{id}/reconsolidate libera las órdenes de un archivo de respuesta FAILED, para que una generación posterior pueda responderlas. El archivo sigue en FAILED.
  • POST /v1/institutions/{institutionId}/return-file/{id}/resolve-transmission aplica una corrección a un envío que ningún camino automático puede terminar: probe_now, attach_transfer, force_fail o cancel_now. El reason va a la pista de auditoría tal como lo escribes, así que no pongas datos personales ni montos en él.
force_fail solo sigue cuando el último intento de envío tiene al menos 5 minutos y Lerian STA no tiene una transferencia del archivo que todavía pueda llegar al BACEN. En caso contrario, devuelve 422. Cada corrección devuelve 503 cuando la Mensageria no puede acceder a Lerian STA.

​
Rotación de claves

La rotación de claves se ejecuta por institución:
  • Clave de cifrado de claves (KEK). POST /v1/institutions/{institutionId}/security/kek:rotate rota la KEK de la institución. La respuesta muestra la versión anterior y la nueva versión de la KEK. La rotación publica un evento kek.rotated. Con KEK_REWRAP_BACKFILL_ENABLED activado, un job en segundo plano vuelve a envolver las claves de datos con la nueva versión de la KEK. Viene desactivado de forma predeterminada. Con AWS KMS en el modo provided, la Mensageria no rota tu clave, y la operación devuelve 422.
  • Keyset de tokenización. POST /v1/institutions/{institutionId}/security/keyset:rotate agrega una nueva clave primaria al keyset de tokenización de la institución. Una institución sin keyset activo devuelve 422.
Una rotación de KEK puede devolver estos errores:
  • SBJ-0007 / 409: otra rotación de la misma clave para la misma institución está en curso. Envíala de nuevo después de que esa rotación termine.
  • SBJ-0012 / 409: no se rotó nada, y la misma solicitud falla otra vez.
  • SBJ-0005 / 404: la institución no tiene clave.
  • SBJ-0008 / 503: el gestor de claves falló antes de la rotación. Envíala de nuevo más tarde.
  • SBJ-0013 / 500: el resultado de la rotación no se conoce. No envíes la rotación de nuevo. La Mensageria reconcilia su registro de claves cuando se reinicia.
  • SBJ-0014 / 500: la clave se rotó, pero un paso posterior falló. No envíes la rotación de nuevo. Contacta al soporte de Lerian.

​
Protección de datos

  • Cifrado envelope. La Mensageria cifra los campos sensibles con AES-256-GCM bajo una clave de datos (DEK). Una KEK envuelve la clave de datos, en HashiCorp Vault Transit o en AWS KMS. Los datos autenticados adicionales vinculan cada texto cifrado con su institución, tabla, registro y campo.
  • Tokenización buscable. Un blind index guarda un token del CPF/CNPJ y del número de proceso. El token viene de una clave HMAC-SHA256 de la institución. Permite la búsqueda por coincidencia exacta.
  • Lecturas enmascaradas. El detalle de la orden y el detalle del archivo enmascaran los campos sensibles, salvo que quien llama tenga admin:read_pii. La Mensageria registra en la pista de auditoría una lectura de orden en texto claro.
  • Pista de auditoría. GET /v1/institutions/{institutionId}/audit/verify verifica un rango del log de auditoría por índice de hoja, sin descifrar ningún payload. Informa las alteraciones y las entradas eliminadas.
  • LGPD. POST /v1/institutions/{institutionId}/lgpd/requests abre una solicitud de acceso o portabilidad. .../resolve registra la decisión. GET /v1/institutions/{institutionId}/lgpd/subject-data exporta los registros de un titular de datos.

​
Roles

La Mensageria declara cuatro roles de negocio: operator, investigator, compliance-officer y admin. Cada permiso va a estos roles: Un rol vale para todas las instituciones de la instalación. La Mensageria no tiene concesión por institución.

​
Superficie HTTP

Las órdenes llegan solo como archivos, así que ninguna operación acepta una orden. La API principal escucha en SERVER_ADDRESS. El valor predeterminado es :4031. Atiende estos grupos de operaciones:
  • Instituciones: crear, leer y actualizar.
  • Órdenes y archivos: listas, detalles, órdenes que necesitan atención, estado de SLA y estadísticas.
  • Verificación de auditoría.
  • Solicitudes LGPD.
  • Justificaciones de incumplimiento.
  • Correcciones de archivos de respuesta.
  • Rotación de claves.
  • Confirmación de dead letter de Lerian STA.
También atiende /health, /readyz, /version y las rutas de administración de Systemplane en /system. La API de ejecución tiene su propio listener. PLUGIN_AUTH_ENABLED debe ser true o false. La Mensageria acepta false solo cuando ENV_NAME es development, develop, dev, local o test, y DEPLOYMENT_MODE no es saas. Con false, las operaciones protegidas siguen exigiendo un bearer token. La Mensageria omite solo la verificación de Access Manager.