Remove an averbado contract from the payroll registry

Removes one averbado contract from the Dataprev registry through excluir-consignado-trabalhador (Manual 003 v1.21 §3.3). THERE IS NO UNDO, which is why the operation is marked x-money-path: true.

The contract is excludable once its averbação is confirmed, or while Dataprev accepted it and it still waits for its documentation (attachment_pending: none sent through POST …/ccb-attachment, the last one failed at Dataprev, or the gateway took it and never sent it, which the exclusion discards; an attachment_invoking call past its attachment_invocation_deadline_at lost its process and counts as failed). From that claim on, documentation for the contract is refused with 409 AVERBACAO_EXCLUDED until the exclusion ends rejected under any evidenceSource but m005_observation. A rejection under m005_observation means the contract already left the registry, so its documentation stays refused. A refinanciamento reversal recorded after that rejection reopens the contract, and with it its documentation and deadline follow-up. A contract with no averbação in this gateway is excludable while the gateway reports it in M015 and it is still in the registry: imported without booking, a renegotiated legado, a portability received, or the new contract of a refinanciamento or renegociação. A contract a renegociação replaced is excluded at the number that replaced it (through successive renegociações to the last), and the fact answers under the number asked; a refinanciamento’s replaced contract is never followed.

The body carries exactly ONE key. codigoSolicitante, cpfTrabalhador, matricula, codigoInscricaoEmpregador and numeroInscricaoEmpregador are never accepted from the caller: they identify the worker and the employer and come from the immutable local booking snapshot or, for a contract without one, from its M015 obligation, so a client cannot address an exclusion at a worker the gateway’s own records never covered.

The answer distinguishes the three outcomes a caller must be able to tell apart:

Status	Meaning
201	This call created the attempt and it reached a terminal state — confirmed (the contract came off the payroll) or rejected (this exclusion did not run: the registry refused it, and its own code and message are in the body; or, under evidenceSource m005_observation, the contract read showed the contract already off the registry, reasonCode contract_left_registry.*)
200	A replay of an attempt that is ALREADY terminal: the outcome in the body is the earlier attempt’s, and this call invoked nothing
202	The gateway holds the request and the effect at the registry is not known yet; M005 reconciliation converges it. A replay of an attempt that is not terminal yet is also a 202 — X-Idempotency-Replayed, not the status code, is what says whether this call invoked anything

A rejected attempt is a BUSINESS answer, not a transport error: the body carries the registry’s refusal, or the contract read that closed it, for the client to read.

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

Remove an averbado contract from the payroll registry

cURL

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

200

{
  "motivoExclusao": "1",
  "numeroContrato": "99999999999AN1",
  "status": "confirmed",
  "evidenceSource": "exclude_response",
  "message": "motivo nao publicado",
  "outcomeAt": "2026-08-05T12:00:00Z",
  "providerReference": "HASH-1",
  "reasonCode": "ME"
}

Autorizaciones

Authorization · string · header · requerido

JWT bearer token issued by the identity provider.

Encabezados

X-Idempotency · string · requerido

Mandatory opaque replay key, 1..128 bytes of valid UTF-8, preserved byte for byte. There is no X-Idempotency-Key alias, no case folding and no normalization: two keys differing in one byte are two keys.

Required string length: 1 - 128

Ejemplo:

"idem-exclusao-0001"

Parámetros de ruta

numero_contrato · string · requerido

The rail contract number (Manual 003 v1.21 §3.3.1 p.16-17: Texto, 2 to 15 characters of free choice). Exact, control-free UTF-8: no trimming and no case folding.

Required string length: 2 - 15

Ejemplo:

"99999999999AN1"

Cuerpo

application/json

motivo_exclusao · enum<string> · requerido

The client's declared reason for removing the contract from the rail, as one of the closed codes Manual 003 §3.3.1 publishes: 1 desistência do empréstimo, 2 falecimento, 3 liquidação antecipada, 7 ação judicial, 8 exclusão por fraude, 9 outros. A string, never a JSON number. Mandatory on every request: the gateway never declares a reason on the client's behalf, and an absent or unpublished code is refused locally before the rail is called.

Opciones disponibles: 1, 2, 3, 7, 8, 9

Ejemplo:

"1"

Respuesta

200

application/json

A replay of an attempt that is already terminal: the outcome in the body is the earlier attempt's, and this call invoked nothing.

motivoExclusao · enum<string> · requerido

The client's declared Manual 003 §3.3.1 reason, echoed from the durable authority.

Opciones disponibles: 1, 2, 3, 7, 8, 9

Ejemplo:

"1"

numeroContrato · string · requerido

The contract number Dataprev was asked to exclude: the number asked for, or the one a renegociação gave that contract.

Ejemplo:

"99999999999AN1"

status · enum<string> · requerido

Durable operation status. confirmed means the contract came off the payroll; rejected means the exclusion did not run: the registry published a refusal, or its contract read showed the contract already off the registry by another way; claimed, invoking and outcome_unknown all mean the effect at the registry is NOT known yet and M005 reconciliation has to close it — none of the three is a failure to retry blindly.

Opciones disponibles: claimed, invoking, confirmed, rejected, outcome_unknown

Ejemplo:

"confirmed"

evidenceSource · string

Which proof produced the terminal state: exclude_response, operator_evidence or m005_observation. Empty until one did.

Ejemplo:

"exclude_response"

message · string

The refusal message the REGISTRY published, or the gateway's account of the contract read that closed it. Present only on a rejected operation.

Ejemplo:

"motivo nao publicado"

outcomeAt · string<date-time>

Instant the registry answered, RFC 3339 UTC. ABSENT until it did.

Ejemplo:

"2026-08-05T12:00:00Z"

providerReference · string

The registry's own receipt for the mutation. ABSENT when it minted none, which is the normal case under an m005_observation confirmation — absence is never a verdict.

Ejemplo:

"HASH-1"

reasonCode · string

The refusal code the REGISTRY published, or contract_left_registry.situacao_N[.origem_N] when its contract read showed the contract already off the registry. Present only on a rejected operation.

Ejemplo:

"ME"