> ## 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 signed consignado contract on the payroll rail > Submits averbar-consignado-trabalhador (Manual 003 v1.19 §3.1) and, when the rail accepts it, continues straight into the signed-CCB attachment — one durable operation with two separately fenced provider mutations. THIS COMMITS MONEY: the averbação creates the payroll-deduction mandate the worker starts paying, and the exclusion that would undo it is not on this surface — so the operation is marked x-money-path: true in this document. The signed CCB is validated BEFORE anything is claimed and before the rail is called: absent, non-base64, non-PDF, or implausibly small is refused, because averbating a real contract against a non-existent document is the one ordering the rail punishes. This route and the lender's averbacao.requested event drive the SAME command, so the two paths cannot diverge. X-Idempotency is required; the lib-commons 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. The conditional signature-evidence fields are mutually exclusive §2.1.1 branches, so send the branch your signing flow used rather than the union of the per-field examples: indicador_analfabetismo, indicador_assinatura_cert_digital_icp_brasil or nsu_contrato makes the flow biometrics-exempt. This intake accepts a bancarizador credential, a fundo credential, or a third party acting for a fundo, and every other rail operation accepts a bancarizador credential only — so do not assume the credential that reaches this route reaches the rest of the rail. ## OpenAPI ````yaml en/openapi/v3-current/consignado.yaml post /v1/consignado/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, disbursement confirmation, portability, refinancing, renegotiation, FGTS guarantees, reconciliation, funds, assignments, usage, throughput, and event subscriptions. Secret material is written to the tenant secret store and is never returned by any operation. license: name: Lerian Studio General License title: Lerian Consignado API version: v1.0.0 servers: - url: https://consignado.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: >- Tenant-scoped consignado gateway usage: priced billable-unit aggregation per competência name: Consignado Usage - 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. Each shares its command implementation with the equivalent lender event trigger. 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 paths: /v1/consignado/contracts/{numero_contrato}/averbacao: post: tags: - Consignado Rail Commands summary: Averbar a signed consignado contract on the payroll rail description: >- Submits averbar-consignado-trabalhador (Manual 003 v1.19 §3.1) and, when the rail accepts it, continues straight into the signed-CCB attachment — one durable operation with two separately fenced provider mutations. THIS COMMITS MONEY: the averbação creates the payroll-deduction mandate the worker starts paying, and the exclusion that would undo it is not on this surface — so the operation is marked x-money-path: true in this document. The signed CCB is validated BEFORE anything is claimed and before the rail is called: absent, non-base64, non-PDF, or implausibly small is refused, because averbating a real contract against a non-existent document is the one ordering the rail punishes. This route and the lender's averbacao.requested event drive the SAME command, so the two paths cannot diverge. X-Idempotency is required; the lib-commons 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. The conditional signature-evidence fields are mutually exclusive §2.1.1 branches, so send the branch your signing flow used rather than the union of the per-field examples: indicador_analfabetismo, indicador_assinatura_cert_digital_icp_brasil or nsu_contrato makes the flow biometrics-exempt. This intake accepts a bancarizador credential, a fundo credential, or a third party acting for a fundo, and every other rail operation accepts a bancarizador credential only — so do not assume the credential that reaches this route reaches the rest of the rail. operationId: averbarConsignadoContract parameters: - description: >- The contract number, minted by the CLIENT — the rail mints nothing here. 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. Must equal the numero_contrato in the body. examples: - NC-000001 type: string - description: >- Required idempotency key. Absent is 422, never a generated default. Values beginning with event: are reserved for deterministic event-driven commands. in: header name: X-Idempotency required: true schema: description: >- Required idempotency key. Absent is 422, never a generated default. Values beginning with event: are reserved for deterministic event-driven commands. examples: - idem-1 type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/AverbacaoRequestedCommand' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/AverbacaoOperationResponse' description: OK default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error security: - BearerAuth: [] components: schemas: AverbacaoRequestedCommand: 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 artifacts: $ref: '#/components/schemas/AverbacaoSignedArtifacts' base_biometrica: description: >- 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. examples: - SERPRO 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. 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 data_fim_contrato: description: Contract end date, RFC 3339 UTC. examples: - '2027-07-30T00:00:00Z' format: date-time type: string data_hora_assinatura: description: >- Instant the worker signed the CCB, RFC 3339 UTC (Obrigatório S, error GA). Rendered to the rail's ddMMyyyyHHmmss by the adapter. examples: - '2026-07-30T12:00:00Z' format: date-time type: string data_inicio_contrato: description: Contract start date, RFC 3339 UTC. examples: - '2026-07-30T00:00:00Z' format: date-time type: string data_primeiro_desconto: description: Date of the first payroll deduction, RFC 3339 UTC. examples: - '2026-08-30T00:00:00Z' format: date-time type: string dispositivo: description: >- Free-text description of the signing device, Texto 1..100 since Manual 004 v1.4 (§2.1.2, Obrigatório N). examples: - iPhone 15 Pro; iOS 18.4 type: string documento_oficial_com_foto_frente_b64: description: >- 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. examples: - /9j/4AAQSkZJRgABAQAAAQABAAD/2Q== type: string documento_oficial_com_foto_verso_b64: description: >- 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. examples: - /9j/4AAQSkZJRgABAQAAAQABAAD/2Q== type: string expected_disbursement_date: description: >- Expected loan disbursement date in YYYY-MM-DD. Required for every booking, including originations without numero_proposta. examples: - '2026-08-01' maxLength: 10 type: string first_deduction_competencia: description: Payroll competência of the first deduction, yyyyMM. examples: - '202608' type: string formalization_deadline: description: >- UTC deadline by which the accepted contract must complete formalization. examples: - '2026-08-02T12:00:00Z' format: date-time type: string fundo_ref: description: >- 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. examples: - ' Fundo: Árvore/Classe A — série № 7 ' maxLength: 128 type: string indicador_analfabetismo: description: >- Whether the worker is illiterate (Obrigatório S, error GA). true is the second §2.1.1 biometric exemption. examples: - false type: boolean indicador_assinatura_cert_digital_icp_brasil: description: >- 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. examples: - true type: boolean indicador_validacao_com_doc_oficial: description: >- 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. examples: - false type: boolean installment_amount: description: valorParcela — the instalment amount (decimal string, BRL). examples: - '201.75' type: string installment_count: description: totalParcelas — the number of instalments. examples: - 12 format: int64 type: integer iof_amount: description: valorIOF — the IOF charged (decimal string, BRL). examples: - '10.00' type: string ip: description: >- 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. examples: - 203.0.113.7 type: string latitude: description: >- 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. examples: - '-23.5505' 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. examples: - product-version-1 maxLength: 128 type: string longitude: description: >- Signing longitude as an exact decimal string (§2.1.2, Obrigatório N). examples: - '-46.6333' 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 type: string monthly_rate: description: >- valorTaxaMensal as a PERCENT-per-month decimal string. "1.80" is 1.80 %/month, NOT the fraction 0.018. examples: - '1.80' type: string nome_trabalhador: description: The worker's full name as it appears on the contract. examples: - MARIA DA SILVA type: string nsu_contrato: description: >- 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). examples: - '1234567890' pattern: ^([0-9]{1,18})?$ type: string numero_contrato: description: >- 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. examples: - NC-000001 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 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 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. examples: - '2160.00' type: string registro_biometrico_facial_b64: description: >- 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. examples: - /9j/4AAQSkZJRgABAQAAAQABAAD/2Q== type: string score: description: >- 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. examples: - '0.9999986' type: string signature_evidence_ref: description: Opaque provider evidence reference for the worker signature. examples: - signature-evidence-1 maxLength: 128 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. examples: - true type: boolean tipo_autenticacao: description: >- 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. examples: - '1' pattern: ^([1-6])?$ type: string 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 - expected_disbursement_date - loan_product_version - formalization_deadline - margin_snapshot - signature_evidence_ref - artifacts - ip - data_hora_assinatura - indicador_assinatura_cert_digital_icp_brasil - indicador_analfabetismo - matricula - codigo_inscricao_empregador - numero_inscricao_empregador - data_inicio_contrato - data_fim_contrato - data_primeiro_desconto - 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. 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: - NC-000001 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 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. 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: false properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). examples: - ERR-0001 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 AverbacaoSignedArtifacts: additionalProperties: false properties: biometrics_documents_pack: $ref: '#/components/schemas/AverbacaoSignedArtifact' signed_ccb: $ref: '#/components/schemas/AverbacaoSignedArtifact' required: - signed_ccb - biometrics_documents_pack 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 an exact decimal string. examples: - '1000.00' maxLength: 64 type: string remuneracao_disponivel: description: >- Available remuneration observed with the margin, as an exact decimal string. examples: - '5000.00' maxLength: 64 type: string required: - available_margin - remuneracao_disponivel - as_of 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 AverbacaoSignedArtifact: additionalProperties: false properties: bytes_base64: description: >- Canonical base64 artifact bytes. The two artifacts remain distinct inputs. examples: - UEsDBEFDS1BBQ0s= maxLength: 8388608 type: string content_type: description: Artifact media type. examples: - application/pdf maxLength: 128 type: string file_name: description: Original artifact file name. examples: - contract.pdf maxLength: 255 type: string required: - file_name - content_type - bytes_base64 type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http ````