Operating Plugin SISBAJUD

This page describes how to set up and run Plugin SISBAJUD. Operating Lerian SISBAJUD describes the Mensageria. How Plugin SISBAJUD runs orders describes what the plugin does with each order.

Institution setup

Register each institution on the Mensageria and on the plugin, with the same institutionId. Operating Lerian SISBAJUD describes the Mensageria request. POST /v1/institutions registers an institution on the plugin. The body has these fields:

Field	Meaning
`institutionId`	The UUID of the institution. Use the same value as on the Mensageria.
`connectorType`	The ledger connector. Set it to `midaz`.
`institutionCode`	The CNPJ root of the institution, 8 digits.
`enabled`	Whether the institution is active. Send `true`.
`connectorMetadata`	The Midaz configuration of the institution. The tables below describe it.
`retryPolicyConfig`	Optional. The retry policy, as JSON.
`branchFormat`	Optional. A Go RE2 regular expression, at most 64 characters, for the branch number that a court can name in a block restriction.
`accountFormat`	Optional. A Go RE2 regular expression, at most 64 characters, for the account number that a court can name in a block restriction. The plugin matches that number with `bankingDetails.account` of the CRM instruments, so the restriction needs `crmMode` `embedded`.

The request also creates the tokenization keyset and the audit keyset of the institution. A second request with the same institutionId returns 409. The plugin 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.

Connector metadata

Key	Required	Meaning
`organizations`	Yes	A list of `{organizationId, ledgers}` entries: the Midaz organizations that the plugin searches for the accounts of a subject. Without `ledgers`, the plugin searches every ledger of the organization.
`baseUrl`	Yes	The base URL of the Midaz ledger of the institution.
`authAddress`	When credentials are stored	The Access Manager address that issues the Midaz token of the institution.
`blockableBalances`	Yes	The Midaz balance keys that a block can use, for example `default`. These are balance keys, not the `available` or `onHold` amounts.
`blockableAccountTypes`	Yes	The account types that a block can use.
`salaryAccountTypes`	Yes	The account types that are salary accounts. Send `["NONE"]` when the institution has no salary account type.
`crmMode`	No	`legacy` or `embedded`. Without a value, the institution uses `MIDAZ_CRM_MODE`.
`crmBaseUrl`	No	The base URL of the standalone Midaz CRM, for `legacy`. With `embedded`, leave it empty: the plugin reads the CRM through `baseUrl`.
`permanentProducts`	To write permanent block results	The product catalog of the institution: `bankCode` and, in `types`, the product class and product code of each account type. Without it, the plugin holds the result of a later block and raises an alarm.
`executorLedger`	To run orders	The ledger where the plugin writes. The next table describes it.

Plugin SISBAJUD ledger

Key	Meaning
`organizationId`	The Midaz organization of the writes.
`ledgerId`	The Midaz ledger of the writes.
`asset`	Set it to `BRL`, exactly.
`judicialDepositAccountAlias`	The alias of the judicial deposit account. It must follow the Midaz alias rule.

The plugin refuses an institution request whose executorLedger is present and not valid, with 400. At startup, the plugin leaves out of its ledger routing an institution that has no valid executorLedger.

Connector credentials

PUT /v1/institutions/{institutionId}/connector-credentials writes the Midaz credentials of the institution:

ledger_client_id and ledger_client_secret are always required.
crm_client_id and crm_client_secret are required with crmMode legacy. With embedded, do not send them.

The plugin encrypts the credentials before it stores them. PATCH /v1/institutions/{institutionId} refuses a body with credentials. A new credential does not revoke the previous one at the Access Manager, so revoke it there. The plugin gets the Midaz token of the institution from {authAddress}/v1/login/oauth/access_token. When the institution has no stored credentials, the plugin sends no Authorization header to Midaz.

Change the configuration

PATCH /v1/institutions/{institutionId} changes the fields of the institution. A connectorMetadata in the body replaces the whole bag, except the stored credentials.
PUT /v1/institutions/{institutionId}/connector-config replaces connectorType and connectorMetadata. It keeps the stored credentials, and it refuses a body with credentials.
GET /v1/institutions/{institutionId} returns the configuration without the credentials.

The plugin reads the configuration of its institutions at startup. After you create an institution or change its configuration, restart the plugin.

Direct channel

