> ## 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 un contrato de consignado firmado en la red de nómina > Envía averbar-consignado-trabalhador (Manual 003 v1.19 §3.1) y, cuando la red la acepta, continúa directamente con el adjunto CCB firmado: una operación duradera con dos mutaciones del proveedor delimitadas de forma independiente. Esta operación compromete dinero: la averbação crea el mandato de deducción de nómina que el trabajador comienza a pagar, y la exclusión que lo desharía no está disponible en esta superficie, por lo que la operación está marcada como x-money-path: true en este documento. El CCB firmado se valida antes de reclamar nada y antes de llamar a la red: se rechaza si está ausente, no está codificado en base64, no es un PDF o es inverosímilmente pequeño, porque averbar un contrato real con un documento inexistente es la condición que la red sanciona. Esta ruta y el evento averbacao.requested del prestamista activan el mismo comando, por lo que las dos rutas no pueden divergir. Se requiere X-Idempotency; el middleware de transporte lib-commons proporciona una reproducción de respuesta de mejor esfuerzo, mientras que el registro de operación duradero de PostgreSQL sigue siendo la autoridad semántica, indexada por tenant y contrato y vinculada al resumen de la carga útil de la solicitud. El numero_contrato del cuerpo debe ser igual al de la ruta. Los campos condicionales de evidencia de firma son ramas mutuamente excluyentes de §2.1.1; por lo tanto, envíe la rama que utilizó su flujo de firma, en lugar de la unión de los ejemplos por campo: indicador_analfabetismo, indicador_assinatura_cert_digital_icp_brasil o nsu_contrato exime al flujo de biometría. Esta entrada acepta una credencial de bancarizador, una credencial de fundo o un tercero que actúa en nombre de un fundo, y todas las demás operaciones de red aceptan solo una credencial de bancarizador, por lo que no asuma que la credencial que llega a esta ruta llega al resto de la red. ## OpenAPI ````yaml es/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: >- Superficie OpenAPI 3.1 para Lerian Consignado — Dataprev. API cubre las credenciales y la configuración de red de tenant, el margen de los trabajadores, las subastas y ofertas de préstamos, el registro y el ciclo de vida de los contratos, la confirmación de desembolsos, la portabilidad, la refinanciación, la renegociación, las garantías de FGTS, la conciliación, los fondos, las asignaciones, el uso, el rendimiento y las suscripciones a eventos. El material secreto se escribe en el almacén secreto tenant y ninguna operación lo devuelve nunca. 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: >- Custodia de credenciales de Dataprev y configuración pública del rail por tenant (carga, estado, rotación, revocación, código del solicitante y URL base del portal del trabajador) name: Credentials - description: >- Uso de la gateway del consignado en el ámbito del tenant: agregación de unidades facturables con precio por competencia name: Consignado Usage - description: >- Plano de control de suscripción al hub de streaming per-tenant (enumerar, crear, obtener, rotar, revocar y probar la entrega) name: Subscriptions - description: >- Superficie de rail de nómina Dataprev: lecturas de saldo y autorización FGTS, ejecución de garantía FGTS, suspensión de contrato, reactivación y cambios de términos, documentos de contrato propios de la red y lecturas bajo demanda de leilão solicitações, escriturações, repasses y terminaciones de empleo. name: Consignado Rail - description: >- Superficie de comando de red síncrona: las operaciones de un bancarizador sin que el prestamista conduzca sobre HTTP. Cada uno comparte su implementación de comando con el activador de evento de prestamista equivalente. name: Consignado Rail Commands - description: >- Confirmación de desembolso propiedad de la gateway: un banco cliente que registra el dinero que ya pagó a un trabajador. No cruza ninguna frontera gubernamental y no representa ninguna operación Dataprev. name: Consignado Disbursement - description: > Rendimiento de red Dataprev saliente de autoservicio per-tenant: lea y configure el requests-per-second propio de este tenant, incluida una pausa deliberada en cero name: Consignado Throughput paths: /v1/consignado/contracts/{numero_contrato}/averbacao: post: tags: - Consignado Rail Commands summary: Averbar un contrato de consignado firmado en la red de nómina description: >- Envía averbar-consignado-trabalhador (Manual 003 v1.19 §3.1) y, cuando la red la acepta, continúa directamente con el adjunto CCB firmado: una operación duradera con dos mutaciones del proveedor delimitadas de forma independiente. Esta operación compromete dinero: la averbação crea el mandato de deducción de nómina que el trabajador comienza a pagar, y la exclusión que lo desharía no está disponible en esta superficie, por lo que la operación está marcada como x-money-path: true en este documento. El CCB firmado se valida antes de reclamar nada y antes de llamar a la red: se rechaza si está ausente, no está codificado en base64, no es un PDF o es inverosímilmente pequeño, porque averbar un contrato real con un documento inexistente es la condición que la red sanciona. Esta ruta y el evento averbacao.requested del prestamista activan el mismo comando, por lo que las dos rutas no pueden divergir. Se requiere X-Idempotency; el middleware de transporte lib-commons proporciona una reproducción de respuesta de mejor esfuerzo, mientras que el registro de operación duradero de PostgreSQL sigue siendo la autoridad semántica, indexada por tenant y contrato y vinculada al resumen de la carga útil de la solicitud. El numero_contrato del cuerpo debe ser igual al de la ruta. Los campos condicionales de evidencia de firma son ramas mutuamente excluyentes de §2.1.1; por lo tanto, envíe la rama que utilizó su flujo de firma, en lugar de la unión de los ejemplos por campo: indicador_analfabetismo, indicador_assinatura_cert_digital_icp_brasil o nsu_contrato exime al flujo de biometría. Esta entrada acepta una credencial de bancarizador, una credencial de fundo o un tercero que actúa en nombre de un fundo, y todas las demás operaciones de red aceptan solo una credencial de bancarizador, por lo que no asuma que la credencial que llega a esta ruta llega al resto de la red. 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 ````