> ## 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. # Averbar a consignado contract on the payroll rail > Submits averbar-consignado-trabalhador (Manual 003 v1.19 §3.1) and nothing else. An accepted averbação answers status attachment_pending and publishes consignado.averbacao.accepted: Dataprev holds the mandate, and the contract waits for its documentation — the signed CCB, the evidence pack when the averbação carries the booking block, and the Manual 004 signature evidence — sent through POST .../ccb-attachment. This body carries no document and no signing instant: artifacts, data_hora_assinatura and the signature-evidence fields are refused 422, or 413 first when the body exceeds 1 MiB, as one carrying a real signed CCB usually does. THIS COMMITS MONEY: the averbação creates the payroll-deduction mandate the worker starts paying — so the operation is marked x-money-path: true in this document. POST .../exclusion can cancel an accepted averbação, also while it waits for its documentation. X-Idempotency is required; the transport middleware supplies best-effort response replay while the durable PostgreSQL operation record remains the semantic authority, keyed by tenant and contract and bound to the request payload's digest. The numero_contrato in the body MUST equal the one in the path. A retry after the documentation was sent answers the operation as it stands and never attaches anything. This intake accepts a bancarizador credential, a fundo credential for its own fund, or an originador credential for a contract whose proposal came from its own bid (a fund it names is validated against the tenant's fund register first, and a contract outside its own bids is refused 403), and most other rail operations accept a bancarizador credential only — so do not assume the credential that reaches this route reaches the rest of the rail. Partner route: the text above describes the party's own route. Here the register id in the path names the party: it must be in the partner credential's scope and registered under the caller's tenant, and the call runs as that party, exactly as the party's own credential would. On this route the body names the fund by fundo_id, its register id, and fundo_ref is refused 422. ## OpenAPI ````yaml /pt/openapi/v3-current/consignado.yaml post /v1/consignado/originadores/{originador_id}/contracts/{numero_contrato}/averbacao openapi: 3.1.0 info: contact: email: contact@lerian.studio name: Lerian Studio url: https://lerian.studio description: >- OpenAPI 3.1 surface for Lerian Consignado — Dataprev. The API covers tenant credentials and rail configuration, worker margin, loan auctions and bids, contract registration and lifecycle, B3 instrument codes, disbursement confirmation, portability, refinancing, renegotiation, FGTS guarantees, reconciliation, funds, assignments, throughput, and event subscriptions. license: name: Lerian Studio General License title: Lerian Consignado API version: v1.0.0 servers: - url: https://br-consignado-gw.sandbox.lerian.net security: - BearerAuth: [] tags: - description: >- Per-tenant Dataprev credential custody and public rail configuration (upload, status, rotation, revoke, requester code, and worker portal base URL) name: Credentials - description: >- Per-tenant streaming-hub subscription control-plane (list, create, get, rotate, revoke, and test delivery) name: Subscriptions - description: >- Dataprev payroll-rail surface: FGTS balance and authorization reads, the FGTS guarantee execution, contract suspension, reactivation and term changes, the rail's own contract documents, and the on-demand reads of leilão solicitações, escriturações, repasses and employment terminations name: Consignado Rail - description: >- Synchronous rail command surface: the operations a bancarizador without the lender drives over HTTP. name: Consignado Rail Commands - description: >- Gateway-owned disbursement confirmation: a client bank recording money it has ALREADY paid to a worker. It crosses no government boundary and proxies no Dataprev operation. name: Consignado Disbursement - description: >- Per-tenant self-service outbound Dataprev rail throughput: read and set this tenant's own requests-per-second, including a deliberate pause at zero name: Consignado Throughput - description: >- The B3 instrument code (Código IF) of an averbado contract: informed once by the bancarizador after B3 registers the CCB, and read back name: Consignado Registro B3 paths: /v1/consignado/originadores/{originador_id}/contracts/{numero_contrato}/averbacao: post: tags: - Consignado Rail Commands summary: Averbar a consignado contract on the payroll rail description: >- Submits averbar-consignado-trabalhador (Manual 003 v1.19 §3.1) and nothing else. An accepted averbação answers status attachment_pending and publishes consignado.averbacao.accepted: Dataprev holds the mandate, and the contract waits for its documentation — the signed CCB, the evidence pack when the averbação carries the booking block, and the Manual 004 signature evidence — sent through POST .../ccb-attachment. This body carries no document and no signing instant: artifacts, data_hora_assinatura and the signature-evidence fields are refused 422, or 413 first when the body exceeds 1 MiB, as one carrying a real signed CCB usually does. THIS COMMITS MONEY: the averbação creates the payroll-deduction mandate the worker starts paying — so the operation is marked x-money-path: true in this document. POST .../exclusion can cancel an accepted averbação, also while it waits for its documentation. X-Idempotency is required; the transport middleware supplies best-effort response replay while the durable PostgreSQL operation record remains the semantic authority, keyed by tenant and contract and bound to the request payload's digest. The numero_contrato in the body MUST equal the one in the path. A retry after the documentation was sent answers the operation as it stands and never attaches anything. This intake accepts a bancarizador credential, a fundo credential for its own fund, or an originador credential for a contract whose proposal came from its own bid (a fund it names is validated against the tenant's fund register first, and a contract outside its own bids is refused 403), and most other rail operations accept a bancarizador credential only — so do not assume the credential that reaches this route reaches the rest of the rail. Partner route: the text above describes the party's own route. Here the register id in the path names the party: it must be in the partner credential's scope and registered under the caller's tenant, and the call runs as that party, exactly as the party's own credential would. On this route the body names the fund by fundo_id, its register id, and fundo_ref is refused 422. operationId: averbarConsignadoContractAsOriginador parameters: - description: >- The originador's register id, as returned in the id field of GET /v1/consignado/originadores. It must be in the partner credential's scope. in: path name: originador_id required: true schema: description: >- The originador's register id, as returned in the id field of GET /v1/consignado/originadores. It must be in the partner credential's scope. examples: - 6f1c2a3b-4d5e-4f60-8a7b-9c0d1e2f3a4b format: uuid type: string - description: >- The contract number, minted by the CLIENT — the rail mints nothing here: 2 to 15 letters or digits. Must equal the numero_contrato in the body. in: path name: numero_contrato required: true schema: description: >- The contract number, minted by the CLIENT — the rail mints nothing here: 2 to 15 letters or digits. Must equal the numero_contrato in the body. examples: - 99999999999AN1 maxLength: 15 minLength: 2 pattern: ^[A-Za-z0-9]+$ type: string - description: Required idempotency key. Absent is 422, never a generated default. in: header name: X-Idempotency required: true schema: description: >- Required idempotency key. Absent is 422, never a generated default. examples: - idem-1 type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/OriginadorAverbacaoRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/AverbacaoOperationResponse' description: OK '409': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- A conflict with the averbação this contract already holds. AVERBACAO_CLAIM_CONFLICT means the averbação is already claimed under another idempotency key, so follow the claim that exists rather than opening a second one. It is definitive. CONTRACT_ALREADY_REGISTERED means the contract number is already a contract in this gateway (minted by a refinanciamento or renegociação, imported, or received by portability); nothing was written and nothing was sent to Dataprev. It is definitive. AVERBACAO_HELD_BY_ANOTHER_SENDER means a credential of another nature (bancarizador, fundo or originador) sent this same request first and it has not reached Dataprev: only a credential of that nature resumes it, by sending it again. It stops once Dataprev answers that request. A 409 carrying NO code and the detail "an identical request is already in flight" is not definitive: hold this idempotency key and retry under it. DATAPREV_CREDENTIAL_REQUIRED means this tenant has no Dataprev credential in custody, so the gateway cannot act for it on the rail at all; it is definitive until the credential is provisioned, and retrying before that never succeeds. DATAPREV_CREDENTIAL_REVOKED means the tenant's credentials were revoked; it holds until a complete upload (PUT /v1/credentials/dataprev with the certificate and the OAuth client together) opens a new custody. DATAPREV_CREDENTIAL_REJECTED means Dataprev refused its OAuth client credentials, so correct them in custody before retrying. '422': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- The request cannot be processed as sent. IDEMPOTENCY_KEY_REUSE means the X-Idempotency key is spent on a different request: send a new key. FUNDO_NOT_REGISTERED means fundo_ref names no fund registered for this tenant, and FUNDO_DEACTIVATED a fund that no longer accepts new credit: correct fundo_ref. A body carrying documents or Manual 004 signature evidence answers 422, or 413 first when it exceeds 1 MiB: they are sent through POST .../ccb-attachment, and so is data_hora_assinatura. FIRST_DEDUCTION_BEFORE_COMPETENCIA means data_primeiro_desconto falls in a month before first_deduction_competencia; DECLARED_DATES_OUT_OF_ORDER means the declared dates break an order the booking requires (see data_inicio_contrato and data_primeiro_desconto); correct the dates and resend. BOOKING_FIELD_INVALID means the lender cannot read a booking field (see loan_product_version, margin_snapshot, contract_id and fundo_ref). DECLARED_TERMS_INCONSISTENT means the declared amounts or rates contradict each other (see principal_amount and monthly_rate); correct the terms. MARGIN_SNAPSHOT_INCONSISTENT means margin_snapshot does not hold installment_amount; read the margin again or re-price. CONTRACT_NOT_BOOKABLE means the lender cannot book this contract at all (see installment_count and expected_disbursement_date); send it without the booking block. RATE_OUTSIDE_PRODUCT_RANGE means monthly_rate times 12 falls outside the annual rate range of the loan_product_version the Lender published; a version this gateway has not seen is not checked. Each detail names the rule. All of these apply only with the booking block, and the rail was not called; a retry of an averbação the rail already accepted is not refused. '500': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Internal Server Error default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error security: - BearerAuth: [] components: schemas: OriginadorAverbacaoRequest: additionalProperties: false properties: annual_rate: description: >- valorTaxaAnual as a PERCENT-per-year decimal string. "23.87" is 23.87 %/year — the effective compounding of monthly_rate 1.80. examples: - '23.87' type: string cet_annual: description: >- valorCETAnual — Custo Efetivo Total as a PERCENT-per-year decimal string (the effective compounding of cet_monthly). examples: - '25.34' type: string cet_monthly: description: >- valorCETMensal — Custo Efetivo Total as a PERCENT-per-month decimal string. Sits above monthly_rate because it absorbs IOF and fees. examples: - '1.90' type: string cnpj_operador: description: >- CNPJ of the operator responsible for the operation — banking correspondent, cooperado or similar (Manual 003 §3.1.1 p.9, Obrigatório NÃO). An absent value is a legitimate "no intermediary operator": the adapter drops the field rather than sending an empty string. examples: - '98765432000188' type: string codigo_inscricao_empregador: description: >- Employer inscription TYPE code. Manual 003 §3.1.1 p.10 publishes exactly two: 1 = CNPJ, 2 = CPF. REQUIRED on the wire (Obrigatório Sim, error SG); a value outside the enumeration is refused 422 before the rail is called. enum: - '1' - '2' examples: - '1' type: string contract_id: description: >- The CLIENT's own contract identity, echoed back on the response and used to correlate the emitted confirmed/rejected fact. Never minted here. 1..128 bytes of UTF-8 without leading or trailing spaces. With the booking block, one with control characters is refused 422 BOOKING_FIELD_INVALID before the rail is called, and so is one outside those bounds on a contract import. examples: - contract-1 type: string cpf: description: >- Worker CPF, exactly 11 digits — a CPF is eleven digits by definition (Manual 002 v1.15 §3.1.1 p.8 types the request field Número, 11 algarismos). In the BODY, never a path or query parameter. examples: - '12345678901' pattern: ^[0-9]{11}$ type: string dados_cadastrais: $ref: '#/components/schemas/DadosCadastrais' description: >- Optional worker, employer, origination and disbursement-account record. Part of the semantic digest. Rendered once at averbação and stored with nome_trabalhador; that rendering, not the request bytes, is what the dados-cadastrais route serves and the digest covers. Provisional until the contract confirms: a documentation that sends its own dados_cadastrais replaces this block whole. Never sent to Dataprev. contract.registered carries only the SHA-256 of the final cadastro. data_fim_contrato: description: >- Contract end date, RFC 3339 UTC. A value other than data_primeiro_desconto plus (installment_count - 1) months does not block the averbação. examples: - '2027-07-30T00:00:00Z' format: date-time type: string data_inicio_contrato: description: >- Contract start date, RFC 3339 UTC. With the booking block, data_fim_contrato, data_primeiro_desconto and expected_disbursement_date must not fall before it, and expected_disbursement_date must be before data_primeiro_desconto, compared as UTC calendar dates: the averbação route refuses that order 422 DECLARED_DATES_OUT_OF_ORDER before the rail is called. examples: - '2026-07-30T00:00:00Z' format: date-time type: string data_primeiro_desconto: description: >- Date of the first payroll deduction, RFC 3339 UTC; its UTC calendar date is what the rail and the Lerian lender receive. With the booking block, a date that is not a banking business day rolls to the next one, or back to the month's last one when the next falls in another month; the rolled date must be after expected_disbursement_date, or the averbação route refuses it 422 DECLARED_DATES_OUT_OF_ORDER before the rail is called. examples: - '2026-08-30T00:00:00Z' format: date-time type: string expected_disbursement_date: description: >- Expected loan disbursement date in YYYY-MM-DD. Required for every booking, including originations without numero_proposta. A date outside 2026 to 2099 is refused 422 CONTRACT_NOT_BOOKABLE by the averbação route before the rail is called. examples: - '2026-08-01' maxLength: 10 type: string first_deduction_competencia: description: >- Payroll competência of the first deduction, yyyyMM. With the booking block, data_primeiro_desconto must fall in this month or a later one: an earlier month is refused 422 FIRST_DEDUCTION_BEFORE_COMPETENCIA by the averbação route before the rail is called. examples: - '202608' type: string formalization_deadline: description: >- UTC deadline by which the accepted contract must complete formalization. The documentation's data_hora_assinatura must not be after it, compared to the second: POST .../ccb-attachment refuses that 422 FORMALIZATION_DEADLINE_EXCEEDED before Dataprev is called. examples: - '2026-08-02T12:00:00Z' format: date-time type: string fundo_id: description: >- OPTIONAL fund the credit is attributed to, named by its register id as returned in the id field of GET /v1/consignado/fundos, in place of fundo_ref, which this route refuses 422. The gateway attributes that fund's reference exactly as fundo_ref does on the principal's route; an id the tenant does not register is refused 422. Omit it and the contract is attributed to no fund. examples: - 3f2504e0-4f89-41d3-9a0c-0305e82c3301 format: uuid type: string fundo_ref: description: >- OPTIONAL opaque UTF-8 fund reference, bounded to 128 bytes. It is preserved byte-for-byte without trimming, case folding, normalization, parsing, or a local character whitelist. NOT a rail field — the fund has no relationship with the rail, so it never crosses the wire; it is persisted and published unchanged. With the booking block, a value of only spaces is refused 422 BOOKING_FIELD_INVALID by the averbação route before the rail is called. VERIFIED against your credential. A fund, or a third party acting for one, may only name the fund its own credential carries: a different value is refused before the rail is called, and an omitted value is filled in from the credential. The comparison is exact bytes, so padding, letter case and accent composition are part of the fund's identity — send the reference exactly as it was issued to you. A bancarizador carries no fund of its own and may name one here; its value is taken as given, unchanged, and a present value must name a fund that still accepts new credit: one the tenant registered in this gateway, or one of the tenant's Lender fund registry, named by its Lender id (the lowercase UUID text of assignment_fund_id). OMIT it entirely and the contract is simply not attributed to any fund: nothing is looked up, nothing is refused, and the operation persists no fund at all. Which fund bought the credit is YOUR bookkeeping, not the rail's - the fund has no relationship with Dataprev. examples: - ' Fundo: Árvore/Classe A — série № 7 ' maxLength: 128 type: string installment_amount: description: valorParcela — the instalment amount (decimal string, BRL). examples: - '201.75' type: string installment_count: description: >- totalParcelas — the number of instalments. With the booking block, more than 96 is refused 422 CONTRACT_NOT_BOOKABLE by the averbação route before the rail is called. examples: - 12 format: int64 type: integer iof_amount: description: valorIOF — the IOF charged (decimal string, BRL). examples: - '10.00' type: string liberated_amount: description: >- valorLiberado — "o valor líquido repassado ao trabalhador após descontos" (Manual 003 §3.1.1 p.9, Obrigatório Sim, errors BL/BQ), also required on the winning proposta (Manual 001 §3.1.2 p.10). DISTINCT from principal_amount and NOT derivable from it: the Manual 001 p.13 example quotes valorEmprestimo 2160.00 / valorIOF 10.00 with valorLiberado 2000.00. Never computed here. examples: - '2000.00' type: string loan_product_version: description: >- Immutable version of the loan product whose terms governed this contract, as a UUID. A value that is not a UUID, or the nil UUID, is refused 422 BOOKING_FIELD_INVALID by the averbação route before the rail is called. The averbação route also refuses, 422 RATE_OUTSIDE_PRODUCT_RANGE before the rail is called, a monthly_rate that times 12 falls outside the annual rate range the Lender published for this version; a version this gateway has not seen is not checked. examples: - 0f9d1a7c-3b52-4c8e-9a1d-2f6b8c4e5d70 maxLength: 128 type: string margin_snapshot: $ref: '#/components/schemas/AverbacaoMarginSnapshot' matricula: description: >- The worker's payroll registration at the employer (Texto 1..30, errors OT/SI). REQUIRED on the wire: Manual 004 v1.6 §2.1.2 marks it Obrigatório S on the CCB attach and the attach reuses this one value. examples: - M-1 maxLength: 30 pattern: ^[^\x00-\x1F\x7F-\x9F]*$ patternDescription: free of control characters type: string monthly_rate: description: >- valorTaxaMensal as a PERCENT-per-month decimal string. "1.80" is 1.80 %/month, NOT the fraction 0.018. With the booking block, the four rates must be greater than zero, annual_rate above monthly_rate, cet_annual above cet_monthly, each CET at least its interest rate, and monthly_rate times 12 at most 1000: the averbação route refuses otherwise 422 DECLARED_TERMS_INCONSISTENT before the rail is called. examples: - '1.80' type: string nome_trabalhador: description: >- The worker's full name as it appears on the contract (Texto 1..90, errors AO/OT). REQUIRED: Manual 003 §3.1.1 marks nomeTrabalhador Obrigatório Sim, so a blank name is refused 422 before the rail is called. examples: - MARIA DA SILVA maxLength: 90 pattern: ^[^\x00-\x1F\x7F-\x9F]*$ patternDescription: free of control characters type: string numero_contrato: description: >- The rail contract number, minted by the CLIENT: 2 to 15 letters or digits, without spaces, accents or symbols. It MUST equal the numero_contrato path parameter — a mismatch is refused 422 so a caller cannot address one contract and averbar another. examples: - 99999999999AN1 maxLength: 15 minLength: 2 pattern: ^[A-Za-z0-9]+$ type: string numero_inscricao_empregador: description: >- Employer inscription NUMBER matching codigo_inscricao_empregador (Texto 14 since Manual 004 v1.6, error SH). REQUIRED on the wire. examples: - '12345678000199' type: string numero_proposta: description: >- The optional proposal identifier this gateway minted for the winning bid. Absent means the origination did not pass through this gateway's auction. Present values are matched exactly: leading or trailing whitespace is refused, never normalized into another identity. examples: - '12345678901234567890' maxLength: 20 pattern: ^[^\x00-\x1F\x7F-\x9F]*$ patternDescription: free of control characters type: string origination_fee_amount: description: >- OPTIONAL origination fee the client charges on this contract, in BRL as a canonical decimal with exactly two places ("10.00", "0.00"). Omitted means zero. It must be below principal_amount and is sent only with the booking block. It is the client's definitive declaration: the gateway never derives it from the other terms and it is carried unchanged on consignado.contract.registered. NOT a rail field: it never reaches Dataprev. examples: - '10.00' maxLength: 20 type: string perc_verba_rescisoria_garantia: description: >- Percentage of the rescission verbas pledged as collateral (decimal string, PERCENT). This rides the SEPARATE employer verba-rescisória track, not the FGTS-guarantee execution API. examples: - '10.00' type: string preparation: $ref: '#/components/schemas/AverbacaoPreparation' description: >- OPTIONAL references to a preparation the client obtained from the Lerian lender before averbação: the quote, the CCB instrument issued from it and the SHA-256 of that original CCB. All three are required when the object is sent, and it is sent only with the booking block. They are the client's declarations: the gateway checks their shape, never looks them up, and carries them unchanged on consignado.contract.registered. NOT a rail field: it never reaches Dataprev. principal_amount: description: >- valorEmprestimo — the amount lent (decimal string, BRL). DISTINCT from liberated_amount and not derivable from it: the Manual 001 §3.1.2 p.13 example quotes valorEmprestimo 2160.00 / valorIOF 10.00 with valorLiberado 2000.00. With the booking block, principal_amount, liberated_amount and installment_amount must be greater than zero, and neither liberated_amount nor iof_amount may exceed principal_amount: the averbação route refuses otherwise 422 DECLARED_TERMS_INCONSISTENT before the rail is called. examples: - '2160.00' type: string tem_garantias: description: >- Whether the contract pledges FGTS collateral. REQUIRED — it is the gate the three collateral values below are conditional on, and false is an authoritative "no collateral" rather than an absence. False with any of them, or true with none, is refused 422 by the averbação route before the rail is called (Dataprev rule FI). examples: - true type: boolean valor_multa_rescisoria_garantia_fgts: description: >- Rescission-penalty portion pledged as collateral (decimal string, BRL). Conditional on tem_garantias; omit rather than send 0. examples: - '400.25' type: string valor_saldo_disponivel_garantia_fgts: description: >- Consignable FGTS balance pledged as collateral (decimal string, BRL). Conditional on tem_garantias. OMIT it when there is no FGTS collateral: the rail reads a sent 0 as an invalid guarantee value. examples: - '1000.50' type: string required: - contract_id - numero_contrato - cpf - principal_amount - installment_amount - installment_count - annual_rate - cet_monthly - cet_annual - iof_amount - first_deduction_competencia - matricula - nome_trabalhador - codigo_inscricao_empregador - numero_inscricao_empregador - data_inicio_contrato - data_fim_contrato - data_primeiro_desconto - monthly_rate - liberated_amount - tem_garantias type: object AverbacaoOperationResponse: additionalProperties: false properties: attachmentAt: description: >- Instant the CCB attachment was recorded, RFC 3339 UTC. ABSENT until the attachment was recorded. examples: - '2026-07-30T12:00:09Z' format: date-time type: string averbacaoAt: description: >- Instant the rail's averbação response was recorded, RFC 3339 UTC. ABSENT until the rail has answered — absence is a state, not a zero timestamp. examples: - '2026-07-30T12:00:04Z' format: date-time type: string contractId: description: >- The client's own contract identity, echoed. Empty for a contract a renegociação minted, which has none. examples: - contract-1 type: string hashOperacao: description: >- The rail's identity for the accepted CCB attachment (hashOperacao, Manual 004 §2.1). Durable, so a replay returns it without touching the rail. examples: - HASH-1 type: string message: description: The rail's own response message. examples: - averbado type: string numeroContrato: description: The contract number the operation was addressed to. examples: - 99999999999AN1 type: string responseCode: description: The rail's own response code for the averbação. examples: - AV type: string status: description: >- Durable operation status. attachment_pending means the averbação was accepted by Dataprev and the contract is waiting for its documentation, sent through POST .../ccb-attachment, also after an earlier one failed at Dataprev; this is a deliberate wait, not a failure. averbacao_unknown means the averbação's outcome at the rail is ambiguous and the operation needs reconciliation — it is not a failure to retry blindly. attachment_unknown is no longer produced. enum: - claimed - averbacao_invoking - averbacao_unknown - attachment_pending - attachment_invoking - attachment_unknown - confirmed - rejected examples: - confirmed type: string required: - contractId - numeroContrato - status type: object Detail: additionalProperties: true properties: code: description: >- Stable, machine-readable product error code. One of the enumerated values: the CLT-NNNN catalog codes for the general refusal classes; the named command conflicts, which a client branches on to tell one conflict from another; the four terminal refusals IDEMPOTENCY_STATE_UNRECOGNISED, IDEMPOTENCY_RECORD_UNREADABLE, IDEMPOTENCY_OUTCOME_UNRECORDED and IDEMPOTENCY_REPLAY_UNAVAILABLE (422), which tell the client to reconcile the original request and never retry under a new key; IDEMPOTENCY_KEY_REUSE (422): the key is spent on a different request, so send a new key; the codes a single surface answers, named after it (FUNDO_*, CESSAO_*, REGISTRO_B3_*, ...); and the 5xx codes naming an upstream (DATAPREV_*, STREAMING_HUB_*, TENANT_MANAGER_*, the Access Manager's AUT-0033 and AUT-1021) or an unknown outcome, whose detail is client-readable. enum: - AUT-0033 - AUT-1021 - AVERBACAO_ARTIFACT_CONFLICT - AVERBACAO_CLAIM_CONFLICT - AVERBACAO_DOCUMENTATION_CONFLICT - AVERBACAO_EXCLUDED - AVERBACAO_HELD_BY_ANOTHER_SENDER - AVERBACAO_NOT_ACCEPTED - AVERBACAO_OPERATIONS_INTERNAL - AVERBACAO_OPERATIONS_INVALID_CURSOR - AVERBACAO_OPERATIONS_INVALID_QUERY - AVERBACAO_OPERATIONS_UNKNOWN_STATUS - AVERBACAO_OPERATION_NOT_FOUND - BID_NO_PROPOSTA_LEFT - BID_ORIGINADOR_INACTIVE - BID_ORIGINADOR_UNKNOWN - BID_PROPOSAL_SLOT_TAKEN - BID_SOLICITACAO_TAKEN - BID_SOLICITACAO_UNKNOWN - BID_SUBMISSIONS_INTERNAL - BID_SUBMISSIONS_INVALID_CURSOR - BID_SUBMISSIONS_UNKNOWN_SITUATION - BOOKING_FIELD_INVALID - CEDED_CREDIT_INTERNAL - CEDED_CREDIT_NO_FUND_ENTITLEMENT - CEDED_CREDIT_UNAVAILABLE - CESSAO_CEDED_TO_OTHER_FUND - CESSAO_CREDIT_NOT_ACCEPTED - CESSAO_CREDIT_NOT_FOUND - CESSAO_CREDIT_NOT_WITNESSED - CESSAO_CREDIT_PENDING - CESSAO_FUNDO_NOT_ATTRIBUTED - CESSAO_INTERNAL - CESSAO_INVALID_INPUT - CESSAO_UNAVAILABLE - CESSAO_UNWIRED - CLT-0001 - CLT-0002 - CLT-0003 - CLT-0004 - CLT-0005 - CLT-0006 - CLT-0007 - CLT-0008 - CLT-0009 - CLT-0010 - CLT-0011 - CONTRACT_ALREADY_REGISTERED - CONTRACT_NOT_BOOKABLE - CURSOR_EXPIRED - CURSOR_FENCE_MISMATCH - DATAPREV_CREDENTIAL_REJECTED - DATAPREV_CREDENTIAL_REQUIRED - DATAPREV_CREDENTIAL_REVOKED - DATAPREV_INVALID_RESPONSE - DATAPREV_TIMEOUT - DATAPREV_UNAVAILABLE - DECLARED_DATES_OUT_OF_ORDER - DECLARED_TERMS_INCONSISTENT - DISBURSEMENT_CONFIRMATIONS_INTERNAL - DISBURSEMENT_CONFIRMATIONS_INVALID_CURSOR - DISBURSEMENT_PAYMENT_CONFLICT - EVENT_DELIVERY_INTERNAL - EXCLUSION_AUTHORITY_CONFLICT - EXCLUSION_BOOKING_IDENTITY_INCOMPLETE - EXCLUSION_DOCUMENTATION_UNDERWAY - EXCLUSION_OPERATIONS_INTERNAL - EXCLUSION_OPERATIONS_INVALID_CURSOR - EXCLUSION_OPERATIONS_INVALID_QUERY - EXCLUSION_OPERATIONS_UNKNOWN_STATUS - EXCLUSION_OPERATION_NOT_FOUND - FGTS_EXECUTION_ALREADY_REFUSED - FGTS_EXECUTION_CONTRACT_TAKEN - FGTS_EXECUTION_OUTCOME_UNRESOLVED - FGTS_EXECUTION_PAYLOAD_MISMATCH - FIRST_DEDUCTION_BEFORE_COMPETENCIA - FORMALIZATION_DEADLINE_EXCEEDED - FUNDO_CNPJ_CONFLICT - FUNDO_DEACTIVATED - FUNDO_INTERNAL - FUNDO_INVALID_ID - FUNDO_INVALID_INPUT - FUNDO_NOT_FOUND - FUNDO_NOT_REGISTERED - FUNDO_REF_CONFLICT - FUNDO_UNAVAILABLE - IDEMPOTENCY_KEY_REUSE - IDEMPOTENCY_OUTCOME_UNRECORDED - IDEMPOTENCY_RECORD_UNREADABLE - IDEMPOTENCY_REPLAY_UNAVAILABLE - IDEMPOTENCY_STATE_UNRECOGNISED - INVALID_CONTRACT_NUMBER - INVALID_CURSOR - INVALID_EVENTS_INVALID_CURSOR - INVALID_EVENT_NOT_FOUND - INVALID_EVENT_NOT_REQUEUEABLE - INVALID_PAGE_LIMIT - INVENTORY_UNAVAILABLE - MARGIN_SNAPSHOT_INCONSISTENT - ORIGINADOR_INTERNAL - ORIGINADOR_INVALID_ID - ORIGINADOR_INVALID_INPUT - ORIGINADOR_NOT_FOUND - ORIGINADOR_REF_CONFLICT - ORIGINADOR_UNAVAILABLE - OUTCOME_UNKNOWN - PORTABILIDADE_WINDOW_EXPIRED - RAIL_COMMANDS_INTERNAL - RAIL_COMMANDS_INVALID_CURSOR - RAIL_COMMANDS_TENANT_REQUIRED - RAIL_COMMANDS_UNKNOWN_FILTER - RAIL_COMMAND_ALREADY_REFUSED - RAIL_COMMAND_ANSWER_NOT_RETAINED - RAIL_COMMAND_CLAIM_CONFLICT - RAIL_COMMAND_OUTCOME_UNRESOLVED - RAIL_COMMAND_PAYLOAD_MISMATCH - RATE_OUTSIDE_PRODUCT_RANGE - REGISTRATION_NOT_FOUND - REGISTRO_B3_AVERBACAO_NAO_CONFIRMADA - REGISTRO_B3_CONTRATO_NAO_ENCONTRADO - REGISTRO_B3_DATA_REGISTRO_INVALIDA - REGISTRO_B3_INTERNAL - REGISTRO_B3_JA_INFORMADO - REGISTRO_B3_NAO_INFORMADO - REGISTRO_B3_UNAVAILABLE - REGISTRO_B3_UNWIRED - REPASSE_EXPECTATIONS_INTERNAL - REPASSE_EXPECTATIONS_INVALID_CURSOR - REPASSE_EXPECTATIONS_UNKNOWN_SITUATION - REVERSAO_WINDOW_EXPIRED - SALDO_DEVEDOR_INTERNAL - SALDO_DEVEDOR_INVALID_CURSOR - SALDO_DEVEDOR_NOT_FOUND - SALDO_DEVEDOR_TENANT_REQUIRED - SALDO_DEVEDOR_UNAVAILABLE - STREAMING_HUB_TIMEOUT - STREAMING_HUB_UNAVAILABLE - TENANT_MANAGER_TIMEOUT - TENANT_MANAGER_UNAVAILABLE - THROUGHPUT_HISTORY_INTERNAL - THROUGHPUT_HISTORY_INVALID_CURSOR - THROUGHPUT_HISTORY_TENANT_REQUIRED - THROUGHPUT_HISTORY_UNAVAILABLE - THROUGH_REQUIRED - UNKNOWN_QUERY_PARAMETER 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 DadosCadastrais: additionalProperties: false properties: dados_bancarios: $ref: '#/components/schemas/DadosCadastraisBancarios' description: >- The worker's own disbursement account. When present it carries at least one complete set: banco + agencia + conta, or chave_pix + tipo_chave_pix. empregador: $ref: '#/components/schemas/DadosCadastraisEmpregador' description: >- Employer record. Required when the averbação's codigo_inscricao_empregador is 1 (CNPJ), refused when it is 2 (a person employer). The CNPJ is numero_inscricao_empregador and is not repeated here. originacao: $ref: '#/components/schemas/DadosCadastraisOriginacao' trabalhador: $ref: '#/components/schemas/DadosCadastraisTrabalhador' required: - trabalhador - originacao type: object AverbacaoMarginSnapshot: additionalProperties: false properties: as_of: description: UTC instant at which the margin snapshot was observed. examples: - '2026-07-30T11:55:00Z' format: date-time type: string available_margin: description: >- Available payroll margin observed for this booking, as a non-negative decimal string with at most two places; anything else is refused 422 BOOKING_FIELD_INVALID by the averbação route before the rail is called. It must hold installment_amount and not exceed remuneracao_disponivel, else 422 MARGIN_SNAPSHOT_INCONSISTENT. examples: - '1000.00' maxLength: 64 type: string remuneracao_disponivel: description: >- Available remuneration observed with the margin, as a non-negative decimal string with at most two places; anything else is refused 422 BOOKING_FIELD_INVALID by the averbação route before the rail is called. It must be greater than zero, else 422 MARGIN_SNAPSHOT_INCONSISTENT. examples: - '5000.00' maxLength: 64 type: string required: - available_margin - remuneracao_disponivel - as_of type: object AverbacaoPreparation: additionalProperties: false properties: credit_instrument_id: description: >- The CCB instrument the lender issued from that quote, as a canonical lowercase UUID. examples: - 7d2e4f6a-8b0c-4e1d-a3f5-6b7c8d9e0f1a maxLength: 36 type: string original_ccb_digest_sha256: description: >- Lowercase hex SHA-256 of the original CCB document the lender issued from the quote, as the lender reported it. It is not the signed CCB. examples: - 3a1e0c5f9b2d4e6a8c7b1f0e2d3c4b5a69788796a5b4c3d2e1f0a9b8c7d6e5f4 maxLength: 64 type: string quote_id: description: >- The lender quote the contract was prepared from, as a canonical lowercase UUID. examples: - 0b6b7c1e-2f4a-4d6e-9a1b-3c5d7e9f1a2b maxLength: 36 type: string required: - quote_id - credit_instrument_id - original_ccb_digest_sha256 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 DadosCadastraisBancarios: additionalProperties: false properties: agencia: description: Branch, without check digit. examples: - '1234' pattern: ^[0-9]{1,5}$ type: string banco: description: COMPE bank code. examples: - '341' pattern: ^[0-9]{3}$ type: string chave_pix: description: >- Pix key. A CPF key must equal the averbação's cpf; a TELEFONE key is E.164. examples: - '12345678901' maxLength: 77 minLength: 1 pattern: ^[^\x00-\x1F\x7F-\x9F]*$ patternDescription: free of control characters type: string conta: description: Account, without check digit. examples: - '56789' pattern: ^[0-9]{1,20}$ type: string conta_digito: description: Account check digit. examples: - '0' pattern: ^[0-9X]{1,2}$ type: string tipo_chave_pix: description: Pix key kind. enum: - CPF - EMAIL - TELEFONE - EVP examples: - CPF type: string tipo_conta: description: Account kind; absent means CORRENTE to the destination. enum: - CORRENTE - POUPANCA - PAGAMENTO examples: - CORRENTE type: string type: object DadosCadastraisEmpregador: additionalProperties: false properties: cnae_principal: description: Main CNAE code. examples: - '4743100' pattern: ^[0-9]{7}$ type: string cnae_principal_descricao: description: Official CNAE description. examples: - Comércio varejista de vidros maxLength: 178 minLength: 1 pattern: ^[^\x00-\x1F\x7F-\x9F]*$ patternDescription: free of control characters type: string data_inicio_atividade: description: Activity start date, YYYY-MM-DD. examples: - '2013-04-01' format: date type: string endereco: $ref: '#/components/schemas/DadosCadastraisEnderecoEmpregador' natureza_juridica: description: CONCLA legal-nature code. examples: - '2062' pattern: ^[0-9]{4}$ type: string natureza_juridica_descricao: description: Official CONCLA description. examples: - Sociedade Empresária Limitada maxLength: 150 minLength: 1 pattern: ^[^\x00-\x1F\x7F-\x9F]*$ patternDescription: free of control characters type: string nome_fantasia: description: >- Trade name; when Receita has none, repeat razao_social and set nome_fantasia_ausente. examples: - Vidraçaria Exemplo maxLength: 150 minLength: 1 pattern: ^[^\x00-\x1F\x7F-\x9F]*$ patternDescription: free of control characters type: string nome_fantasia_ausente: description: >- True when nome_fantasia repeats razao_social because Receita has no trade name. examples: - false type: boolean opcao_mei: description: Whether the employer opted into MEI. examples: - false type: boolean porte_receita: description: Receita company-size code. enum: - '00' - '01' - '03' - '05' examples: - '01' type: string qtd_empregados_clt: description: CLT headcount. examples: - 187 format: int64 minimum: 0 type: integer razao_social: description: Legal name. examples: - VIDRACARIA EXEMPLO LTDA maxLength: 150 minLength: 1 pattern: ^[^\x00-\x1F\x7F-\x9F]*$ patternDescription: free of control characters type: string required: - razao_social - nome_fantasia - data_inicio_atividade - natureza_juridica - natureza_juridica_descricao type: object DadosCadastraisOriginacao: additionalProperties: false properties: autorizacao_consulta_scr: description: >- Whether the worker authorized an SCR (BACEN credit registry) inquiry. examples: - true type: boolean data_solicitacao: description: Request date, YYYY-MM-DD. examples: - '2026-09-04' format: date type: string id_contrato_interno: description: The client's internal contract identifier. examples: - WNG-2026-31892162 maxLength: 64 minLength: 1 pattern: ^[^\x00-\x1F\x7F-\x9F]*$ patternDescription: free of control characters type: string id_decisao_credito: description: Stable identifier of the credit decision that approved the contract. examples: - CAI-DEC-2026-09-04-7f3a19 maxLength: 64 minLength: 1 pattern: ^[^\x00-\x1F\x7F-\x9F]*$ patternDescription: free of control characters type: string lote_id: description: Stable batch identifier, unique per batch. examples: - CAI-2026-09-17-001 pattern: ^[A-Za-z0-9_.-]{1,64}$ type: string numero_ccb: description: CCB number; absent means equal to numero_contrato. examples: - DIDI2090 maxLength: 30 minLength: 1 pattern: ^[^\x00-\x1F\x7F-\x9F]*$ patternDescription: free of control characters type: string referencias_externas: description: Identifiers owned by third-party systems. items: $ref: '#/components/schemas/DadosCadastraisReferenciaExterna' maxItems: 10 type: - array - 'null' required: - lote_id - id_contrato_interno - id_decisao_credito type: object DadosCadastraisTrabalhador: additionalProperties: false properties: categoria_esocial: description: eSocial worker category. examples: - '101' pattern: ^[0-9]{3}$ type: string cbo: description: CBO occupation code. examples: - '354815' pattern: ^[0-9]{6}$ type: string cbo_descricao: description: Official CBO description. examples: - Agente de viagem maxLength: 150 minLength: 1 pattern: ^[^\x00-\x1F\x7F-\x9F]*$ patternDescription: free of control characters type: string data_admissao: description: Admission date, YYYY-MM-DD. examples: - '2024-06-10' format: date type: string data_nascimento: description: Birth date, YYYY-MM-DD. examples: - '1970-09-04' format: date type: string email: description: E-mail address. examples: - fulano.de.tal@example.com format: email maxLength: 254 type: string endereco: $ref: '#/components/schemas/DadosCadastraisEndereco' estado_civil: description: Marital status. enum: - SOLTEIRO - CASADO - DIVORCIADO - VIUVO - UNIAO_ESTAVEL - SEPARADO examples: - SOLTEIRO type: string nome_mae: description: Mother's name. examples: - Beltrana de Tal maxLength: 150 minLength: 1 pattern: ^[^\x00-\x1F\x7F-\x9F]*$ patternDescription: free of control characters type: string renda_base: description: Base income, BRL decimal string with at most two places. examples: - '2201.17' pattern: ^[0-9]+(\.[0-9]{1,2})?$ type: string rg: $ref: '#/components/schemas/DadosCadastraisRG' sexo: description: Sex. enum: - M - F examples: - M type: string telefone_celular: description: Mobile phone with area code, digits only. examples: - '21900000000' pattern: ^[0-9]{10,11}$ type: string vinculo_ativo: description: Whether the employment relationship is active. examples: - true type: boolean required: - data_nascimento - nome_mae - sexo - estado_civil - renda_base - cbo - vinculo_ativo - endereco type: object DadosCadastraisEnderecoEmpregador: additionalProperties: false properties: bairro: description: District. examples: - Centro maxLength: 100 minLength: 1 pattern: ^[^\x00-\x1F\x7F-\x9F]*$ patternDescription: free of control characters type: string cep: description: Postal code, eight digits, no hyphen. examples: - '20040020' pattern: ^[0-9]{8}$ type: string complemento: description: Address complement. examples: - sala 5 maxLength: 100 pattern: ^[^\x00-\x1F\x7F-\x9F]*$ patternDescription: free of control characters type: string logradouro: description: Street. examples: - Avenida Rio Branco maxLength: 150 minLength: 1 pattern: ^[^\x00-\x1F\x7F-\x9F]*$ patternDescription: free of control characters type: string municipio: description: Official municipality name. examples: - Rio de Janeiro maxLength: 100 minLength: 1 pattern: ^[^\x00-\x1F\x7F-\x9F]*$ patternDescription: free of control characters type: string municipio_ibge: description: IBGE municipality code. examples: - '3304557' pattern: ^[0-9]{7}$ type: string numero: description: Street number. examples: - '1' maxLength: 20 minLength: 1 pattern: ^[^\x00-\x1F\x7F-\x9F]*$ patternDescription: free of control characters type: string uf: description: State. examples: - RJ pattern: ^[A-Z]{2}$ type: string required: - cep - logradouro - numero - bairro - municipio_ibge - municipio - uf type: object DadosCadastraisReferenciaExterna: additionalProperties: false properties: sistema: description: Owning system. examples: - REGISTRADORA_X pattern: ^[A-Z0-9_]{1,32}$ type: string tipo: description: Identifier kind. examples: - ipoc maxLength: 64 minLength: 1 pattern: ^[^\x00-\x1F\x7F-\x9F]*$ patternDescription: free of control characters type: string valor: description: Identifier value. examples: - IPOC-000123 maxLength: 128 minLength: 1 pattern: ^[^\x00-\x1F\x7F-\x9F]*$ patternDescription: free of control characters type: string required: - sistema - tipo - valor type: object DadosCadastraisEndereco: additionalProperties: false properties: bairro: description: District. examples: - Laranjeiras maxLength: 100 minLength: 1 pattern: ^[^\x00-\x1F\x7F-\x9F]*$ patternDescription: free of control characters type: string cep: description: Postal code, eight digits, no hyphen. examples: - '22240003' pattern: ^[0-9]{8}$ type: string cidade: description: City. examples: - Rio de Janeiro maxLength: 100 minLength: 1 pattern: ^[^\x00-\x1F\x7F-\x9F]*$ patternDescription: free of control characters type: string complemento: description: Address complement. examples: - apto 41 maxLength: 100 pattern: ^[^\x00-\x1F\x7F-\x9F]*$ patternDescription: free of control characters type: string logradouro: description: Street. examples: - Rua das Laranjeiras maxLength: 150 minLength: 1 pattern: ^[^\x00-\x1F\x7F-\x9F]*$ patternDescription: free of control characters type: string numero: description: Street number; S/N is valid. examples: - '120' maxLength: 20 minLength: 1 pattern: ^[^\x00-\x1F\x7F-\x9F]*$ patternDescription: free of control characters type: string uf: description: State. examples: - RJ pattern: ^[A-Z]{2}$ type: string required: - logradouro - numero - bairro - cidade - uf - cep type: object DadosCadastraisRG: additionalProperties: false properties: data_emissao: description: Issue date, YYYY-MM-DD. examples: - '2010-03-15' format: date type: string numero: description: RG number. examples: - '12345678' maxLength: 20 minLength: 1 pattern: ^[^\x00-\x1F\x7F-\x9F]*$ patternDescription: free of control characters type: string orgao_emissor: description: Issuing body. examples: - DETRAN maxLength: 20 minLength: 1 pattern: ^[^\x00-\x1F\x7F-\x9F]*$ patternDescription: free of control characters type: string uf_emissor: description: Issuing state. examples: - RJ pattern: ^[A-Z]{2}$ type: string required: - numero - orgao_emissor - uf_emissor 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.