How Plugin SISBAJUD runs orders describes the channel. To put an institution on it, send PUT /v1/institutions/{institutionId}/channel with DIRECT. Send MENSAGERIA to switch it back. The call answers 200 with changed false when the institution is on that channel already. The channel needs PLUGIN_AUTH_ENABLED on, one tenant, and the executor mode. The switch needs a person with the platform-admin role. The plugin refuses an application token and a tenant-scoped token with 403. The switch refuses with these codes:

SBJ-0040 / 422: the deployment is multi-tenant.
SBJ-0041 / 422: PLUGIN_AUTH_ENABLED is off.
SBJ-0042 / 422: the stored institution code is not the 8-character CNPJ root of the responsible grouping.
SBJ-0043 / 409: the institution has an open order, or a block that still holds money.
SBJ-0046 / 409: another switch won. Nothing moved. Send the request again.
SBJ-0060 / 409: another Plugin SISBAJUD installation owns the institution.

Erase a direct order

A platform administrator calls two routes to erase direct-channel orders. How Plugin SISBAJUD runs orders describes what an erase removes and what it keeps.

POST /v1/admin/direct/orders/{orderId}/erase erases one order. The body carries reason, ticket, and an optional note. reason is lgpd-subject-request or retention-purge. ticket is up to 64 characters, and note is up to 256. None of them may hold personal data. The answer is 200 with outcome erased, or noop when the order is already erased, and the number of rows erased.
POST /v1/admin/direct/purge lists the orders that can be erased now and changes nothing. The body carries reason, ticket, limit (1 to 100, and 100 when absent), and dryRun, which must be true. The answer holds orderIds, oldest first, asOf, and truncated. truncated is true when the list stopped before the plugin read every candidate.

The caller needs the token of a person, with no tenant. The plugin refuses an application token with 403 SBJ-0044, and a tenant-scoped token with 403 SBJ-0045. The routes exist only when the plugin runs in executor mode with PLUGIN_AUTH_ENABLED on. A multi-tenant deployment gets 422 SBJ-0059. An unknown order gets 404 SBJ-0015. The Plugin SISBAJUD error list lists SBJ-0056 to SBJ-0059. The gauge sisbajud_executor_direct_intake_purge_eligible counts the orders that can be erased now. The count is a lower bound. EXECUTOR_DIRECT_PURGE_REFRESH_EVERY sets how often the plugin counts.

Ledger routing

With SYSTEMPLANE_ENABLED on, the plugin serves the tenant documents of its accounting routes under /tenant-system. The plugin reads two of them: routing.organizations turns on accounting routes for each organization, and routing.ledger_bindings holds the routes. With SYSTEMPLANE_ENABLED off, the plugin writes without routes. routing.organizations accepts schemaVersion 1 or 2. At schemaVersion 2, each organization entry holds its own routes for each flow and its ledgers, the ledgers that post with those routes. The plugin then does not read routing.ledger_bindings, and a write to a ledger outside ledgers goes out without routes. GET /v1/admin/ledger-routing/preflight checks the routing configuration against the ledger of the institution. It writes nothing. A single-tenant plugin needs the institutionId query parameter. The report covers these checks:

The transaction routes and the operation routes exist, and they match the writes of the plugin.
A ledger that validates account types has sisbajud_block registered.
The judicial deposit account in executorLedger exists in the ledger and is not blocked.
At schemaVersion 2, the ledger of each write is in the ledgers of its organization. A ledger outside the list gets the issue ledger_not_listed, and the bindings document gets the state ignored.

The ready field reports whether the configuration is ready. The report shows the stored executorLedger. The running plugin uses the configuration that it read at startup.

Orders that need attention

Operation	What it returns
`GET /v1/institutions/{institutionId}/executor/failed-orders`	The order revisions that the plugin failed or abandoned. Each item has the order ID, the revision, a reason token, and the ID of its journal entry. It does not list the revisions whose outcome is not known yet.
`GET /v1/institutions/{institutionId}/executor/human-decisions`	The order revisions that the plugin stopped on a human decision.

Each human decision has a humanDisposition:

GAVE_UP: the plugin attempted no ledger write and answered EXECUTOR_GAVE_UP.
HELD_MONEY_MOVED: the plugin attempted a write. Money can have moved, and the plugin posted no answer.

The plugin also records a human decision when it parks a result after EXECUTOR_RESULT_MAX_ATTEMPTS failed posts, and when the ledger is down at the cut of an order. How Plugin SISBAJUD runs orders describes the cut.

Resolve a human decision

