Skip to main content
POST
Averbar a signed consignado contract on the payroll rail

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. Values beginning with event: are reserved for deterministic event-driven commands.

Example:

"idem-1"

Path Parameters

​
numero_contrato
string
required

The contract number, minted by the CLIENT — the rail mints nothing here. Must equal the numero_contrato in the body.

Example:

"NC-000001"

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"

​
artifacts
object
required
​
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.

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.

Example:

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

​
data_hora_assinatura
string<date-time>
required

Instant the worker signed the CCB, RFC 3339 UTC (Obrigatório S, error GA). Rendered to the rail's ddMMyyyyHHmmss by the adapter.

Example:

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

​
data_inicio_contrato
string<date-time>
required

Contract start date, RFC 3339 UTC.

Example:

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

​
data_primeiro_desconto
string<date-time>
required

Date of the first payroll deduction, RFC 3339 UTC.

Example:

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

​
expected_disbursement_date
string
required

Expected loan disbursement date in YYYY-MM-DD. Required for every booking, including originations without numero_proposta.

Maximum string length: 10
Example:

"2026-08-01"

​
first_deduction_competencia
string
required

Payroll competência of the first deduction, yyyyMM.

Example:

"202608"

​
formalization_deadline
string<date-time>
required

UTC deadline by which the accepted contract must complete formalization.

Example:

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

​
indicador_analfabetismo
boolean
required

Whether the worker is illiterate (Obrigatório S, error GA). true is the second §2.1.1 biometric exemption.

Example:

false

​
indicador_assinatura_cert_digital_icp_brasil
boolean
required

Whether the CCB was signed with a qualified ICP-Brasil certificate (Obrigatório S, error GA). true is one of the three §2.1.1 biometric EXEMPTIONS — §6.5 states the qualified signature "substitui a necessidade de biometria facial" — so the biometric fields below may then be omitted.

Example:

true

​
installment_amount
string
required

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

Example:

"201.75"

​
installment_count
integer<int64>
required

totalParcelas — the number of instalments.

Example:

12

​
iof_amount
string
required

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

Example:

"10.00"

​
ip
string
required

The IP the worker signed from, IPv4 or IPv6 (Manual 004 §2.1.2, Obrigatório S, errors GA/GB). The example uses the RFC 5737 documentation range.

Example:

"203.0.113.7"

​
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"

​
loan_product_version
string
required

Immutable version of the loan product whose terms governed this contract.

Maximum string length: 128
Example:

"product-version-1"

​
margin_snapshot
object
required
​
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.

Example:

"M-1"

​
numero_contrato
string
required

The rail contract number, minted by the CLIENT. It MUST equal the numero_contrato path parameter — a mismatch is refused 422 so a caller cannot address one contract and averbar another.

Example:

"NC-000001"

​
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.

Example:

"2160.00"

​
signature_evidence_ref
string
required

Opaque provider evidence reference for the worker signature.

Maximum string length: 128
Example:

"signature-evidence-1"

​
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

​
base_biometrica
string

Identifier of the government biometric base the facial record was matched against. Required together with score when indicador_validacao_com_doc_oficial is false (§2.1.1, error BK). Manual 004 publishes no enumeration for it, so the value is relayed verbatim.

Example:

"SERPRO"

​
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"

​
dispositivo
string

Free-text description of the signing device, Texto 1..100 since Manual 004 v1.4 (§2.1.2, Obrigatório N).

Example:

"iPhone 15 Pro; iOS 18.4"

​
documento_oficial_com_foto_frente_b64
string

Front face of the official photo ID, base64 JPEG. Required together with the verso when indicador_validacao_com_doc_oficial is true; each must decode to a JPEG of at least 250×250 px (§2.1.1, error PY). THE EXAMPLE IS TRUNCATED.

Example:

"/9j/4AAQSkZJRgABAQAAAQABAAD/2Q=="

​
documento_oficial_com_foto_verso_b64
string

Back face of the official photo ID, base64 JPEG. Same requiredness and same 250×250 px floor as the frente (error PY). THE EXAMPLE IS TRUNCATED.

Example:

"/9j/4AAQSkZJRgABAQAAAQABAAD/2Q=="

​
fundo_ref
string

Mandatory 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.

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 names one here; its value is taken as given, unchanged. It must also name a fund the tenant has registered and that still accepts new credit.

Maximum string length: 128
Example:

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

​
indicador_validacao_com_doc_oficial
boolean

Selects which §2.1.1 evidence branch applies: false demands the base_biometrica + score pair, true demands both photo-ID faces. false is a DECISION the rail must see and is distinguishable from absent, so send it explicitly rather than omitting it.

Example:

false

​
latitude
string

Signing latitude as an exact decimal string (§2.1.2, Obrigatório N). Crosses the rail as an unquoted Numérico and never passes through a float.

Example:

"-23.5505"

​
longitude
string

Signing longitude as an exact decimal string (§2.1.2, Obrigatório N).

Example:

"-46.6333"

​
monthly_rate
string

valorTaxaMensal as a PERCENT-per-month decimal string. "1.80" is 1.80 %/month, NOT the fraction 0.018.

Example:

"1.80"

​
nome_trabalhador
string

The worker's full name as it appears on the contract.

Example:

"MARIA DA SILVA"

​
nsu_contrato
string

Número Sequencial Único of a contract closed through the IF's own attendance network (Manual 004 §2.1.2: Numérico, Tamanho 18, Obrigatório N, error OT). Up to 18 digits — the column is a maximum, and the manual's own example for this field is 98765. Kept as digits end to end. PRESENT means biometrics are exempt AND tipo_autenticacao becomes mandatory (error NS).

Pattern: ^([0-9]{1,18})?$
Example:

"1234567890"

​
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"

​
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"

​
registro_biometrico_facial_b64
string

The 2D facial-biometric record, base64 (Obrigatório N at the rail, but demanded by §2.1.1 for every flow that is NOT biometrics-exempt). THE EXAMPLE IS TRUNCATED — it shows a JPEG's base64 encoding, not a usable record.

Example:

"/9j/4AAQSkZJRgABAQAAAQABAAD/2Q=="

​
score
string

The biometric match score as an EXACT decimal string, required together with base_biometrica (§2.1.1, error BK). It crosses the rail as an unquoted Numérico published to seven decimals and never passes through a float.

Example:

"0.9999986"

​
tipo_autenticacao
string

Authentication channel used, one of the published codes 1..6 (Manual 004 §2.1.2, error GE). Mandatory whenever nsu_contrato is informed; omit it, or send an empty string, when it is not.

Pattern: ^([1-6])?$
Example:

"1"

​
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

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:

"NC-000001"

​
status
enum<string>
required

Durable operation status. attachment_pending means the averbação was accepted and the signed CCB still has to be attached; averbacao_unknown and attachment_unknown mean the rail's outcome is ambiguous and the operation needs reconciliation — NEITHER is a failure to retry blindly.

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"