> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zipdin.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Averbação

> Envio dos dados do contrato à DATAPREV para inclusão da averbação

<Note>Etapa **obrigatória** — a averbação é o passo indispensável para incluir o contrato junto à DATAPREV.</Note>

Envio dos dados do contrato, cadastrais e de pagamento para inclusão junto à DATAPREV. O resultado é
assíncrono — acompanhe em [Resultado da averbação](/docs/e-consignado/resultado-averbacao).

<Info>
  Todos os endpoints requerem autenticação via **Bearer token** no header `Authorization`.
  Consulte o [guia de autenticação](/docs/primeiros-passos/authentication) para obter suas credenciais e gerar um token.
</Info>

<Warning>
  O path antigo `POST /contract` (sem `/averbacao`) ainda funciona, mas está **deprecated** — a resposta
  inclui o header `Deprecation: true`. Use `POST /contract/averbacao`.
</Warning>

## Parâmetros

<ParamField body="assignee" type="string" required>
  CNPJ do cedente — exatamente 14 dígitos numéricos
</ParamField>

<ParamField body="endorsement" type="object" required>
  Dados do contrato e da operação

  <Expandable>
    <ParamField body="endorsement.cpf" type="string" required>CPF do trabalhador (8-11 dígitos)</ParamField>
    <ParamField body="endorsement.contractStartDate" type="string" required>Formato `ddMMyyyy`</ParamField>
    <ParamField body="endorsement.contractEndDate" type="string" required>Formato `ddMMyyyy`</ParamField>
    <ParamField body="endorsement.firstDiscountDate" type="string" required>Formato `ddMMyyyy`</ParamField>
    <ParamField body="endorsement.registration" type="string" required>Matrícula do trabalhador</ParamField>
    <ParamField body="endorsement.workerName" type="string" required>Nome do trabalhador (máx. 90 caracteres)</ParamField>
    <ParamField body="endorsement.contract" type="string" required>Identificador do contrato (13-15 caracteres alfanuméricos)</ParamField>
    <ParamField body="endorsement.employerRegistrationNumber" type="string" required>Inscrição do empregador</ParamField>
    <ParamField body="endorsement.employerName" type="string" required>Nome do empregador</ParamField>
    <ParamField body="endorsement.proposal" type="string">Identificador da proposta (opcional)</ParamField>
    <ParamField body="endorsement.installmentsNumber" type="integer" required>Número de parcelas (inteiro positivo)</ParamField>
    <ParamField body="endorsement.installmentValue" type="number" required>Valor da parcela (> 0)</ParamField>
    <ParamField body="endorsement.loanValue" type="number" required>Valor do empréstimo (> 0)</ParamField>
    <ParamField body="endorsement.fundedValue" type="number" required>Valor financiado (> 0)</ParamField>
    <ParamField body="endorsement.iofValue" type="number" required>Valor do IOF (≥ 0)</ParamField>
    <ParamField body="endorsement.monthlyCetValue" type="number" required>CET mensal (> 0)</ParamField>
    <ParamField body="endorsement.yearlyCetValue" type="number" required>CET anual (> 0)</ParamField>
    <ParamField body="endorsement.monthlyRateValue" type="number" required>Taxa mensal (> 0)</ParamField>
    <ParamField body="endorsement.yearlyRateValue" type="number" required>Taxa anual (> 0)</ParamField>
    <ParamField body="endorsement.hasGuarantees" type="boolean" required>Se a operação tem garantias</ParamField>
    <ParamField body="endorsement.availableGuaranteeFgtsBalance" type="number">Saldo FGTS de garantia (opcional)</ParamField>
    <ParamField body="endorsement.rescissionFineGuaranteeFgts" type="number">Multa rescisória de garantia (opcional)</ParamField>
    <ParamField body="endorsement.rescissionAllowanceGuaranteePercentage" type="number">% de garantia sobre aviso de rescisão (opcional)</ParamField>
  </Expandable>
</ParamField>

