> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Search direct orders by externalReference > 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. ## OpenAPI ````yaml /en/openapi/v3-current/sisbajud-executor.yaml get /v1/institutions/{institutionId}/executor/orders openapi: 3.1.0 info: description: >- API for the Lerian SISBAJUD executor, which runs judicial orders on Midaz. It covers institution and Midaz connector configuration, orders that need attention, ledger-routing checks, credential key rotation and audit verification. title: Lerian SISBAJUD Executor API version: 1.0.0 servers: - url: https://api.example.com description: >- Replace the example host with the URL provided during environment onboarding. security: - BearerAuth: [] 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 paths: /v1/institutions/{institutionId}/executor/orders: get: tags: - Executor summary: Search direct orders by externalReference 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 components: schemas: 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 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 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 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 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 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 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 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 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 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 securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.