Record a correction to a registered contract

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

import requests

url = "https://br-consignado-gw.sandbox.lerian.net/v1/consignado/contracts/{numero_contrato}/corrections"

payload = {
    "content_type": "application/pdf",
    "correction_type": "ccb",
    "file_name": "ccb-corrigida.pdf",
    "payment_reference": "E32074986202608011200A1B2C3D4E5F",
    "resource_base64": "JVBERi0xLjcKJSVFT0Y="
}
headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Idempotency': '<x-idempotency>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    content_type: 'application/pdf',
    correction_type: 'ccb',
    file_name: 'ccb-corrigida.pdf',
    payment_reference: 'E32074986202608011200A1B2C3D4E5F',
    resource_base64: 'JVBERi0xLjcKJSVFT0Y='
  })
};

fetch('https://br-consignado-gw.sandbox.lerian.net/v1/consignado/contracts/{numero_contrato}/corrections', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://br-consignado-gw.sandbox.lerian.net/v1/consignado/contracts/{numero_contrato}/corrections",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'content_type' => 'application/pdf',
    'correction_type' => 'ccb',
    'file_name' => 'ccb-corrigida.pdf',
    'payment_reference' => 'E32074986202608011200A1B2C3D4E5F',
    'resource_base64' => 'JVBERi0xLjcKJSVFT0Y='
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "X-Idempotency: <x-idempotency>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://br-consignado-gw.sandbox.lerian.net/v1/consignado/contracts/{numero_contrato}/corrections"

	payload := strings.NewReader("{\n  \"content_type\": \"application/pdf\",\n  \"correction_type\": \"ccb\",\n  \"file_name\": \"ccb-corrigida.pdf\",\n  \"payment_reference\": \"E32074986202608011200A1B2C3D4E5F\",\n  \"resource_base64\": \"JVBERi0xLjcKJSVFT0Y=\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://br-consignado-gw.sandbox.lerian.net/v1/consignado/contracts/{numero_contrato}/corrections")
  .header("X-Idempotency", "<x-idempotency>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"content_type\": \"application/pdf\",\n  \"correction_type\": \"ccb\",\n  \"file_name\": \"ccb-corrigida.pdf\",\n  \"payment_reference\": \"E32074986202608011200A1B2C3D4E5F\",\n  \"resource_base64\": \"JVBERi0xLjcKJSVFT0Y=\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://br-consignado-gw.sandbox.lerian.net/v1/consignado/contracts/{numero_contrato}/corrections")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Idempotency"] = '<x-idempotency>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"content_type\": \"application/pdf\",\n  \"correction_type\": \"ccb\",\n  \"file_name\": \"ccb-corrigida.pdf\",\n  \"payment_reference\": \"E32074986202608011200A1B2C3D4E5F\",\n  \"resource_base64\": \"JVBERi0xLjcKJSVFT0Y=\"\n}"

response = http.request(request)
puts response.read_body

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

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

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 disbursement correction naming a payment this deployment holds no confirmation for is refused with 404: 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

consignado

contracts

{numero_contrato}

corrections

Record a correction to a registered contract

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

import requests

url = "https://br-consignado-gw.sandbox.lerian.net/v1/consignado/contracts/{numero_contrato}/corrections"

payload = {
    "content_type": "application/pdf",
    "correction_type": "ccb",
    "file_name": "ccb-corrigida.pdf",
    "payment_reference": "E32074986202608011200A1B2C3D4E5F",
    "resource_base64": "JVBERi0xLjcKJSVFT0Y="
}
headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Idempotency': '<x-idempotency>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    content_type: 'application/pdf',
    correction_type: 'ccb',
    file_name: 'ccb-corrigida.pdf',
    payment_reference: 'E32074986202608011200A1B2C3D4E5F',
    resource_base64: 'JVBERi0xLjcKJSVFT0Y='
  })
};

