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

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 the Mensageria and on Plugin SISBAJUD

Register each institution on the Mensageria and on Plugin SISBAJUD:
  1. Send POST /v1/institutions to the Mensageria with the institution’s institutionId and "enabled": true.
  2. Send POST /v1/institutions to Plugin SISBAJUD with the same institutionId and "enabled": true. Plugin SISBAJUD’s body also carries its Midaz connector configuration, and it takes the optional fields branchFormat and accountFormat. Operating Plugin SISBAJUD describes this request.
Plugin SISBAJUD 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. Plugin SISBAJUD writes on the ledger only for the institutions it owns.

One client per installation

Each Mensageria installation serves one client. One installation 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 runs the block-response scan only when RETURN_FILE_GENERATION_ENABLED is true, and the information-response scan only when INFORMATION_RETURN_FILE_GENERATION_ENABLED is true. Both default to false. The scans run 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 a FAILED or REJECTED response file, and the file keeps its status. For a 5302 or 5312, it releases the orders, so that a later generation can answer them. For an AJUD302-B, it gives the captures back to the queue, and the answer says how many. A delivered AJUD302-B that BACEN never answered in full is given up by this call: it becomes FAILED, and its captures return. The replacement for the same origin remittance goes out only after the next business day following the give-up has ended. The calendar counts weekends only. An AJUD303B or AJUD304B that arrives in that time belongs to the given-up file, and one that arrives later belongs to the replacement. The AJUD304B refuses a line that repeats an earlier sequence of the same block with error 04, so the court does not take a capture twice. At worst, the 04 shows as a rejected capture that you justify, with no separate notice to the court.
  • 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.
force_fail goes ahead only when the last submission attempt is at least 5 minutes old and Lerian STA holds no transfer of the file that can still reach BACEN. Otherwise it returns 422. Every remedy returns 503 when the Mensageria cannot reach Lerian STA.

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. 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. With AWS KMS in provided mode, the Mensageria does not rotate your key, and the operation returns 422.
  • 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 KEK rotation can return these errors:
  • SBJ-0007 / 409: another rotation of the same key for the same institution is in progress. Send it again after that rotation ends.
  • SBJ-0012 / 409: nothing rotated, and the same request fails again.
  • SBJ-0005 / 404: the institution has no key.
  • SBJ-0008 / 503: the key manager failed before the rotation. Send it again later.
  • SBJ-0013 / 500: the outcome of the rotation is not known. Do not send the rotation again. The Mensageria reconciles its key registry when it restarts.
  • SBJ-0014 / 500: the key rotated, but a later step failed. Do not send the rotation again. Contact Lerian support.

Data protection


  • Envelope encryption. The Mensageria encrypts sensitive fields with AES-256-GCM under a data key (DEK). A 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 list of failed orders masks the amount of a rejected capture on the same terms. 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 installation. The Mensageria has no per-institution grant.

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.