Averbate a portability whose origin exclusion already ran

Performs averbar-portabilidade-trabalhador (Manual 008 §5.3): the PROPONENTE institution’s averbação of a portability, whose origin-side exclusion must already have run. The origin exclusion is a SEPARATE command at POST /v1/consignado/contracts//portabilidade/exclusao; Dataprev refuses this averbação with rule PT when the exclusion has not run and with rule PW when the portability is already closed (Manual 008 §5.3), and either refusal frees the contract number.

dataExclusaoOrigem is OPTIONAL and NOT sent to Dataprev. When the client supplies it, it is the origin exclusion date the client itself tracks, echoed here so the gateway can refuse an averbação whose 20-CALENDAR-day window (Manual 008 §4) has already passed before the rail is ever called. No calendar is consulted: the window is explicitly “corridos”. When absent, only that pre-rail window check is skipped and the rail judges the order and the window.

X-Idempotency is required as this surface’s mandatory transport replay key. A retry under the SAME key is answered from the stored rail answer instead of re-submitting to the rail. A refusal the gateway gives on its own is not stored, so a corrected body under the same key is processed. A 500, 503 or 504 that may have reached Dataprev holds the key for its 7-day TTL: that answer carries X-Idempotency-Fenced: true, and a resend under the key is refused with 422 IDEMPOTENCY_OUTCOME_UNRECORDED. A 503 whose only Dataprev code is OZ (service suspended) does not hold the key. The contract number is claimed before the call, so a resend under a new key never submits again while that outcome is open: it answers 409 while the first call may still be running, then 503 OUTCOME_UNKNOWN until the gateway settles it by reading the contract on Dataprev (Manual 005). A contract Dataprev registered is then recorded as an acceptance is; one Dataprev holds no record of frees the number.

An accepted averbação is recorded before this answer as a contract of this gateway waiting for its documentation (GET /v1/consignado/contracts//averbacao reads attachment_pending), at the competência Dataprev echoed, together with its saldo devedor (Manual 015) obligation; its contract_id is its numeroContrato. A refusal Dataprev publishes for this averbação leaves the number free. A contract number this tenant already holds, including one this route recorded, is refused 409 CONTRACT_ALREADY_REGISTERED before the rail; a number only an averbação Dataprev refused held is free, unless that averbação’s contract_id is the same number. The optional booking object books the contract: its liberated_amount is valorEmprestimo less iof_amount (the origin payoffs plus the troco), and its origins name every origin contract the purchase pays off, one entry when there is one, with its share of valorPago. A booking the lender would refuse answers 422 with the averbação’s codes before the rail. Document the contract through POST /v1/consignado/contracts//ccb-attachment exactly as an averbação: booked, with the signed CCB, the evidence pack and signature_evidence_ref, and once Dataprev accepts the documentation the Lerian lender receives consignado.contract.registered carrying portability_in once Dataprev’s status record for this portability (Manual 008 §5.4) shows exactly the origin contracts booked (each with its bank, its number and its share of valorPago, and the latest exclusion instant); without booking, the signed CCB alone and no lender fact.

POST /v1/consignado/portabilidade/{numero_unico}/averbacao

Averbate a portability whose origin exclusion already ran

cURL

curl --request POST \
  --url https://br-consignado-gw.sandbox.lerian.net/v1/consignado/portabilidade/{numero_unico}/averbacao \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "codigoInscricaoEmpregador": "1",
  "cpfTrabalhador": "99999999999",
  "dataFimContrato": "2031-01-01T00:00:00Z",
  "dataInicioContrato": "2026-01-01T00:00:00Z",
  "dataPrimeiroDesconto": "2026-02-01T00:00:00Z",
  "matricula": "99999999999-A",
  "nomeTrabalhador": "Trabalhador 99999999999",
  "numeroContrato": "199971600000",
  "numeroInscricaoEmpregador": "99999999999881",
  "numeroParcelas": 48,
  "temGarantias": false,
  "valorCETAnual": "11.00",
  "valorCETMensal": "0.90",
  "valorEmprestimo": "2160.00",
  "valorPago": "2000.00",
  "valorParcela": "180.00",
  "valorTaxaAnual": "10.00",
  "valorTaxaMensal": "0.80",
  "cnpjOperador": "12345678000199",
  "competenciaInicioDesconto": "202602",
  "dataExclusaoOrigem": "2026-01-01T00:00:00Z",
  "numeroProposta": "7K9M2P4R6T8V3W5X2Y4Z",
  "percVerbaRescisoriaGarantia": "15.00",
  "valorMultaRescisoriaGarantiaFgts": "300.00",
  "valorSaldoDisponivelGarantiaFgts": "600.00"
}
'

