1. Configure a tenant
Before a tenant can call the rail, register:- an ICP-Brasil A1 client certificate and private key
- OAuth2 client credentials
- the tenant’s three-digit Dataprev requester code
- optionally, the worker portal base URL offered as a formalization contact in bid proposals
DATAPREV_CREDENTIAL_REQUIRED. A revoked credential answers DATAPREV_CREDENTIAL_REVOKED, and a revocation is permanent. When Dataprev refuses the tenant’s OAuth client credentials, a read answers DATAPREV_CREDENTIAL_REJECTED, and a write can park. Correct the credentials in custody, then see Credentials and artifacts before you send a write again.
When partners originate loans in the tenant’s name, register each one as an originador. A deactivated originador cannot place bids, and the gateway keeps its record.
When the tenant assigns credits to funds, register each fund. A fund that the gateway learns from Lender’s fund facts needs no registration here. Until the gateway knows the fund, an averbação that names it answers FUNDO_NOT_REGISTERED.
An averbação names a Lender fund by its Lender id, and so does a Lender cessão. A fund’s CNPJ matters only for a Lender cessão fact without a fund id. The gateway then cedes the contract to the registered fund with that CNPJ.
2. Read worker data and margin
The margin endpoint authenticates the tenant, obtains the worker’s Dataprev authorization context, and returns the rail response without turning it into an underwriting decision. When Dataprev returns them, the answer also carries the worker, employment, and employer records. The API also exposes new employment links, termination reports, authorized FGTS records, and FGTS balance reads. The gateway keeps the eSocial category and the admission date from the latest margin read of each employment link. It deletes them 30 days after the last read. When the averbação’sdados_cadastrais does not declare these fields, consignado.contract.registered carries them from that margin read.
3. Discover auctions and submit proposals
A scheduled discovery loop lists open loan requests and publishes each new one. An optional fast lane repeats that listing every second. A client can then submit a bid through the authenticated HTTP API. The gateway retains the durable bid payload needed to prove what the client sent and later publishes the accepted-proposal witness. A bid can name an originador. The gateway refuses a bid for an unknown or deactivated originador. An originador that authenticates with its own credential bids under its own reference. Every proposal must reach the worker through at least one contact. The gateway adds a formalization portal as a contact when it finds one: on the bid first, then on the named originador, then on the tenant. When none of the three has a portal, each proposal must carry a client contact. Otherwise the gateway refuses the bid before it calls Dataprev. Portability auctions use a separate response operation and a bounded Dataprev request window.4. Register and fund the contract
The registration flow:- sends the averbação to Dataprev
- sends the contract’s documentation to Dataprev
- exposes registration status and rail documents
- records the client’s disbursement confirmation
- publishes immutable booking and payment facts through the outbox
nome_trabalhador, the worker’s full name. You mint the contract number: 2 to 15 letters or digits, with no spaces, accents, or symbols. The same rule applies to the new contract of a refinancing, a renegotiation, or an inbound portability.
With the booking block, the gateway checks the booking before it calls Dataprev and answers 422 when Lender cannot book it. The problem detail names the rule, and the error list gives each code. When Dataprev accepts the averbação, the operation answers attachment_pending and the gateway publishes consignado.averbacao.accepted. Dataprev then holds the payroll-deduction mandate, and the contract waits for its documentation.
Send the documentation in a second request, under its own X-Idempotency key. It runs only Manual 004. It carries the signed CCB, the signature evidence, and data_hora_assinatura, the instant the worker signed the CCB. The worker can sign days after the averbação.
When the averbação carried the booking block, the documentation also carries the evidence pack and signature_evidence_ref. Without the block, both are refused. With the block, a signing instant after formalization_deadline answers FORMALIZATION_DEADLINE_EXCEEDED. An instant more than 5 minutes ahead of the gateway clock answers DECLARED_DATES_OUT_OF_ORDER.
Without an accepted averbação, the documentation answers AVERBACAO_NOT_ACCEPTED and nothing reaches Dataprev. The refusal is final only when the averbação reads rejected, because averbação recovery (DATAPREV_AVERBACAO_RECOVERY_ENABLED, off by default) can still accept one that reads averbacao_unknown. Without it, contact Lerian with the contract number.
A contract takes one accepted documentation. The same documentation under a new key replays the first answer. A different one answers AVERBACAO_DOCUMENTATION_CONFLICT while the first is accepted or on its way to Dataprev. When Dataprev accepts the documentation, the operation answers confirmed and the gateway publishes consignado.averbacao.confirmed. Confirmation hands a contract sent with the booking block to Lender for booking and disbursement.
When Dataprev refuses the documentation, the request answers 422 with Dataprev’s codes in upstream, and the contract waits for its documentation again. Send corrected documentation under a new key, or exclude the contract. When the call ends without a verdict, the request answers 503 or 504, and the contract also waits again. Send the same documentation again.
Manual 004 gives the financial institution 7 days after the averbação to send the documentation. The gateway does not enforce that deadline. The averbação read shows documentation_due_at, 7 calendar days after the averbação, and documentation_overdue while the documentation is late. Two optional loops help you watch it, and both are off by default. The deadline signal publishes consignado.averbacao.documentation_deadline. The documentation follow-up reads each waiting contract at Dataprev once a day and shows what it finds in dataprev_follow_up.
A downstream lender or ledger decides what those facts mean for its own books. The gateway does not post directly to the ledger.
After confirmation, inform the B3 instrument code that B3 returned when it accepted the CCB registration. Only the tenant’s own credential can inform or read it, not a fund or originador credential. The gateway stores the code once and publishes consignado.registro_b3.registered. Sending the same code and date again answers the original record. A different code or date answers REGISTRO_B3_JA_INFORMADO, and the API offers no correction. The gateway does not talk to B3 and does not check the code against the CCB.
Import a contract that is already registered on the rail outside this gateway. The import reads the contract from Dataprev and moves no money. Only an active or suspended contract can be imported. Without the booking, a contract that already has a saldo devedor obligation here answers CONTRACT_ALREADY_REGISTERED.
An import can also carry the booking, in two objects sent together. The booking object is the averbação body with its full booking block and an empty numero_proposta. It also carries the documentation: the signed CCB, the evidence pack, signature_evidence_ref, and the signature evidence.
The registration object holds what Dataprev returned for the original averbação. It carries averbado_at, the averbação response_code, and the Manual 004 hash_operacao of the documentation. Its averbado_at must fall within one minute of the inclusion instant in the Dataprev read. Sending only one of the two is refused.
The gateway checks the booking and averbado_at against the Dataprev read, keeps the documents in custody, and publishes consignado.contract.registered. Lender then books the contract as it books one registered through averbação here. The import sends no averbação and no CCB to Dataprev.
With the booking, an obligation the contract already holds is not a conflict. The gateway leaves it untouched, and saldo_devedor_dispatch_scheduled answers false. In this mode, CONTRACT_ALREADY_REGISTERED means the contract was averbado through this gateway, or was imported earlier with a different booking.
Record a correction against the registered contract when something the client already asserted turns out to be wrong. Examples are the wrong CCB file and a disbursement confirmation with the wrong evidence. A correction crosses no government boundary: the rail’s own rectification fields are retired, so the client remains the only authority. The gateway takes custody of the corrected bytes, publishes the fact that names them, and serves them back under authentication. Corrections chain: each one supersedes the event before it. Only the tenant’s own credential records a correction, and a fund reads the corrections of a contract ceded to it.
5. Service the contract
The API covers the rail lifecycle after registration: suspension, reactivation, term changes, installment anticipation and reversal, and exclusion. It also covers refinancing and reversal, renegotiation, portability registration, and legacy-contract operations. Portability runs in both directions. As the proponent institution, register the inbound portability. As the origin institution, exclude the contract the worker moved away. The gateway accepts that only for a contract it registered itself. It refuses anything else before it calls the rail. Reversing a refinancing works the same way. You can reverse a refinancing through this gateway only if the gateway registered it. The 7-business-day window is judged against the gateway’s own record of when that refinancing committed. The gateway reports the outstanding balance (saldo devedor) to Dataprev for each contract it holds on the registry. These are the contracts it registers through averbação, refinancing, renegotiation, or inbound portability, and the contracts it imports. For a contract it registers, the obligation opens when Dataprev accepts that operation. For an averbação, that is before the documentation. The reported balance is the present value of the unpaid installments still ahead, on the Brasília date of the report. The gateway discounts each installment at the contract’s monthly rate and assumes payment on the due date. It sends a report when the debt changes, when an installment falls due without payment, and on the last business day of a month with no report. Reporting stops when the contract leaves the registry. A contract leaves the registry when:- Dataprev confirms its exclusion, or accepts its origin-side portability exclusion
- an accepted refinancing or renegotiation replaces it, and no reversal undoes that
- a reversal undoes the refinancing that created it
- the documentation follow-up reads it excluded or ended at Dataprev
- the employment termination report lists it
AVERBACAO_EXCLUDED, unless Dataprev rejects the exclusion. Documentation for a contract that left the registry also answers AVERBACAO_EXCLUDED. When documentation is already recorded or in flight, the exclusion answers EXCLUSION_DOCUMENTATION_UNDERWAY. While the averbação reads attachment_pending, send the same documentation again to complete it, then exclude the confirmed contract.
6. Reconcile payroll and repasse
The reconciliation worker reads two independent Dataprev sources:- bookkeeping records, keyed by the payroll competence and contract context
- CEF repasse records, which represent the settlement movement
7. Operate portfolios and guarantees
Additional API families cover operational calendars, employment terminations, FGTS guarantee execution, funds, originadores, assigned credits, assignments, per-tenant throughput, usage, and event-delivery subscriptions. Lender can also cede a contract. When Lender publishes that a fund accepted a contract this gateway confirmed through averbação or imported with its booking, the gateway records the cessão. It publishesconsignado.cessao.registered, as it does for a cessão the client registers. The fund’s assigned-credit read then lists the contract, also when it did not come from an auction. A client cessão of a contract that Lender already ceded to another fund answers CESSAO_CEDED_TO_OTHER_FUND.
Use the API reference operation page for exact required headers, idempotency rules, validation ranges, and response schemas.