Skip to main content
This page describes how to run the Mensageria. Operating the Lerian SISBAJUD executor describes the executor.

​
Institutions

POST /v1/institutions registers an institution on the Mensageria. The body has these fields: The request creates the institution’s tokenization keyset and audit keyset. A second request with the same institutionId returns 409. PATCH /v1/institutions/{institutionId} changes institutionCode, retryPolicyConfig, or enabled.

​
Register the institution on both components

Register each institution on the Mensageria and on the executor:
  1. Send POST /v1/institutions to the Mensageria with the institution’s institutionId and "enabled": true.
  2. Send POST /v1/institutions to the executor with the same institutionId and "enabled": true. The executor’s body also carries its Midaz connector configuration, and it takes the optional fields branchFormat and accountFormat. Operating the Lerian SISBAJUD executor describes this request.
The executor records itself as the owner of the institution, from its own M2M identity (EXECUTOR_M2M_SUBJECT). No request field sets the owner, and a PATCH does not change it. The executor writes on the ledger only for the institutions it owns.

​
Tenant

A single-tenant Mensageria uses DEFAULT_TENANT_ID. The default is 11111111-1111-1111-1111-111111111111. One tenant can hold many institutions.

​
Orders that need attention

GET /v1/institutions/{institutionId}/orders and GET /v1/institutions/{institutionId}/files list the orders and the files. The detail operations return one order or one file.

​
Response windows

SISBAJUD sets the block-response deadline by the send time of each remittance. A remittance sent up to 13:00 BRT is due by 19:00 BRT the same day. A remittance sent after 13:00 BRT is due by 12:00 BRT the next business day. The Mensageria generates response files at intervals, not at fixed times. Set RETURN_FILE_GENERATION_SCAN_INTERVAL and INFORMATION_RETURN_FILE_GENERATION_SCAN_INTERVAL so that each cycle ends inside the BACEN window. Both values are in seconds, and both default to one hour.

​
Response-file remedies

  • POST /v1/institutions/{institutionId}/return-file/generate runs one response-file generation now.
  • POST /v1/institutions/{institutionId}/return-file/{id}/reconsolidate releases the orders of a FAILED response file, so that a later generation can answer them. The file stays FAILED.
  • POST /v1/institutions/{institutionId}/return-file/{id}/resolve-transmission applies one remedy to a submission that no automatic path can finish: probe_now, attach_transfer, force_fail, or cancel_now. The reason goes into the audit trail as written, so do not put personal data or amounts in it.

​
Key rotation

Key rotation runs per institution:
  • Key-encryption key (KEK). POST /v1/institutions/{institutionId}/security/kek:rotate rotates the institution’s KEK. The response shows the previous and the new KEK version. With HashiCorp Vault as the key provider, the rotation publishes a kek.rotated event. With KEK_REWRAP_BACKFILL_ENABLED on, a background job re-wraps the data keys under the new KEK version. It is off by default.
  • Tokenization keyset. POST /v1/institutions/{institutionId}/security/keyset:rotate adds a new primary key to the institution’s tokenization keyset. An institution with no active keyset returns 422.
A rotation returns SBJ-0007 / 409 when another rotation of the same key for the same institution is in progress. Send it again after that rotation ends. A rotation that returns SBJ-0002 / 500 can have committed: the key can already be at the new version. Do not send the rotation again, because a second request rotates the key again. Contact Lerian support.

​
Data protection

  • Envelope encryption. The Mensageria encrypts sensitive fields with AES-256-GCM under a data key (DEK). The institution’s KEK wraps the data key, in HashiCorp Vault Transit or AWS KMS. The additional authenticated data binds each ciphertext to its institution, table, record, and field.
  • Searchable tokenization. A blind index keeps a token of the CPF/CNPJ and of the process number. The token comes from an HMAC-SHA256 key of the institution. It supports exact-match search.
  • Masked reads. The order detail and the file detail mask sensitive fields unless the caller holds admin:read_pii. The Mensageria records a cleartext order read in the audit trail.
  • Audit trail. GET /v1/institutions/{institutionId}/audit/verify checks a range of the audit log by leaf index without decrypting any payload. It reports tampering and deleted entries.
  • LGPD. POST /v1/institutions/{institutionId}/lgpd/requests opens an access or portability request. .../resolve records the decision. GET /v1/institutions/{institutionId}/lgpd/subject-data exports the records of a data subject.

​
Roles

The Mensageria declares four business roles: operator, investigator, compliance-officer, and admin. Each permission goes to these roles: A role applies to every institution of the tenant. The Mensageria has no per-institution grant. The executor uses a separate M2M role, which Integrating with Lerian SISBAJUD describes.

​
HTTP surface

Orders arrive only as files, so no operation accepts an order. The main API listens at SERVER_ADDRESS. The default is :4031. It serves these operation groups:
  • Institutions: create, read, and update.
  • Orders and files: lists, details, orders that need attention, SLA status, and statistics.
  • Audit verification.
  • LGPD requests.
  • Non-compliance justifications.
  • Response-file remedies.
  • Key rotation.
  • Lerian STA dead-letter acknowledgement.
It also serves /health, /readyz, /version, and the Systemplane admin routes under /system. The execution API has its own listener. PLUGIN_AUTH_ENABLED must be true or false. The Mensageria accepts false only when ENV_NAME is development, develop, dev, local, or test, and DEPLOYMENT_MODE is not saas. With false, protected operations still require a bearer token. The Mensageria skips only the Access Manager check.