Boletos

Endpoints para criar, consultar, atualizar e cancelar boletos.

Status do Boleto

Status	Descricao
`draft`	Rascunho - boleto criado mas nao registrado
`registered`	Registrado na Nuclea (PCR)
`paid`	Pago pelo pagador
`settled`	Liquidado - fundos transferidos
`cancelled`	Cancelado

Criar Boleto

Cria um novo boleto e registra na plataforma PCR da Nuclea.

POST /boletos

Corpo da Requisicao

Campo	Tipo	Obrigatorio	Descricao
`nosso_numero`	string	Sim	Numero de referencia unico (11 digitos)
`amount_cents`	integer	Sim	Valor em centavos (ex: 10000 = R$ 100,00)
`due_date`	string	Sim	Data de vencimento (YYYY-MM-DD)
`payer_document`	string	Sim	CPF/CNPJ do pagador (somente numeros)
`payer_name`	string	Sim	Nome completo do pagador
`beneficiary_ispb`	string	Sim	ISPB do beneficiario (8 digitos)
`beneficiary_name`	string	Sim	Nome do beneficiario

Valor em Centavos

O campo amount_cents deve ser enviado em centavos para evitar problemas de precisao com numeros decimais. Por exemplo, R$ 150,50 deve ser enviado como 15050.

Exemplo de Requisicao

cURLJavaScriptPython

bash

curl -X POST "https://api.pixconnect.com.br/api/v1/central/boletos" \
  -H "X-API-Key: pk_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "boleto": {
      "nosso_numero": "12345678901",
      "amount_cents": 15000,
      "due_date": "2026-03-15",
      "payer_document": "12345678901",
      "payer_name": "Joao Silva Santos",
      "beneficiary_ispb": "02992335",
      "beneficiary_name": "Empresa XYZ Ltda"
    }
  }'

javascript

const response = await fetch(
  "https://api.pixconnect.com.br/api/v1/central/boletos",
  {
    method: "POST",
    headers: {
      "X-API-Key": "pk_live_abc123def456",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      boleto: {
        nosso_numero: "12345678901",
        amount_cents: 15000,
        due_date: "2026-03-15",
        payer_document: "12345678901",
        payer_name: "Joao Silva Santos",
        beneficiary_ispb: "02992335",
        beneficiary_name: "Empresa XYZ Ltda"
      }
    }),
  }
);

const data = await response.json();
console.log(data);

python

import requests

url = "https://api.pixconnect.com.br/api/v1/central/boletos"
headers = {
    "X-API-Key": "pk_live_abc123def456",
    "Content-Type": "application/json"
}
payload = {
    "boleto": {
        "nosso_numero": "12345678901",
        "amount_cents": 15000,
        "due_date": "2026-03-15",
        "payer_document": "12345678901",
        "payer_name": "Joao Silva Santos",
        "beneficiary_ispb": "02992335",
        "beneficiary_name": "Empresa XYZ Ltda"
    }
}

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

Resposta de Sucesso

Status: 201 Created

json

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "nosso_numero": "12345678901",
    "barcode": "23793381286000000000000000012345678901500001",
    "linha_digitavel": "23793.38128 60000.000003 00001.234567 8 90150000015000",
    "amount_cents": 15000,
    "due_date": "2026-03-15",
    "payer_document": "12345678901",
    "payer_name": "Joao Silva Santos",
    "beneficiary_ispb": "02992335",
    "beneficiary_name": "Empresa XYZ Ltda",
    "status": "registered",
    "pcr_protocol": "PCR2026021512345678",
    "registered_at": "2026-02-15T10:30:00Z",
    "paid_at": null,
    "cancelled_at": null,
    "inserted_at": "2026-02-15T10:30:00Z",
    "updated_at": "2026-02-15T10:30:00Z"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

Erros Possiveis

Codigo	Erro	Descricao
`400`	`BAD_REQUEST`	Campo `boleto` ausente no corpo da requisicao
`422`	`VALIDATION_ERROR`	Dados invalidos (documento, data, etc.)
`422`	`DUPLICATE_ENTRY`	`nosso_numero` ja existe

Consultar Boleto

Recupera os detalhes de um boleto pelo seu numero de referencia.

GET /boletos/:nosso_numero

Parametros de URL

Parametro	Tipo	Descricao
`nosso_numero`	string	Numero de referencia unico do boleto

Exemplo de Requisicao

cURLJavaScriptPython

bash

curl -X GET "https://api.pixconnect.com.br/api/v1/central/boletos/12345678901" \
  -H "X-API-Key: pk_live_abc123def456" \
  -H "Content-Type: application/json"

javascript

const nossoNumero = "12345678901";
const response = await fetch(
  `https://api.pixconnect.com.br/api/v1/central/boletos/${nossoNumero}`,
  {
    method: "GET",
    headers: {
      "X-API-Key": "pk_live_abc123def456",
      "Content-Type": "application/json",
    },
  }
);

const data = await response.json();
console.log(data);

python

import requests