fetch('https://br-consignado-gw.sandbox.lerian.net/v1/consignado/contracts/{numero_contrato}/corrections', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://br-consignado-gw.sandbox.lerian.net/v1/consignado/contracts/{numero_contrato}/corrections",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'content_type' => 'application/pdf',
    'correction_type' => 'ccb',
    'file_name' => 'ccb-corrigida.pdf',
    'payment_reference' => 'E32074986202608011200A1B2C3D4E5F',
    'resource_base64' => 'JVBERi0xLjcKJSVFT0Y='
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "X-Idempotency: <x-idempotency>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://br-consignado-gw.sandbox.lerian.net/v1/consignado/contracts/{numero_contrato}/corrections"

	payload := strings.NewReader("{\n  \"content_type\": \"application/pdf\",\n  \"correction_type\": \"ccb\",\n  \"file_name\": \"ccb-corrigida.pdf\",\n  \"payment_reference\": \"E32074986202608011200A1B2C3D4E5F\",\n  \"resource_base64\": \"JVBERi0xLjcKJSVFT0Y=\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://br-consignado-gw.sandbox.lerian.net/v1/consignado/contracts/{numero_contrato}/corrections")
  .header("X-Idempotency", "<x-idempotency>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"content_type\": \"application/pdf\",\n  \"correction_type\": \"ccb\",\n  \"file_name\": \"ccb-corrigida.pdf\",\n  \"payment_reference\": \"E32074986202608011200A1B2C3D4E5F\",\n  \"resource_base64\": \"JVBERi0xLjcKJSVFT0Y=\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://br-consignado-gw.sandbox.lerian.net/v1/consignado/contracts/{numero_contrato}/corrections")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Idempotency"] = '<x-idempotency>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"content_type\": \"application/pdf\",\n  \"correction_type\": \"ccb\",\n  \"file_name\": \"ccb-corrigida.pdf\",\n  \"payment_reference\": \"E32074986202608011200A1B2C3D4E5F\",\n  \"resource_base64\": \"JVBERi0xLjcKJSVFT0Y=\"\n}"

response = http.request(request)
puts response.read_body

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

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Authorizations

Authorization

string

header

required

JWT bearer token issued by the identity provider.

Headers

X-Idempotency

string

required

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

Example:

"idem-correcao-0001"

Path Parameters

numero_contrato

string

required

The rail contract number the correction is about. Exact, control-free UTF-8, bounded in BYTES: 2..15, which is the consumer's own bound for this field.

Required string length: 2 - 15

Example:

"99999999999AN1"

Body

application/json

content_type

string

required

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

Example:

"application/pdf"

correction_type

enum<string>

required

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

Available options:

ccb,

disbursement

Example:

"ccb"

file_name

string

required

Original file name of the corrected resource.

Maximum string length: 255

Example:

"ccb-corrigida.pdf"

payment_reference

string

required

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

Example:

"E32074986202608011200A1B2C3D4E5F"

resource_base64

string

required

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

Maximum string length: 8388608

Example:

"JVBERi0xLjcKJSVFT0Y="

Response

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

correction_id

string

required

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

Example:

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

correction_type

string

required

What was corrected.

Example:

"ccb"

gateway_received_at

string

required

When the gateway took custody, strict RFC 3339 UTC.

Example:

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

numero_contrato

string

required

The rail contract number, echoed from the path.

Example:

"99999999999AN1"

resource_digest_sha256

string

required

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

Example:

"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

resource_uri

string

required

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

Example:

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

source_authority

string

required

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

Example:

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

Example:

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

Pix — Lerian SPI (native messaging)

Pix — JD (interface, direct)

Pix — BTG (interface, indirect)

TED — Lerian SPB (native messaging)

TED — JD (interface)

Boletos — BTG (interface)

Lerian SILOC (native messaging)

Lerian SLC (native messaging)

Lerian STA (native messaging)

Lerian SISBAJUD (native messaging)

Lerian Consignado — Dataprev

Record a correction to a registered contract

Authorizations

Headers

Path Parameters

Body

Response