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/<code>, 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.