<ParamField body="contractInfo" type="object" required>
  Dados da assinatura/formalização

  <Expandable>
    <ParamField body="contractInfo.digitalCertificateSignatureIndicator" type="boolean" required />

    <ParamField body="contractInfo.officialDocumentValidationIndicator" type="boolean" required />

    <ParamField body="contractInfo.ipAddress" type="string" required>IP do assinante</ParamField>
    <ParamField body="contractInfo.signatureDateTime" type="string" required>Formato `ddMMyyyyHHmmss`</ParamField>
    <ParamField body="contractInfo.illiteracyIndicator" type="boolean" required>Deve ser `false` — analfabetos não são permitidos</ParamField>
    <ParamField body="contractInfo.insuranceValue" type="number">Valor do seguro (opcional)</ParamField>
    <ParamField body="contractInfo.biometricBase" type="string">Base biométrica (opcional)</ParamField>
    <ParamField body="contractInfo.formalizationId" type="string">Deve ser enviado junto com `formalizationDateTime` (ambos ou nenhum)</ParamField>
    <ParamField body="contractInfo.formalizationDateTime" type="string">Formato `ddMMyyyyHHmmss` — junto com `formalizationId`</ParamField>
  </Expandable>
</ParamField>

<ParamField body="workerInfo" type="object" required>
  Dados cadastrais do trabalhador

  <Expandable>
    <ParamField body="workerInfo.gender" type="string" required />

    <ParamField body="workerInfo.birthdate" type="string" required>Formato `yyyyMMdd`</ParamField>

    <ParamField body="workerInfo.motherName" type="string" required />

    <ParamField body="workerInfo.street" type="string" required />

    <ParamField body="workerInfo.number" type="string" required />

    <ParamField body="workerInfo.neighborhood" type="string" required />

    <ParamField body="workerInfo.city" type="string" required />

    <ParamField body="workerInfo.state" type="string" required>UF — exatamente 2 caracteres</ParamField>

    <ParamField body="workerInfo.zipCode" type="string" required />

    <ParamField body="workerInfo.incomeValue" type="number" required>Renda (> 0)</ParamField>
    <ParamField body="workerInfo.phones" type="array">Opcional — array de `{ddd, number, phoneType}`</ParamField>
  </Expandable>
</ParamField>

<ParamField body="paymentList" type="array" required>
  Lista de pagamentos (ao menos 1 item). Cada item precisa de **dados bancários completos OU `pixKey`**,
  nunca os dois.

  <Expandable>
    <ParamField body="paymentList[].cpfCnpj" type="string" required />

    <ParamField body="paymentList[].paymentValue" type="number" required>> 0</ParamField>
    <ParamField body="paymentList[].bank" type="string">Junto com agency/account/accountDigit/accountType</ParamField>

    <ParamField body="paymentList[].agency" type="string" />

    <ParamField body="paymentList[].account" type="string" />

    <ParamField body="paymentList[].accountDigit" type="string" />

    <ParamField body="paymentList[].accountType" type="number" />

    <ParamField body="paymentList[].pixKey" type="string">CPF, CNPJ, e-mail ou telefone — chaves aleatórias não são aceitas</ParamField>
  </Expandable>
</ParamField>

<Warning>
  Regra de negócio: a soma de todos os `paymentValue` em `paymentList` deve ser **exatamente igual** a
  `endorsement.loanValue`.
</Warning>

## Exemplo

<ResponseExample>
  ```json 202 - Aceito theme={null}
  {
    "requestId": "e7f8a9b0-c1d2-3456-e7f8-a9b0c1d23456",
    "status": "queued",
    "_links": {
      "self": { "href": "/dataprev-controller/contract/averbacao", "method": "POST" },
      "result": { "href": "/dataprev-controller/request/e7f8a9b0-c1d2-3456-e7f8-a9b0c1d23456", "method": "GET" }
    }
  }
  ```
</ResponseExample>

A resposta é assíncrona (`202` + `requestId`). Acompanhe o processamento em
[Resultado da averbação](/docs/e-consignado/resultado-averbacao).

## Erros de `/contract/*` (averbação, refin e documentos)

Formato **RFC7807-like** — o erro vem em `error.errors[]`, um item por campo inválido.

```json 400 - Exemplo (/contract/*) theme={null}
{
  "error": {
    "type": null,
    "title": "Validation failed",
    "detail": null,
    "instance": "/dataprev-controller/contract/averbacao",
    "status": 400,
    "errors": [
      { "field": "X-Idempotency-Key", "message": "Header X-Idempotency-Key é obrigatório" },
      { "field": "endorsement.loanValue", "message": "endorsement.loanValue deve ser maior que 0" }
    ]
  }
}
```