Registrar uma correção em um 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 uma correção em um contrato registrado

Registra uma correção de algo que o cliente já afirmou sobre um contrato registrado e publica o fato que a nomeia.

Esta NÃO é uma operação da Dataprev: nenhuma credencial da rede é usada e nenhuma fronteira governamental é atravessada. O Manual 005 revisão 1.13 declara que os campos de retificação da rede não são mais usados e sempre retornam null, portanto o cliente é a única autoridade que uma correção pode ter — source_authority é sempre client.

NADA É ALTERADO. Uma correção é um acréscimo que nomeia o que ela substitui, e o registro que ela corrige permanece imutável no banco de dados exatamente como estava. Corrigir a mesma coisa duas vezes acrescenta uma segunda correção que substitui a primeira.

O gateway assume a custódia do recurso corrigido e calcula o SHA-256 dele por conta própria; um digest declarado pelo cliente nunca é aceito. O fato publicado carrega um caminho de mesma origem de volta a este gateway mais esse digest, e o consumidor o busca e o verifica por M2M autenticado.

correction_type	payment_reference	supersedes
`ccb`	deve estar vazio	a correção de CCB anterior, ou nada na primeira
`disbursement`	obrigatório	o pagamento confirmado que ela repara, depois a correção anterior desse pagamento

Uma correção de disbursement que nomeia um pagamento para o qual esta instalação não possui confirmação é recusada com 404: uma substituição que aponta para nada é pior do que nenhuma correção.

X-Idempotency é obrigatório, opaco, de 1..128 bytes, e nunca assume valor padrão. O PostgreSQL é a autoridade: a mesma chave repete o corpo 202 idêntico e não publica um segundo fato, e a mesma chave carregando uma correção diferente responde 422 sem nunca retornar o corpo anterior.

POST

consignado

contracts

{numero_contrato}

corrections

Registrar uma correção em um 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"
  }
}

Autorizações

Authorization

string

header

obrigatório

JWT bearer token issued by the identity provider.

Cabeçalhos

X-Idempotency

string

obrigatório

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

Exemplo:

"idem-correcao-0001"

Parâmetros de caminho

numero_contrato

string

obrigatório

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

Exemplo:

"99999999999AN1"

Corpo

application/json

content_type

string

obrigatório

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

Exemplo:

"application/pdf"

correction_type

enum<string>

obrigatório

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

Opções disponíveis:

ccb,

disbursement

Exemplo:

"ccb"

file_name

string

obrigatório

Original file name of the corrected resource.

Maximum string length: 255

Exemplo:

"ccb-corrigida.pdf"

payment_reference

string

obrigatório

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

Exemplo:

"E32074986202608011200A1B2C3D4E5F"

resource_base64

string

obrigatório

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

Maximum string length: 8388608

Exemplo:

"JVBERi0xLjcKJSVFT0Y="

Resposta

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

correction_id

string

obrigatório

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

Exemplo:

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

correction_type

string

obrigatório

What was corrected.

Exemplo:

"ccb"

gateway_received_at

string

obrigatório

When the gateway took custody, strict RFC 3339 UTC.

Exemplo:

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

numero_contrato

string

obrigatório

The rail contract number, echoed from the path.

Exemplo:

"99999999999AN1"

resource_digest_sha256

string

obrigatório

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

Exemplo:

"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

resource_uri

string

obrigatório

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

Exemplo:

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

source_authority

string

obrigatório

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

Exemplo:

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

Exemplo:

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

Pix — Lerian SPI (mensageria nativa)

Pix — JD (interface, direto)

Pix — BTG (interface, indireto)

TED — Lerian SPB (mensageria nativa)

TED — JD (interface)

Boletos — BTG (interface)

Lerian SILOC (mensageria nativa)

Lerian SLC (mensageria nativa)

Lerian STA (mensageria nativa)

Lerian SISBAJUD (mensageria nativa)

Lerian Consignado — Dataprev

Registrar uma correção em um contrato registrado

Autorizações

Cabeçalhos

Parâmetros de caminho

Corpo

Resposta