200

{
  "codigoSucesso": "BD",
  "competenciaInicioDesconto": 202602,
  "numeroContrato": "199971600000",
  "numeroUnico": "100000000000000000001",
  "submittedAt": "2026-01-15T00:00:00Z",
  "mensagem": "Averbacao realizada com sucesso"
}

Autorizaciones

Authorization · string · header · requerido

JWT bearer token issued by the identity provider.

Encabezados

X-Idempotency · string · requerido

Required transport replay key, scoped by authenticated tenant.

Required string length: 1 - 128

Ejemplo:

"idem-portabilidade-averbacao-2026-01-21-0001"

Parámetros de ruta

numero_unico · string · requerido

The portability's NSU (Manual 008 v1.14 publishes 21 algarismos, which overflows int64/float64 — carried and validated as a digit string only).

Required string length: 1 - 21

Pattern: ^[0-9]{1,21}$

Ejemplo:

"100000000000000000001"

Cuerpo

application/json

codigoInscricaoEmpregador · string · requerido

1 CNPJ, 2 CPF.

Pattern: ^[12]$

Ejemplo:

"1"

cpfTrabalhador · string · requerido

Worker CPF, 11 digits.

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

Ejemplo:

"99999999999"

dataFimContrato · string<date-time> · requerido

Contract end date.

Ejemplo:

"2031-01-01T00:00:00Z"

dataInicioContrato · string<date-time> · requerido

Contract start date.

Ejemplo:

"2026-01-01T00:00:00Z"

dataPrimeiroDesconto · string<date-time> · requerido

First payroll discount date.

Ejemplo:

"2026-02-01T00:00:00Z"

matricula · string · requerido

Worker registration number at the employer.

Required string length: 1 - 30

Ejemplo:

"99999999999-A"

nomeTrabalhador · string · requerido

Worker's full name. Manual 008 §5.3.1 publishes 90 characters; the mirrored Swagger publishes maxLength 100 for the same field — the wider bound is accepted here so a value the rail itself would honour is never rejected first.

Required string length: 1 - 100

Ejemplo:

"Trabalhador 99999999999"

numeroContrato · string · requerido

