components: schemas: Amount: additionalProperties: false properties: currency: description: Currency; BRL only. enum: - BRL examples: - BRL type: string value: description: Decimal amount with two places, non-negative. examples: - "10000.00" pattern: ^(0|[1-9]\d{0,16})\.\d{2}$ type: string required: - value - currency type: object 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 BalancesView: additionalProperties: false properties: remaining: $ref: "#/components/schemas/Amount" description: Remaining amount. remainingSalary: $ref: "#/components/schemas/Amount" description: Remaining amount in salary accounts. required: - remaining - remainingSalary type: object BlockKey: additionalProperties: false properties: blockReiteration: description: "REITERACAO_BLOQUEIO: 2 digits; 00 = original, 01+ = reiterated or cancelled." examples: - "00" pattern: ^[0-9]{2}$ type: string blockSequence: description: "SEQUENCIAL_BLOQUEIO: 5 digits, zero-padded." examples: - "00001" pattern: ^[0-9]{5}$ type: string orderCancelled: description: "ORDEM_CANCELADA: true = cancelled (T), false = reiterated (F). Required when blockReiteration is not 00; with 00 it is ignored (the original block)." examples: - false type: boolean protocol: description: "PROTOCOLO: 14 digits, zero-padded." examples: - "20261027000123" pattern: ^[0-9]{14}$ type: string required: - protocol - blockSequence - blockReiteration type: object BlockSpec: additionalProperties: false properties: blockingAccount: description: Account the block is restricted to. Personal data. maxLength: 32 type: string blockingBranch: description: Branch the block is restricted to. Personal data. maxLength: 16 type: string blockingInstitutionCnpj: description: 8-char CNPJ root the block is restricted to. pattern: ^[A-Z0-9]{8}$ type: string minimumAmount: $ref: "#/components/schemas/Amount" description: No block below this amount; must be less than or equal to amount (422 invalid-order otherwise). monitoringUntil: description: End of the monitoring window. format: date-time type: string permanent: description: "Permanent block: SISBAJUD INDICADOR_BLOQUEIO_PERMANENTE \"P\" (without permanentUntil) or \"D\" (with permanentUntil); false or absent is \"T\". Its creation (the original block and its reiterations) is refused with 422 permanent-block-not-supported while the deployment does not take permanent blocks; its cancellation and its UNBLOCK/TRANSFER are taken." type: boolean permanentUntil: description: Deadline of a "D" permanent block (DATA_PRAZO_BLOQUEIO_PERMANENTE); only with permanent true (422 invalid-order otherwise). format: date-time type: string salaryAccountAllowed: description: Whether a salary account may be blocked; absent is silence and never means allowed. type: boolean 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 DirectOrderEraseRequest: additionalProperties: false properties: note: description: Optional note (at most 256 characters, no personal data). Stored sealed in the audit trail; never echoed when refused. examples: - DPO request routed by the institution. type: string reason: description: "Required: lgpd-subject-request (a data subject's request) or retention-purge (retention ended)." examples: - lgpd-subject-request type: string ticket: description: "Required: the request id the erase is filed under (at most 64 characters, no personal data). Stored sealed in the audit trail." examples: - LGPD-2026-0042 type: string type: object DirectOrderEraseResponse: additionalProperties: false properties: erasedAt: description: Instant of the request (UTC). format: date-time type: string erasedBy: description: Subject of the platform administrator who made the request. type: string orderId: description: The direct order's identifier. type: string outcome: description: "erased: this request erased the order. noop: it was already erased (audited again)." enum: - erased - noop type: string rows: $ref: "#/components/schemas/DirectOrderEraseRows" description: Rows shredded beyond the intake. required: - orderId - outcome - rows - erasedBy - erasedAt type: object DirectOrderEraseRows: additionalProperties: false properties: dailyAttempt: description: permanent_block_daily_attempt rows erased. format: int64 type: integer executionOrder: description: execution_order revisions erased. format: int64 type: integer judicialBlock: description: judicial_order_block rows erased. format: int64 type: integer permanentBlock: description: permanent_block_order rows erased. format: int64 type: integer required: - executionOrder - permanentBlock - dailyAttempt - judicialBlock type: object DirectPurgePreviewRequest: additionalProperties: false properties: dryRun: description: "Must be true: the preview only lists the eligible orders; each erase is a separate request." examples: - true type: boolean limit: description: Most orders listed, 1 to 100; 0 or absent lists up to 100. examples: - 100 format: int64 type: integer reason: description: "Required: retention-purge or lgpd-subject-request." examples: - retention-purge type: string ticket: description: "Required: the request id (at most 64 characters, no personal data)." examples: - PURGE-2026-10 type: string type: object DirectPurgePreviewResponse: additionalProperties: false properties: asOf: description: Instant the eligibility was read (UTC). format: date-time type: string dryRun: description: "Always true: nothing was erased." type: boolean orderIds: description: Direct orders eligible for erasure as of asOf, oldest eligibility first. items: type: string type: - array - "null" truncated: description: "True when the listing stopped at its read bound before it found limit orders or ran out of candidates: more eligible orders may exist. Each listed order is one the erase would accept (eligibility and the money rule)." type: boolean required: - orderIds - dryRun - asOf - truncated 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 HumanDecisionLedgerEvidence: additionalProperties: false properties: kind: description: "Required. What the reference points to: transaction (a ledger transaction) or balance (a balance query)." examples: - transaction type: string observedAt: description: "Required. RFC 3339 date-time at which the ledger was read: at most 2 minutes ahead of the server clock, and not before the revision's latest moved-needs-human request (otherwise 422 SBJ-0052)." examples: - "2026-10-29T11:30:00Z" type: string reference: description: "Required. Opaque reference to the ledger query: 1 to 128 characters of letters, digits and . _ : / -, starting with a letter or digit, with at least one letter. No spaces, no amounts, no personal data (CPF, CNPJ, judicial process numbers)." examples: - midaz-tx-3f9a1c7e type: string type: object HumanDecisionResolutionRequest: additionalProperties: false properties: decisionId: description: "Required. Journal row id of the human-decision request being answered: the revision's LATEST request. A request raised again after it makes this one stale (409 SBJ-0051), so a retry never resolves an occurrence nobody reviewed." examples: - 7d1e8400-e29b-41d4-a716-446655440000 type: string ledgerEvidence: $ref: "#/components/schemas/HumanDecisionLedgerEvidence" description: "Required when the revision is UNCERTAIN: the executor raised moved-needs-human and the journal holds no posted row nor a moving effect, so only the ledger tells whether money moved (missing: 422 SBJ-0052). Optional otherwise, validated whenever present, and it never changes which resolution the journal admits. Stored only in the sealed audit row; never echoed, logged nor traced. On an acknowledgement, a transaction reference is also journaled as the ledger transaction the human read." movedAmount: description: "The TOTAL, a decimal string above zero (e.g. 150.00), that left the block account for this leg, including any effect the executor already read: an effect of the executor on the same release counts once, never added to it. Required, with a transaction ledgerEvidence, to acknowledge the effect of a release (UNBLOCK or TRANSFER) whose parent block landed without its origin legs: the executor could not plan that return, and the block counts as released only when the acknowledged amounts equal what it holds. Refused anywhere else (422 SBJ-0052); a transaction ledgerEvidence that is the executor's own effect is refused (409 SBJ-0064). Journaled; never echoed, logged nor audited." examples: - "150.00" type: string reason: description: "Required. Short justification or ticket reference (at most 200 characters, no personal data: CPF, CNPJ, judicial process numbers). Never echoed." examples: - "OPS-4512: ledger statement reviewed with the institution." type: string resolution: description: "Required. proven-no-effect: the ledger evidence shows the revision's writes never landed (refused with 409 SBJ-0054 when the journal shows money moved). effect-acknowledged: the effect is acknowledged as it is (refused with 409 SBJ-0055 when the journal shows no landed effect)." examples: - effect-acknowledged type: string type: object HumanDecisionResolutionResponse: additionalProperties: false properties: keys: description: How many keys the resolution was journaled under by this request (the revision's unresolved request keys; 0 on NOOP). format: int64 type: integer orderId: description: The executor order's identifier. type: string outcome: description: "RESOLVED: the resolution was journaled now. NOOP: the same resolution was already journaled under every key; nothing changed." enum: - RESOLVED - NOOP type: string resolution: description: The resolution journaled, as requested. type: string resolvedAt: description: Instant of the request (UTC). format: date-time type: string resolvedBy: description: Subject of the platform administrator who made the request. type: string revision: description: The order revision. format: int64 type: integer required: - orderId - revision - resolution - outcome - keys - resolvedBy - resolvedAt type: object InfoSpec: additionalProperties: false properties: account: description: Account filter. Personal data. maxLength: 32 type: string balanceLimit: $ref: "#/components/schemas/Amount" description: Balance ceiling of the answer. branch: description: Branch filter. Personal data. maxLength: 16 type: string closedRelationships: description: Include closed relationships. type: boolean searchAddresses: description: Whether the court asks for addresses. type: boolean searchBalance: description: Return blockable balances. type: boolean searchBranchesAccounts: description: Whether the court asks for the relation of branches and accounts. type: boolean targetInstitutionCnpj: description: 8-char CNPJ root the request targets. pattern: ^[A-Z0-9]{8}$ type: string type: object InformationBalancesView: additionalProperties: false properties: blockableSalary: $ref: "#/components/schemas/Amount" description: Blockable amount in salary accounts. blockableTotal: $ref: "#/components/schemas/Amount" description: Total blockable amount. required: - blockableTotal - blockableSalary type: object InstitutionChannelResponse: additionalProperties: false properties: changed: description: False when the institution was already on the requested channel. type: boolean changedAt: description: Instant of the request (UTC). format: date-time type: string changedBy: description: Subject of the platform administrator who made the request. type: string channel: description: The channel now in charge. type: string institutionId: description: The institution's unique identifier. type: string previousChannel: description: The channel before the request (equal to channel when nothing changed). type: string required: - institutionId - channel - previousChannel - changed - changedBy - changedAt 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 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 LATEST human decision request: the decisionId the resolution route binds to (after a re-raise, the new request). A revision with no request (only a parked result) carries its first 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 MovementKey: additionalProperties: false properties: movementReiteration: description: "REITERACAO_DESBLOQUEIO / REITERACAO_TRANSFERENCIA: 2 digits, always required (never inferred); 00 = original movement, 01+ = a reiteration of the movement, answered from the original movement and never executed again." examples: - "00" pattern: ^[0-9]{2}$ type: string movementSequence: description: "SEQUENCIAL_DESBLOQUEIO (UNBLOCK) or SEQUENCIAL_TRANSFERENCIA (TRANSFER): 5 digits, zero-padded." examples: - "00001" pattern: ^[0-9]{5}$ type: string required: - movementSequence - movementReiteration 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 NormativeKey: additionalProperties: false properties: blockReiteration: description: "REITERACAO_BLOQUEIO: 2 digits; 00 = original, 01+ = reiterated or cancelled." examples: - "00" pattern: ^[0-9]{2}$ type: string blockSequence: description: "SEQUENCIAL_BLOQUEIO: 5 digits, zero-padded." examples: - "00001" pattern: ^[0-9]{5}$ type: string protocol: description: "PROTOCOLO: 14 digits, zero-padded." examples: - "20261027000123" pattern: ^[0-9]{14}$ type: string required: - protocol - blockSequence - blockReiteration type: object OrderPage: additionalProperties: false properties: items: description: Orders whose externalReference matches. items: $ref: "#/components/schemas/OrderView" type: - array - "null" nextCursor: description: Opaque cursor of the next page; null at the end. type: - string - "null" required: - items - nextCursor type: object OrderView: additionalProperties: false properties: clientOrderId: description: Client key. type: string cutPassedAtReceipt: description: The cut was past at receipt. type: boolean deadlineAt: description: Raw deadline of the latest revision. format: date-time type: string deadlinePassedAtReceipt: description: deadlineAt was past at receipt. type: boolean executionState: description: "Execution state of the latest revision: ACCEPTED before any result, otherwise the state of latestResult." enum: - ACCEPTED - EXECUTING - MONITORING - RESOLVED - INDETERMINATE - AWAITING_RECONCILIATION type: string externalReference: description: externalReference; null when absent. type: - string - "null" institutionCode: description: Registered code (CNPJ root) of the institution. type: string latestResult: $ref: "#/components/schemas/ResultItem" description: Latest execution version of the latest revision; null before any. metadata: additionalProperties: description: Value of at most 256 bytes (UTF-8). type: string description: Metadata of the latest revision. Omitted entirely when the caller lacks metadata:read; null when absent or erased. type: - object - "null" metadataErasedAt: description: When the metadata was erased; omitted otherwise. format: date-time type: string operation: description: Operation. enum: - BLOCK - UNBLOCK - TRANSFER - INFO - INTERRUPT type: string orderId: description: Order id. format: uuid type: string orderRevision: description: Highest accepted revision. format: int64 type: integer originalOrderId: description: "orderId of the original order this one is derived from: set on the UNBLOCK derived from a cancellation (it points at the original block); null otherwise." format: uuid type: - string - "null" parked: description: "Whether the plugin parked the order after exhausting its delivery attempts (raised with an alarm). Parking is outside executionState: a parked order keeps its executionState." type: boolean parkedAt: description: When the order was parked; null when not parked. format: date-time type: - string - "null" permanentUntil: description: Validity of the permanent block; null otherwise. format: date-time type: - string - "null" receivedAt: description: "The receipt of this revision (the latest accepted one). The term of a permanent block is reported by permanentBlock.endsAt, never derived from this field." format: date-time type: string required: - orderId - clientOrderId - orderRevision - operation - executionState - externalReference - institutionCode - deadlineAt - permanentUntil - deadlinePassedAtReceipt - cutPassedAtReceipt - receivedAt - originalOrderId - parked - parkedAt - latestResult 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 PermanentAttemptLeg: additionalProperties: false properties: accountId: description: Required. Ledger account id of one of the write's origin legs, as journaled. examples: - 0193b2c4-acc1 type: string amount: description: Required. Decimal above zero moved from that leg, at most its journaled amount. examples: - "10.00" type: string type: object PermanentAttemptResolutionRequest: additionalProperties: false properties: allocation: description: "Optional per-leg allocation of movedAmount: required when a partial amount of a write of several origin legs is acknowledged (422 SBJ-0052, LEG_ALLOCATION_REQUIRED); it must name the write's own legs once each, each at most its amount, summing to movedAmount (LEG_ALLOCATION_INVALID)." items: $ref: "#/components/schemas/PermanentAttemptLeg" type: - array - "null" ledgerEvidence: $ref: "#/components/schemas/HumanDecisionLedgerEvidence" description: "Required: a parked write is uncertain by definition. Its kind is transaction on effect-acknowledged (the reference is journaled as the ledger transaction). observedAt must not be before the attempt's write. Stored only in the sealed audit row." movedAmount: description: "Required with effect-acknowledged, refused otherwise: the decimal amount above zero the write moved. At most the permanent's remaining while it is open, at most the write's journaled amount always (422 SBJ-0062). Never echoed, logged nor audited." examples: - "30.00" type: string reason: description: Required. Short justification or ticket (at most 200 characters, no personal data). Never echoed. examples: - "OPS-4512: ledger statement reviewed." type: string resolution: description: "Required. proven-no-effect: the ledger shows the parked write never landed; the account is released and new credits resume (the attempt stays FAILED). effect-acknowledged: the write landed movedAmount; it counts toward the permanent block and the attempt becomes BLOCKED." examples: - effect-acknowledged type: string type: object PermanentAttemptResolutionResponse: additionalProperties: false properties: attemptId: description: The permanent attempt's identifier. type: string orderId: description: The executor order's identifier. type: string outcome: description: "RESOLVED: journaled now. NOOP: the same resolution was already journaled; nothing changed." enum: - RESOLVED - NOOP type: string resolution: description: The resolution journaled, as requested. type: string resolvedAt: description: Instant of the request (UTC). format: date-time type: string resolvedBy: description: Subject of the platform administrator who made the request. type: string required: - orderId - attemptId - resolution - outcome - resolvedBy - resolvedAt type: object PermanentBlockView: additionalProperties: false properties: accumulatedAmount: $ref: "#/components/schemas/Amount" description: Total blocked by the order so far, across its reiteration revisions. closeReason: description: Why it closed; null while ACTIVE. Amounts already blocked stay blocked on INTERRUPTED and EXPIRED. enum: - TARGET_REACHED - EXPIRED - INTERRUPTED - RELEASED - CANCELLED type: - string - "null" endsAt: description: "Informative: the term in force, min(DATA_PRAZO, the order's receipt + 1 year). The source of the term: a client reads it here, never derives it from receivedAt." format: date-time type: string status: description: ACTIVE while the permanent keeps blocking new credits; CLOSED afterwards. enum: - ACTIVE - CLOSED type: string targetAmount: $ref: "#/components/schemas/Amount" description: The amount the permanent block pursues. required: - status - closeReason - accumulatedAmount - targetAmount - endsAt type: object ProductDetail: additionalProperties: false properties: account: description: CONTA of the product. Personal data. examples: - "123456" type: string accountCheckDigit: description: "DAC of the account; \"0\" when the account has none (layout: zeros). Personal data." examples: - "0" type: string bankCode: description: "CODIGO_BANCO: the executing institution's COMPE code." examples: - "001" type: string blockedAmount: $ref: "#/components/schemas/Amount" description: "VALOR_BLOQUEADO: what this subsequent block took from the product." branch: description: AGENCIA of the product. Personal data. examples: - "0001" type: string command: description: "Layout command: INCLUDE (I) on the product's first report for the order, UPDATE (A) afterwards." enum: - INCLUDE - UPDATE type: string demandDeposit: description: "Norm field IND_DEPOSITO_VISTA (T = true, F = false): required on INCLUDE (I), omitted on UPDATE (A)." type: boolean detailSequence: description: "SEQUENCIAL_PRODUTO_DETALHE: the product's detail sequence within the order (>= 1); kept by every later UPDATE (A) detail." examples: - "1" pattern: ^[1-9][0-9]*$ type: string executingInstitutionCnpj: description: 8-char CNPJ root of the executing institution. examples: - "12345678" pattern: ^[A-Z0-9]{8}$ type: string indivisibleProduct: description: "Norm field IND_PRODUTO_INDIVISIVEL (T = true, F = false): required on INCLUDE (I), omitted on UPDATE (A)." type: boolean liquidityTermDays: description: "PRAZO_LIQUIDEZ (norm field): calendar days to redeem the product (>= 0; 0 = immediate): required on INCLUDE (I), omitted on UPDATE (A)." format: int64 minimum: 0 type: integer nonPricedProduct: description: "Norm field IND_PRODUTO_N_PRECIFICADO (T = true, F = false): required on INCLUDE (I), omitted on UPDATE (A)." type: boolean nonSellableProduct: description: "Norm field IND_PRODUTO_N_VENDAVEL (T = true, F = false): required on INCLUDE (I), omitted on UPDATE (A)." type: boolean productClass: description: "CLASSE_PRODUTO: required on INCLUDE (I), omitted on UPDATE (A)." type: string productCode: description: "CODIGO_PRODUTO: required on INCLUDE (I), omitted on UPDATE (A)." type: string salaryAccount: description: Whether the product is a salary account. type: boolean salaryAmount: $ref: "#/components/schemas/Amount" description: The salary part of blockedAmount; null when not a salary account. termDeposit: description: "Norm field IND_DEPOSITO_PRAZO (T = true, F = false): required on INCLUDE (I), omitted on UPDATE (A)." type: boolean required: - detailSequence - command - bankCode - branch - account - accountCheckDigit - blockedAmount - salaryAccount - salaryAmount - executingInstitutionCnpj 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 PutInstitutionChannelRequest: additionalProperties: false properties: channel: description: "Target channel: DIRECT or MENSAGERIA (exact, upper case)." examples: - DIRECT type: string required: - channel type: object ResultItem: additionalProperties: false description: "One item of the results feed. Kind RESULT is one execution version of one revision. Kind PERMANENT_BLOCK is one subsequent block of a permanent order. The fields products and permanentBlock are omitted when absent. Clients MUST ignore items whose kind they do not recognise. terminal=true always arrives on a RESULT: every close of a permanent order is reported by a close RESULT on that order. terminal=true arrives on the LAST RESULT item of the order: the outcome no longer changes. PERMANENT_BLOCK items may follow it (money landing after the close, a held block republished after the close); they never reopen the permanent. Read past the terminal RESULT: PERMANENT_BLOCK items can follow it. The feed does not signal human-decision holds." properties: appliedAmount: $ref: "#/components/schemas/Amount" description: Amount applied; null when none. appliedSalaryAmount: $ref: "#/components/schemas/Amount" description: Part of appliedAmount taken from salary accounts; null when not applicable. clientOrderId: description: Client key. type: string effect: description: Ledger effect. enum: - NONE - FULL - PARTIAL - INDETERMINATE type: string executionState: description: Lifecycle state. enum: - ACCEPTED - EXECUTING - MONITORING - RESOLVED - INDETERMINATE - AWAITING_RECONCILIATION type: string executionVersion: description: Version (>= 1); the highest executionVersion of the highest orderRevision wins. format: int64 type: integer informationBalances: $ref: "#/components/schemas/InformationBalancesView" description: "INFO: blockable total and blockable salary amounts; null otherwise." kind: description: "Item kind: an open string, deliberately not a closed enum. Known values: RESULT (one execution version) and PERMANENT_BLOCK (one subsequent block of a permanent order). Clients MUST ignore items whose kind they do not recognise." type: string occurredAt: description: When the version occurred. format: date-time type: string orderId: description: Order id. format: uuid type: string orderRevision: description: Revision the result is reported against. format: int64 type: integer originalOrderId: description: "orderId of the original order this one is derived from: set on the UNBLOCK derived from a cancellation (it points at the original block); null otherwise." format: uuid type: - string - "null" permanentBlock: $ref: "#/components/schemas/PermanentBlockView" description: "The permanent block's state after this version (a subsequent block, the INTERRUPT that stopped it, the TRANSFER that released it, or its expiry). The permanentBlock of a late item (published after later conclusions or after the close) reflects the current state of the permanent; the block's own amount is appliedAmount. Omitted when the order has no permanent state to report." products: description: "PERMANENT_BLOCK only: one entry per product the subsequent block hit (AJUD302-B detail record). Omitted when absent." items: $ref: "#/components/schemas/ProductDetail" type: - array - "null" reasonCode: description: Reason; null when absent. The client translates effect+reason to the court. enum: - NO_CLIENT - BLOCKED_TOTAL - NO_BALANCE - BLOCKED_PARTIAL - UNBLOCKED - NOTHING_TO_RELEASE - NO_BLOCK_FOUND - ORIGINAL_INVALID - TRANSFERRED - TRANSFERRED_PARTIAL - NOTHING_TO_TRANSFER - INFO_FULFILLED - INFO_NON_CLIENT - PARENT_UNRESOLVED - TARGET_NOT_HELD - TARGET_INVALID - DESTINATION_INVALID - BELOW_MINIMUM - EXECUTOR_GAVE_UP type: - string - "null" remainingBalances: $ref: "#/components/schemas/BalancesView" description: What remains blocked after this version (e.g. TRANSFER); null when not applicable. salaryAccount: description: Whether a salary account was reached; null when not applicable. type: - boolean - "null" terminal: description: "On a permanent order (permanentBlock present) it is false while the permanent is ACTIVE, even when RESOLVED: subsequent blocks follow as new versions; it is true once permanentBlock.status is CLOSED. Invariant: terminal=true always arrives on a RESULT item. When a permanent closes (TARGET_REACHED, EXPIRED, INTERRUPTED, RELEASED) its own order gets one close RESULT (no products, permanentBlock CLOSED, terminal true). terminal=true arrives on the LAST RESULT item of the order: the outcome no longer changes. PERMANENT_BLOCK items may follow it (money landing after the close, a held block republished after the close); they never reopen the permanent. Read past the terminal RESULT: PERMANENT_BLOCK items can follow it." type: boolean transferDeadline: description: "TRANSFER: civil date by which the transfer settles; null otherwise." format: date type: - string - "null" unblockBalances: $ref: "#/components/schemas/BalancesView" description: "UNBLOCK: what remains blocked in the parent after the release; null otherwise." required: - kind - orderId - clientOrderId - orderRevision - executionVersion - executionState - effect - reasonCode - appliedAmount - occurredAt - terminal - originalOrderId - salaryAccount - appliedSalaryAmount - unblockBalances - remainingBalances - transferDeadline - informationBalances type: object ResultPage: additionalProperties: false properties: items: description: Result versions in feed order. items: $ref: "#/components/schemas/ResultItem" type: - array - "null" nextCursor: description: Opaque cursor of the next page; null at the end. type: - string - "null" required: - items - nextCursor type: object ResultRearmRequest: additionalProperties: false properties: reason: description: "Required. Short justification (at most 200 characters, no personal data: CPF, CNPJ, judicial process numbers). Stored sealed in the audit trail; never echoed." examples: - Mensageria outage fixed; re-sending the parked result. type: string type: object ResultRearmResponse: additionalProperties: false properties: attemptsBefore: description: The row's attempts when the request read it. format: int64 type: integer executionVersion: description: The result's execution version. format: int64 type: integer orderId: description: The executor order's identifier. type: string outcome: description: "REARMED: attempts reset to 0, the drainer retries it now. NOOP: the result was pending but not parked; nothing changed." enum: - REARMED - NOOP type: string rearmedAt: description: Instant of the request (UTC). format: date-time type: string rearmedBy: description: Subject of the platform administrator who made the request. type: string revision: description: The order revision. format: int64 type: integer required: - orderId - revision - executionVersion - outcome - attemptsBefore - rearmedBy - rearmedAt 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 Subject: additionalProperties: false properties: document: description: CPF (11 digits) or CNPJ (14 alphanumeric; the full CNPJ also with CNPJ_ROOT). Personal data. examples: - "11144477735" pattern: ^[A-Z0-9]{11,14}$ type: string documentType: description: Kind of the document. CNPJ_ROOT is forbidden on INFO (422 invalid-order). enum: - CPF - CNPJ - CNPJ_ROOT examples: - CPF type: string required: - document - documentType type: object SubmitOrderBody: additionalProperties: false properties: amount: $ref: "#/components/schemas/Amount" description: Requested amount; required on BLOCK/UNBLOCK/TRANSFER, absent on INFO and INTERRUPT. block: $ref: "#/components/schemas/BlockSpec" description: BLOCK only (required). blockKey: $ref: "#/components/schemas/BlockKey" description: Normative key of this block (PROTOCOLO + SEQUENCIAL_BLOQUEIO + REITERACAO_BLOQUEIO) and its ORDEM_CANCELADA flag; required on BLOCK, absent otherwise. blockReiteration 00 is the original block; any other value is a reiteration (orderCancelled false) or a cancellation (orderCancelled true) of the original, never a new block. clientOrderId: description: Opaque client key of the order, unique per institution. MUST NOT contain personal data or judicial identifiers (CPF/CNPJ, process number, long digit runs). examples: - ord-7Q2K-b1 pattern: ^[A-Za-z0-9_.:-]{1,128}$ type: string deadlineAt: description: Final deadline of the initial 5302 answer to the court, raw (the plugin applies its margin once). Required on every operation, INFO included. A past deadline is accepted and signalled. examples: - "2026-10-28T20:00:00Z" format: date-time type: string externalReference: description: Client search key, not unique, set on revision 1 and immutable. MUST NOT contain personal data or judicial identifiers. examples: - REM-2026-10-22-A maxLength: 128 pattern: ^[A-Za-z0-9_.:-]{1,128}$ type: string info: $ref: "#/components/schemas/InfoSpec" description: INFO only (required). metadata: additionalProperties: type: string description: "Flat string map: <= 16 keys, key ^[A-Za-z0-9_.-]{1,64}$, value <= 256 bytes (UTF-8), total (keys + values) <= 4096 bytes. Sealed at rest; never logged." maxProperties: 16 type: object movementKey: $ref: "#/components/schemas/MovementKey" description: The movement's own key (SEQUENCIAL + REITERACAO of the unblock/transfer); required on UNBLOCK/TRANSFER, absent otherwise. movementReiteration 00 is the original movement; any other value is a reiteration of it, never a new movement. operation: description: "Operation. INTERRUPT (layout record \"10\") stops a permanent BLOCK (\"P\"/\"D\"): it carries parentClientOrderId and parentBlockKey only (no amount, block, transfer, info nor movementKey), has no key of its own, keeps what is already blocked and is never refused by the permanent-block policy; a parent that is not a permanent block is 422 invalid-order." enum: - BLOCK - UNBLOCK - TRANSFER - INFO - INTERRUPT examples: - BLOCK type: string orderRevision: description: Revision of the order (>= 1). The highest accepted revision wins. examples: - 1 format: int64 minimum: 1 type: integer parentBlockKey: $ref: "#/components/schemas/NormativeKey" description: "Normative key of the parent block, as the court cites it on the unblock/transfer/interrupt record; required on UNBLOCK/TRANSFER/INTERRUPT, absent otherwise. It is also the only key of an INTERRUPT (the record \"10\" carries the key of the permanent it stops). The plugin checks it against the parent named by parentClientOrderId: a divergent key is the same parent-not-in-custody 422 as an unknown parent (no oracle)." parentClientOrderId: description: clientOrderId of the parent BLOCK; required on UNBLOCK/TRANSFER/INTERRUPT, absent otherwise. Submit the child only after the parent's 202. pattern: ^[A-Za-z0-9_.:-]{1,128}$ type: string responsibleInstitutionCnpj: description: 8-char CNPJ root of the institution responsible for the answer. Compared exactly (no zero-padding) with the institution_code registered for the institution in the path, only for routing consistency and only after authorization; a mismatch, or an institution without a registered code, is 422 institution-mismatch. It is not an authorization check. examples: - "12345678" pattern: ^[A-Z0-9]{8}$ type: string scope: description: Reach of the order. enum: - AMPLO - POR_IF - POR_AGENCIA - DIRECIONADO examples: - AMPLO type: string subject: $ref: "#/components/schemas/Subject" description: Subject of the order. Personal data. transfer: $ref: "#/components/schemas/TransferSpec" description: TRANSFER only (required). required: - clientOrderId - orderRevision - operation - deadlineAt - subject - scope - responsibleInstitutionCnpj type: object SubmitOrderResponse: additionalProperties: false properties: clientOrderId: description: Echo of the client key. type: string cutPassedAtReceipt: description: The plugin's cut (deadlineAt minus margin) was already past when the order was received. type: boolean deadlinePassedAtReceipt: description: deadlineAt was already past when the order was received. type: boolean executionState: description: Execution state of the accepted revision; ACCEPTED means durably accepted and nothing executed yet. enum: - ACCEPTED - EXECUTING - MONITORING - RESOLVED - INDETERMINATE - AWAITING_RECONCILIATION type: string externalReference: description: Echo of the externalReference; null when absent. type: - string - "null" institutionCode: description: Registered code (CNPJ root) of the institution; the client answers the court for it. type: string orderId: description: Server-generated order id (UUIDv7). format: uuid type: string orderRevision: description: Accepted revision. format: int64 type: integer originalOrderId: description: "orderId of the original order this one is derived from: set on the UNBLOCK derived from a cancellation (it points at the original block); null otherwise." format: uuid type: - string - "null" receivedAt: description: "The receipt of this revision: when the plugin durably accepted the answered revision (the instant the deadline flags are measured at). The term of a permanent block is reported by permanentBlock.endsAt, never derived from this field." format: date-time type: string required: - orderId - clientOrderId - orderRevision - executionState - externalReference - institutionCode - deadlinePassedAtReceipt - cutPassedAtReceipt - receivedAt - originalOrderId type: object TransferSpec: additionalProperties: false properties: depositRevenueCode: description: Deposit revenue code. maxLength: 16 type: string judicialDepositType: description: Judicial deposit kind; absent = other. enum: - TRIBUTARIO - PREVIDENCIARIO type: string referenceNumber: description: Deposit reference number. maxLength: 32 type: string releaseRemainingBalance: description: Release what remains in the parent block after the transfer. type: boolean 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 Plugin SISBAJUD, 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: Plugin SISBAJUD 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: /en/reference/interfaces/plugin-sisbajud/verify-audit-trail-integrity-admin /v1/admin/direct/orders/{orderId}/erase: post: description: "Crypto-shreds one direct order: its intake (every revision's sealed body and DEK; clientOrderId and externalReference become keyed tokens, the normative keys stay so a resubmission is never a new order), its execution_order revisions and its block rows, in ONE transaction with the audit row (event LGPD_CRYPTO_ELIMINATION, entity EXECUTION_ORDER). If the audit write fails nothing is erased. The execution journal and the result outbox keep their pseudonymous residue (ids and amounts): an append-only accounting and audit record. A human platform-administrator action (direct_order_erasure:erase, never held by M2M): an application token (SBJ-0044) or a tenant-carrying token (SBJ-0045) is refused with 403. 200 outcome noop: already erased (audited again). 404 SBJ-0015: unknown order, or one of an institution this executor does not own. 409 SBJ-0056: not eligible (the purge-eligibility predicate, or a child whose parent is not erased). 409 SBJ-0057: permanent block in force, or its end unreadable. 422 SBJ-0058: reason, ticket or note invalid. 422 SBJ-0059: multi-tenant deployment." operationId: erase-direct-order parameters: - description: The direct order's identifier (UUID). in: path name: orderId required: true schema: description: The direct order's identifier (UUID). examples: - 0b9b7c2e-4f8a-4d3e-9a51-7c2d1e0f3a44 type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/DirectOrderEraseRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/DirectOrderEraseResponse" 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: Erase a direct order (LGPD) tags: - Direct Channel Administration x-mint: href: /en/reference/interfaces/plugin-sisbajud/erase-a-direct-order-lgpd /v1/admin/direct/purge: post: description: "Lists up to limit (at most 100) direct orders eligible for erasure as of now, in the institutions this executor owns, oldest eligibility first; the same predicate as the purge-eligible gauge, the money rule and the parent rule of the erase. A permanent block's permanentUntil lives only in its sealed body, so the erase may still refuse a listed permanent order (SBJ-0057). The preview is a dry run only: nothing is erased, and each erase is a separate POST .../orders/{orderId}/erase. A human platform-administrator action (direct_order_erasure:purge_preview): 403 SBJ-0044/SBJ-0045 for M2M or tenant-carrying tokens. 422 SBJ-0058: dryRun not true, limit out of range, reason or ticket invalid. 422 SBJ-0059: multi-tenant deployment." operationId: preview-direct-order-purge requestBody: content: application/json: schema: $ref: "#/components/schemas/DirectPurgePreviewRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/DirectPurgePreviewResponse" 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: Preview the direct order purge (dry run) tags: - Direct Channel Administration x-mint: href: /en/reference/interfaces/plugin-sisbajud/preview-the-direct-order-purge-dry-run /v1/admin/executor/orders/{orderId}/permanent-attempts/{attemptId}/resolution: post: description: "The audited resolution of a PARKED DIRECT permanent block attempt (its reactive write failed every retry, or its window passed, so its block account holds every new credit) of a single-tenant deployment (multi-tenant: 422 SBJ-0053). Declaring no effect releases the account: credits resume and the open-order probe lets the order go; the attempt stays FAILED. Acknowledging the effect journals movedAmount as the write's landed effect: it is added to the permanent's accumulated amount (the next credit blocks only the remainder; reaching the target closes the block) and the attempt becomes BLOCKED with its result. On a permanent already CLOSED the attempt is SKIPPED_CLOSED, nothing reopens, and closed_with_effect is alarmed. A human platform-administrator action (executor_human_decision:resolve): an application token (SBJ-0044) or a tenant-carrying token (SBJ-0045) is refused with 403. The journal rows, the attempt and the audit row commit in one transaction. 200 outcome NOOP: the same resolution was already journaled. 404: unknown attempt, or one of an institution this executor does not own. 409 SBJ-0061: not parked, or the order is busy. 409 SBJ-0054: the journal shows money moved. 409 SBJ-0055: already resolved as no effect. 422 SBJ-0052: invalid request (the reason is named in the answer, e.g. LEG_ALLOCATION_REQUIRED). 422 SBJ-0062: movedAmount above the cap." operationId: resolve-executor-parked-permanent-attempt parameters: - description: The executor order's identifier (UUID). in: path name: orderId required: true schema: description: The executor order's identifier (UUID). examples: - 0b9b7c2e-4f8a-4d3e-9a51-7c2d1e0f3a44 type: string - description: The parked permanent attempt's identifier (UUID). in: path name: attemptId required: true schema: description: The parked permanent attempt's identifier (UUID). examples: - 1d2e3f40-5a6b-4c7d-8e9f-0a1b2c3d4e5f type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/PermanentAttemptResolutionRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/PermanentAttemptResolutionResponse" 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: Resolve a parked DIRECT permanent attempt tags: - Executor x-mint: href: /en/reference/interfaces/plugin-sisbajud/resolve-a-parked-direct-permanent-attempt /v1/admin/executor/orders/{orderId}/revisions/{revision}/human-decision/resolution: post: description: "The audited MANUAL resolution path of a single-tenant deployment: the only route that resolves an executor human decision. A multi-tenant deployment answers 422 SBJ-0053 before any read and must use the audited manual procedure instead. ledgerEvidence is REQUIRED when the revision is UNCERTAIN, and never changes the answer on a proven revision. Journals a human platform administrator's resolution of the revision's open human decision under every write key of the revision (one row with no key when it wrote nothing), so the open-order probe stops counting it under HumanDecision. Nothing is sent to any channel: the answer to the court stays with the institution. decisionId binds the resolution to the request it answers (the revision's latest). A human platform-administrator action (executor_human_decision:resolve, never held by M2M): an application token (SBJ-0044) or a tenant-carrying token (SBJ-0045) is refused with 403. The rows and the audit row commit in one transaction. 200 outcome NOOP: the same resolution was already journaled. 409 SBJ-0051: no open human decision. 409 SBJ-0054: the journal contradicts the resolution (no effect declared on a PROVEN EFFECT revision, or an acknowledgment while the write is undetermined). 409 SBJ-0055: an acknowledgment on a PROVEN NO EFFECT revision. 409 SBJ-0064: an acknowledgment whose transaction ledgerEvidence is the executor's own effect (a transaction its recovery probe recorded for the revision); movedAmount is the total that left the block account. Each revision is classified, under the same locks as the write, by its journal evidence: PROVEN EFFECT (a posted row or a moving effect) admits only the acknowledgment; PROVEN NO EFFECT (neither, and no moved-needs-human request) admits only the no-effect declaration; UNCERTAIN (a moved-needs-human request without a posted row or a moving effect) admits both, only with ledgerEvidence. 422 SBJ-0052: resolution, reason or ledgerEvidence invalid (reason missing, longer than 200 characters or with personal data), or an UNCERTAIN revision without ledgerEvidence, or movedAmount missing, invalid or not admitted. A release (UNBLOCK or TRANSFER) whose parent block landed without its origin legs is UNCERTAIN whatever its request: its acknowledgement requires movedAmount and a transaction ledgerEvidence. 422 SBJ-0053: multi-tenant deployment (single-tenant only; use the audited manual procedure). 404: unknown revision, or one of an institution this executor does not own (the same answer)." operationId: resolve-executor-human-decision parameters: - description: The executor order's identifier (UUID). in: path name: orderId required: true schema: description: The executor order's identifier (UUID). examples: - 0b9b7c2e-4f8a-4d3e-9a51-7c2d1e0f3a44 type: string - description: The order revision (>= 1). in: path name: revision required: true schema: description: The order revision (>= 1). examples: - 1 format: int64 minimum: 1 type: integer requestBody: content: application/json: schema: $ref: "#/components/schemas/HumanDecisionResolutionRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/HumanDecisionResolutionResponse" 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: Resolve an executor human decision tags: - Executor x-mint: href: /en/reference/interfaces/plugin-sisbajud/resolve-an-executor-human-decision /v1/admin/executor/orders/{orderId}/revisions/{revision}/results/{executionVersion}/rearm: post: description: "Gives a result outbox row parked at the drainer's attempt cap (EXECUTOR_RESULT_MAX_ATTEMPTS) its way out: attempts go back to 0 and the drainer retries it at once, so later versions of the same order held behind it can follow. A human platform-administrator action (executor_result:rearm, never held by M2M): an application token (SBJ-0044) or a tenant-carrying token (SBJ-0045) is refused with 403. The reset, its journal row and its audit row commit in one transaction. Every attempt with a known result, accepted or refused, is recorded append-only in the audit trail with the reason. 200 outcome NOOP: the result is pending but not parked (nothing changed). 409 SBJ-0048: the result is terminal. 422 SBJ-0049: reason missing, blank, longer than 200 characters or containing personal data. 422 SBJ-0050: multi-tenant deployment (the rearm is single-tenant only). 404: unknown result." operationId: rearm-parked-executor-result parameters: - description: The executor order's identifier (UUID). in: path name: orderId required: true schema: description: The executor order's identifier (UUID). examples: - 0b9b7c2e-4f8a-4d3e-9a51-7c2d1e0f3a44 type: string - description: The order revision (>= 1). in: path name: revision required: true schema: description: The order revision (>= 1). examples: - 1 format: int64 minimum: 1 type: integer - description: The result's execution version (>= 1). in: path name: executionVersion required: true schema: description: The result's execution version (>= 1). examples: - 1 format: int64 minimum: 1 type: integer requestBody: content: application/json: schema: $ref: "#/components/schemas/ResultRearmRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/ResultRearmResponse" 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: Rearm a parked executor result tags: - Executor x-mint: href: /en/reference/interfaces/plugin-sisbajud/rearm-a-parked-executor-result /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: /en/reference/interfaces/plugin-sisbajud/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: /en/reference/interfaces/plugin-sisbajud/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: /en/reference/interfaces/plugin-sisbajud/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: /en/reference/interfaces/plugin-sisbajud/update-institution-config-by-id /v1/institutions/{institutionId}/channel: put: description: "Switches the channel an institution's results take back to Sisbajud. A human platform-administrator action (institution_channel:write, never held by M2M): an application token or a tenant-carrying token is refused with 403. Every attempt, accepted or refused with 403/409/422, is recorded append-only in the audit trail. 422: DIRECT in a multi-tenant deployment, DIRECT with PLUGIN_AUTH_ENABLED=false, or DIRECT while the stored institution_code is not the 8-character CNPJ root of the RESPONSIBLE GROUPING (CNPJ_INSTITUICAO_RESPONSAVEL), ^[A-Z0-9]{8}$ exactly as stored, never the executing institution's CNPJ. 409: the institution has any open order (in either direction); 409 SBJ-0060: the institution's execution owner is not this executor's M2M subject (another executor's institution, also when the current channel is requested): set the owner before switching. 404: unknown institution. 400: channel is not DIRECT or MENSAGERIA. Requesting the current channel answers 200 with changed=false." operationId: put-institution-channel 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/PutInstitutionChannelRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/InstitutionChannelResponse" 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: Switch the institution's result channel (Mensageria or DIRECT) tags: - Institution x-mint: href: /en/reference/interfaces/plugin-sisbajud/switch-the-institutions-result-channel-mensageria-or-direct /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: /en/reference/interfaces/plugin-sisbajud/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: /en/reference/interfaces/plugin-sisbajud/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: /en/reference/interfaces/plugin-sisbajud/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: /en/reference/interfaces/plugin-sisbajud/list-executor-human-decisions /v1/institutions/{institutionId}/executor/orders: get: description: | Cursor-paginated search by externalReference over the orders of direct origin; orders without one are not listed. 200 for any institution: an empty page when it has no direct history. **Direct channel rules.** - Answering the court (the 5302 response, and every later answer) is the duty of the client's messaging; the plugin never builds it. The response echoes institutionCode, the code the client answers for. - Submit a child (UNBLOCK/TRANSFER) only after the parent's 202. - A consumer keeps, per order, the highest executionVersion of the highest orderRevision wins. - The results feed is at-least-once: deduplicate by (orderId, orderRevision, executionVersion). - clientOrderId and externalReference are opaque client keys and MUST NOT contain personal data or judicial identifiers. - The personal-data guard is fail-closed and can refuse a legitimate key (422 personal-data-in-key). Use a hyphenated UUID as clientOrderId: 3 to 4 refusals measured over 20000 (0.02%, a valid CPF or CNPJ inside one of its digit groups); on a refusal, generate another UUID. Measured refusals of other shapes: 0 for ORD-YYYY-MM-DD-NNNN and for ULIDs; 0.2% for UUIDs without hyphens; 2.3% for keys whose separated digit groups add up to exactly 11 digits (ord-YYYY-MM-DD-NNN). - Avoid 32-hex keys (UUIDs without hyphens) as clientOrderId or externalReference: the long-digit-run check is not applied to them (it would refuse about 5% of random ones), so the guard is weaker on that shape. Use a hyphenated UUID. - A past deadlineAt is accepted (202) and signalled by deadlinePassedAtReceipt / cutPassedAtReceipt; it is never refused. **Permanent block** (layout INDICADOR_BLOQUEIO_PERMANENTE and DATA_PRAZO_BLOQUEIO_PERMANENTE). - "T" (traditional) is block.permanent false or absent; "P" (permanent) is block.permanent true without block.permanentUntil; "D" (permanent with a deadline) is block.permanent true with block.permanentUntil (the deadline). - block.permanentUntil without block.permanent true is no layout value: 422 invalid-order. - While the deployment does not take permanent blocks (the default), the CREATION of a permanent block is refused with 422 permanent-block-not-supported: an original BLOCK with block.permanent true (P and D alike) and a reiteration (orderCancelled false) of a permanent original block. Nothing is recorded and the order remains due: answering the court is the client's duty. - What releases money is never refused for being permanent: the cancellation (orderCancelled true) of a permanent original, and every UNBLOCK or TRANSFER of a permanent parent block, are taken as for any other block. - INTERRUPT (layout record "10") stops a permanent block and is never refused by that policy: stopping is the safe side. It carries parentClientOrderId and parentBlockKey only (its key is the permanent's), its parent must be a permanent block in custody (otherwise 422 parent-not-in-custody, or 422 invalid-order when the parent is a traditional block), it keeps what is already blocked, and it is idempotent by clientOrderId. Its result is a RESULT with permanentBlock CLOSED / INTERRUPTED; resending it to a closed permanent reports the same state. - terminal=true always arrives on a RESULT. A permanent order's subsequent blocks are PERMANENT_BLOCK items with terminal false while it is ACTIVE; when it closes (TARGET_REACHED, EXPIRED, INTERRUPTED, RELEASED) the permanent's own order gets exactly one close RESULT: RESOLVED, effect NONE, no products, permanentBlock CLOSED with the reason, terminal true. terminal=true arrives on the LAST RESULT item of the order: the outcome no longer changes. PERMANENT_BLOCK items may follow it (money landing after the close, a held block republished after the close); they never reopen the permanent. Read past the terminal RESULT: PERMANENT_BLOCK items can follow it. The INTERRUPT and the TRANSFER that caused the close are answered on their own orders as usual. **Reiteration and cancellation of a block** (SISBAJUD manual: they exist only for a block not answered; layout REITERACAO_BLOQUEIO and ORDEM_CANCELADA). - A BLOCK with blockReiteration other than 00 is never a new block. orderCancelled is required when blockReiteration is not 00 (422 missing-operation-field without it). - blockReiteration 00 with any orderCancelled is the original block (the flag is ignored, as the Lerian SISBAJUD Mensageria classifies it). - Reiteration (blockReiteration 01 or higher, orderCancelled false): the plugin resolves the ORIGINAL block by the same protocol and blockSequence, in the same institution (the reiteration digits are not part of the lookup), and returns the original's result, the outcome of its first execution: no new block and no new revision. While the original is not yet determined, the answer is the current state of the original, never a new execution. - Cancellation (blockReiteration 01 or higher, orderCancelled true): a derived unblock of the original's effect, limited to its remaining balance; an original already unblocked gets no second effect. - The original block (blockReiteration 00) is unique per institution by protocol and blockSequence, whatever its clientOrderId (as the Lerian SISBAJUD Mensageria keeps one order per institution and record key). A second original with the same protocol and blockSequence in the same institution is never a second block: the same content answers 200 with the response of the original already accepted; different content is 409 content-conflict (SBJ-0016). Content is the whole body except clientOrderId. - An original that is not registered in the institution (reiteration or cancellation alike) is the same 422 parent-not-in-custody as an unknown parent: the same body, except instance. - An UNBLOCK/TRANSFER's parentBlockKey names its parent block by protocol and blockSequence; its blockReiteration digits are ignored when it is checked against the parent (as the Lerian SISBAJUD Mensageria resolves the cited block). **Reiteration of an unblock or a transfer** (layout REITERACAO_DESBLOQUEIO / REITERACAO_TRANSFERENCIA). - An UNBLOCK/TRANSFER carries its own movementKey: movementSequence (SEQUENCIAL_DESBLOQUEIO / SEQUENCIAL_TRANSFERENCIA, 5 digits) and movementReiteration (2 digits, always required). movementReiteration 00 is the original movement; 01 or higher is a reiteration of a movement already sent, never a new movement. - A reiterated movement resolves to the ORIGINAL movement by institution, operation (UNBLOCK or TRANSFER: their sequences are separate counters), the cited parentBlockKey's protocol and blockSequence (its blockReiteration is ignored, as when it is checked against the parent: a reiteration citing 01 resolves to an original that cited 00), the same movementSequence and movementReiteration 00 (its own reiteration digits are not part of the lookup), and is answered from it with no new effect: no second unblock, no second transfer, no ledger write. A reiterated movement whose original is not registered in the institution is the same 422 parent-not-in-custody. - The original movement (movementReiteration 00) is unique per institution by that same key (operation included), whatever its clientOrderId and whatever blockReiteration its parentBlockKey cites, with the same 200 / 409 rule as the original block: an identical body is a 200 replay; any other body is 409 content-conflict (SBJ-0016), including one that differs only in the cited blockReiteration (a second order, not a reiteration); never a second movement. - Content of a reiteration (block or movement): it is compared with the original's on every field except clientOrderId, orderRevision, deadlineAt, externalReference, metadata, the reiteration digits (blockReiteration, the cited parentBlockKey.blockReiteration, movementReiteration) and orderCancelled. The same content is answered from the original; different content is 409 content-conflict (SBJ-0016). **Answers to a reiteration, a cancellation and their replays.** - A block reiteration and a reiterated movement answer 200 with the ORIGINAL order: its orderId, its clientOrderId and its current state (originalOrderId null), never 202 and never an execution; a replay answers the same. - A cancellation answers 202 with a derived UNBLOCK order: its own orderId, and originalOrderId is the orderId of the original block. There is one cancellation per original block: its idempotency key is the original block's protocol and blockSequence and its kind, whatever its clientOrderId and whatever its blockReiteration (as the Lerian SISBAJUD Mensageria keeps one cancellation row per block). The same cancellation again (same blockReiteration, same content: the whole body except clientOrderId) answers 200 with the orderId and current state of the derived UNBLOCK already created, with no second effect; a cancellation under another blockReiteration (for example 02 after 01) is a reiteration of it, compared under the reiteration content rule below, and the same content answers 200 with that same derived UNBLOCK, never a second one; different content is 409 content-conflict (SBJ-0016). - originalOrderId is on the submit response, the order view and every results item: the orderId of the order this one is derived from, null when it is not derived. **Parity criterion with the Lerian SISBAJUD Mensageria** (one rule for the whole contract). - where the Mensageria classifies an explicit value, the direct channel classifies it the same way: blockReiteration 00 is the original block whatever orderCancelled says, and from 01 on orderCancelled true is a cancellation and false a reiteration. - where the Mensageria infers a value from an absent field, the direct channel requires the field explicitly: orderCancelled is required when blockReiteration is not 00, where the Mensageria reads it as F (422 missing-operation-field); blockReiteration is always required by the schema, where the Mensageria reads a blank one as 00 (422 invalid-order). - where the Mensageria reads a blank movement reiteration as the original movement, the direct channel requires movementKey.movementReiteration (422 invalid-order). - A reiterated INFO is a new order: submit it as an INFO with its own clientOrderId; INFO carries no block key. **Declared divergences from the Lerian SISBAJUD Mensageria.** These are the only declared divergences; everything else follows the parity criterion above. - absent-order-cancelled: orderCancelled absent with blockReiteration other than 00 is 422 missing-operation-field; the Mensageria reads a blank ORDEM_CANCELADA as F, a reiteration. - absent-block-reiteration: a blank blockReiteration is 422 invalid-order; the Mensageria reads a blank REITERACAO_BLOQUEIO as 00, the original block. - absent-movement-reiteration: a blank movementReiteration (or a missing movementKey) is 422 invalid-order (422 missing-operation-field); the Mensageria reads a blank REITERACAO of the movement as the original movement and executes it. - reiteration-content-conflict: a reiteration of a block or of a movement whose content differs from the original's is 409 content-conflict (SBJ-0016), with no effect; content is every field except clientOrderId, orderRevision, deadlineAt, externalReference, metadata, the reiteration digits (blockReiteration, the cited parentBlockKey.blockReiteration, movementReiteration) and orderCancelled; the Mensageria answers it from the original without comparing its content. - duplicate-normative-key: a second submission under a normative key already used in the institution, whatever its kind, is never a second order: a second original block, original movement or cancellation answers 200 with the response of the accepted one when its content (the whole body except clientOrderId, and except the digits the key leaves out) is the same, and 409 content-conflict (SBJ-0016) otherwise; a cancellation under another blockReiteration is compared under the reiteration rule; a repeated reiteration (block or movement) is answered from the original again, under the same reiteration rule; the Mensageria persists every order, reiterations included, under its record key with a unique index per institution, with no content comparison and no replay answer. - movement-key-carries-operation-type: the identity of a movement (its uniqueness key and the lookup key of the original of a reiterated movement) carries the operation type, so an UNBLOCK and a TRANSFER with the same movementSequence under the same block are distinct movements; the Mensageria keys a movement without its type, so UNBLOCK n and TRANSFER n under the same block collide. - movement-key-ignores-cited-block-reiteration: the key of a movement (the uniqueness of an original and the lookup of the original of a reiterated movement) reads the blockReiteration its parentBlockKey cites as 00, as when the parent is checked: a second original UNBLOCK or TRANSFER that differs only in that digit is found under the first and is 409 content-conflict (SBJ-0016), never a second execution, and a reiterated movement citing 01 resolves to an original that cited 00; the Mensageria keeps the cited REITERACAO_BLOQUEIO in the record key of a movement, so two such movements are two orders and both execute, and a reiteration citing another digit does not find its original. **Error catalog** (RFC 9457; `type` = https://errors.lerian.studio/v1/, one code per entry). | Status | Code | Type | Slug | Title | Meaning | |---|---|---|---|---|---| | 400 | SBJ-0001 | https://errors.lerian.studio/v1/SBJ-0001 | malformed-request | Malformed request | The request body or a path/query parameter could not be parsed. | | 401 | SBJ-0003 | https://errors.lerian.studio/v1/SBJ-0003 | unauthorized | Unauthorized | The bearer token is missing, expired or invalid. | | 403 | SBJ-0004 | https://errors.lerian.studio/v1/SBJ-0004 | forbidden | Forbidden | The credential is not authorized for this action. | | 404 | SBJ-0015 | https://errors.lerian.studio/v1/SBJ-0015 | order-not-found | Not found | No such direct-channel order in this institution (single-order routes only; list routes answer an empty page). | | 409 | SBJ-0016 | https://errors.lerian.studio/v1/SBJ-0016 | content-conflict | Content conflict | This clientOrderId and orderRevision were already accepted with a different body, the externalReference differs from revision 1, or a submission under a normative key already used in this institution carries a different body: a second original block or movement, or a second cancellation, with a different body, or a reiteration of a block or a movement whose content differs from the original's. | | 409 | SBJ-0017 | https://errors.lerian.studio/v1/SBJ-0017 | revision-stale | Revision stale | A higher orderRevision of this clientOrderId was already accepted. | | 413 | SBJ-0018 | https://errors.lerian.studio/v1/SBJ-0018 | body-too-large | Body too large | The request body exceeds the accepted size. | | 422 | SBJ-0019 | https://errors.lerian.studio/v1/SBJ-0019 | invalid-order | Invalid order | A field violates the contract schema or a field rule. | | 422 | SBJ-0020 | https://errors.lerian.studio/v1/SBJ-0020 | field-outside-operation | Field outside operation | A field or block was sent that the operation does not take. | | 422 | SBJ-0021 | https://errors.lerian.studio/v1/SBJ-0021 | missing-operation-field | Missing operation field | A field or block the operation requires is absent. | | 422 | SBJ-0022 | https://errors.lerian.studio/v1/SBJ-0022 | metadata-invalid | Metadata invalid | metadata exceeds 16 keys, a value of 256 bytes (UTF-8), 4096 bytes in total, or a key is outside ^[A-Za-z0-9_.-]{1,64}$. | | 422 | SBJ-0023 | https://errors.lerian.studio/v1/SBJ-0023 | personal-data-in-key | Personal data in client key | clientOrderId, parentClientOrderId or externalReference looks like it carries a CPF/CNPJ, a judicial process number or a long digit run. | | 422 | SBJ-0024 | https://errors.lerian.studio/v1/SBJ-0024 | institution-mismatch | Institution mismatch | responsibleInstitutionCnpj does not match the registered code of the institution in the path. | | 422 | SBJ-0025 | https://errors.lerian.studio/v1/SBJ-0025 | institution-channel-not-direct | Institution not on the direct channel | The institution in the path does not take orders through the direct channel. | | 422 | SBJ-0026 | https://errors.lerian.studio/v1/SBJ-0026 | parent-not-in-custody | Child not taken into custody | The plugin does not accept custody of this child: no matching registered parent in this institution. The order remains due; answering the court is the client's duty. | | 429 | SBJ-0009 | https://errors.lerian.studio/v1/SBJ-0009 | rate-limited | Too many requests | The client exceeded its request rate. | | 422 | SBJ-0027 | https://errors.lerian.studio/v1/SBJ-0027 | permanent-block-not-supported | Permanent block not supported | This deployment does not take permanent blocks: an original BLOCK with block.permanent true, or a reiteration of a permanent original block, is refused. A cancellation and every UNBLOCK or TRANSFER of a permanent block are taken. Nothing is recorded; the order remains due. | The single parent-not-in-custody 422 covers parent not found, parent not BLOCK and holder divergent alike; it carries no court response code, and the order remains due. A request-schema violation (missing field, type, pattern) is the same 422 invalid-order, and no 422 echoes a rejected personal-data or client-key value. 404 exists only on the single-order routes and is uniform: unknown order, other institution, or an order not of direct origin. The list routes (search and feed) answer 200 for any institution and list only orders of direct origin: an empty page when there are none, and direct history stays readable after the institution switches channel. A POST to an institution whose channel is not DIRECT is 422 institution-channel-not-direct. operationId: list-direct-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 format: uuid type: string - description: "externalReference to search by. Same rules as the stored key: a value that looks like personal data is refused (422 personal-data-in-key) and never echoed." explode: false in: query name: externalReference required: true schema: description: "externalReference to search by. Same rules as the stored key: a value that looks like personal data is refused (422 personal-data-in-key) and never echoed." examples: - REM-2026-10-22-A maxLength: 128 pattern: ^[A-Za-z0-9_.:-]{1,128}$ type: string - description: Opaque cursor from a previous page. explode: false in: query name: cursor schema: description: Opaque cursor from a previous page. maxLength: 512 type: string - description: Maximum items per page. explode: false in: query name: limit schema: default: 50 description: Maximum items per page. format: int64 maximum: 200 minimum: 1 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/OrderPage" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "429": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Too Many Requests "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error summary: Search direct orders by externalReference tags: - Executor x-mint: href: /en/reference/interfaces/plugin-sisbajud/search-direct-orders-by-externalreference post: description: | Durably records the sealed order (or a new revision) and answers 202 before any execution; a replay of the same body answers 200 with the same response. **Direct channel rules.** - Answering the court (the 5302 response, and every later answer) is the duty of the client's messaging; the plugin never builds it. The response echoes institutionCode, the code the client answers for. - Submit a child (UNBLOCK/TRANSFER) only after the parent's 202. - A consumer keeps, per order, the highest executionVersion of the highest orderRevision wins. - The results feed is at-least-once: deduplicate by (orderId, orderRevision, executionVersion). - clientOrderId and externalReference are opaque client keys and MUST NOT contain personal data or judicial identifiers. - The personal-data guard is fail-closed and can refuse a legitimate key (422 personal-data-in-key). Use a hyphenated UUID as clientOrderId: 3 to 4 refusals measured over 20000 (0.02%, a valid CPF or CNPJ inside one of its digit groups); on a refusal, generate another UUID. Measured refusals of other shapes: 0 for ORD-YYYY-MM-DD-NNNN and for ULIDs; 0.2% for UUIDs without hyphens; 2.3% for keys whose separated digit groups add up to exactly 11 digits (ord-YYYY-MM-DD-NNN). - Avoid 32-hex keys (UUIDs without hyphens) as clientOrderId or externalReference: the long-digit-run check is not applied to them (it would refuse about 5% of random ones), so the guard is weaker on that shape. Use a hyphenated UUID. - A past deadlineAt is accepted (202) and signalled by deadlinePassedAtReceipt / cutPassedAtReceipt; it is never refused. **Permanent block** (layout INDICADOR_BLOQUEIO_PERMANENTE and DATA_PRAZO_BLOQUEIO_PERMANENTE). - "T" (traditional) is block.permanent false or absent; "P" (permanent) is block.permanent true without block.permanentUntil; "D" (permanent with a deadline) is block.permanent true with block.permanentUntil (the deadline). - block.permanentUntil without block.permanent true is no layout value: 422 invalid-order. - While the deployment does not take permanent blocks (the default), the CREATION of a permanent block is refused with 422 permanent-block-not-supported: an original BLOCK with block.permanent true (P and D alike) and a reiteration (orderCancelled false) of a permanent original block. Nothing is recorded and the order remains due: answering the court is the client's duty. - What releases money is never refused for being permanent: the cancellation (orderCancelled true) of a permanent original, and every UNBLOCK or TRANSFER of a permanent parent block, are taken as for any other block. - INTERRUPT (layout record "10") stops a permanent block and is never refused by that policy: stopping is the safe side. It carries parentClientOrderId and parentBlockKey only (its key is the permanent's), its parent must be a permanent block in custody (otherwise 422 parent-not-in-custody, or 422 invalid-order when the parent is a traditional block), it keeps what is already blocked, and it is idempotent by clientOrderId. Its result is a RESULT with permanentBlock CLOSED / INTERRUPTED; resending it to a closed permanent reports the same state. - terminal=true always arrives on a RESULT. A permanent order's subsequent blocks are PERMANENT_BLOCK items with terminal false while it is ACTIVE; when it closes (TARGET_REACHED, EXPIRED, INTERRUPTED, RELEASED) the permanent's own order gets exactly one close RESULT: RESOLVED, effect NONE, no products, permanentBlock CLOSED with the reason, terminal true. terminal=true arrives on the LAST RESULT item of the order: the outcome no longer changes. PERMANENT_BLOCK items may follow it (money landing after the close, a held block republished after the close); they never reopen the permanent. Read past the terminal RESULT: PERMANENT_BLOCK items can follow it. The INTERRUPT and the TRANSFER that caused the close are answered on their own orders as usual. **Reiteration and cancellation of a block** (SISBAJUD manual: they exist only for a block not answered; layout REITERACAO_BLOQUEIO and ORDEM_CANCELADA). - A BLOCK with blockReiteration other than 00 is never a new block. orderCancelled is required when blockReiteration is not 00 (422 missing-operation-field without it). - blockReiteration 00 with any orderCancelled is the original block (the flag is ignored, as the Lerian SISBAJUD Mensageria classifies it). - Reiteration (blockReiteration 01 or higher, orderCancelled false): the plugin resolves the ORIGINAL block by the same protocol and blockSequence, in the same institution (the reiteration digits are not part of the lookup), and returns the original's result, the outcome of its first execution: no new block and no new revision. While the original is not yet determined, the answer is the current state of the original, never a new execution. - Cancellation (blockReiteration 01 or higher, orderCancelled true): a derived unblock of the original's effect, limited to its remaining balance; an original already unblocked gets no second effect. - The original block (blockReiteration 00) is unique per institution by protocol and blockSequence, whatever its clientOrderId (as the Lerian SISBAJUD Mensageria keeps one order per institution and record key). A second original with the same protocol and blockSequence in the same institution is never a second block: the same content answers 200 with the response of the original already accepted; different content is 409 content-conflict (SBJ-0016). Content is the whole body except clientOrderId. - An original that is not registered in the institution (reiteration or cancellation alike) is the same 422 parent-not-in-custody as an unknown parent: the same body, except instance. - An UNBLOCK/TRANSFER's parentBlockKey names its parent block by protocol and blockSequence; its blockReiteration digits are ignored when it is checked against the parent (as the Lerian SISBAJUD Mensageria resolves the cited block). **Reiteration of an unblock or a transfer** (layout REITERACAO_DESBLOQUEIO / REITERACAO_TRANSFERENCIA). - An UNBLOCK/TRANSFER carries its own movementKey: movementSequence (SEQUENCIAL_DESBLOQUEIO / SEQUENCIAL_TRANSFERENCIA, 5 digits) and movementReiteration (2 digits, always required). movementReiteration 00 is the original movement; 01 or higher is a reiteration of a movement already sent, never a new movement. - A reiterated movement resolves to the ORIGINAL movement by institution, operation (UNBLOCK or TRANSFER: their sequences are separate counters), the cited parentBlockKey's protocol and blockSequence (its blockReiteration is ignored, as when it is checked against the parent: a reiteration citing 01 resolves to an original that cited 00), the same movementSequence and movementReiteration 00 (its own reiteration digits are not part of the lookup), and is answered from it with no new effect: no second unblock, no second transfer, no ledger write. A reiterated movement whose original is not registered in the institution is the same 422 parent-not-in-custody. - The original movement (movementReiteration 00) is unique per institution by that same key (operation included), whatever its clientOrderId and whatever blockReiteration its parentBlockKey cites, with the same 200 / 409 rule as the original block: an identical body is a 200 replay; any other body is 409 content-conflict (SBJ-0016), including one that differs only in the cited blockReiteration (a second order, not a reiteration); never a second movement. - Content of a reiteration (block or movement): it is compared with the original's on every field except clientOrderId, orderRevision, deadlineAt, externalReference, metadata, the reiteration digits (blockReiteration, the cited parentBlockKey.blockReiteration, movementReiteration) and orderCancelled. The same content is answered from the original; different content is 409 content-conflict (SBJ-0016). **Answers to a reiteration, a cancellation and their replays.** - A block reiteration and a reiterated movement answer 200 with the ORIGINAL order: its orderId, its clientOrderId and its current state (originalOrderId null), never 202 and never an execution; a replay answers the same. - A cancellation answers 202 with a derived UNBLOCK order: its own orderId, and originalOrderId is the orderId of the original block. There is one cancellation per original block: its idempotency key is the original block's protocol and blockSequence and its kind, whatever its clientOrderId and whatever its blockReiteration (as the Lerian SISBAJUD Mensageria keeps one cancellation row per block). The same cancellation again (same blockReiteration, same content: the whole body except clientOrderId) answers 200 with the orderId and current state of the derived UNBLOCK already created, with no second effect; a cancellation under another blockReiteration (for example 02 after 01) is a reiteration of it, compared under the reiteration content rule below, and the same content answers 200 with that same derived UNBLOCK, never a second one; different content is 409 content-conflict (SBJ-0016). - originalOrderId is on the submit response, the order view and every results item: the orderId of the order this one is derived from, null when it is not derived. **Parity criterion with the Lerian SISBAJUD Mensageria** (one rule for the whole contract). - where the Mensageria classifies an explicit value, the direct channel classifies it the same way: blockReiteration 00 is the original block whatever orderCancelled says, and from 01 on orderCancelled true is a cancellation and false a reiteration. - where the Mensageria infers a value from an absent field, the direct channel requires the field explicitly: orderCancelled is required when blockReiteration is not 00, where the Mensageria reads it as F (422 missing-operation-field); blockReiteration is always required by the schema, where the Mensageria reads a blank one as 00 (422 invalid-order). - where the Mensageria reads a blank movement reiteration as the original movement, the direct channel requires movementKey.movementReiteration (422 invalid-order). - A reiterated INFO is a new order: submit it as an INFO with its own clientOrderId; INFO carries no block key. **Declared divergences from the Lerian SISBAJUD Mensageria.** These are the only declared divergences; everything else follows the parity criterion above. - absent-order-cancelled: orderCancelled absent with blockReiteration other than 00 is 422 missing-operation-field; the Mensageria reads a blank ORDEM_CANCELADA as F, a reiteration. - absent-block-reiteration: a blank blockReiteration is 422 invalid-order; the Mensageria reads a blank REITERACAO_BLOQUEIO as 00, the original block. - absent-movement-reiteration: a blank movementReiteration (or a missing movementKey) is 422 invalid-order (422 missing-operation-field); the Mensageria reads a blank REITERACAO of the movement as the original movement and executes it. - reiteration-content-conflict: a reiteration of a block or of a movement whose content differs from the original's is 409 content-conflict (SBJ-0016), with no effect; content is every field except clientOrderId, orderRevision, deadlineAt, externalReference, metadata, the reiteration digits (blockReiteration, the cited parentBlockKey.blockReiteration, movementReiteration) and orderCancelled; the Mensageria answers it from the original without comparing its content. - duplicate-normative-key: a second submission under a normative key already used in the institution, whatever its kind, is never a second order: a second original block, original movement or cancellation answers 200 with the response of the accepted one when its content (the whole body except clientOrderId, and except the digits the key leaves out) is the same, and 409 content-conflict (SBJ-0016) otherwise; a cancellation under another blockReiteration is compared under the reiteration rule; a repeated reiteration (block or movement) is answered from the original again, under the same reiteration rule; the Mensageria persists every order, reiterations included, under its record key with a unique index per institution, with no content comparison and no replay answer. - movement-key-carries-operation-type: the identity of a movement (its uniqueness key and the lookup key of the original of a reiterated movement) carries the operation type, so an UNBLOCK and a TRANSFER with the same movementSequence under the same block are distinct movements; the Mensageria keys a movement without its type, so UNBLOCK n and TRANSFER n under the same block collide. - movement-key-ignores-cited-block-reiteration: the key of a movement (the uniqueness of an original and the lookup of the original of a reiterated movement) reads the blockReiteration its parentBlockKey cites as 00, as when the parent is checked: a second original UNBLOCK or TRANSFER that differs only in that digit is found under the first and is 409 content-conflict (SBJ-0016), never a second execution, and a reiterated movement citing 01 resolves to an original that cited 00; the Mensageria keeps the cited REITERACAO_BLOQUEIO in the record key of a movement, so two such movements are two orders and both execute, and a reiteration citing another digit does not find its original. **Error catalog** (RFC 9457; `type` = https://errors.lerian.studio/v1/, one code per entry). | Status | Code | Type | Slug | Title | Meaning | |---|---|---|---|---|---| | 400 | SBJ-0001 | https://errors.lerian.studio/v1/SBJ-0001 | malformed-request | Malformed request | The request body or a path/query parameter could not be parsed. | | 401 | SBJ-0003 | https://errors.lerian.studio/v1/SBJ-0003 | unauthorized | Unauthorized | The bearer token is missing, expired or invalid. | | 403 | SBJ-0004 | https://errors.lerian.studio/v1/SBJ-0004 | forbidden | Forbidden | The credential is not authorized for this action. | | 404 | SBJ-0015 | https://errors.lerian.studio/v1/SBJ-0015 | order-not-found | Not found | No such direct-channel order in this institution (single-order routes only; list routes answer an empty page). | | 409 | SBJ-0016 | https://errors.lerian.studio/v1/SBJ-0016 | content-conflict | Content conflict | This clientOrderId and orderRevision were already accepted with a different body, the externalReference differs from revision 1, or a submission under a normative key already used in this institution carries a different body: a second original block or movement, or a second cancellation, with a different body, or a reiteration of a block or a movement whose content differs from the original's. | | 409 | SBJ-0017 | https://errors.lerian.studio/v1/SBJ-0017 | revision-stale | Revision stale | A higher orderRevision of this clientOrderId was already accepted. | | 413 | SBJ-0018 | https://errors.lerian.studio/v1/SBJ-0018 | body-too-large | Body too large | The request body exceeds the accepted size. | | 422 | SBJ-0019 | https://errors.lerian.studio/v1/SBJ-0019 | invalid-order | Invalid order | A field violates the contract schema or a field rule. | | 422 | SBJ-0020 | https://errors.lerian.studio/v1/SBJ-0020 | field-outside-operation | Field outside operation | A field or block was sent that the operation does not take. | | 422 | SBJ-0021 | https://errors.lerian.studio/v1/SBJ-0021 | missing-operation-field | Missing operation field | A field or block the operation requires is absent. | | 422 | SBJ-0022 | https://errors.lerian.studio/v1/SBJ-0022 | metadata-invalid | Metadata invalid | metadata exceeds 16 keys, a value of 256 bytes (UTF-8), 4096 bytes in total, or a key is outside ^[A-Za-z0-9_.-]{1,64}$. | | 422 | SBJ-0023 | https://errors.lerian.studio/v1/SBJ-0023 | personal-data-in-key | Personal data in client key | clientOrderId, parentClientOrderId or externalReference looks like it carries a CPF/CNPJ, a judicial process number or a long digit run. | | 422 | SBJ-0024 | https://errors.lerian.studio/v1/SBJ-0024 | institution-mismatch | Institution mismatch | responsibleInstitutionCnpj does not match the registered code of the institution in the path. | | 422 | SBJ-0025 | https://errors.lerian.studio/v1/SBJ-0025 | institution-channel-not-direct | Institution not on the direct channel | The institution in the path does not take orders through the direct channel. | | 422 | SBJ-0026 | https://errors.lerian.studio/v1/SBJ-0026 | parent-not-in-custody | Child not taken into custody | The plugin does not accept custody of this child: no matching registered parent in this institution. The order remains due; answering the court is the client's duty. | | 429 | SBJ-0009 | https://errors.lerian.studio/v1/SBJ-0009 | rate-limited | Too many requests | The client exceeded its request rate. | | 422 | SBJ-0027 | https://errors.lerian.studio/v1/SBJ-0027 | permanent-block-not-supported | Permanent block not supported | This deployment does not take permanent blocks: an original BLOCK with block.permanent true, or a reiteration of a permanent original block, is refused. A cancellation and every UNBLOCK or TRANSFER of a permanent block are taken. Nothing is recorded; the order remains due. | The single parent-not-in-custody 422 covers parent not found, parent not BLOCK and holder divergent alike; it carries no court response code, and the order remains due. A request-schema violation (missing field, type, pattern) is the same 422 invalid-order, and no 422 echoes a rejected personal-data or client-key value. 404 exists only on the single-order routes and is uniform: unknown order, other institution, or an order not of direct origin. The list routes (search and feed) answer 200 for any institution and list only orders of direct origin: an empty page when there are none, and direct history stays readable after the institution switches channel. A POST to an institution whose channel is not DIRECT is 422 institution-channel-not-direct. operationId: submit-direct-order 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 format: uuid type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/SubmitOrderBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/SubmitOrderResponse" description: "Idempotent replay (the same body was already accepted: same response), or a reiteration answered from the original (the original order's response and current state; no new execution)." "202": content: application/json: schema: $ref: "#/components/schemas/SubmitOrderResponse" description: Accepted "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" 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/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/problem+json: schema: $ref: "#/components/schemas/Detail" description: Too Many Requests "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error summary: Submit a direct order or revision tags: - Executor x-mint: href: /en/reference/interfaces/plugin-sisbajud/submit-a-direct-order-or-revision /v1/institutions/{institutionId}/executor/orders/{orderId}: get: description: | Returns the state of the order and its latest result. With a read replica configured, this read is eventually consistent: a result may appear a moment after it was written. **Direct channel rules.** - Answering the court (the 5302 response, and every later answer) is the duty of the client's messaging; the plugin never builds it. The response echoes institutionCode, the code the client answers for. - Submit a child (UNBLOCK/TRANSFER) only after the parent's 202. - A consumer keeps, per order, the highest executionVersion of the highest orderRevision wins. - The results feed is at-least-once: deduplicate by (orderId, orderRevision, executionVersion). - clientOrderId and externalReference are opaque client keys and MUST NOT contain personal data or judicial identifiers. - The personal-data guard is fail-closed and can refuse a legitimate key (422 personal-data-in-key). Use a hyphenated UUID as clientOrderId: 3 to 4 refusals measured over 20000 (0.02%, a valid CPF or CNPJ inside one of its digit groups); on a refusal, generate another UUID. Measured refusals of other shapes: 0 for ORD-YYYY-MM-DD-NNNN and for ULIDs; 0.2% for UUIDs without hyphens; 2.3% for keys whose separated digit groups add up to exactly 11 digits (ord-YYYY-MM-DD-NNN). - Avoid 32-hex keys (UUIDs without hyphens) as clientOrderId or externalReference: the long-digit-run check is not applied to them (it would refuse about 5% of random ones), so the guard is weaker on that shape. Use a hyphenated UUID. - A past deadlineAt is accepted (202) and signalled by deadlinePassedAtReceipt / cutPassedAtReceipt; it is never refused. **Permanent block** (layout INDICADOR_BLOQUEIO_PERMANENTE and DATA_PRAZO_BLOQUEIO_PERMANENTE). - "T" (traditional) is block.permanent false or absent; "P" (permanent) is block.permanent true without block.permanentUntil; "D" (permanent with a deadline) is block.permanent true with block.permanentUntil (the deadline). - block.permanentUntil without block.permanent true is no layout value: 422 invalid-order. - While the deployment does not take permanent blocks (the default), the CREATION of a permanent block is refused with 422 permanent-block-not-supported: an original BLOCK with block.permanent true (P and D alike) and a reiteration (orderCancelled false) of a permanent original block. Nothing is recorded and the order remains due: answering the court is the client's duty. - What releases money is never refused for being permanent: the cancellation (orderCancelled true) of a permanent original, and every UNBLOCK or TRANSFER of a permanent parent block, are taken as for any other block. - INTERRUPT (layout record "10") stops a permanent block and is never refused by that policy: stopping is the safe side. It carries parentClientOrderId and parentBlockKey only (its key is the permanent's), its parent must be a permanent block in custody (otherwise 422 parent-not-in-custody, or 422 invalid-order when the parent is a traditional block), it keeps what is already blocked, and it is idempotent by clientOrderId. Its result is a RESULT with permanentBlock CLOSED / INTERRUPTED; resending it to a closed permanent reports the same state. - terminal=true always arrives on a RESULT. A permanent order's subsequent blocks are PERMANENT_BLOCK items with terminal false while it is ACTIVE; when it closes (TARGET_REACHED, EXPIRED, INTERRUPTED, RELEASED) the permanent's own order gets exactly one close RESULT: RESOLVED, effect NONE, no products, permanentBlock CLOSED with the reason, terminal true. terminal=true arrives on the LAST RESULT item of the order: the outcome no longer changes. PERMANENT_BLOCK items may follow it (money landing after the close, a held block republished after the close); they never reopen the permanent. Read past the terminal RESULT: PERMANENT_BLOCK items can follow it. The INTERRUPT and the TRANSFER that caused the close are answered on their own orders as usual. **Reiteration and cancellation of a block** (SISBAJUD manual: they exist only for a block not answered; layout REITERACAO_BLOQUEIO and ORDEM_CANCELADA). - A BLOCK with blockReiteration other than 00 is never a new block. orderCancelled is required when blockReiteration is not 00 (422 missing-operation-field without it). - blockReiteration 00 with any orderCancelled is the original block (the flag is ignored, as the Lerian SISBAJUD Mensageria classifies it). - Reiteration (blockReiteration 01 or higher, orderCancelled false): the plugin resolves the ORIGINAL block by the same protocol and blockSequence, in the same institution (the reiteration digits are not part of the lookup), and returns the original's result, the outcome of its first execution: no new block and no new revision. While the original is not yet determined, the answer is the current state of the original, never a new execution. - Cancellation (blockReiteration 01 or higher, orderCancelled true): a derived unblock of the original's effect, limited to its remaining balance; an original already unblocked gets no second effect. - The original block (blockReiteration 00) is unique per institution by protocol and blockSequence, whatever its clientOrderId (as the Lerian SISBAJUD Mensageria keeps one order per institution and record key). A second original with the same protocol and blockSequence in the same institution is never a second block: the same content answers 200 with the response of the original already accepted; different content is 409 content-conflict (SBJ-0016). Content is the whole body except clientOrderId. - An original that is not registered in the institution (reiteration or cancellation alike) is the same 422 parent-not-in-custody as an unknown parent: the same body, except instance. - An UNBLOCK/TRANSFER's parentBlockKey names its parent block by protocol and blockSequence; its blockReiteration digits are ignored when it is checked against the parent (as the Lerian SISBAJUD Mensageria resolves the cited block). **Reiteration of an unblock or a transfer** (layout REITERACAO_DESBLOQUEIO / REITERACAO_TRANSFERENCIA). - An UNBLOCK/TRANSFER carries its own movementKey: movementSequence (SEQUENCIAL_DESBLOQUEIO / SEQUENCIAL_TRANSFERENCIA, 5 digits) and movementReiteration (2 digits, always required). movementReiteration 00 is the original movement; 01 or higher is a reiteration of a movement already sent, never a new movement. - A reiterated movement resolves to the ORIGINAL movement by institution, operation (UNBLOCK or TRANSFER: their sequences are separate counters), the cited parentBlockKey's protocol and blockSequence (its blockReiteration is ignored, as when it is checked against the parent: a reiteration citing 01 resolves to an original that cited 00), the same movementSequence and movementReiteration 00 (its own reiteration digits are not part of the lookup), and is answered from it with no new effect: no second unblock, no second transfer, no ledger write. A reiterated movement whose original is not registered in the institution is the same 422 parent-not-in-custody. - The original movement (movementReiteration 00) is unique per institution by that same key (operation included), whatever its clientOrderId and whatever blockReiteration its parentBlockKey cites, with the same 200 / 409 rule as the original block: an identical body is a 200 replay; any other body is 409 content-conflict (SBJ-0016), including one that differs only in the cited blockReiteration (a second order, not a reiteration); never a second movement. - Content of a reiteration (block or movement): it is compared with the original's on every field except clientOrderId, orderRevision, deadlineAt, externalReference, metadata, the reiteration digits (blockReiteration, the cited parentBlockKey.blockReiteration, movementReiteration) and orderCancelled. The same content is answered from the original; different content is 409 content-conflict (SBJ-0016). **Answers to a reiteration, a cancellation and their replays.** - A block reiteration and a reiterated movement answer 200 with the ORIGINAL order: its orderId, its clientOrderId and its current state (originalOrderId null), never 202 and never an execution; a replay answers the same. - A cancellation answers 202 with a derived UNBLOCK order: its own orderId, and originalOrderId is the orderId of the original block. There is one cancellation per original block: its idempotency key is the original block's protocol and blockSequence and its kind, whatever its clientOrderId and whatever its blockReiteration (as the Lerian SISBAJUD Mensageria keeps one cancellation row per block). The same cancellation again (same blockReiteration, same content: the whole body except clientOrderId) answers 200 with the orderId and current state of the derived UNBLOCK already created, with no second effect; a cancellation under another blockReiteration (for example 02 after 01) is a reiteration of it, compared under the reiteration content rule below, and the same content answers 200 with that same derived UNBLOCK, never a second one; different content is 409 content-conflict (SBJ-0016). - originalOrderId is on the submit response, the order view and every results item: the orderId of the order this one is derived from, null when it is not derived. **Parity criterion with the Lerian SISBAJUD Mensageria** (one rule for the whole contract). - where the Mensageria classifies an explicit value, the direct channel classifies it the same way: blockReiteration 00 is the original block whatever orderCancelled says, and from 01 on orderCancelled true is a cancellation and false a reiteration. - where the Mensageria infers a value from an absent field, the direct channel requires the field explicitly: orderCancelled is required when blockReiteration is not 00, where the Mensageria reads it as F (422 missing-operation-field); blockReiteration is always required by the schema, where the Mensageria reads a blank one as 00 (422 invalid-order). - where the Mensageria reads a blank movement reiteration as the original movement, the direct channel requires movementKey.movementReiteration (422 invalid-order). - A reiterated INFO is a new order: submit it as an INFO with its own clientOrderId; INFO carries no block key. **Declared divergences from the Lerian SISBAJUD Mensageria.** These are the only declared divergences; everything else follows the parity criterion above. - absent-order-cancelled: orderCancelled absent with blockReiteration other than 00 is 422 missing-operation-field; the Mensageria reads a blank ORDEM_CANCELADA as F, a reiteration. - absent-block-reiteration: a blank blockReiteration is 422 invalid-order; the Mensageria reads a blank REITERACAO_BLOQUEIO as 00, the original block. - absent-movement-reiteration: a blank movementReiteration (or a missing movementKey) is 422 invalid-order (422 missing-operation-field); the Mensageria reads a blank REITERACAO of the movement as the original movement and executes it. - reiteration-content-conflict: a reiteration of a block or of a movement whose content differs from the original's is 409 content-conflict (SBJ-0016), with no effect; content is every field except clientOrderId, orderRevision, deadlineAt, externalReference, metadata, the reiteration digits (blockReiteration, the cited parentBlockKey.blockReiteration, movementReiteration) and orderCancelled; the Mensageria answers it from the original without comparing its content. - duplicate-normative-key: a second submission under a normative key already used in the institution, whatever its kind, is never a second order: a second original block, original movement or cancellation answers 200 with the response of the accepted one when its content (the whole body except clientOrderId, and except the digits the key leaves out) is the same, and 409 content-conflict (SBJ-0016) otherwise; a cancellation under another blockReiteration is compared under the reiteration rule; a repeated reiteration (block or movement) is answered from the original again, under the same reiteration rule; the Mensageria persists every order, reiterations included, under its record key with a unique index per institution, with no content comparison and no replay answer. - movement-key-carries-operation-type: the identity of a movement (its uniqueness key and the lookup key of the original of a reiterated movement) carries the operation type, so an UNBLOCK and a TRANSFER with the same movementSequence under the same block are distinct movements; the Mensageria keys a movement without its type, so UNBLOCK n and TRANSFER n under the same block collide. - movement-key-ignores-cited-block-reiteration: the key of a movement (the uniqueness of an original and the lookup of the original of a reiterated movement) reads the blockReiteration its parentBlockKey cites as 00, as when the parent is checked: a second original UNBLOCK or TRANSFER that differs only in that digit is found under the first and is 409 content-conflict (SBJ-0016), never a second execution, and a reiterated movement citing 01 resolves to an original that cited 00; the Mensageria keeps the cited REITERACAO_BLOQUEIO in the record key of a movement, so two such movements are two orders and both execute, and a reiteration citing another digit does not find its original. **Error catalog** (RFC 9457; `type` = https://errors.lerian.studio/v1/, one code per entry). | Status | Code | Type | Slug | Title | Meaning | |---|---|---|---|---|---| | 400 | SBJ-0001 | https://errors.lerian.studio/v1/SBJ-0001 | malformed-request | Malformed request | The request body or a path/query parameter could not be parsed. | | 401 | SBJ-0003 | https://errors.lerian.studio/v1/SBJ-0003 | unauthorized | Unauthorized | The bearer token is missing, expired or invalid. | | 403 | SBJ-0004 | https://errors.lerian.studio/v1/SBJ-0004 | forbidden | Forbidden | The credential is not authorized for this action. | | 404 | SBJ-0015 | https://errors.lerian.studio/v1/SBJ-0015 | order-not-found | Not found | No such direct-channel order in this institution (single-order routes only; list routes answer an empty page). | | 409 | SBJ-0016 | https://errors.lerian.studio/v1/SBJ-0016 | content-conflict | Content conflict | This clientOrderId and orderRevision were already accepted with a different body, the externalReference differs from revision 1, or a submission under a normative key already used in this institution carries a different body: a second original block or movement, or a second cancellation, with a different body, or a reiteration of a block or a movement whose content differs from the original's. | | 409 | SBJ-0017 | https://errors.lerian.studio/v1/SBJ-0017 | revision-stale | Revision stale | A higher orderRevision of this clientOrderId was already accepted. | | 413 | SBJ-0018 | https://errors.lerian.studio/v1/SBJ-0018 | body-too-large | Body too large | The request body exceeds the accepted size. | | 422 | SBJ-0019 | https://errors.lerian.studio/v1/SBJ-0019 | invalid-order | Invalid order | A field violates the contract schema or a field rule. | | 422 | SBJ-0020 | https://errors.lerian.studio/v1/SBJ-0020 | field-outside-operation | Field outside operation | A field or block was sent that the operation does not take. | | 422 | SBJ-0021 | https://errors.lerian.studio/v1/SBJ-0021 | missing-operation-field | Missing operation field | A field or block the operation requires is absent. | | 422 | SBJ-0022 | https://errors.lerian.studio/v1/SBJ-0022 | metadata-invalid | Metadata invalid | metadata exceeds 16 keys, a value of 256 bytes (UTF-8), 4096 bytes in total, or a key is outside ^[A-Za-z0-9_.-]{1,64}$. | | 422 | SBJ-0023 | https://errors.lerian.studio/v1/SBJ-0023 | personal-data-in-key | Personal data in client key | clientOrderId, parentClientOrderId or externalReference looks like it carries a CPF/CNPJ, a judicial process number or a long digit run. | | 422 | SBJ-0024 | https://errors.lerian.studio/v1/SBJ-0024 | institution-mismatch | Institution mismatch | responsibleInstitutionCnpj does not match the registered code of the institution in the path. | | 422 | SBJ-0025 | https://errors.lerian.studio/v1/SBJ-0025 | institution-channel-not-direct | Institution not on the direct channel | The institution in the path does not take orders through the direct channel. | | 422 | SBJ-0026 | https://errors.lerian.studio/v1/SBJ-0026 | parent-not-in-custody | Child not taken into custody | The plugin does not accept custody of this child: no matching registered parent in this institution. The order remains due; answering the court is the client's duty. | | 429 | SBJ-0009 | https://errors.lerian.studio/v1/SBJ-0009 | rate-limited | Too many requests | The client exceeded its request rate. | | 422 | SBJ-0027 | https://errors.lerian.studio/v1/SBJ-0027 | permanent-block-not-supported | Permanent block not supported | This deployment does not take permanent blocks: an original BLOCK with block.permanent true, or a reiteration of a permanent original block, is refused. A cancellation and every UNBLOCK or TRANSFER of a permanent block are taken. Nothing is recorded; the order remains due. | The single parent-not-in-custody 422 covers parent not found, parent not BLOCK and holder divergent alike; it carries no court response code, and the order remains due. A request-schema violation (missing field, type, pattern) is the same 422 invalid-order, and no 422 echoes a rejected personal-data or client-key value. 404 exists only on the single-order routes and is uniform: unknown order, other institution, or an order not of direct origin. The list routes (search and feed) answer 200 for any institution and list only orders of direct origin: an empty page when there are none, and direct history stays readable after the institution switches channel. A POST to an institution whose channel is not DIRECT is 422 institution-channel-not-direct. operationId: get-direct-order 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 format: uuid type: string - description: Server-generated order id (UUIDv7). in: path name: orderId required: true schema: description: Server-generated order id (UUIDv7). examples: - 01929b3e-7c1a-7d2e-9a5e-6c1c1c1a0001 format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/OrderView" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "429": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Too Many Requests "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error summary: Get a direct order tags: - Executor x-mint: href: /en/reference/interfaces/plugin-sisbajud/get-a-direct-order /v1/institutions/{institutionId}/executor/orders/{orderId}/results: get: description: | Returns every execution version of the order after afterVersion. With a read replica configured, this read is eventually consistent: a result may appear a moment after it was written. **Direct channel rules.** - Answering the court (the 5302 response, and every later answer) is the duty of the client's messaging; the plugin never builds it. The response echoes institutionCode, the code the client answers for. - Submit a child (UNBLOCK/TRANSFER) only after the parent's 202. - A consumer keeps, per order, the highest executionVersion of the highest orderRevision wins. - The results feed is at-least-once: deduplicate by (orderId, orderRevision, executionVersion). - clientOrderId and externalReference are opaque client keys and MUST NOT contain personal data or judicial identifiers. - The personal-data guard is fail-closed and can refuse a legitimate key (422 personal-data-in-key). Use a hyphenated UUID as clientOrderId: 3 to 4 refusals measured over 20000 (0.02%, a valid CPF or CNPJ inside one of its digit groups); on a refusal, generate another UUID. Measured refusals of other shapes: 0 for ORD-YYYY-MM-DD-NNNN and for ULIDs; 0.2% for UUIDs without hyphens; 2.3% for keys whose separated digit groups add up to exactly 11 digits (ord-YYYY-MM-DD-NNN). - Avoid 32-hex keys (UUIDs without hyphens) as clientOrderId or externalReference: the long-digit-run check is not applied to them (it would refuse about 5% of random ones), so the guard is weaker on that shape. Use a hyphenated UUID. - A past deadlineAt is accepted (202) and signalled by deadlinePassedAtReceipt / cutPassedAtReceipt; it is never refused. **Permanent block** (layout INDICADOR_BLOQUEIO_PERMANENTE and DATA_PRAZO_BLOQUEIO_PERMANENTE). - "T" (traditional) is block.permanent false or absent; "P" (permanent) is block.permanent true without block.permanentUntil; "D" (permanent with a deadline) is block.permanent true with block.permanentUntil (the deadline). - block.permanentUntil without block.permanent true is no layout value: 422 invalid-order. - While the deployment does not take permanent blocks (the default), the CREATION of a permanent block is refused with 422 permanent-block-not-supported: an original BLOCK with block.permanent true (P and D alike) and a reiteration (orderCancelled false) of a permanent original block. Nothing is recorded and the order remains due: answering the court is the client's duty. - What releases money is never refused for being permanent: the cancellation (orderCancelled true) of a permanent original, and every UNBLOCK or TRANSFER of a permanent parent block, are taken as for any other block. - INTERRUPT (layout record "10") stops a permanent block and is never refused by that policy: stopping is the safe side. It carries parentClientOrderId and parentBlockKey only (its key is the permanent's), its parent must be a permanent block in custody (otherwise 422 parent-not-in-custody, or 422 invalid-order when the parent is a traditional block), it keeps what is already blocked, and it is idempotent by clientOrderId. Its result is a RESULT with permanentBlock CLOSED / INTERRUPTED; resending it to a closed permanent reports the same state. - terminal=true always arrives on a RESULT. A permanent order's subsequent blocks are PERMANENT_BLOCK items with terminal false while it is ACTIVE; when it closes (TARGET_REACHED, EXPIRED, INTERRUPTED, RELEASED) the permanent's own order gets exactly one close RESULT: RESOLVED, effect NONE, no products, permanentBlock CLOSED with the reason, terminal true. terminal=true arrives on the LAST RESULT item of the order: the outcome no longer changes. PERMANENT_BLOCK items may follow it (money landing after the close, a held block republished after the close); they never reopen the permanent. Read past the terminal RESULT: PERMANENT_BLOCK items can follow it. The INTERRUPT and the TRANSFER that caused the close are answered on their own orders as usual. **Reiteration and cancellation of a block** (SISBAJUD manual: they exist only for a block not answered; layout REITERACAO_BLOQUEIO and ORDEM_CANCELADA). - A BLOCK with blockReiteration other than 00 is never a new block. orderCancelled is required when blockReiteration is not 00 (422 missing-operation-field without it). - blockReiteration 00 with any orderCancelled is the original block (the flag is ignored, as the Lerian SISBAJUD Mensageria classifies it). - Reiteration (blockReiteration 01 or higher, orderCancelled false): the plugin resolves the ORIGINAL block by the same protocol and blockSequence, in the same institution (the reiteration digits are not part of the lookup), and returns the original's result, the outcome of its first execution: no new block and no new revision. While the original is not yet determined, the answer is the current state of the original, never a new execution. - Cancellation (blockReiteration 01 or higher, orderCancelled true): a derived unblock of the original's effect, limited to its remaining balance; an original already unblocked gets no second effect. - The original block (blockReiteration 00) is unique per institution by protocol and blockSequence, whatever its clientOrderId (as the Lerian SISBAJUD Mensageria keeps one order per institution and record key). A second original with the same protocol and blockSequence in the same institution is never a second block: the same content answers 200 with the response of the original already accepted; different content is 409 content-conflict (SBJ-0016). Content is the whole body except clientOrderId. - An original that is not registered in the institution (reiteration or cancellation alike) is the same 422 parent-not-in-custody as an unknown parent: the same body, except instance. - An UNBLOCK/TRANSFER's parentBlockKey names its parent block by protocol and blockSequence; its blockReiteration digits are ignored when it is checked against the parent (as the Lerian SISBAJUD Mensageria resolves the cited block). **Reiteration of an unblock or a transfer** (layout REITERACAO_DESBLOQUEIO / REITERACAO_TRANSFERENCIA). - An UNBLOCK/TRANSFER carries its own movementKey: movementSequence (SEQUENCIAL_DESBLOQUEIO / SEQUENCIAL_TRANSFERENCIA, 5 digits) and movementReiteration (2 digits, always required). movementReiteration 00 is the original movement; 01 or higher is a reiteration of a movement already sent, never a new movement. - A reiterated movement resolves to the ORIGINAL movement by institution, operation (UNBLOCK or TRANSFER: their sequences are separate counters), the cited parentBlockKey's protocol and blockSequence (its blockReiteration is ignored, as when it is checked against the parent: a reiteration citing 01 resolves to an original that cited 00), the same movementSequence and movementReiteration 00 (its own reiteration digits are not part of the lookup), and is answered from it with no new effect: no second unblock, no second transfer, no ledger write. A reiterated movement whose original is not registered in the institution is the same 422 parent-not-in-custody. - The original movement (movementReiteration 00) is unique per institution by that same key (operation included), whatever its clientOrderId and whatever blockReiteration its parentBlockKey cites, with the same 200 / 409 rule as the original block: an identical body is a 200 replay; any other body is 409 content-conflict (SBJ-0016), including one that differs only in the cited blockReiteration (a second order, not a reiteration); never a second movement. - Content of a reiteration (block or movement): it is compared with the original's on every field except clientOrderId, orderRevision, deadlineAt, externalReference, metadata, the reiteration digits (blockReiteration, the cited parentBlockKey.blockReiteration, movementReiteration) and orderCancelled. The same content is answered from the original; different content is 409 content-conflict (SBJ-0016). **Answers to a reiteration, a cancellation and their replays.** - A block reiteration and a reiterated movement answer 200 with the ORIGINAL order: its orderId, its clientOrderId and its current state (originalOrderId null), never 202 and never an execution; a replay answers the same. - A cancellation answers 202 with a derived UNBLOCK order: its own orderId, and originalOrderId is the orderId of the original block. There is one cancellation per original block: its idempotency key is the original block's protocol and blockSequence and its kind, whatever its clientOrderId and whatever its blockReiteration (as the Lerian SISBAJUD Mensageria keeps one cancellation row per block). The same cancellation again (same blockReiteration, same content: the whole body except clientOrderId) answers 200 with the orderId and current state of the derived UNBLOCK already created, with no second effect; a cancellation under another blockReiteration (for example 02 after 01) is a reiteration of it, compared under the reiteration content rule below, and the same content answers 200 with that same derived UNBLOCK, never a second one; different content is 409 content-conflict (SBJ-0016). - originalOrderId is on the submit response, the order view and every results item: the orderId of the order this one is derived from, null when it is not derived. **Parity criterion with the Lerian SISBAJUD Mensageria** (one rule for the whole contract). - where the Mensageria classifies an explicit value, the direct channel classifies it the same way: blockReiteration 00 is the original block whatever orderCancelled says, and from 01 on orderCancelled true is a cancellation and false a reiteration. - where the Mensageria infers a value from an absent field, the direct channel requires the field explicitly: orderCancelled is required when blockReiteration is not 00, where the Mensageria reads it as F (422 missing-operation-field); blockReiteration is always required by the schema, where the Mensageria reads a blank one as 00 (422 invalid-order). - where the Mensageria reads a blank movement reiteration as the original movement, the direct channel requires movementKey.movementReiteration (422 invalid-order). - A reiterated INFO is a new order: submit it as an INFO with its own clientOrderId; INFO carries no block key. **Declared divergences from the Lerian SISBAJUD Mensageria.** These are the only declared divergences; everything else follows the parity criterion above. - absent-order-cancelled: orderCancelled absent with blockReiteration other than 00 is 422 missing-operation-field; the Mensageria reads a blank ORDEM_CANCELADA as F, a reiteration. - absent-block-reiteration: a blank blockReiteration is 422 invalid-order; the Mensageria reads a blank REITERACAO_BLOQUEIO as 00, the original block. - absent-movement-reiteration: a blank movementReiteration (or a missing movementKey) is 422 invalid-order (422 missing-operation-field); the Mensageria reads a blank REITERACAO of the movement as the original movement and executes it. - reiteration-content-conflict: a reiteration of a block or of a movement whose content differs from the original's is 409 content-conflict (SBJ-0016), with no effect; content is every field except clientOrderId, orderRevision, deadlineAt, externalReference, metadata, the reiteration digits (blockReiteration, the cited parentBlockKey.blockReiteration, movementReiteration) and orderCancelled; the Mensageria answers it from the original without comparing its content. - duplicate-normative-key: a second submission under a normative key already used in the institution, whatever its kind, is never a second order: a second original block, original movement or cancellation answers 200 with the response of the accepted one when its content (the whole body except clientOrderId, and except the digits the key leaves out) is the same, and 409 content-conflict (SBJ-0016) otherwise; a cancellation under another blockReiteration is compared under the reiteration rule; a repeated reiteration (block or movement) is answered from the original again, under the same reiteration rule; the Mensageria persists every order, reiterations included, under its record key with a unique index per institution, with no content comparison and no replay answer. - movement-key-carries-operation-type: the identity of a movement (its uniqueness key and the lookup key of the original of a reiterated movement) carries the operation type, so an UNBLOCK and a TRANSFER with the same movementSequence under the same block are distinct movements; the Mensageria keys a movement without its type, so UNBLOCK n and TRANSFER n under the same block collide. - movement-key-ignores-cited-block-reiteration: the key of a movement (the uniqueness of an original and the lookup of the original of a reiterated movement) reads the blockReiteration its parentBlockKey cites as 00, as when the parent is checked: a second original UNBLOCK or TRANSFER that differs only in that digit is found under the first and is 409 content-conflict (SBJ-0016), never a second execution, and a reiterated movement citing 01 resolves to an original that cited 00; the Mensageria keeps the cited REITERACAO_BLOQUEIO in the record key of a movement, so two such movements are two orders and both execute, and a reiteration citing another digit does not find its original. **Error catalog** (RFC 9457; `type` = https://errors.lerian.studio/v1/, one code per entry). | Status | Code | Type | Slug | Title | Meaning | |---|---|---|---|---|---| | 400 | SBJ-0001 | https://errors.lerian.studio/v1/SBJ-0001 | malformed-request | Malformed request | The request body or a path/query parameter could not be parsed. | | 401 | SBJ-0003 | https://errors.lerian.studio/v1/SBJ-0003 | unauthorized | Unauthorized | The bearer token is missing, expired or invalid. | | 403 | SBJ-0004 | https://errors.lerian.studio/v1/SBJ-0004 | forbidden | Forbidden | The credential is not authorized for this action. | | 404 | SBJ-0015 | https://errors.lerian.studio/v1/SBJ-0015 | order-not-found | Not found | No such direct-channel order in this institution (single-order routes only; list routes answer an empty page). | | 409 | SBJ-0016 | https://errors.lerian.studio/v1/SBJ-0016 | content-conflict | Content conflict | This clientOrderId and orderRevision were already accepted with a different body, the externalReference differs from revision 1, or a submission under a normative key already used in this institution carries a different body: a second original block or movement, or a second cancellation, with a different body, or a reiteration of a block or a movement whose content differs from the original's. | | 409 | SBJ-0017 | https://errors.lerian.studio/v1/SBJ-0017 | revision-stale | Revision stale | A higher orderRevision of this clientOrderId was already accepted. | | 413 | SBJ-0018 | https://errors.lerian.studio/v1/SBJ-0018 | body-too-large | Body too large | The request body exceeds the accepted size. | | 422 | SBJ-0019 | https://errors.lerian.studio/v1/SBJ-0019 | invalid-order | Invalid order | A field violates the contract schema or a field rule. | | 422 | SBJ-0020 | https://errors.lerian.studio/v1/SBJ-0020 | field-outside-operation | Field outside operation | A field or block was sent that the operation does not take. | | 422 | SBJ-0021 | https://errors.lerian.studio/v1/SBJ-0021 | missing-operation-field | Missing operation field | A field or block the operation requires is absent. | | 422 | SBJ-0022 | https://errors.lerian.studio/v1/SBJ-0022 | metadata-invalid | Metadata invalid | metadata exceeds 16 keys, a value of 256 bytes (UTF-8), 4096 bytes in total, or a key is outside ^[A-Za-z0-9_.-]{1,64}$. | | 422 | SBJ-0023 | https://errors.lerian.studio/v1/SBJ-0023 | personal-data-in-key | Personal data in client key | clientOrderId, parentClientOrderId or externalReference looks like it carries a CPF/CNPJ, a judicial process number or a long digit run. | | 422 | SBJ-0024 | https://errors.lerian.studio/v1/SBJ-0024 | institution-mismatch | Institution mismatch | responsibleInstitutionCnpj does not match the registered code of the institution in the path. | | 422 | SBJ-0025 | https://errors.lerian.studio/v1/SBJ-0025 | institution-channel-not-direct | Institution not on the direct channel | The institution in the path does not take orders through the direct channel. | | 422 | SBJ-0026 | https://errors.lerian.studio/v1/SBJ-0026 | parent-not-in-custody | Child not taken into custody | The plugin does not accept custody of this child: no matching registered parent in this institution. The order remains due; answering the court is the client's duty. | | 429 | SBJ-0009 | https://errors.lerian.studio/v1/SBJ-0009 | rate-limited | Too many requests | The client exceeded its request rate. | | 422 | SBJ-0027 | https://errors.lerian.studio/v1/SBJ-0027 | permanent-block-not-supported | Permanent block not supported | This deployment does not take permanent blocks: an original BLOCK with block.permanent true, or a reiteration of a permanent original block, is refused. A cancellation and every UNBLOCK or TRANSFER of a permanent block are taken. Nothing is recorded; the order remains due. | The single parent-not-in-custody 422 covers parent not found, parent not BLOCK and holder divergent alike; it carries no court response code, and the order remains due. A request-schema violation (missing field, type, pattern) is the same 422 invalid-order, and no 422 echoes a rejected personal-data or client-key value. 404 exists only on the single-order routes and is uniform: unknown order, other institution, or an order not of direct origin. The list routes (search and feed) answer 200 for any institution and list only orders of direct origin: an empty page when there are none, and direct history stays readable after the institution switches channel. A POST to an institution whose channel is not DIRECT is 422 institution-channel-not-direct. operationId: list-direct-order-results 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 format: uuid type: string - description: Server-generated order id (UUIDv7). in: path name: orderId required: true schema: description: Server-generated order id (UUIDv7). examples: - 01929b3e-7c1a-7d2e-9a5e-6c1c1c1a0001 format: uuid type: string - description: Return only executionVersion greater than this. explode: false in: query name: afterVersion schema: description: Return only executionVersion greater than this. format: int64 minimum: 0 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/ResultPage" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "429": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Too Many Requests "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error summary: List the result versions of a direct order tags: - Executor x-mint: href: /en/reference/interfaces/plugin-sisbajud/list-the-result-versions-of-a-direct-order /v1/institutions/{institutionId}/executor/results: get: description: | Cursor-paginated, at-least-once feed of every result version of the institution's orders of direct origin. 200 for any institution: an empty page when it has no direct history; direct history stays readable after a channel switch. Every item carries kind. Clients MUST ignore items whose kind they do not recognise. The feed does not signal human-decision holds. Clients poll GET /v1/institutions/{institutionId}/executor/human-decisions after each response deadline (19h and 12h, business days); for an order with humanDisposition HELD_MONEY_MOVED they must not answer the court before the human resolution. With a read replica configured, this read is eventually consistent: a result may appear a moment after it was written. **Direct channel rules.** - Answering the court (the 5302 response, and every later answer) is the duty of the client's messaging; the plugin never builds it. The response echoes institutionCode, the code the client answers for. - Submit a child (UNBLOCK/TRANSFER) only after the parent's 202. - A consumer keeps, per order, the highest executionVersion of the highest orderRevision wins. - The results feed is at-least-once: deduplicate by (orderId, orderRevision, executionVersion). - clientOrderId and externalReference are opaque client keys and MUST NOT contain personal data or judicial identifiers. - The personal-data guard is fail-closed and can refuse a legitimate key (422 personal-data-in-key). Use a hyphenated UUID as clientOrderId: 3 to 4 refusals measured over 20000 (0.02%, a valid CPF or CNPJ inside one of its digit groups); on a refusal, generate another UUID. Measured refusals of other shapes: 0 for ORD-YYYY-MM-DD-NNNN and for ULIDs; 0.2% for UUIDs without hyphens; 2.3% for keys whose separated digit groups add up to exactly 11 digits (ord-YYYY-MM-DD-NNN). - Avoid 32-hex keys (UUIDs without hyphens) as clientOrderId or externalReference: the long-digit-run check is not applied to them (it would refuse about 5% of random ones), so the guard is weaker on that shape. Use a hyphenated UUID. - A past deadlineAt is accepted (202) and signalled by deadlinePassedAtReceipt / cutPassedAtReceipt; it is never refused. **Permanent block** (layout INDICADOR_BLOQUEIO_PERMANENTE and DATA_PRAZO_BLOQUEIO_PERMANENTE). - "T" (traditional) is block.permanent false or absent; "P" (permanent) is block.permanent true without block.permanentUntil; "D" (permanent with a deadline) is block.permanent true with block.permanentUntil (the deadline). - block.permanentUntil without block.permanent true is no layout value: 422 invalid-order. - While the deployment does not take permanent blocks (the default), the CREATION of a permanent block is refused with 422 permanent-block-not-supported: an original BLOCK with block.permanent true (P and D alike) and a reiteration (orderCancelled false) of a permanent original block. Nothing is recorded and the order remains due: answering the court is the client's duty. - What releases money is never refused for being permanent: the cancellation (orderCancelled true) of a permanent original, and every UNBLOCK or TRANSFER of a permanent parent block, are taken as for any other block. - INTERRUPT (layout record "10") stops a permanent block and is never refused by that policy: stopping is the safe side. It carries parentClientOrderId and parentBlockKey only (its key is the permanent's), its parent must be a permanent block in custody (otherwise 422 parent-not-in-custody, or 422 invalid-order when the parent is a traditional block), it keeps what is already blocked, and it is idempotent by clientOrderId. Its result is a RESULT with permanentBlock CLOSED / INTERRUPTED; resending it to a closed permanent reports the same state. - terminal=true always arrives on a RESULT. A permanent order's subsequent blocks are PERMANENT_BLOCK items with terminal false while it is ACTIVE; when it closes (TARGET_REACHED, EXPIRED, INTERRUPTED, RELEASED) the permanent's own order gets exactly one close RESULT: RESOLVED, effect NONE, no products, permanentBlock CLOSED with the reason, terminal true. terminal=true arrives on the LAST RESULT item of the order: the outcome no longer changes. PERMANENT_BLOCK items may follow it (money landing after the close, a held block republished after the close); they never reopen the permanent. Read past the terminal RESULT: PERMANENT_BLOCK items can follow it. The INTERRUPT and the TRANSFER that caused the close are answered on their own orders as usual. **Reiteration and cancellation of a block** (SISBAJUD manual: they exist only for a block not answered; layout REITERACAO_BLOQUEIO and ORDEM_CANCELADA). - A BLOCK with blockReiteration other than 00 is never a new block. orderCancelled is required when blockReiteration is not 00 (422 missing-operation-field without it). - blockReiteration 00 with any orderCancelled is the original block (the flag is ignored, as the Lerian SISBAJUD Mensageria classifies it). - Reiteration (blockReiteration 01 or higher, orderCancelled false): the plugin resolves the ORIGINAL block by the same protocol and blockSequence, in the same institution (the reiteration digits are not part of the lookup), and returns the original's result, the outcome of its first execution: no new block and no new revision. While the original is not yet determined, the answer is the current state of the original, never a new execution. - Cancellation (blockReiteration 01 or higher, orderCancelled true): a derived unblock of the original's effect, limited to its remaining balance; an original already unblocked gets no second effect. - The original block (blockReiteration 00) is unique per institution by protocol and blockSequence, whatever its clientOrderId (as the Lerian SISBAJUD Mensageria keeps one order per institution and record key). A second original with the same protocol and blockSequence in the same institution is never a second block: the same content answers 200 with the response of the original already accepted; different content is 409 content-conflict (SBJ-0016). Content is the whole body except clientOrderId. - An original that is not registered in the institution (reiteration or cancellation alike) is the same 422 parent-not-in-custody as an unknown parent: the same body, except instance. - An UNBLOCK/TRANSFER's parentBlockKey names its parent block by protocol and blockSequence; its blockReiteration digits are ignored when it is checked against the parent (as the Lerian SISBAJUD Mensageria resolves the cited block). **Reiteration of an unblock or a transfer** (layout REITERACAO_DESBLOQUEIO / REITERACAO_TRANSFERENCIA). - An UNBLOCK/TRANSFER carries its own movementKey: movementSequence (SEQUENCIAL_DESBLOQUEIO / SEQUENCIAL_TRANSFERENCIA, 5 digits) and movementReiteration (2 digits, always required). movementReiteration 00 is the original movement; 01 or higher is a reiteration of a movement already sent, never a new movement. - A reiterated movement resolves to the ORIGINAL movement by institution, operation (UNBLOCK or TRANSFER: their sequences are separate counters), the cited parentBlockKey's protocol and blockSequence (its blockReiteration is ignored, as when it is checked against the parent: a reiteration citing 01 resolves to an original that cited 00), the same movementSequence and movementReiteration 00 (its own reiteration digits are not part of the lookup), and is answered from it with no new effect: no second unblock, no second transfer, no ledger write. A reiterated movement whose original is not registered in the institution is the same 422 parent-not-in-custody. - The original movement (movementReiteration 00) is unique per institution by that same key (operation included), whatever its clientOrderId and whatever blockReiteration its parentBlockKey cites, with the same 200 / 409 rule as the original block: an identical body is a 200 replay; any other body is 409 content-conflict (SBJ-0016), including one that differs only in the cited blockReiteration (a second order, not a reiteration); never a second movement. - Content of a reiteration (block or movement): it is compared with the original's on every field except clientOrderId, orderRevision, deadlineAt, externalReference, metadata, the reiteration digits (blockReiteration, the cited parentBlockKey.blockReiteration, movementReiteration) and orderCancelled. The same content is answered from the original; different content is 409 content-conflict (SBJ-0016). **Answers to a reiteration, a cancellation and their replays.** - A block reiteration and a reiterated movement answer 200 with the ORIGINAL order: its orderId, its clientOrderId and its current state (originalOrderId null), never 202 and never an execution; a replay answers the same. - A cancellation answers 202 with a derived UNBLOCK order: its own orderId, and originalOrderId is the orderId of the original block. There is one cancellation per original block: its idempotency key is the original block's protocol and blockSequence and its kind, whatever its clientOrderId and whatever its blockReiteration (as the Lerian SISBAJUD Mensageria keeps one cancellation row per block). The same cancellation again (same blockReiteration, same content: the whole body except clientOrderId) answers 200 with the orderId and current state of the derived UNBLOCK already created, with no second effect; a cancellation under another blockReiteration (for example 02 after 01) is a reiteration of it, compared under the reiteration content rule below, and the same content answers 200 with that same derived UNBLOCK, never a second one; different content is 409 content-conflict (SBJ-0016). - originalOrderId is on the submit response, the order view and every results item: the orderId of the order this one is derived from, null when it is not derived. **Parity criterion with the Lerian SISBAJUD Mensageria** (one rule for the whole contract). - where the Mensageria classifies an explicit value, the direct channel classifies it the same way: blockReiteration 00 is the original block whatever orderCancelled says, and from 01 on orderCancelled true is a cancellation and false a reiteration. - where the Mensageria infers a value from an absent field, the direct channel requires the field explicitly: orderCancelled is required when blockReiteration is not 00, where the Mensageria reads it as F (422 missing-operation-field); blockReiteration is always required by the schema, where the Mensageria reads a blank one as 00 (422 invalid-order). - where the Mensageria reads a blank movement reiteration as the original movement, the direct channel requires movementKey.movementReiteration (422 invalid-order). - A reiterated INFO is a new order: submit it as an INFO with its own clientOrderId; INFO carries no block key. **Declared divergences from the Lerian SISBAJUD Mensageria.** These are the only declared divergences; everything else follows the parity criterion above. - absent-order-cancelled: orderCancelled absent with blockReiteration other than 00 is 422 missing-operation-field; the Mensageria reads a blank ORDEM_CANCELADA as F, a reiteration. - absent-block-reiteration: a blank blockReiteration is 422 invalid-order; the Mensageria reads a blank REITERACAO_BLOQUEIO as 00, the original block. - absent-movement-reiteration: a blank movementReiteration (or a missing movementKey) is 422 invalid-order (422 missing-operation-field); the Mensageria reads a blank REITERACAO of the movement as the original movement and executes it. - reiteration-content-conflict: a reiteration of a block or of a movement whose content differs from the original's is 409 content-conflict (SBJ-0016), with no effect; content is every field except clientOrderId, orderRevision, deadlineAt, externalReference, metadata, the reiteration digits (blockReiteration, the cited parentBlockKey.blockReiteration, movementReiteration) and orderCancelled; the Mensageria answers it from the original without comparing its content. - duplicate-normative-key: a second submission under a normative key already used in the institution, whatever its kind, is never a second order: a second original block, original movement or cancellation answers 200 with the response of the accepted one when its content (the whole body except clientOrderId, and except the digits the key leaves out) is the same, and 409 content-conflict (SBJ-0016) otherwise; a cancellation under another blockReiteration is compared under the reiteration rule; a repeated reiteration (block or movement) is answered from the original again, under the same reiteration rule; the Mensageria persists every order, reiterations included, under its record key with a unique index per institution, with no content comparison and no replay answer. - movement-key-carries-operation-type: the identity of a movement (its uniqueness key and the lookup key of the original of a reiterated movement) carries the operation type, so an UNBLOCK and a TRANSFER with the same movementSequence under the same block are distinct movements; the Mensageria keys a movement without its type, so UNBLOCK n and TRANSFER n under the same block collide. - movement-key-ignores-cited-block-reiteration: the key of a movement (the uniqueness of an original and the lookup of the original of a reiterated movement) reads the blockReiteration its parentBlockKey cites as 00, as when the parent is checked: a second original UNBLOCK or TRANSFER that differs only in that digit is found under the first and is 409 content-conflict (SBJ-0016), never a second execution, and a reiterated movement citing 01 resolves to an original that cited 00; the Mensageria keeps the cited REITERACAO_BLOQUEIO in the record key of a movement, so two such movements are two orders and both execute, and a reiteration citing another digit does not find its original. **Error catalog** (RFC 9457; `type` = https://errors.lerian.studio/v1/, one code per entry). | Status | Code | Type | Slug | Title | Meaning | |---|---|---|---|---|---| | 400 | SBJ-0001 | https://errors.lerian.studio/v1/SBJ-0001 | malformed-request | Malformed request | The request body or a path/query parameter could not be parsed. | | 401 | SBJ-0003 | https://errors.lerian.studio/v1/SBJ-0003 | unauthorized | Unauthorized | The bearer token is missing, expired or invalid. | | 403 | SBJ-0004 | https://errors.lerian.studio/v1/SBJ-0004 | forbidden | Forbidden | The credential is not authorized for this action. | | 404 | SBJ-0015 | https://errors.lerian.studio/v1/SBJ-0015 | order-not-found | Not found | No such direct-channel order in this institution (single-order routes only; list routes answer an empty page). | | 409 | SBJ-0016 | https://errors.lerian.studio/v1/SBJ-0016 | content-conflict | Content conflict | This clientOrderId and orderRevision were already accepted with a different body, the externalReference differs from revision 1, or a submission under a normative key already used in this institution carries a different body: a second original block or movement, or a second cancellation, with a different body, or a reiteration of a block or a movement whose content differs from the original's. | | 409 | SBJ-0017 | https://errors.lerian.studio/v1/SBJ-0017 | revision-stale | Revision stale | A higher orderRevision of this clientOrderId was already accepted. | | 413 | SBJ-0018 | https://errors.lerian.studio/v1/SBJ-0018 | body-too-large | Body too large | The request body exceeds the accepted size. | | 422 | SBJ-0019 | https://errors.lerian.studio/v1/SBJ-0019 | invalid-order | Invalid order | A field violates the contract schema or a field rule. | | 422 | SBJ-0020 | https://errors.lerian.studio/v1/SBJ-0020 | field-outside-operation | Field outside operation | A field or block was sent that the operation does not take. | | 422 | SBJ-0021 | https://errors.lerian.studio/v1/SBJ-0021 | missing-operation-field | Missing operation field | A field or block the operation requires is absent. | | 422 | SBJ-0022 | https://errors.lerian.studio/v1/SBJ-0022 | metadata-invalid | Metadata invalid | metadata exceeds 16 keys, a value of 256 bytes (UTF-8), 4096 bytes in total, or a key is outside ^[A-Za-z0-9_.-]{1,64}$. | | 422 | SBJ-0023 | https://errors.lerian.studio/v1/SBJ-0023 | personal-data-in-key | Personal data in client key | clientOrderId, parentClientOrderId or externalReference looks like it carries a CPF/CNPJ, a judicial process number or a long digit run. | | 422 | SBJ-0024 | https://errors.lerian.studio/v1/SBJ-0024 | institution-mismatch | Institution mismatch | responsibleInstitutionCnpj does not match the registered code of the institution in the path. | | 422 | SBJ-0025 | https://errors.lerian.studio/v1/SBJ-0025 | institution-channel-not-direct | Institution not on the direct channel | The institution in the path does not take orders through the direct channel. | | 422 | SBJ-0026 | https://errors.lerian.studio/v1/SBJ-0026 | parent-not-in-custody | Child not taken into custody | The plugin does not accept custody of this child: no matching registered parent in this institution. The order remains due; answering the court is the client's duty. | | 429 | SBJ-0009 | https://errors.lerian.studio/v1/SBJ-0009 | rate-limited | Too many requests | The client exceeded its request rate. | | 422 | SBJ-0027 | https://errors.lerian.studio/v1/SBJ-0027 | permanent-block-not-supported | Permanent block not supported | This deployment does not take permanent blocks: an original BLOCK with block.permanent true, or a reiteration of a permanent original block, is refused. A cancellation and every UNBLOCK or TRANSFER of a permanent block are taken. Nothing is recorded; the order remains due. | The single parent-not-in-custody 422 covers parent not found, parent not BLOCK and holder divergent alike; it carries no court response code, and the order remains due. A request-schema violation (missing field, type, pattern) is the same 422 invalid-order, and no 422 echoes a rejected personal-data or client-key value. 404 exists only on the single-order routes and is uniform: unknown order, other institution, or an order not of direct origin. The list routes (search and feed) answer 200 for any institution and list only orders of direct origin: an empty page when there are none, and direct history stays readable after the institution switches channel. A POST to an institution whose channel is not DIRECT is 422 institution-channel-not-direct. operationId: list-direct-results 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 format: uuid type: string - description: Opaque cursor from a previous page; absent = from the start. explode: false in: query name: cursor schema: description: Opaque cursor from a previous page; absent = from the start. maxLength: 512 type: string - description: Maximum items per page. explode: false in: query name: limit schema: default: 50 description: Maximum items per page. format: int64 maximum: 200 minimum: 1 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/ResultPage" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "429": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Too Many Requests "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error summary: Direct results feed tags: - Executor x-mint: href: /en/reference/interfaces/plugin-sisbajud/direct-results-feed /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: /en/reference/interfaces/plugin-sisbajud/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