Record a correction to a registered contract

Records a correction to something the client already asserted about a registered contract, and publishes the fact that names it.

This is NOT a Dataprev operation: no rail credential is used and no government boundary is crossed. Manual 005 revision 1.13 states the rail’s retification fields are no longer used and always return null, so the client is the only authority a correction can have — source_authority is always client.

NOTHING IS MUTATED. A correction is an append that names what it supersedes, and the record it corrects stays immutable in the database exactly as it was. Correcting the same thing twice appends a second correction that supersedes the first.

The gateway takes custody of the corrected resource and computes its SHA-256 itself; a client-declared digest is never accepted. The published fact carries a same-origin path back to this gateway plus that digest, and the consumer fetches and verifies it over authenticated M2M.

correction_type	payment_reference	supersedes
ccb	must be empty	the previous CCB correction, or nothing on the first
disbursement	required	the confirmed payment it repairs, then the previous correction of that payment

A first CCB correction for a contract number this tenant never registered nor imported is refused with 404, before anything is retained: retained storage cannot delete, so a typo would otherwise stay for five years. A disbursement correction naming a payment this deployment holds no confirmation for is refused with 404 too: a supersession pointing at nothing is worse than no correction.

X-Idempotency is mandatory, opaque, 1..128 bytes, and never defaulted. PostgreSQL is the authority: the same key replays the identical 202 body and publishes no second fact, and the same key carrying a different correction answers 422 without ever returning the earlier body.

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

Record a correction to a registered contract

cURL

curl --request POST \
  --url https://br-consignado-gw.sandbox.lerian.net/v1/consignado/contracts/{numero_contrato}/corrections \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "content_type": "application/pdf",
  "correction_type": "ccb",
  "file_name": "ccb-corrigida.pdf",
  "payment_reference": "E32074986202608011200A1B2C3D4E5F",
  "resource_base64": "JVBERi0xLjcKJSVFT0Y="
}
'

202

{
  "correction_id": "1f5b9c26-6f5a-4f77-9c1c-5d1c0f0a9b21",
  "correction_type": "ccb",
  "gateway_received_at": "2026-08-29T12:00:05Z",
  "numero_contrato": "99999999999AN1",
  "resource_digest_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "resource_uri": "/v1/consignado/contracts/99999999999AN1/corrections/1f5b9c26-6f5a-4f77-9c1c-5d1c0f0a9b21",
  "source_authority": "client",
  "supersedes_event_id": "7c2a1b40-11f4-4a1e-9a44-1f4d7cbb8e02"
}

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. No default, no alias header, no case folding: two keys differing in one byte are two keys.

Required string length: 1 - 128

Ejemplo:

"idem-correcao-0001"

Parámetros de ruta

numero_contrato · string · requerido

The rail contract number the correction is about. 2 to 15 letters or digits, the rail's own rule.

Required string length: 2 - 15

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

Ejemplo:

"99999999999AN1"

Cuerpo

application/json

content_type · string · requerido

Media type of the corrected resource. Its media type must be application/pdf or application/zip — parameters are permitted — and the bytes are sniffed against it.

Maximum string length: 128

Ejemplo:

"application/pdf"

correction_type · enum<string> · requerido

What this correction corrects. Selects which fact is published; the payload shape is identical for both.

Opciones disponibles: ccb, disbursement

Ejemplo:

"ccb"

file_name · string · requerido

Original file name of the corrected resource.

Maximum string length: 255

Ejemplo:

"ccb-corrigida.pdf"

payment_reference · string · requerido

The payment_reference of the confirmed disbursement this correction repairs. Required when correction_type is disbursement, and must be empty otherwise.

Maximum string length: 256

Ejemplo:

"E32074986202608011200A1B2C3D4E5F"

resource_base64 · string · requerido

Canonical base64 of the corrected resource. The gateway computes the SHA-256 itself; no client-declared digest is accepted.

Maximum string length: 8388608

Ejemplo:

"JVBERi0xLjcKJSVFT0Y="

Respuesta

202

application/json

The correction is durably recorded and its fact queued. A replay under the same key answers with the identical body.

correction_id · string · requerido

The gateway's identity for this correction. It is also the published event id.

Ejemplo:

"1f5b9c26-6f5a-4f77-9c1c-5d1c0f0a9b21"

correction_type · string · requerido

What was corrected.

Ejemplo:

"ccb"

gateway_received_at · string · requerido

When the gateway took custody, strict RFC 3339 UTC.

Ejemplo:

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

numero_contrato · string · requerido

The rail contract number, echoed from the path.

Ejemplo:

"99999999999AN1"

resource_digest_sha256 · string · requerido

Lowercase hex SHA-256 the gateway computed over the corrected bytes.

Ejemplo:

"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

resource_uri · string · requerido

Same-origin relative path serving the corrected resource under M2M bearer auth.

Ejemplo:

"/v1/consignado/contracts/99999999999AN1/corrections/1f5b9c26-6f5a-4f77-9c1c-5d1c0f0a9b21"

source_authority · string · requerido

Who is authoritative for the corrected value. Always client on this gateway.

Ejemplo:

"client"

supersedes_event_id · string

The event id this correction supersedes: the corrected disbursement confirmation, or the previous correction. ABSENT on a first CCB correction, meaning the original contract fact.

Ejemplo:

"7c2a1b40-11f4-4a1e-9a44-1f4d7cbb8e02"