Operate Lerian Consignado — Dataprev

Operational guidance for Consignado: workers, idempotency, rail windows, throughput, reconciliation, credentials, and failure recovery.

Operate Lerian Consignado as a tenant-isolated rail, not as a stateless proxy. Commands, background reads, the outbox, and recovery state all participate in the contract.

Command and read surfaces

Use the authenticated HTTP API for client commands and queries. The API separates commands from reads. Each client operation requires an authorization action and runs in the caller’s tenant. Follow the operation’s idempotency requirements. Retries after timeouts are normal and must reuse the same business identity.

A mounted operation is not proof that a specific deployment wires its Dataprev adapter. An unavailable rail integration returns 501 Not Implemented for that request instead of disappearing from the API. The capabilities operation reports which operation families your deployment reaches. Registering the B3 instrument code of a confirmed contract does not call Dataprev, so it needs no rail switch.

The Lender command stream remains available for the supported integration commands. It is not a replacement for the complete HTTP surface. See Consignado events.

Scheduled workers

The gateway runs sixteen scheduled loops. They share delayed first execution, stable per-replica staggering, panic isolation, and graceful shutdown. Every loop except the auction fast lane also runs non-overlapping passes with positive jitter.

Worker	Purpose	Default cadence
Reconciliation poller	Reads bookkeeping and repasse data for every employer and evaluates expected settlement.	1 hour
Auction discovery poller	Lists open loan requests and publishes each new one.	1 hour
Auction fast lane	Lists the last 60 seconds of open loan requests and publishes each new one. Off by default.	1 second
Portability discovery poller	Lists open inbound portability requests and relays each one with its own expiry.	1 hour
Employment report poller	Reads employment termination data per tenant.	1 hour
Exclusion recovery	Drives admitted exclusions to a terminal state.	30 seconds
Averbação recovery	Converges averbações whose outcome was never established against the rail registry.	1 minute
Rail-command recovery	Converges refinancing, reversal, renegotiation, and portability-exclusion commands whose outcome was never established.	1 minute
Bid reconduction	Resends a bid whose rail answer was lost, under its original proposal number.	15 seconds
Credential cleanup	Expires stale tenant credentials under a lease.	30 seconds
Bid payload cleanup	Removes expired bid payloads and resolved auctions. Deletes the employment bond a margin read stored, 30 days after the last read.	1 minute
Proposal witness	Confirms accepted proposal terms against the durable client bid.	5 seconds
Outstanding-balance clock	Evaluates missed-installment and month-end balance obligations.	24 hours
Outstanding-balance resend	Sends the outstanding-balance reports that a competência turnover held back.	1 minute
Documentation deadline	Publishes the deadline signal for averbações that wait for their documentation. Off by default.	1 minute
Documentation follow-up	Reads each averbação that waits for its documentation at Dataprev, once a day per contract. Off by default.	5 minutes

Thirteen of the sixteen take their cadence from environment configuration and need a restart to change. The auction fast lane, bid payload cleanup, and proposal witness read their cadence through the Systemplane and take effect on the next delay.

Averbação recovery and rail-command recovery exist because a rail command can leave its outcome unestablished: the process died mid-call, or the rail never answered. They converge that state against the rail’s own registry instead of losing it. Bid reconduction resends a bid whose rail answer was lost, under its original proposal number. Each resend uses the tenant’s rail budget. The three loops are off by default. Enable the two recovery loops in any deployment that submits averbações or rail commands.

When Dataprev refuses the documentation, the request answers 422 with Dataprev’s codes in upstream, and the contract returns to attachment_pending. Send corrected documentation under a new X-Idempotency key, or exclude the contract. When the call ends without a verdict, such as a timeout, a Dataprev 5xx, or an unusable receipt, the request answers 503 or 504. The contract also returns to attachment_pending: send the same documentation again, under the same key or a new one. The averbação read shows the newest attempt that Dataprev did not accept in last_documentation_close.

A CCB attachment cut off mid-call stays in attachment_invoking until its attachment_invocation_deadline_at. After that instant, the next documentation or exclusion for the contract takes over the call. Once the gateway records a contract’s documentation, its exclusion answers 409 EXCLUSION_DOCUMENTATION_UNDERWAY until the contract is confirmed, even while it shows attachment_pending. In that state, send the same documentation again to complete it.