nosso_numero = "12345678901"
url = f"https://api.pixconnect.com.br/api/v1/central/boletos/{nosso_numero}"
headers = {
    "X-API-Key": "pk_live_abc123def456",
    "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
print(response.json())

Resposta de Sucesso

Status: 200 OK

json

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "nosso_numero": "12345678901",
    "barcode": "23793381286000000000000000012345678901500001",
    "linha_digitavel": "23793.38128 60000.000003 00001.234567 8 90150000015000",
    "amount_cents": 15000,
    "due_date": "2026-03-15",
    "payer_document": "12345678901",
    "payer_name": "Joao Silva Santos",
    "beneficiary_ispb": "02992335",
    "beneficiary_name": "Empresa XYZ Ltda",
    "status": "registered",
    "pcr_protocol": "PCR2026021512345678",
    "registered_at": "2026-02-15T10:30:00Z",
    "paid_at": null,
    "cancelled_at": null,
    "inserted_at": "2026-02-15T10:30:00Z",
    "updated_at": "2026-02-15T10:30:00Z"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

Erros Possiveis

Codigo	Erro	Descricao
`404`	`NOT_FOUND`	Boleto nao encontrado

Atualizar Boleto

Atualiza os dados de um boleto. Apenas boletos em status draft podem ser atualizados.

PATCH /boletos/:nosso_numero

Parametros de URL

Parametro	Tipo	Descricao
`nosso_numero`	string	Numero de referencia unico do boleto

Corpo da Requisicao

Campo	Tipo	Descricao
`amount_cents`	integer	Novo valor em centavos
`due_date`	string	Nova data de vencimento (YYYY-MM-DD)
`payer_document`	string	Novo CPF/CNPJ do pagador
`payer_name`	string	Novo nome do pagador

Restricao de Status

Apenas boletos com status draft podem ser atualizados. Boletos ja registrados na Nuclea nao podem ser modificados.

Exemplo de Requisicao

cURLJavaScriptPython

bash

curl -X PATCH "https://api.pixconnect.com.br/api/v1/central/boletos/12345678901" \
  -H "X-API-Key: pk_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "boleto": {
      "amount_cents": 20000,
      "due_date": "2026-03-20"
    }
  }'

javascript

const nossoNumero = "12345678901";
const response = await fetch(
  `https://api.pixconnect.com.br/api/v1/central/boletos/${nossoNumero}`,
  {
    method: "PATCH",
    headers: {
      "X-API-Key": "pk_live_abc123def456",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      boleto: {
        amount_cents: 20000,
        due_date: "2026-03-20"
      }
    }),
  }
);

const data = await response.json();
console.log(data);

python

import requests

nosso_numero = "12345678901"
url = f"https://api.pixconnect.com.br/api/v1/central/boletos/{nosso_numero}"
headers = {
    "X-API-Key": "pk_live_abc123def456",
    "Content-Type": "application/json"
}
payload = {
    "boleto": {
        "amount_cents": 20000,
        "due_date": "2026-03-20"
    }
}

response = requests.patch(url, headers=headers, json=payload)
print(response.json())

Resposta de Sucesso

Status: 200 OK

json

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "nosso_numero": "12345678901",
    "amount_cents": 20000,
    "due_date": "2026-03-20",
    "status": "draft",
    // ... outros campos
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

Erros Possiveis

Codigo	Erro	Descricao
`400`	`BAD_REQUEST`	Campo `boleto` ausente no corpo da requisicao
`404`	`NOT_FOUND`	Boleto nao encontrado
`422`	`INVALID_STATUS`	Boleto nao esta em status `draft`
`422`	`VALIDATION_ERROR`	Dados invalidos

Cancelar Boleto

Cancela um boleto existente.

DELETE /boletos/:nosso_numero

Parametros de URL

Parametro	Tipo	Descricao
`nosso_numero`	string	Numero de referencia unico do boleto

Cancelamento

Boletos ja pagos ou liquidados nao podem ser cancelados. O cancelamento e irreversivel.

Exemplo de Requisicao

cURLJavaScriptPython

bash

curl -X DELETE "https://api.pixconnect.com.br/api/v1/central/boletos/12345678901" \
  -H "X-API-Key: pk_live_abc123def456" \
  -H "Content-Type: application/json"

javascript

const nossoNumero = "12345678901";
const response = await fetch(
  `https://api.pixconnect.com.br/api/v1/central/boletos/${nossoNumero}`,
  {
    method: "DELETE",
    headers: {
      "X-API-Key": "pk_live_abc123def456",
      "Content-Type": "application/json",
    },
  }
);

const data = await response.json();
console.log(data);

python

import requests

nosso_numero = "12345678901"
url = f"https://api.pixconnect.com.br/api/v1/central/boletos/{nosso_numero}"
headers = {
    "X-API-Key": "pk_live_abc123def456",
    "Content-Type": "application/json"
}

response = requests.delete(url, headers=headers)
print(response.json())

Resposta de Sucesso

Status: 200 OK

json