POST /v1/admin/executor/orders/{orderId}/revisions/{revision}/human-decision/resolution closes the open human decision of an order revision. The body carries the decisionId of the decision, a reason, and a resolution:

proven-no-effect: the ledger shows that the writes of the revision did not land.
effect-acknowledged: you accept the effect as it is. For a release whose parent block landed without its origin legs, send movedAmount and a transaction as ledgerEvidence.

ledgerEvidence is required when the revision is uncertain. The reason has at most 200 characters and no personal data. The plugin records the resolution and its audit entry in one transaction. It sends nothing to the court: the institution answers the court. The route needs PLUGIN_AUTH_ENABLED on and a person with the platform-admin role, and the plugin refuses an application token and a tenant-scoped token with 403. A multi-tenant deployment answers 422 SBJ-0053. The route can return these errors:

SBJ-0051 / 409: the revision has no open human decision to resolve here.
SBJ-0052 / 422: the resolution, the reason, or the evidence is not valid.
SBJ-0054 / 409: the journal shows that money moved, so proven-no-effect is refused. An acknowledgment is also refused while the write is undetermined.
SBJ-0055 / 409: the journal shows no landed effect, so there is nothing to acknowledge.
SBJ-0064 / 409: the evidence is a transaction that the plugin itself recorded for the revision.

Re-arm a parked result

POST /v1/admin/executor/orders/{orderId}/revisions/{revision}/results/{executionVersion}/rearm takes a result that the plugin parked at EXECUTOR_RESULT_MAX_ATTEMPTS. It sets the attempts back to 0, and the plugin posts the result again at once. The subsequent versions of the same order then follow. Send a reason of at most 200 characters, with no personal data. A result that is pending but not parked answers 200 with the outcome NOOP. The route needs PLUGIN_AUTH_ENABLED on and a person with the platform-admin role, and it works in a single-tenant deployment only.

SBJ-0048 / 409: the result is terminal. There is nothing to re-arm.
SBJ-0049 / 422: the reason is missing, blank, too long, or holds personal data.
SBJ-0050 / 422: the deployment is multi-tenant.

Resolve a parked permanent attempt

POST /v1/admin/executor/orders/{orderId}/permanent-attempts/{attemptId}/resolution resolves a parked attempt of a permanent block on the direct channel. It follows the rules of the human-decision resolution, and it needs the same role and PLUGIN_AUTH_ENABLED on. With proven-no-effect, the new credits of the block resume. With effect-acknowledged, the plugin counts movedAmount toward the order amount. It adds these errors:

SBJ-0061 / 409: the attempt is not parked, or the order is busy.
SBJ-0062 / 422: the acknowledged amount is above what the open permanent block still holds, or above the write that the plugin journaled for a closed one.

The Mensageria also lists the orders that the plugin gave up on. Operating Lerian SISBAJUD describes that list.

Credential key rotation

POST /v1/institutions/{institutionId}/security/credential-kek:rotate rotates the key that wraps the stored Midaz credentials of the institution. This key is not the institution-data key that the Mensageria rotates.

The rotation moves the stored credentials to the new key version. The credential values do not change. To replace a credential, use PUT /v1/institutions/{institutionId}/connector-credentials.
The response shows the previous and the new key version.
An institution with no stored credentials returns 404.
With STREAMING_ENABLED on, the rotation publishes a kek.rotated event with keyPurpose CREDENTIALS.
With AWS KMS in provided mode, the plugin does not rotate your key, and the operation returns 422.

The rotation can return these errors:

SBJ-0007 / 409: another rotation of the same institution is in progress. Send it again after that rotation ends.
SBJ-0012 / 409: nothing rotated, and the same request fails again.
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.
SBJ-0014 / 500: the key rotated, but a later step failed. Do not send the rotation again. Contact Lerian support.

With PLUGIN_AUTH_ENABLED off, the plugin does not serve this operation.

Audit verification

GET /v1/admin/audit/verify checks a range of the audit log of the institution, from fromIndex to toIndex. It does not decrypt any payload. It reports tampering and deleted entries.

Roles

Each operation needs one permission:

