Averbate a portability

Performs averbar-portabilidade-trabalhador (Manual 008 v1.10 §5.3): the proponent institution’s averbação of a portability. The origin-side exclusion is a separate command, POST /v1/consignado/contracts//portabilidade/exclusao. It may occur before or after this averbação under Manual 008 §4, which explicitly defines the before-exclusion case and treats the reserved value as zero.

dataExclusaoOrigem is optional and is not sent to Dataprev. When supplied, it is the origin exclusion date tracked by the client. The gateway echoes it so it can refuse an averbação whose 20-calendar-day window (Manual 008 §4) has already elapsed before calling the rail. No business calendar is consulted because the window is in calendar days. When absent, the gateway submits the averbação as occurring before the origin exclusion. The gateway has no initiating fact to fall back on, so the client is the only source of the exclusion date when one exists.

X-Idempotency is the mandatory transport replay key. A retry with the same key is answered from the stored Dataprev answer instead of being resubmitted to the rail. A rejection that the gateway issues 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 response carries X-Idempotency-Fenced: true, and a resend under the same key is rejected with 422 IDEMPOTENCY_OUTCOME_UNRECORDED. A 503 whose only Dataprev code is OZ (service suspended) does not hold the key. Reconcile on GET /v1/consignado/portabilidade/efetivacoes instead of resending under a new key, which would submit the averbação again. This route does not have durable Postgres-backed replay storage, so, unlike the bid route, that guarantee does not survive a Redis eviction or restart.

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

Averbate a portability

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

Authorizations

Authorization · string · header · required

JWT bearer token issued by the identity provider.

Headers

X-Idempotency · string · required

Required transport replay key, scoped by authenticated tenant.

Required string length: 1 - 128

Example:

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

Path Parameters

numero_unico · string · required

The portability's NSU (Manual 008 v1.10 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}$

Example:

"100000000000000000001"

Body

application/json

codigoInscricaoEmpregador · string · required

1 CNPJ, 2 CPF.

Pattern: ^[12]$

Example:

"1"

cpfTrabalhador · string · required

Worker CPF, 11 digits.

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

Example:

"99999999999"

dataFimContrato · string<date-time> · required

Contract end date.

Example:

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

dataInicioContrato · string<date-time> · required

Contract start date.

Example:

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

dataPrimeiroDesconto · string<date-time> · required

First payroll discount date.

Example:

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

matricula · string · required

Worker registration number at the employer.

Required string length: 1 - 30

Example:

"99999999999-A"

nomeTrabalhador · string · required

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

Example:

"Trabalhador 99999999999"

numeroContrato · string · required

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]+$

Example:

"199971600000"

numeroInscricaoEmpregador · string · required

Employer inscription number.

Required string length: 1 - 15

Example:

"99999999999881"

numeroParcelas · integer<int64> · required

Number of instalments.

Required range: 1 <= x <= 999

Example:

48

temGarantias · boolean · required

Whether this averbação pledges FGTS collateral.

Example:

false

valorCETAnual · string · required

Annual total effective cost in percent.

Maximum string length: 10

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

Example:

"11.00"

valorCETMensal · string · required

Monthly total effective cost in percent.

Maximum string length: 10

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

Example:

"0.90"

valorEmprestimo · string · required

Principal plus financed costs as an exact decimal string.

Maximum string length: 13

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

Example:

"2160.00"

valorPago · string · required

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})?$

Example:

"2000.00"

valorParcela · string · required

Instalment amount as an exact decimal string.

Maximum string length: 13

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

Example:

"180.00"

valorTaxaAnual · string · required

Annual interest rate in percent.

Maximum string length: 10

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

Example:

"10.00"

valorTaxaMensal · string · required

Monthly interest rate in percent.

Maximum string length: 10

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

Example:

"0.80"

cnpjOperador · string

OPTIONAL correspondent/cooperado CNPJ.

Maximum string length: 14

Example:

"12345678000199"

competenciaInicioDesconto · string

OPTIONAL. yyyyMM.

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

Example:

"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, this averbação is submitted as occurring BEFORE the origin exclusion (Manual 008 §4 permits either order).

Example:

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

numeroProposta · string

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

Maximum string length: 20

Example:

"7K9M2P4R6T8V3W5X2Y4Z"

percVerbaRescisoriaGarantia · string

OPTIONAL severance-pay percentage pledged as collateral.

Maximum string length: 6

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

Example:

"15.00"

valorMultaRescisoriaGarantiaFgts · string

OPTIONAL rescission-penalty amount pledged as collateral.

Maximum string length: 13

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

Example:

"300.00"

valorSaldoDisponivelGarantiaFgts · string

OPTIONAL consignable FGTS balance pledged as collateral.

Maximum string length: 13

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

Example:

"600.00"

Response

200

application/json

OK

codigoSucesso · string · required

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

Maximum string length: 32

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

Example:

"BD"

competenciaInicioDesconto · integer<int64> · required

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

Example:

202602

numeroContrato · string · required

Contract number echoed by Dataprev.

Example:

"199971600000"

numeroUnico · string · required

The portability identity addressed by this averbação.

Example:

"100000000000000000001"

submittedAt · string<date-time> · required

UTC instant the gateway submitted this averbação.

Example:

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

mensagem · string

Rail message, relayed verbatim.

Example:

"Averbacao realizada com sucesso"