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.

POST /v1/consignado/contracts/{numero_contrato}/averbacao

Averbar a consignado contract on the payroll rail

cURL

curl --request POST \
  --url https://br-consignado-gw.sandbox.lerian.net/v1/consignado/contracts/{numero_contrato}/averbacao \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "annual_rate": "23.87",
  "cet_annual": "25.34",
  "cet_monthly": "1.90",
  "codigo_inscricao_empregador": "1",
  "contract_id": "contract-1",
  "cpf": "12345678901",
  "data_fim_contrato": "2027-07-30T00:00:00Z",
  "data_inicio_contrato": "2026-07-30T00:00:00Z",
  "data_primeiro_desconto": "2026-08-30T00:00:00Z",
  "first_deduction_competencia": "202608",
  "installment_amount": "201.75",
  "installment_count": 12,
  "iof_amount": "10.00",
  "liberated_amount": "2000.00",
  "matricula": "M-1",
  "monthly_rate": "1.80",
  "nome_trabalhador": "MARIA DA SILVA",
  "numero_contrato": "99999999999AN1",
  "numero_inscricao_empregador": "12345678000199",
  "principal_amount": "2160.00",
  "tem_garantias": true,
  "cnpj_operador": "98765432000188",
  "expected_disbursement_date": "2026-08-01",
  "formalization_deadline": "2026-08-02T12:00:00Z",
  "fundo_ref": "  Fundo: Árvore/Classe A — série № 7  ",
  "loan_product_version": "0f9d1a7c-3b52-4c8e-9a1d-2f6b8c4e5d70",
  "numero_proposta": "12345678901234567890",
  "origination_fee_amount": "10.00",
  "perc_verba_rescisoria_garantia": "10.00",
  "valor_multa_rescisoria_garantia_fgts": "400.25",
  "valor_saldo_disponivel_garantia_fgts": "1000.50"
}
'

200

{
  "contractId": "contract-1",
  "numeroContrato": "99999999999AN1",
  "status": "confirmed",
  "attachmentAt": "2026-07-30T12:00:09Z",
  "averbacaoAt": "2026-07-30T12:00:04Z",
  "hashOperacao": "HASH-1",
  "message": "averbado",
  "responseCode": "AV"
}

Authorizations

Authorization · string · header · required

JWT bearer token issued by the identity provider.

Headers

X-Idempotency · string · required

Required idempotency key. Absent is 422, never a generated default.

Example:

"idem-1"

Path Parameters

numero_contrato · string · required

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.

Required string length: 2 - 15

Pattern: ^[A-Za-z0-9]+$

Example:

"99999999999AN1"

Body

application/json

annual_rate · string · required

valorTaxaAnual as a PERCENT-per-year decimal string. "23.87" is 23.87 %/year — the effective compounding of monthly_rate 1.80.

Example:

"23.87"

cet_annual · string · required

valorCETAnual — Custo Efetivo Total as a PERCENT-per-year decimal string (the effective compounding of cet_monthly).

Example:

"25.34"

cet_monthly · string · required

valorCETMensal — Custo Efetivo Total as a PERCENT-per-month decimal string. Sits above monthly_rate because it absorbs IOF and fees.

Example:

"1.90"

codigo_inscricao_empregador · enum<string> · required

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.

Available options: 1, 2

Example:

"1"

contract_id · string · required

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.

Example:

"contract-1"

cpf · string · required

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.

Pattern: ^[0-9]{11}$

Example:

"12345678901"

data_fim_contrato · string<date-time> · required

Contract end date, RFC 3339 UTC. A value other than data_primeiro_desconto plus (installment_count - 1) months does not block the averbação.

Example:

"2027-07-30T00:00:00Z"

data_inicio_contrato · string<date-time> · required

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.

Example:

"2026-07-30T00:00:00Z"

data_primeiro_desconto · string<date-time> · required

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.

Example:

"2026-08-30T00:00:00Z"

first_deduction_competencia · string · required

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.

Example:

"202608"

installment_amount · string · required

valorParcela — the instalment amount (decimal string, BRL).

Example:

"201.75"

installment_count · integer<int64> · required

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.

Example:

12

iof_amount · string · required

valorIOF — the IOF charged (decimal string, BRL).

Example:

"10.00"

liberated_amount · string · required

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.

Example:

"2000.00"

matricula · string · required

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.

Maximum string length: 30

Example:

"M-1"

monthly_rate · string · required

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.

Example:

"1.80"

nome_trabalhador · string · required

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.

Maximum string length: 90

Example:

"MARIA DA SILVA"

numero_contrato · string · required

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.

Required string length: 2 - 15

Pattern: ^[A-Za-z0-9]+$

Example:

"99999999999AN1"

numero_inscricao_empregador · string · required

Employer inscription NUMBER matching codigo_inscricao_empregador (Texto 14 since Manual 004 v1.6, error SH). REQUIRED on the wire.

Example:

"12345678000199"

principal_amount · string · required

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.

Example:

"2160.00"

tem_garantias · boolean · required

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.

Example:

true

cnpj_operador · string

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.

Example:

"98765432000188"

dados_cadastrais · object

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.

Show child attributes

expected_disbursement_date · string

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.

Maximum string length: 10

Example:

"2026-08-01"

formalization_deadline · string<date-time>

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.

Example:

"2026-08-02T12:00:00Z"

fundo_ref · string

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.

Maximum string length: 128

Example:

" Fundo: Árvore/Classe A — série № 7 "

loan_product_version · string

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.

Maximum string length: 128

Example:

"0f9d1a7c-3b52-4c8e-9a1d-2f6b8c4e5d70"

margin_snapshot · object

Show child attributes

numero_proposta · string

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.

Maximum string length: 20

Example:

"12345678901234567890"

origination_fee_amount · string

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.

Maximum string length: 20

Example:

"10.00"

perc_verba_rescisoria_garantia · string

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.

Example:

"10.00"

preparation · object

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.

Show child attributes

valor_multa_rescisoria_garantia_fgts · string

Rescission-penalty portion pledged as collateral (decimal string, BRL). Conditional on tem_garantias; omit rather than send 0.

Example:

"400.25"

valor_saldo_disponivel_garantia_fgts · string

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.

Example:

"1000.50"

Response

200

application/json

OK

contractId · string · required

The client's own contract identity, echoed.

Example:

"contract-1"

numeroContrato · string · required

The contract number the operation was addressed to.

Example:

"99999999999AN1"

status · enum<string> · required

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.

Available options: claimed, averbacao_invoking, averbacao_unknown, attachment_pending, attachment_invoking, attachment_unknown, confirmed, rejected

Example:

"confirmed"

attachmentAt · string<date-time>

Instant the CCB attachment was recorded, RFC 3339 UTC. ABSENT until the attachment was recorded.

Example:

"2026-07-30T12:00:09Z"

averbacaoAt · string<date-time>

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.

Example:

"2026-07-30T12:00:04Z"

hashOperacao · string

The rail's identity for the accepted CCB attachment (hashOperacao, Manual 004 §2.1). Durable, so a replay returns it without touching the rail.

Example:

"HASH-1"

message · string

The rail's own response message.

Example:

"averbado"

responseCode · string

The rail's own response code for the averbação.

Example:

"AV"