{
  "success": true,
  "data": {
    "nosso_numero": "12345678901",
    "status": "cancelled",
    "cancelled_at": "2026-02-15T14:30:00Z"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

Erros Possiveis

Codigo	Erro	Descricao
`404`	`NOT_FOUND`	Boleto nao encontrado
`422`	`INVALID_STATUS`	Boleto ja pago ou liquidado

Marcar como Pago

Marca um boleto como pago. Este endpoint e usado quando o pagamento foi confirmado externamente.

POST /boletos/:nosso_numero/pay

Parametros de URL

Parametro	Tipo	Descricao
`nosso_numero`	string	Numero de referencia unico do boleto

Webhook

Ao marcar um boleto como pago, um webhook boleto.paid e enviado automaticamente para a URL configurada.

Exemplo de Requisicao

cURLJavaScriptPython

bash

curl -X POST "https://api.pixconnect.com.br/api/v1/central/boletos/12345678901/pay" \
  -H "X-API-Key: pk_live_abc123def456" \
  -H "Content-Type: application/json"

javascript

const nossoNumero = "12345678901";
const response = await fetch(
  `https://api.pixconnect.com.br/api/v1/central/boletos/${nossoNumero}/pay`,
  {
    method: "POST",
    headers: {
      "X-API-Key": "pk_live_abc123def456",
      "Content-Type": "application/json",
    },
  }
);

const data = await response.json();
console.log(data);

python

import requests

nosso_numero = "12345678901"
url = f"https://api.pixconnect.com.br/api/v1/central/boletos/{nosso_numero}/pay"
headers = {
    "X-API-Key": "pk_live_abc123def456",
    "Content-Type": "application/json"
}

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

Resposta de Sucesso

Status: 200 OK

json

{
  "success": true,
  "data": {
    "nosso_numero": "12345678901",
    "status": "paid",
    "paid_at": "2026-02-15T16:45:00Z"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

Erros Possiveis

Codigo	Erro	Descricao
`404`	`NOT_FOUND`	Boleto nao encontrado
`422`	`INVALID_STATUS`	Boleto ja esta pago, liquidado ou cancelado

Campos do Boleto

Campos Retornados

Campo	Tipo	Descricao
`id`	uuid	Identificador unico do boleto
`nosso_numero`	string	Numero de referencia (11 digitos)
`barcode`	string	Codigo de barras (44 digitos)
`linha_digitavel`	string	Linha digitavel (47 digitos formatados)
`amount_cents`	integer	Valor em centavos
`due_date`	date	Data de vencimento
`payer_document`	string	CPF/CNPJ do pagador
`payer_name`	string	Nome do pagador
`beneficiary_ispb`	string	ISPB do beneficiario
`beneficiary_name`	string	Nome do beneficiario
`status`	string	Status atual do boleto
`pcr_protocol`	string	Protocolo de registro na PCR (quando registrado)
`registered_at`	datetime	Data/hora do registro na Nuclea
`paid_at`	datetime	Data/hora do pagamento
`cancelled_at`	datetime	Data/hora do cancelamento
`inserted_at`	datetime	Data/hora de criacao
`updated_at`	datetime	Data/hora da ultima atualizacao

Proximos Passos

Liquidacao - Processar arquivos de liquidacao
Webhooks - Receber notificacoes em tempo real
Fluxo de Boleto - Entenda o ciclo de vida completo

Boletos ​

Status do Boleto ​

Criar Boleto ​

Corpo da Requisicao ​

Exemplo de Requisicao ​

Resposta de Sucesso ​

Erros Possiveis ​

Consultar Boleto ​

Parametros de URL ​

Exemplo de Requisicao ​

Resposta de Sucesso ​

Erros Possiveis ​

Atualizar Boleto ​

Parametros de URL ​

Corpo da Requisicao ​

Exemplo de Requisicao ​

Resposta de Sucesso ​

Erros Possiveis ​

Cancelar Boleto ​

Parametros de URL ​

Exemplo de Requisicao ​

Resposta de Sucesso ​

Erros Possiveis ​

Marcar como Pago ​

Parametros de URL ​

Exemplo de Requisicao ​

Resposta de Sucesso ​

Erros Possiveis ​

Campos do Boleto ​

Campos Retornados ​

Proximos Passos ​

Boletos

Status do Boleto

Criar Boleto

Corpo da Requisicao

Exemplo de Requisicao

Resposta de Sucesso

Erros Possiveis

Consultar Boleto

Parametros de URL

Exemplo de Requisicao

Resposta de Sucesso

Erros Possiveis

Atualizar Boleto

Parametros de URL

Corpo da Requisicao

Exemplo de Requisicao

Resposta de Sucesso

Erros Possiveis

Cancelar Boleto

Parametros de URL

Exemplo de Requisicao

Resposta de Sucesso

Erros Possiveis

Marcar como Pago

Parametros de URL

Exemplo de Requisicao

Resposta de Sucesso

Erros Possiveis

Campos do Boleto

Campos Retornados

Proximos Passos