Registrar una corrección sobre un contrato registrado

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

Registrar una corrección sobre un contrato registrado

Registra una corrección de algo que el cliente ya afirmó sobre un contrato registrado, y publica el hecho que la nombra.

Esta NO es una operación de Dataprev: no se usa ninguna credencial de la red y no se cruza ninguna frontera gubernamental. El Manual 005 revisión 1.13 indica que los campos de rectificación de la red ya no se usan y siempre devuelven null, por lo que el cliente es la única autoridad que puede tener una corrección: source_authority siempre es client.

NADA SE MUTA. Una corrección es una adición que nombra lo que sustituye, y el registro que corrige permanece inmutable en la base de datos exactamente como estaba. Corregir lo mismo dos veces agrega una segunda corrección que sustituye a la primera.

El gateway toma custodia del recurso corregido y calcula su SHA-256 por sí mismo; nunca se acepta un resumen declarado por el cliente. El hecho publicado lleva una ruta del mismo origen de vuelta a este gateway más ese resumen, y el consumidor lo obtiene y lo verifica por M2M autenticado.

correction_type	payment_reference	supersedes
`ccb`	debe estar vacío	la corrección CCB anterior, o nada en la primera
`disbursement`	obligatorio	el pago confirmado que repara, luego la corrección anterior de ese pago

Una corrección disbursement que nombra un pago del que este despliegue no tiene ninguna confirmación se rechaza con 404: una sustitución que no apunta a nada es peor que ninguna corrección.

X-Idempotency es obligatoria, opaca, de 1..128 bytes, y nunca tiene un valor por defecto. PostgreSQL es la autoridad: la misma clave repite el mismo cuerpo 202 y no publica un segundo hecho, y la misma clave que lleva una corrección diferente responde 422 sin devolver nunca el cuerpo anterior.

POST

consignado

contracts

{numero_contrato}

corrections

Registrar una corrección sobre un contrato registrado

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

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

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

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"

Pix — Lerian SPI (mensajería nativa)

Pix — JD (interfaz, directo)

Pix — BTG (interfaz, indirecto)

TED — Lerian SPB (mensajería nativa)

TED — JD (interfaz)

Boletos — BTG (interfaz)

Lerian SILOC (mensajería nativa)

Lerian SLC (mensajería nativa)

Lerian STA (mensajería nativa)

Lerian SISBAJUD (mensajería nativa)

Lerian Consignado — Dataprev

Registrar una corrección sobre un contrato registrado

Autorizaciones

Encabezados

Parámetros de ruta

Cuerpo

Respuesta