components: schemas: AuditVerifyResponse: additionalProperties: false properties: firstMissingIndex: format: int64 type: integer firstTamperedIndex: format: int64 type: integer fromIndex: format: int64 type: integer ok: type: boolean toIndex: format: int64 type: integer verified: format: int64 type: integer required: - ok - verified - fromIndex - toIndex type: object CreateInstitutionConfigRequest: additionalProperties: false properties: accountFormat: description: Regular expression (Go RE2 syntax, at most 64 characters) the institution DECLARES for the account number a court may indicate in a BLOQUEIO restriction. A value is proven invalid (TARGET_INVALID) only when it fails the WHOLE pattern; with no declaration nothing is ever proven invalid. Per institution and never defaulted. A pattern that does not compile, or is longer than 64 characters, is refused with 400. Absent or blank declares nothing. examples: - ^[0-9]{1,12}$ type: string branchFormat: description: Regular expression (Go RE2 syntax, at most 64 characters) the institution DECLARES for the branch (agência) number a court may indicate in a BLOQUEIO restriction. A value is proven invalid (TARGET_INVALID) only when it fails the WHOLE pattern; with no declaration nothing is ever proven invalid. Per institution and never defaulted. A pattern that does not compile, or is longer than 64 characters, is refused with 400. Absent or blank declares nothing. examples: - ^[0-9]{4}$ type: string connectorMetadata: description: "Connector-specific configuration bag: routing (baseUrl required; organizations[] required — the only targeting form, at least one entry naming a Midaz organizationId with optional ledgers; authAddress required when credentials are present; crmBaseUrl optional; crmMode optional — legacy|embedded, where absent/null/blank INHERITS the service-wide MIDAZ_CRM_MODE, an unrecognised value is rejected, and embedded requires an EMPTY crmBaseUrl), admission sets (blockableBalances/blockableAccountTypes), and the connector's credentials under their snake_case allowlisted names: ledger_client_id + ledger_client_secret are always required when credentials are present; crm_client_id + crm_client_secret are an all-or-nothing pair that is REQUIRED when the effective crmMode is legacy and FORBIDDEN when it is embedded (an embedded bag carries the ledger pair only, e.g. credentials:{ledger_client_id,ledger_client_secret}); the example shows the legacy four-field shape. blockableBalances carries the LEDGER's balance-key values (for Midaz: balanceKey, e.g. default/overdraft/a client-registered key) — NOT available/onHold, which are fields of a balance, not keys; the set is open and unvalidated, so a wrong value is not rejected, it only makes the admission gate never match. The presence of the credentials subtree selects authentication; there is no authMode. crmMode is a cleartext routing selector, never a credential: it is preserved on GET, which also echoes the RESOLVED surface as the read-only effectiveCrmMode. Credential values are sealed before the row is written and are never echoed." examples: - authAddress: https://auth.example.com baseUrl: https://midaz.example.com blockableAccountTypes: - deposit blockableBalances: - default credentials: crm_client_id: midaz-crm-client crm_client_secret: REPLACE_ME ledger_client_id: midaz-ledger-client ledger_client_secret: REPLACE_ME crmBaseUrl: https://midaz-crm.example.com crmMode: legacy organizations: - ledgers: - 019fcd7c-1e18-7034-8cd3-9e39c1759e41 organizationId: 019fcd7b-97df-71a5-8023-6eb3c661968b connectorType: description: The outbound connector type for this institution. examples: - midaz type: string enabled: description: Whether the connector configuration is active. examples: - true type: boolean institutionCode: description: The institution's BACEN CNPJ (8 digits) for return-file headers and file header validation. examples: - "12345678" type: string institutionId: description: The institution's unique identifier (UUID) that addresses the new configuration. examples: - 550e8400-e29b-41d4-a716-446655440000 type: string retryPolicyConfig: description: Operational retry policy (backoff/attempts) as arbitrary JSON. examples: - initialBackoffMs: 100 maxAttempts: 3 required: - institutionId - connectorType - institutionCode - enabled type: object Detail: additionalProperties: true properties: code: description: "Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN)." type: string detail: description: A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: "#/components/schemas/ErrorDetail" type: - array - "null" instance: description: A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: "#/components/schemas/Upstream" description: "RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one." type: object ErrorDetail: additionalProperties: false properties: location: description: Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object ErrorResponse: additionalProperties: false properties: code: type: string details: additionalProperties: {} type: object message: type: string title: type: string required: - code - title - message type: object InstitutionConfigResponse: additionalProperties: false properties: accountFormat: description: The regular expression the institution declared for the account number of a court-indicated target; omitted when none is declared. examples: - ^[0-9]{1,12}$ type: string branchFormat: description: The regular expression the institution declared for the branch (agência) number of a court-indicated target; omitted when none is declared. examples: - ^[0-9]{4}$ type: string connectorMetadata: description: Connector-specific configuration bag. The non-secret connector-owned keys (baseUrl, authAddress, crmBaseUrl, crmMode, organizations[], blockableBalances, blockableAccountTypes, salaryAccountTypes) are preserved verbatim; secret-bearing keys — the whole credentials subtree included — are removed and never echoed. blockableBalances carries the LEDGER's balance-key values — for Midaz, balanceKey (default/overdraft/a client-registered key), not the available/onHold fields of a balance. examples: - baseUrl: https://midaz.example.com blockableAccountTypes: - deposit blockableBalances: - default organizations: - ledgers: - 019fcd7c-1e18-7034-8cd3-9e39c1759e41 organizationId: 019fcd7b-97df-71a5-8023-6eb3c661968b connectorMetadataValid: description: Present and false only when the stored connector metadata cannot be parsed by its connector; absent otherwise. The offending value is never echoed. examples: - false readOnly: true type: boolean connectorType: description: The outbound connector type for this institution. examples: - midaz type: string createdAt: description: RFC 3339 creation timestamp (UTC). examples: - "2024-01-15T10:30:00Z" type: string effectiveCrmMode: description: "The CRM surface this institution resolves to (legacy|embedded): its own crmMode override when the connector metadata names one, the service-wide default otherwise. Derived and read-only; omitted when the connector metadata cannot be parsed." enum: - legacy - embedded examples: - legacy readOnly: true type: string enabled: description: Whether the connector configuration is active. examples: - true type: boolean institutionCode: description: The institution's BACEN CNPJ (8 digits) for return-file headers and file header validation. examples: - "12345678" type: string institutionId: description: The institution's unique identifier (UUID). examples: - 550e8400-e29b-41d4-a716-446655440000 type: string retryPolicyConfig: description: Operational retry policy (backoff/attempts) as arbitrary JSON. examples: - maxAttempts: 3 updatedAt: description: RFC 3339 last-update timestamp (UTC). examples: - "2024-01-15T12:00:00Z" type: string required: - institutionId - connectorType - institutionCode - enabled - createdAt - updatedAt type: object JournalFailedOrderItem: additionalProperties: false properties: evidence: $ref: "#/components/schemas/NoEffectEvidenceItem" description: No-effect evidence, present only when the journal proves every write failed before effect. journalEntryId: description: "Id of the execution-journal row the item was derived from: the revision's first failed row, or its abandoned row." examples: - 7d1e8400-e29b-41d4-a716-446655440000 type: string orderId: description: Order id. examples: - 660e8400-e29b-41d4-a716-446655440000 type: string orderRevision: description: Order revision (>= 1). examples: - 1 format: int64 type: integer reason: description: Closed-set v1 FailReason token; never raw ledger text. examples: - baseline-refused type: string required: - journalEntryId - orderId - orderRevision - reason type: object JournalHumanDecisionItem: additionalProperties: false properties: executionId: description: executionId of the given-up answer; present only for GAVE_UP. examples: - 9b2e8400-e29b-51d4-a716-446655440000 type: string executionVersion: description: executionVersion the given-up answer was enqueued with; present only for GAVE_UP once that result is in the outbox. examples: - 1 format: int64 type: integer humanDisposition: description: "GAVE_UP: the revision attempted no ledger write and was answered EXECUTOR_GAVE_UP (a next revision is a reopenable candidate). HELD_MONEY_MOVED: a write was attempted, money may have moved, no answer was posted." enum: - GAVE_UP - HELD_MONEY_MOVED examples: - GAVE_UP type: string journalEntryId: description: Id of the revision's human_decision journal row. examples: - 7d1e8400-e29b-41d4-a716-446655440000 type: string orderId: description: Order id. examples: - 660e8400-e29b-41d4-a716-446655440000 type: string orderRevision: description: Order revision (>= 1). examples: - 1 format: int64 type: integer required: - journalEntryId - orderId - orderRevision - humanDisposition type: object LedgerRoutingPreflightLine: additionalProperties: false properties: covered: description: "False when the flow or organization has no binding in the document. With schemaVersion 2: the organization routes the flow on a listed ledger." examples: - true type: boolean flowType: description: Ledger write the line covers; empty on the organization-level line. enum: - BLOCK - UNBLOCK - TRANSFER - "" examples: - BLOCK type: string ledgerId: description: Midaz ledger id; empty on the organization-level line. examples: - 0196a1b2-0000-7000-8000-0000000000b1 type: string ledgerValidateRoutes: description: The ledger's accounting.validateRoutes setting; absent when it was not read or the read failed. examples: - true type: boolean membership: description: Whether the operation routes were checked against the transaction route's member list. enum: - verified - unverified - not_applicable examples: - verified type: string mode: description: Binding mode; absent on coverage lines (covered=false). enum: - routes - omit examples: - routes type: string organizationId: description: Midaz organization id. examples: - 0196a1b2-0000-7000-8000-0000000000a1 type: string reasons: description: "Failed rules, in a fixed order; empty when the line passes. In executor mode (the plugin) the TRANSFER judicial account checks read the institution's connector_metadata.executorLedger instead of transfer.judicial_accounts: executor_judicial_account_missing or executor_judicial_account_invalid name its judicialDepositAccountAlias field (never the value), judicial_account_not_found that its account is not in the ledger, judicial_account_blocked that it is there but blocked (both refuse every plugin TRANSFER); executor_ledger_config_invalid and executor_institution_not_owned are carried by a line without flowType. With routing.organizations at schemaVersion 2, ledger_not_listed marks a ledger the connector writes to that is outside the organization's ledgers (its writes post without routes; with omit_on_validating_ledger the ledger refuses them), and binding_not_found on a listed ledger means the organization has no route for the flow." items: enum: - transaction_route_not_found - source_route_not_found - destination_route_not_found - midaz_unavailable - source_not_member - destination_not_member - transaction_route_extra_members - source_operation_type - destination_operation_type - source_direct_entry_missing - destination_direct_entry_missing - block_account_rule - deposit_alias_rule - binding_not_found - organization_not_bound - organization_not_configured - omit_on_validating_ledger - block_account_type_not_registered - judicial_account_not_configured - executor_judicial_account_missing - executor_judicial_account_invalid - judicial_account_not_found - judicial_account_blocked - executor_ledger_config_invalid - executor_institution_not_owned - organization_routes_disabled - ledger_not_listed - connector_unavailable - connector_not_midaz type: string type: - array - "null" routesEnabled: description: The organization's accountingRoutesEnabled in routing.organizations; false means its writes post without routes and its bindings are not used. examples: - true type: boolean verdict: description: Line outcome, by precedence unavailable > missing > mismatched > ok; not_applicable for omit bindings, unconfigured organizations and organizations without routes whose writes nothing refuses. enum: - ok - missing - mismatched - unavailable - not_applicable examples: - ok type: string required: - organizationId - ledgerId - flowType - covered - routesEnabled - verdict - membership - reasons type: object LedgerRoutingPreflightResponse: additionalProperties: false properties: documentState: description: "Shape of the tenant's ledger bindings document (tenant_policy/routing.ledger_bindings): sentinel is the unconfigured {} default, empty has no binding, bindings has at least one, invalid is a stored document that does not parse. ignored: routing.organizations is at schemaVersion 2, whose organizations carry their own routes, so this document is not read." enum: - sentinel - empty - bindings - invalid - ignored examples: - bindings type: string judicialAccountsDocumentState: description: "Shape of the tenant's transfer.judicial_accounts document, which holds the judicial deposit account of each organization and ledger for the legacy executor: sentinel is the {} default (no account), empty has no entry, entries has at least one, invalid does not parse. In executor mode the plugin does not use it, and invalid does not block the report." enum: - sentinel - empty - entries - invalid examples: - entries type: string lines: description: One line per binding, plus one per flow or organization the connector writes to that has no binding or judicial account (covered=false). No line carries an account alias. items: $ref: "#/components/schemas/LedgerRoutingPreflightLine" type: - array - "null" organizationsDocumentState: description: "Shape of the tenant's routing.organizations document, which enables accounting routes per organization: sentinel is the {} default (no organization uses routes), empty has no entry, entries has at least one, invalid does not parse." enum: - sentinel - empty - entries - invalid examples: - entries type: string ready: description: True only when the documents the run uses parse (in executor mode transfer.judicial_accounts is not used), every line is ok or not_applicable and, with routing.organizations at schemaVersion 1, when some organization has routes enabled, the bindings document carries bindings. examples: - false type: boolean required: - documentState - organizationsDocumentState - judicialAccountsDocumentState - ready - lines type: object NoEffectEvidenceItem: additionalProperties: false properties: intents: description: Every write of the revision, each failed before effect. items: $ref: "#/components/schemas/NoEffectIntentItem" type: - array - "null" required: - intents type: object NoEffectIntentItem: additionalProperties: false properties: baselineAvailable: description: Available balance of the blocking account read before the write (decimal string). examples: - "12.34" type: string baselineVersion: description: Balance version read before the write. examples: - 7 format: int64 type: integer failureClass: description: Before-effect class of the write's terminal row. examples: - before-effect type: string idempotencyKey: description: Idempotency key pairing the journaled intent with its failed row. examples: - 9f1c2d3e-key type: string required: - idempotencyKey - failureClass - baselineAvailable - baselineVersion type: object PageJournalFailedOrderItem: additionalProperties: false properties: data: items: $ref: "#/components/schemas/JournalFailedOrderItem" type: - array - "null" limit: format: int64 type: integer offset: format: int64 type: integer total: format: int64 type: integer required: - data - limit - offset - total type: object PageJournalHumanDecisionItem: additionalProperties: false properties: data: items: $ref: "#/components/schemas/JournalHumanDecisionItem" type: - array - "null" limit: format: int64 type: integer offset: format: int64 type: integer total: format: int64 type: integer required: - data - limit - offset - total type: object PatchInstitutionConfigRequest: additionalProperties: false properties: accountFormat: description: Regular expression (Go RE2 syntax, at most 64 characters) the institution DECLARES for the account number a court may indicate in a BLOQUEIO restriction. A value is proven invalid (TARGET_INVALID) only when it fails the WHOLE pattern; with no declaration nothing is ever proven invalid. Per institution and never defaulted. A pattern that does not compile, or is longer than 64 characters, is refused with 400. Omitted leaves the stored declaration unchanged; an empty string clears it. examples: - ^[0-9]{1,12}$ type: string branchFormat: description: Regular expression (Go RE2 syntax, at most 64 characters) the institution DECLARES for the branch (agência) number a court may indicate in a BLOQUEIO restriction. A value is proven invalid (TARGET_INVALID) only when it fails the WHOLE pattern; with no declaration nothing is ever proven invalid. Per institution and never defaulted. A pattern that does not compile, or is longer than 64 characters, is refused with 400. Omitted leaves the stored declaration unchanged; an empty string clears it. examples: - ^[0-9]{4}$ type: string connectorMetadata: description: "Connector-specific configuration bag. When present, replaces the entire bag wholesale, with ONLY the connector-owned credentials subtree carried over when omitted. baseUrl, organizations[] and authAddress are NOT carried over, so a replacing bag must re-supply baseUrl and organizations[] (both always required) and authAddress (required whenever credentials remain, supplied or carried), or the write is rejected. A credentials subtree in the patched bag is REFUSED with 400: credentials are written only by PUT /v1/institutions/{institutionId}/connector-credentials. Omitting credentials leaves the stored ones untouched (they are carried over). There is no authMode. crmMode is part of the replaced bag like any other key: a patched bag that omits it drops the override and the institution falls back to inheriting MIDAZ_CRM_MODE. Omit this field entirely to leave the stored bag untouched — an explicitly supplied null decodes to the same absent pointer and is likewise a no-op on this column, not a request to clear it (true of every field of this body, since they are all pointers)." examples: - authAddress: https://auth.example.com baseUrl: https://midaz.example.com blockableAccountTypes: - deposit blockableBalances: - default crmBaseUrl: https://midaz-crm.example.com crmMode: legacy organizations: - ledgers: - 019fcd7c-1e18-7034-8cd3-9e39c1759e41 organizationId: 019fcd7b-97df-71a5-8023-6eb3c661968b connectorType: description: The outbound connector type. Omitted fields are left unchanged. examples: - midaz type: string enabled: description: Whether the connector configuration is active. Omitted leaves the flag unchanged; explicitly false disables it. examples: - false type: boolean institutionCode: description: The institution's BACEN CNPJ (8 digits). When present, replaces the stored value. examples: - "12345678" type: string retryPolicyConfig: description: Operational retry policy as arbitrary JSON. When present, replaces the stored value. examples: - maxAttempts: 5 type: object PutConnectorConfigRequest: additionalProperties: false properties: connectorMetadata: description: "The connector's NON-SECRET configuration bag. REPLACES the stored bag wholesale (baseUrl and organizations[] always required; authAddress whenever credentials are stored), while the stored sealed credentials subtree is PRESERVED untouched. A credentials subtree, or any secret-bearing key (secret, token, password, api key, client id, ...) at any depth, is refused with 400 before any write: credentials are written only by PUT /v1/institutions/{institutionId}/connector-credentials." examples: - authAddress: https://auth.example.com baseUrl: https://midaz.example.com blockableAccountTypes: - deposit blockableBalances: - default crmBaseUrl: https://midaz-crm.example.com organizations: - ledgers: - 019fcd7c-1e18-7034-8cd3-9e39c1759e41 organizationId: 019fcd7b-97df-71a5-8023-6eb3c661968b connectorType: description: The outbound connector type. Replaces the stored value; an unknown type is refused with 400. examples: - midaz minLength: 1 type: string required: - connectorType - connectorMetadata type: object PutConnectorCredentialsRequest: additionalProperties: false properties: credentials: additionalProperties: type: string description: The connector's credentials under their snake_case allowlisted names (ledger_client_id, ledger_client_secret, crm_client_id, crm_client_secret). Sealed under a fresh data key before the row is written and never echoed. Rotating does NOT revoke the previous credential upstream. examples: - crm_client_id: midaz-crm-client crm_client_secret: REPLACE_ME ledger_client_id: midaz-ledger-client ledger_client_secret: REPLACE_ME minProperties: 1 type: object required: - credentials type: object RotateInstitutionKekResponse: additionalProperties: false properties: institutionId: description: The institution the rotation targeted. examples: - 44444444-4444-4444-4444-444444444444 type: string newKekVersion: description: The newly active KEK version. examples: - v3 type: string previousKekVersion: description: The KEK version that was active before the rotation. examples: - v2 type: string rewrapStatus: description: The rewrap progress status (e.g. IN_PROGRESS). examples: - IN_PROGRESS type: string rotatedAt: description: The RFC3339 timestamp the rotation committed. examples: - "2026-06-08T12:00:00Z" type: string required: - institutionId - newKekVersion - previousKekVersion - rotatedAt - rewrapStatus type: object RotateKEKRequest: additionalProperties: false properties: reason: description: Optional operator-supplied free-text reason for the rotation (sealed verbatim into the audit payload). examples: - scheduled_annual_rotation type: string type: object Upstream: additionalProperties: false properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http info: description: API for the Lerian SISBAJUD executor, which runs judicial orders on Midaz. It covers institution and Midaz connector configuration, orders that need attention, ledger-routing checks, credential key rotation and audit verification. title: Lerian SISBAJUD Executor API version: 1.0.0 openapi: 3.1.0 paths: /v1/admin/audit/verify: get: description: Re-verifies a contiguous slice of the caller institution's append-only audit log by leaf index, without decrypting any payload. Returns a tamper / internal-deletion report. The institution is derived from the validated identity, never from the body or path. operationId: verify-audit-trail parameters: - description: Zero-based leaf index of the first event to verify (required). explode: false in: query name: fromIndex required: true schema: description: Zero-based leaf index of the first event to verify (required). examples: - "0" type: string - description: Zero-based leaf index of the last event to verify (required). explode: false in: query name: toIndex required: true schema: description: Zero-based leaf index of the last event to verify (required). examples: - "99" type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/AuditVerifyResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Verify audit trail integrity (admin) tags: - Admin x-mint: href: /pt/reference/rails/sisbajud/executor/verify-audit-trail-integrity-admin /v1/admin/ledger-routing/preflight: get: description: "Checks the caller tenant's ledger routing documents against the institution's ledger. For every organization with accounting routes enabled (routing.organizations): transaction and operation routes exist, the legs are members of the transaction route, their operation types, direct entries and account rules match, a ledger that validates account types has the block account type registered, and each flow of every configured ledger has a binding. An organization without routes is checked the same way, so it can be fixed before routes are turned on, but its lines are not_applicable unless its writes are refused without routes too (organization_routes_disabled). With routing.organizations at schemaVersion 2 the routes come from each organization's own routes for every ledger it lists, a target ledger outside its ledgers is reported with ledger_not_listed, and routing.ledger_bindings is not read (documentState ignored). Every TRANSFER, with or without routes, needs a judicial deposit account: transfer.judicial_accounts for the legacy executor; in executor mode (the plugin) the institution's connector_metadata.executorLedger.judicialDepositAccountAlias, whose account must exist, unblocked, in the executor ledger. The executor-mode report reflects the STORED executorLedger; the running plugin keeps the one it loaded at boot until it restarts. The report never carries an account alias. The route is read-only: it never writes a document nor the ledger. Single-tenant (MULTI_TENANT_ENABLED=false) the institution is the required institutionId query parameter, with auth on or off, and the documents are the instance's single-tenant ones. Multi-tenant the tenant and institution are the validated token's tenantId, never the request; an institutionId that differs from it is refused with 403. Requires tenant_policy:read." operationId: get-ledger-routing-preflight parameters: - description: Institution to preflight (UUID). Required single-tenant (MULTI_TENANT_ENABLED=false), where one instance hosts many institutions. Multi-tenant the institution is the validated token's tenantId; when sent it must equal that tenant, otherwise the request is refused with 403. explode: false in: query name: institutionId schema: description: Institution to preflight (UUID). Required single-tenant (MULTI_TENANT_ENABLED=false), where one instance hosts many institutions. Multi-tenant the institution is the validated token's tenantId; when sent it must equal that tenant, otherwise the request is refused with 403. examples: - 0196a1b2-0000-7000-8000-000000000001 type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/LedgerRoutingPreflightResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Preflight the tenant's ledger routing configuration (admin) tags: - Ledger Routing x-mint: href: /pt/reference/rails/sisbajud/executor/preflight-the-tenant-s-ledger-routing-configuration-admin /v1/institutions: post: description: "Creates a new institution configuration (create-only; 409 if one already exists for the id) and provisions its tokenization PRF + audit MAC keysets in the same flow. The institution id is supplied in the request body. Invalid input is refused with 400 SBJ-0001, including an empty or malformed institutionCode and a branchFormat/accountFormat that does not compile or is longer than 64 characters. A key that is not the one the key registry records (the institution's key alias resolves to another key, or the registry records no ACTIVE key) maps to 409 SBJ-0012 and changes nothing: do not retry. A key being provisioned by another request, or a key registry that cannot be read, maps to 503 (retryable). 401 and 403 come from the /v1 auth chain and 429 from the rate limiter, as an application/json ErrorResponse; 413 has the two shapes described on the credentials KEK rotation route." operationId: create-institution-config requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateInstitutionConfigRequest" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/InstitutionConfigResponse" description: Created "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" description: Unauthorized "403": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" description: Forbidden "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "413": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Request Entity Too Large "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "429": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" description: Too Many Requests "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: Create institution config and provision keys tags: - Institution x-mint: href: /pt/reference/rails/sisbajud/executor/create-institution-config-and-provision-keys /v1/institutions/{institutionId}: get: description: Returns the institution's configuration as a safe metadata view (the credentials reference and any other secret material are omitted). The institution is addressed by the path id. operationId: get-institution-config parameters: - description: The institution's unique identifier (UUID). in: path name: institutionId required: true schema: description: The institution's unique identifier (UUID). examples: - 550e8400-e29b-41d4-a716-446655440000 type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/InstitutionConfigResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Get institution config by id tags: - Institution x-mint: href: /pt/reference/rails/sisbajud/executor/get-institution-config-by-id patch: description: "Applies a partial update (connectorType/institutionCode/retryPolicyConfig/connectorMetadata/branchFormat/accountFormat/enabled) to an existing institution configuration addressed by the path id. connectorMetadata, when present, replaces the entire bag wholesale. Invalid input is refused with 400 SBJ-0001, including a branchFormat/accountFormat that does not compile or is longer than 64 characters, and a merged configuration left without a valid institutionCode. Returns 404 when the institution has no configuration. A key that is not the one the key registry records (the institution's key alias resolves to another key, or the registry records no ACTIVE key) maps to 409 SBJ-0012 and changes nothing: do not retry. A key being provisioned by another request, or a key registry that cannot be read, maps to 503 (retryable). 401 and 403 come from the /v1 auth chain and 429 from the rate limiter, as an application/json ErrorResponse; 413 has the two shapes described on the credentials KEK rotation route." operationId: patch-institution-config parameters: - description: The institution's unique identifier (UUID). in: path name: institutionId required: true schema: description: The institution's unique identifier (UUID). examples: - 550e8400-e29b-41d4-a716-446655440000 type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/PatchInstitutionConfigRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/InstitutionConfigResponse" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" description: Unauthorized "403": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "413": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Request Entity Too Large "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "429": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" description: Too Many Requests "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: Update institution config by id tags: - Institution x-mint: href: /pt/reference/rails/sisbajud/executor/update-institution-config-by-id /v1/institutions/{institutionId}/connector-config: put: description: "Replaces the connector type and the non-secret connector configuration of an existing institution. The stored sealed credentials are preserved untouched; a body carrying credential material is refused with 400 before any write (credentials are written only by PUT /v1/institutions/{institutionId}/connector-credentials). The connector cache is invalidated on success. Returns 404 when the institution has no configuration. A key that is not the one the key registry records (the institution's key alias resolves to another key, or the registry records no ACTIVE key) maps to 409 SBJ-0012 and changes nothing: do not retry. A key being provisioned by another request, or a key registry that cannot be read, maps to 503 (retryable). 401 and 403 come from the /v1 auth chain and 429 from the rate limiter, as an application/json ErrorResponse; 413 has the two shapes described on the credentials KEK rotation route." operationId: put-institution-connector-config parameters: - description: The institution's unique identifier (UUID). in: path name: institutionId required: true schema: description: The institution's unique identifier (UUID). examples: - 550e8400-e29b-41d4-a716-446655440000 type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/PutConnectorConfigRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/InstitutionConfigResponse" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" description: Unauthorized "403": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "413": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Request Entity Too Large "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "429": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" description: Too Many Requests "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: Replace the institution's connector configuration tags: - Institution x-mint: href: /pt/reference/rails/sisbajud/executor/replace-the-institution-s-connector-configuration /v1/institutions/{institutionId}/connector-credentials: put: description: "Writes (or rotates) the connector credentials of an existing institution: the credentials subtree of connector_metadata is replaced, sealed under a fresh data key, audited as a credential rotation, and never echoed; every other metadata key is kept as stored. This is the ONLY credential write path: PATCH /v1/institutions/{institutionId} refuses a credentials subtree with 400. Returns 404 when the institution has no configuration. A key that is not the one the key registry records (the institution's key alias resolves to another key, or the registry records no ACTIVE key) maps to 409 SBJ-0012 and changes nothing: do not retry. A key being provisioned by another request, or a key registry that cannot be read, maps to 503 (retryable). 401 and 403 come from the /v1 auth chain and 429 from the rate limiter, as an application/json ErrorResponse; 413 has the two shapes described on the credentials KEK rotation route." operationId: put-institution-connector-credentials parameters: - description: The institution's unique identifier (UUID). in: path name: institutionId required: true schema: description: The institution's unique identifier (UUID). examples: - 550e8400-e29b-41d4-a716-446655440000 type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/PutConnectorCredentialsRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/InstitutionConfigResponse" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" description: Unauthorized "403": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "413": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Request Entity Too Large "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "429": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" description: Too Many Requests "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: Write the institution's connector credentials tags: - Institution x-mint: href: /pt/reference/rails/sisbajud/executor/write-the-institution-s-connector-credentials /v1/institutions/{institutionId}/executor/failed-orders: get: description: Returns the institution-scoped paginated list of order revisions the executor failed or abandoned, read from its execution journal. Each item names the journal row it was derived from and a closed-set reason; uncertain revisions are not listed. operationId: list-executor-failed-orders parameters: - description: The institution's unique identifier (UUID). in: path name: institutionId required: true schema: description: The institution's unique identifier (UUID). examples: - 550e8400-e29b-41d4-a716-446655440000 type: string - description: Maximum items per page. explode: false in: query name: limit schema: description: Maximum items per page. examples: - 50 format: int64 type: integer - description: Pagination offset. explode: false in: query name: offset schema: description: Pagination offset. examples: - 0 format: int64 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/PageJournalFailedOrderItem" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: List executor failed orders tags: - Executor x-mint: href: /pt/reference/rails/sisbajud/executor/list-executor-failed-orders /v1/institutions/{institutionId}/executor/human-decisions: get: description: Returns the institution-scoped paginated list of order revisions the executor stopped on a human decision, read from its execution journal. GAVE_UP items attempted no ledger write and carry the executionId and executionVersion of the given-up answer; HELD_MONEY_MOVED items attempted a write and carry neither. Another institution gets an empty page. operationId: list-executor-human-decisions parameters: - description: The institution's unique identifier (UUID). in: path name: institutionId required: true schema: description: The institution's unique identifier (UUID). examples: - 550e8400-e29b-41d4-a716-446655440000 type: string - description: Maximum items per page. explode: false in: query name: limit schema: description: Maximum items per page. examples: - 50 format: int64 type: integer - description: Pagination offset. explode: false in: query name: offset schema: description: Pagination offset. examples: - 0 format: int64 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/PageJournalHumanDecisionItem" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: List executor human decisions tags: - Executor x-mint: href: /pt/reference/rails/sisbajud/executor/list-executor-human-decisions /v1/institutions/{institutionId}/security/credential-kek:rotate: post: description: "Rotates the key that wraps this institution's stored connector credentials — a DIFFERENT key from the institution-data KEK governing PII, whose rotation is owned by the Lerian SISBAJUD Mensageria. The Transit key advances and the stored credentials envelope is rebound to the new version; no credential is decrypted and no credential VALUE changes, so a leaked client_secret is NOT invalidated by this call (rotate the material itself with PUT /v1/institutions/{institutionId}/connector-credentials, and revoke it upstream). rewrapStatus reports whether the stored envelope was rebound or the row carried no sealed subtree to rebind. An institution that has never stored a connector credential has no credentials KEK and maps to 404, not to a rotation. Code SBJ-0007 is a 409 a retry resolves: a contended same-institution rotation (retry once it completes) or a key registry this request reconciled or that changed while it was being reconciled (below); every other 409 below carries code SBJ-0012 (rotation not retryable; see detail). Any failure after the key rotated (reading the new version, recording it in the key registry, loading the configuration, rewrapping or persisting the envelope, including a concurrent change to this institution's connector configuration that wins the envelope write; the envelope still decrypts under the previous version) maps to 500 with code SBJ-0014 (rotation committed but a follow-up step failed; do not retry). Before the rotation, an ACTIVE key-registry version behind the key service's is reconciled by the request itself (recorded with a SYSTEM audit event) and the call maps to 409 (SBJ-0007) with nothing rotated: retry (if the registry or the live key version changed during that reconciliation, also 409 SBJ-0007: retry); a version ahead of the key service's, or one that is not readable, maps to 409 (SBJ-0012) with nothing rotated: do not retry. With KMS_AWS_KEY_MODE=managed, a key alias that no longer resolves to the key the registry records also maps to 409 (not retryable): nothing is rotated or written. So does a rewrap whose key is not the one the key registry records (the alias resolves to another key, or the registry records no ACTIVE key); a key registry that cannot be read before any key is used maps to 503 (retryable). A recorded key reference that cannot be verified (a legacy label or an unknown format) also maps to 409, before any key-service call; so does a definitive key-service refusal (access denied, a disabled key, a key state that does not allow rotation, or the key's exhausted on-demand rotation quota), naming the reason. A key-service throttle or outage before the rotation request was sent maps to 503 (retryable); a failure once the rotation request may have reached the key service (a timeout, a 5xx, a conflict, a dropped connection) maps to 500 with code SBJ-0013 (rotation outcome unknown; do not retry; the next rotation request reconciles the key registry). An unknown institution maps to 404. A committed-but-unaudited rotation maps to 500 with code SBJ-0014 (non-retryable; escalate). Every 500 body is the scrubbed internal error: the code carries the meaning. With KMS_PROVIDER=aws and KMS_AWS_KEY_MODE=provided the key is customer-provided and its rotation is owned by the key custodian: the call maps to 422 (SBJ-0006) and changes nothing — no lock, no audit, no KMS call. That refusal precedes any institution lookup, so in that mode an unknown institution, or one without a credentials KEK, also gets 422 rather than 404. A body of 1 MiB (1,048,576 bytes, the operation's body limit) or more maps to 413 as application/problem+json (SBJ-0010); only a body over HTTP_BODY_LIMIT_BYTES (100 MiB by default) is refused earlier by the server's body limit, as a 413 application/json ErrorResponse, so both media types are declared for 413. 401 and 403 come from the /v1 auth chain and 429 from the rate limiter (SBJ-0009), each as an application/json ErrorResponse; that chain can also answer 500 or 503 (for example when the authorization or tenant backend is unavailable) in the same ErrorResponse shape, while the 500 and 503 documented below are the handler's application/problem+json responses." operationId: rotate-institution-credentials-kek parameters: - description: The institution's unique identifier (UUID) whose connector-credentials KEK is rotated. in: path name: institutionId required: true schema: description: The institution's unique identifier (UUID) whose connector-credentials KEK is rotated. examples: - 44444444-4444-4444-4444-444444444444 type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/RotateKEKRequest" responses: "200": content: application/json: schema: $ref: "#/components/schemas/RotateInstitutionKekResponse" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" description: Unauthorized "403": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "413": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Request Entity Too Large "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "429": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" description: Too Many Requests "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable summary: Rotate an institution's connector-credentials KEK tags: - Security x-mint: href: /pt/reference/rails/sisbajud/executor/rotate-an-institution-s-connector-credentials-kek security: - BearerAuth: [] servers: - url: https://api.example.com description: Replace the example host with the URL provided during environment onboarding. tags: - description: "Institution configuration lifecycle: create (with key provisioning), read, and partial update of a connector configuration addressed by institution id." name: Institution - description: "Rotation of the key that wraps an institution's stored connector credentials, addressed by institution id." name: Security - description: "Admin API: audit-trail integrity verification." name: Admin