Contract number being averbado, minted by the CLIENT: 2 to 15 letters or digits, without spaces, accents or symbols (Manual 008 §5.3.1 and its note [2]; the Swagger's maxLength 20 is not followed).

Required string length: 2 - 15

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

Ejemplo:

"199971600000"

numeroInscricaoEmpregador · string · requerido

Employer inscription number.

Required string length: 1 - 15

Ejemplo:

"99999999999881"

numeroParcelas · integer<int64> · requerido

Number of instalments.

Rango requerido: 1 <= x <= 999

Ejemplo:

48

temGarantias · boolean · requerido

Whether this averbação pledges FGTS collateral. True with none of the three collateral values below is refused 422 before the rail is called (Dataprev rule FI).

Ejemplo:

false

valorCETAnual · string · requerido

Annual total effective cost in percent.

Maximum string length: 10

Pattern: ^[0-9]+(\.[0-9]{1,2})?$

Ejemplo:

"11.00"

valorCETMensal · string · requerido

Monthly total effective cost in percent.

Maximum string length: 10

Pattern: ^[0-9]+(\.[0-9]{1,2})?$

Ejemplo:

"0.90"

valorEmprestimo · string · requerido

Principal plus financed costs as an exact decimal string.

Maximum string length: 13

Pattern: ^[0-9]+(\.[0-9]{1,2})?$

Ejemplo:

"2160.00"

valorPago · string · requerido

Settlement amount for the ORIGINAL contract(s) being ported — a field unique to this averbação.

Maximum string length: 13

Pattern: ^[0-9]+(\.[0-9]{1,2})?$

Ejemplo:

"2000.00"

valorParcela · string · requerido

Instalment amount as an exact decimal string.

Maximum string length: 13

Pattern: ^[0-9]+(\.[0-9]{1,2})?$

Ejemplo:

"180.00"

valorTaxaAnual · string · requerido

Annual interest rate in percent.

Maximum string length: 10

Pattern: ^[0-9]+(\.[0-9]{1,2})?$

Ejemplo:

"10.00"

valorTaxaMensal · string · requerido

Monthly interest rate in percent.

Maximum string length: 10

Pattern: ^[0-9]+(\.[0-9]{1,2})?$

Ejemplo:

"0.80"

booking · object

OPTIONAL. The block the Lerian lender books the bought contract with, never sent to Dataprev: all of its members or the object omitted. Omitted, the contract is rail-only and no lender fact follows.

Show child attributes

cnpjOperador · string

OPTIONAL correspondent/cooperado CNPJ.

Maximum string length: 14

Ejemplo:

"12345678000199"

competenciaInicioDesconto · string

OPTIONAL. yyyyMM.

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

Ejemplo:

"202602"

dataExclusaoOrigem · string<date-time>

OPTIONAL. Origin exclusion date the client tracks, NEVER sent to Dataprev. When present, the gateway's own 20-calendar-day pre-rail refusal is judged against it. When absent, only that check is skipped and Dataprev judges the order (rule PT: the origin exclusion must have run).

Ejemplo:

"2026-01-01T00:00:00Z"

numeroProposta · string

OPTIONAL. Manual-only field of undocumented referent — see the operation description.

Maximum string length: 20

Ejemplo:

"7K9M2P4R6T8V3W5X2Y4Z"

percVerbaRescisoriaGarantia · string

OPTIONAL severance-pay percentage pledged as collateral.

Maximum string length: 6

Pattern: ^[0-9]+(\.[0-9]{1,2})?$

Ejemplo:

"15.00"

valorMultaRescisoriaGarantiaFgts · string

OPTIONAL rescission-penalty amount pledged as collateral.

Maximum string length: 13

Pattern: ^[0-9]+(\.[0-9]{1,2})?$

Ejemplo:

"300.00"

valorSaldoDisponivelGarantiaFgts · string

OPTIONAL consignable FGTS balance pledged as collateral.

Maximum string length: 13

Pattern: ^[0-9]+(\.[0-9]{1,2})?$

Ejemplo:

"600.00"

Respuesta

200

application/json

OK

codigoSucesso · string · requerido

Bounded rail outcome code, relayed verbatim. Free-form provider text is never returned.

Maximum string length: 32

Pattern: ^[A-Za-z0-9_-]*$

Ejemplo:

"BD"

competenciaInicioDesconto · integer<int64> · requerido

First payroll-discount competência (yyyyMM) echoed by Dataprev.

Ejemplo:

202602

numeroContrato · string · requerido

Contract number echoed by Dataprev.

Ejemplo:

"199971600000"

numeroUnico · string · requerido

The portability identity addressed by this averbação.

Ejemplo:

"100000000000000000001"

submittedAt · string<date-time> · requerido

UTC instant the gateway submitted this averbação.

Ejemplo:

"2026-01-15T00:00:00Z"

mensagem · string

Rail message, relayed verbatim.

Ejemplo:

"Averbacao realizada com sucesso"