Import a contract already averbado outside this gateway

Adopts a contract that is ALREADY averbado on the payroll rail — registered on the Dataprev portal by hand, by a previous provider, or carried in from a book you are migrating — so its recurring saldo devedor obligation (Manual 015 §2.2) exists here and its first M015 report is scheduled.

It does NOT averbate anything and it moves no money: the only call it makes to Dataprev is consultar-emprestimo-trabalhador (Manual 005 v1.13 §3.2.1), a read, under your own credential. Everything the obligation needs — the worker’s CPF and matrícula, the employer inscription, the instalment count, the instalment amount, the first discount competência, the monthly rate and the first deduction date — is taken from that read. You send the contract number and, optionally, how many competências have already amortized; you never send worker or employer identifiers, and none come back.

Only a LIVE contract can be imported: situação 0 (Ativo), 7 (Contrato suspenso), 8 (Suspenso banco) or 17 (Contrato suspenso por antecipação de parcela). A suspension is not a closure — the deduction is still attached to the worker and the debt is still reportable. Situação 2, 3, 15 and 16 are closed and refused 422 whose detail names the código the registry published (situacaoEmprestimo 3 não é vigente) and nothing else — Dataprev’s own descrição is never relayed into the body. Importing one would make this gateway file recurring reports about a debt the registry already ended. A read that carries no situação at all, no competência de início de desconto, no monthly rate (valorTaxaMensal) or first deduction date (dataPrimeiroDesconto), or one that answers about a different contract number, is refused 422 the same way rather than guessed at.

The import is not idempotent in the ordinary sense: a contract this tenant already holds an obligation for is answered 409 CONTRACT_ALREADY_REGISTERED, with nothing changed and the parcelas_pagas you sent NOT applied. X-Idempotency is still required, and the transport middleware replays the answer of a duplicate request under the same key.

WITH BOOKING (booking + registration): the contract is also handed to the Lerian lender exactly as an averbação through this gateway would hand it — both documents are retained in this gateway’s custody and consignado_contract.registered is published afterwards. booking is the averbação body with its full booking block; registration is the rail acknowledgement you received. First, before the Dataprev read, a booking the lender would refuse to book answers 422 with the codes of the averbação and documentation routes (BOOKING_FIELD_INVALID, DECLARED_TERMS_INCONSISTENT, MARGIN_SNAPSHOT_INCONSISTENT, CONTRACT_NOT_BOOKABLE, DECLARED_DATES_OUT_OF_ORDER, FORMALIZATION_DEADLINE_EXCEEDED), its detail naming the rule, and nothing is read or written; when the refused value is the one Dataprev holds, import the contract without booking. FIRST_DEDUCTION_BEFORE_COMPETENCIA is the averbação’s own rule and never refuses an import. Before anything is written the booking is checked against the same Dataprev read: worker, employer and contract must be the published ones; every money term (principal, liberado, parcela, quantidade, taxas, CET, IOF), the first discount competência, the contract dates and the guarantee must equal what the read publishes (a date or guarantee value the rail does not publish is not compared); registration.averbado_at must sit within one minute of the read’s aceito_em; and the read must carry every term the registration needs. Otherwise 422. The same request replays with the same answer; a different booking for a contract already in the averbação book is 409 CONTRACT_ALREADY_REGISTERED. In this mode an obligation the contract already holds is NOT a conflict: it is left untouched and saldo_devedor_dispatch_scheduled answers false. Nothing is averbated and the CCB is not attached at Dataprev.

POST /v1/consignado/contracts/{numero_contrato}/import

Import a contract already averbado outside this gateway

cURL

curl --request POST \
  --url https://br-consignado-gw.sandbox.lerian.net/v1/consignado/contracts/{numero_contrato}/import \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "parcelas_pagas": 7
}
'

201

{
  "competencia_inicio_desconto": "202601",
  "numero_contrato": "199971600000",
  "numero_parcelas": 24,
  "origem": "importado",
  "parcelas_pagas": 7,
  "saldo_devedor_dispatch_scheduled": true,
  "situacao_emprestimo": 0,
  "valor_parcela": "1116.31"
}

Authorizations

Authorization · string · header · required

JWT bearer token issued by the identity provider.

Headers

X-Idempotency · string · required

Required idempotency key. Absent is 422, never a generated default.

Example:

"idem-import-1"

Path Parameters

numero_contrato · string · required

The contract number as the RAIL holds it (Manual 005 v1.13 §3.2.1 p.13, 2..15 alphanumerics). It is the only identifier the import takes: everything else about the contract is read back from Dataprev.

Required string length: 2 - 15

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

Example:

"199971600000"

Body

application/json

booking · object

OPTIONAL. The lender booking of this contract: the body the averbação route takes, with the FULL booking block and an EMPTY numero_proposta, plus the documentation the CCB-attachment route takes — both documents, signature_evidence_ref, data_hora_assinatura and the signature evidence — in one object. Its numero_contrato must equal the path, and its cpf, matricula, codigo_inscricao_empregador and numero_inscricao_empregador must equal what Dataprev publishes for the contract (an employer published as its 8-digit CNPJ root is sent as that root). Its money terms, first_deduction_competencia, contract dates and guarantee must equal the rail read wherever the read publishes them. Nothing in it reaches Dataprev. Requires registration.

Show child attributes

parcelas_pagas · integer<int64> · default: 0

How many monthly competências of this contract have ALREADY amortized under whoever averbou it. It must lie between 0 and the contract's own total de parcelas as the rail reports it; anything outside that is refused 422. Leave it at 0 only for a contract that has genuinely not been discounted yet. The saldo devedor treats as paid only the parcelas already due on the import day; this count decides when the contract reaches quitado — a value higher than reality ends the reports early, a lower one never reaches quitado, and the full count reports 0.00.

Required range: x >= 0

Example:

7

registration · object

OPTIONAL. The rail's acknowledgement of the averbação somebody else performed, as you received it. Requires booking.

Show child attributes

Response

201

application/json

Created

competencia_inicio_desconto · string · required

The first payroll competência the discount runs in, as the rail's verbatim AAAAMM literal.

Example:

"202601"

numero_contrato · string · required

The contract that was imported.

Example:

"199971600000"

numero_parcelas · integer<int64> · required

The contract's total de parcelas, as the rail reports it. Read back, never supplied.

Example:

24

origem · enum<string> · required

Always "importado" on this route — the provenance stamped on the obligation, distinguishing it forever from one this gateway averbou.

Available options: importado

Example:

"importado"

parcelas_pagas · integer<int64> · required

The amortized count recorded on the obligation — the value sent with the request.

Example:

7

saldo_devedor_dispatch_scheduled · boolean · required

True when this request minted the obligation and scheduled its first M015 saldo devedor report durably alongside it; it does NOT mean the report has been delivered to Dataprev — the outbox does that afterwards. False only on an import with booking whose contract already held an obligation: that obligation was left untouched and parcelas_pagas was not applied.

Example:

true

situacao_emprestimo · integer<int64> · required

The rail's own situação código for the contract at the moment it was imported (Manual 005 §3.2.2 p.17). Only 0, 7, 8 and 17 are importable.

Example:

0

valor_parcela · string · required

The instalment, as the rail reports it, verbatim (BRL decimal string).

Example:

"1116.31"