Operation	Permission
Create or update an institution, its connector configuration, or its credentials	`institution_config:write`
Read an institution, the failed orders, the human decisions, or the audit verification	`admin:read`
Credential key rotation	`credential_kek:rotate`
Ledger-routing preflight, and reads under `/tenant-system`	`tenant_policy:read`
Writes under `/tenant-system`	`tenant_policy:write`
Switch the channel of an institution	`institution_channel:write`
Re-arm a parked result	`executor_result:rearm`
Resolve a human decision or a parked permanent attempt	`executor_human_decision:resolve`
Erase a direct order	`direct_order_erasure:erase`
Preview the purge of direct orders	`direct_order_erasure:purge_preview`
Submit a direct order	`order:submit`
Read direct orders and results	`result:read`

The plugin declares the roles viewer, operator, investigator, cross-org-reader, admin, platform-admin, order-submitter, and result-reader. Each of the first six roles binds the group plugin-br-sisbajud-<role>-group, and admin also binds admin-group. The roles order-submitter and result-reader bind no group. Your M2M application holds admin, order-submitter, and result-reader. The admin role holds the permissions of the first five rows of the table. The viewer, operator, investigator, and cross-org-reader roles hold admin:read. The platform-admin role holds institution_channel:write, executor_result:rearm, executor_human_decision:resolve, direct_order_erasure:erase, direct_order_erasure:purge_preview, and the systemplane permissions of /system. No other role holds them. The plugin refuses an application token and a tenant-scoped token on the five platform operations with 403. The result-reader role holds result:read only. The order-submitter role holds order:submit, result:read, and metadata:read. Only a caller with metadata:read reads the order metadata on the direct reads.

The plugin on the Mensageria

The plugin calls the execution API of the Mensageria with its own M2M client. Set the client in MENSAGERIA_CLIENT_ID and MENSAGERIA_CLIENT_SECRET. The plugin gets its token from the Access Manager at PLUGIN_AUTH_HOST.

Listeners

The plugin has two listeners:

Main API, at SERVER_ADDRESS. Set it to :4029, the port that the image exposes. It serves the operations of the API reference. It also serves /health, /readyz, and /version. With SYSTEMPLANE_ENABLED on, it serves /system and /tenant-system. With SWAGGER_ENABLED on, it serves /swagger.
Webhook listener, at EXECUTOR_HUB_WEBHOOK_ADDRESS. The default is :9082. It has one route, POST at EXECUTOR_HUB_WEBHOOK_PATH, whose default is /v1/webhooks/hub. Expose this port to the Streaming Hub, and use your ingress address plus this path as the subscription URL.

The webhook listener has no application authentication. It accepts a delivery only when the HMAC signature verifies with the subscription secret or with the previous secret. Outside DEPLOYMENT_MODE=local, the listener needs its own TLS certificate. As an alternative, terminate TLS in front of it and set EXECUTOR_HUB_WEBHOOK_UPSTREAM_TLS_VALIDATED=true. /readyz includes two plugin checks:

hub_webhook: the webhook listener.
executor_institutions: the number of institutions that the plugin owns, and how many of them have ledger routing. This check does not fail readiness.

Deploy constraints

One tenant for each process. The plugin does not start when its tenant list holds more than one tenant.
Its own database. The plugin runs on its own empty PostgreSQL database. Its migrations refuse a database that already holds another migration history.
Restart after configuration changes. The plugin reads its institutions at startup.

Introduction

TED Lerian

TED JD

Pix Lerian

Pix JD

JD Courier

Pix BTG

Payments BTG

Plugin SISBAJUD

Operating Plugin SISBAJUD

Institution setup

Connector metadata

Plugin SISBAJUD ledger

Connector credentials

Change the configuration

Direct channel

Erase a direct order

Ledger routing

Orders that need attention

Resolve a human decision

Re-arm a parked result

Resolve a parked permanent attempt

Credential key rotation

Audit verification

Roles

The plugin on the Mensageria

Listeners

Deploy constraints

​Institution setup

​Connector metadata

​Plugin SISBAJUD ledger

​Connector credentials

​Change the configuration

​Direct channel

​Erase a direct order

​Ledger routing

​Orders that need attention

​Resolve a human decision

​Re-arm a parked result

​Resolve a parked permanent attempt

​Credential key rotation

​Audit verification

​Roles

​The plugin on the Mensageria

​Listeners

​Deploy constraints

Institution setup

Connector metadata

Plugin SISBAJUD ledger

Connector credentials

Change the configuration

Direct channel

Erase a direct order

Ledger routing

Orders that need attention

Resolve a human decision

Re-arm a parked result

Resolve a parked permanent attempt

Credential key rotation

Audit verification

Roles

The plugin on the Mensageria

Listeners

Deploy constraints