Once a month, Dataprev closes for its competência turnover and refuses requests. Four loops pause for that tenant when one of them meets that refusal. They are auction discovery, the auction fast lane, portability discovery, and bid reconduction. The pause lasts 5 minutes, then 15, then 30 for each later refusal. Averbação recovery, rail-command recovery, and reconciliation do not wait out that pause. Each of their passes stops calling Dataprev at the refusal and tries again on the next pass.

Client requests still reach Dataprev and receive its refusal. The scheduled-jobs report shows paused_until for a paused loop. On Lerian Cloud, the gateway publishes consignado.rail.paused once per turnover and consignado.rail.resumed when Dataprev answers again.

Rail windows

Rail defaults and constraints include:

• a 24-hour loan-auction validity window that Dataprev supplies and the gateway does not configure
• a 72-hour portability-request lookback
• 20 calendar days from the origin exclusion to register an inbound portability, when the request names the exclusion date
• 7 business days to reverse refinancing
• 7 days after an averbação to send its documentation through the CCB attachment. Find the averbações still waiting with GET /v1/consignado/averbacao-operations?status=attachment_pending, and read documentation_due_at and documentation_overdue on each one. An averbação you asked to exclude also stays in attachment_pending. Its documentation answers 409 AVERBACAO_EXCLUDED unless Dataprev rejected the exclusion. Before you send it, read GET /v1/consignado/contracts/{numero_contrato}/exclusion with the tenant’s own credential. A fund or originador credential cannot read it.
• a 48-hour auction-discovery window, with a five-minute clock-skew allowance

Treat these as rail constraints, not internal timeouts. Configure only settings exposed by the gateway when the Dataprev contract for the target environment requires a different value. The gateway does not let you change fixed values that Dataprev supplies, including the loan-auction validity window.

Throughput and pacing

Dataprev traffic is paced per tenant. The throughput API sets the tenant’s rate, from 0 to 25 requests per second, and no setting raises that ceiling. A tenant with no stored rate runs at 3 requests per second. A stored value of 0 pauses rail traffic for that tenant.

Reconciliation safety

Bookkeeping and repasse reads are independent. One failing source must not suppress the other. Expected repasses can emit three states:

• consignado.repasse.overdue: the expected movement is late
• consignado.repasse.resolved: the movement arrived after an overdue alarm
• consignado.repasse.unobserved: the gateway cannot currently prove presence or absence

Reconciliation reads every employer of each tenant it serves. A repasse closes its expectation by contract and competência, never by employer. A repasse record whose employer or competência no expectation can supply is held: the gateway does not publish it. The repasse-expectation list counts open expectations by employer. Read its freshness state first: an empty list proves nothing unless the state is fresh.

Credentials and artifacts

Rotate the tenant certificate, OAuth secret, requester code, and portal URL through the credentials API. Local certificate-file variables are a development fallback, not a substitute for tenant custody in managed deployments.

When Dataprev refuses the tenant’s OAuth client credentials, operations that reach Dataprev answer 409 DATAPREV_CREDENTIAL_REJECTED. The averbação and the CCB attachment answer it before they reserve anything. The exclusion does not: it answers with the operation parked in outcome_unknown. A command that answers RAIL_COMMAND_* codes answers 409 and also parks in outcome_unknown. An FGTS guarantee execution and a bid also answer 409 and park in unknown.

Correct the credentials, and reads work again. Send a refused averbação or CCB attachment again under the same key. To resume a parked bid, send it again under the same key. Any other parked write does not run again under its key: contact Lerian with the contract number. Revocation is permanent: for a revoked tenant, rail operations and credential uploads answer 409 DATAPREV_CREDENTIAL_REVOKED.

Registering a worker portal base URL is optional, for the tenant and for each originador. See Discover auctions and submit proposals for the order in which the gateway selects a portal.

CCB and rail artifacts use the configured object store. Keep the bucket private and deliver content only through the authenticated artifact operation.

The averbação carries no document, and a body of 1 MiB or more answers 413. The CCB attachment accepts a signed CCB and, after an averbação with the booking block, a biometrics pack. The base64 text of each is up to 8 MiB. A contract import that carries these documents follows the same limits. A contract correction accepts a corrected resource whose base64 text is up to 8 MiB.

Failure behavior

The rail fails closed on missing tenant identity, malformed command identifiers, and Dataprev endpoints outside the deployment policy: HTTPS in a managed deployment, loopback HTTP only otherwise. A managed deployment also fails closed on missing credentials and on unsupported adapters. Business facts are written through the outbox and delivered at least once. Consumers must deduplicate by CloudEvent source and ID.