# Boletos

Endpoints to create, query, update, and cancel boletos.

## Boleto Status

| Status       | Description                                        |
|--------------|---------------------------------------------------|
| `draft`      | Draft - boleto created but not registered         |
| `registered` | Registered with Nuclea (PCR)                      |
| `paid`       | Paid by the payer                                 |
| `settled`    | Settled - funds transferred                       |
| `cancelled`  | Cancelled                                         |

## Create Boleto

Creates a new boleto and registers it on Nuclea's PCR platform.

```
POST /boletos
```

### Request Body

| Field              | Type     | Required    | Description                              |
|--------------------|----------|-------------|------------------------------------------|
| `nosso_numero`     | string   | Yes         | Unique reference number (11 digits)      |
| `amount_cents`     | integer  | Yes         | Value in cents (e.g., 10000 = R$ 100.00) |
| `due_date`         | string   | Yes         | Due date (YYYY-MM-DD)                    |
| `payer_document`   | string   | Yes         | Payer's CPF/CNPJ (numbers only)          |
| `payer_name`       | string   | Yes         | Payer's full name                        |
| `beneficiary_ispb` | string   | Yes         | Beneficiary's ISPB (8 digits)            |
| `beneficiary_name` | string   | Yes         | Beneficiary's name                       |

::: warning Value in Cents
The `amount_cents` field must be sent in cents to avoid precision issues with decimal numbers. For example, R$ 150.50 should be sent as `15050`.
:::

### Request Example

::: code-group

```bash [cURL]
curl -X POST "https://api.monetarie_npc.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 [JavaScript]
const response = await fetch(
  "https://api.monetarie_npc.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 [Python]
import requests

url = "https://api.monetarie_npc.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())
```

:::

### Success Response

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

### Possible Errors

| Code   | Error                 | Description                                  |
|--------|----------------------|----------------------------------------------|
| `400`  | `BAD_REQUEST`        | `boleto` field missing from request body     |
| `422`  | `VALIDATION_ERROR`   | Invalid data (document, date, etc.)          |
| `422`  | `DUPLICATE_ENTRY`    | `nosso_numero` already exists                |

---

## Query Boleto

Retrieves the details of a boleto by its reference number.

```
GET /boletos/:nosso_numero
```

### URL Parameters

| Parameter      | Type   | Description                          |
|----------------|--------|--------------------------------------|
| `nosso_numero` | string | Unique boleto reference number       |

### Request Example

::: code-group

```bash [cURL]
curl -X GET "https://api.monetarie_npc.com.br/api/v1/central/boletos/12345678901" \
  -H "X-API-Key: pk_live_abc123def456" \
  -H "Content-Type: application/json"
```

```javascript [JavaScript]
const nossoNumero = "12345678901";
const response = await fetch(
  `https://api.monetarie_npc.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 [Python]
import requests

nosso_numero = "12345678901"
url = f"https://api.monetarie_npc.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())
```

:::

### Success Response

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

### Possible Errors

| Code   | Error         | Description             |
|--------|---------------|-------------------------|
| `404`  | `NOT_FOUND`   | Boleto not found        |

---

## Update Boleto

Updates the data of a boleto. Only boletos with `draft` status can be updated.

```
PATCH /boletos/:nosso_numero
```

### URL Parameters

| Parameter      | Type   | Description                          |
|----------------|--------|--------------------------------------|
| `nosso_numero` | string | Unique boleto reference number       |

### Request Body

| Field              | Type     | Description                              |
|--------------------|----------|------------------------------------------|
| `amount_cents`     | integer  | New value in cents                       |
| `due_date`         | string   | New due date (YYYY-MM-DD)                |
| `payer_document`   | string   | New payer CPF/CNPJ                       |
| `payer_name`       | string   | New payer name                           |

::: warning Status Restriction
Only boletos with `draft` status can be updated. Boletos already registered with Nuclea cannot be modified.
:::

### Request Example

::: code-group

```bash [cURL]
curl -X PATCH "https://api.monetarie_npc.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 [JavaScript]
const nossoNumero = "12345678901";
const response = await fetch(
  `https://api.monetarie_npc.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 [Python]
import requests

nosso_numero = "12345678901"
url = f"https://api.monetarie_npc.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())
```

:::

### Success Response

**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",
    // ... other fields
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}
```

### Possible Errors

| Code   | Error                 | Description                                    |
|--------|----------------------|------------------------------------------------|
| `400`  | `BAD_REQUEST`        | `boleto` field missing from request body       |
| `404`  | `NOT_FOUND`          | Boleto not found                               |
| `422`  | `INVALID_STATUS`     | Boleto is not in `draft` status                |
| `422`  | `VALIDATION_ERROR`   | Invalid data                                   |

---

## Cancel Boleto

Cancels an existing boleto.

```
DELETE /boletos/:nosso_numero
```

### URL Parameters

| Parameter      | Type   | Description                          |
|----------------|--------|--------------------------------------|
| `nosso_numero` | string | Unique boleto reference number       |

::: warning Cancellation
Boletos that are already paid or settled cannot be cancelled. Cancellation is irreversible.
:::

### Request Example

::: code-group

```bash [cURL]
curl -X DELETE "https://api.monetarie_npc.com.br/api/v1/central/boletos/12345678901" \
  -H "X-API-Key: pk_live_abc123def456" \
  -H "Content-Type: application/json"
```

```javascript [JavaScript]
const nossoNumero = "12345678901";
const response = await fetch(
  `https://api.monetarie_npc.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 [Python]
import requests

nosso_numero = "12345678901"
url = f"https://api.monetarie_npc.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())
```

:::

### Success Response

**Status:** `200 OK`

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

### Possible Errors

| Code   | Error                 | Description                                    |
|--------|----------------------|------------------------------------------------|
| `404`  | `NOT_FOUND`          | Boleto not found                               |
| `422`  | `INVALID_STATUS`     | Boleto already paid or settled                 |

---

## Mark as Paid

Marks a boleto as paid. This endpoint is used when payment was confirmed externally.

```
POST /boletos/:nosso_numero/pay
```

### URL Parameters

| Parameter      | Type   | Description                          |
|----------------|--------|--------------------------------------|
| `nosso_numero` | string | Unique boleto reference number       |

::: info Webhook
When marking a boleto as paid, a `boleto.paid` webhook is automatically sent to the configured URL.
:::

### Request Example

::: code-group

```bash [cURL]
curl -X POST "https://api.monetarie_npc.com.br/api/v1/central/boletos/12345678901/pay" \
  -H "X-API-Key: pk_live_abc123def456" \
  -H "Content-Type: application/json"
```

```javascript [JavaScript]
const nossoNumero = "12345678901";
const response = await fetch(
  `https://api.monetarie_npc.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 [Python]
import requests

nosso_numero = "12345678901"
url = f"https://api.monetarie_npc.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())
```

:::

### Success Response

**Status:** `200 OK`

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

### Possible Errors

| Code   | Error                 | Description                                    |
|--------|----------------------|------------------------------------------------|
| `404`  | `NOT_FOUND`          | Boleto not found                               |
| `422`  | `INVALID_STATUS`     | Boleto already paid, settled, or cancelled     |

---

## Boleto Fields

### Returned Fields

| Field              | Type      | Description                                    |
|--------------------|-----------|------------------------------------------------|
| `id`               | uuid      | Unique boleto identifier                       |
| `nosso_numero`     | string    | Reference number (11 digits)                   |
| `barcode`          | string    | Barcode (44 digits)                            |
| `linha_digitavel`  | string    | Typeable line (47 formatted digits)            |
| `amount_cents`     | integer   | Value in cents                                 |
| `due_date`         | date      | Due date                                       |
| `payer_document`   | string    | Payer's CPF/CNPJ                               |
| `payer_name`       | string    | Payer's name                                   |
| `beneficiary_ispb` | string    | Beneficiary's ISPB                             |
| `beneficiary_name` | string    | Beneficiary's name                             |
| `status`           | string    | Current boleto status                          |
| `pcr_protocol`     | string    | PCR registration protocol (when registered)    |
| `registered_at`    | datetime  | Date/time of Nuclea registration               |
| `paid_at`          | datetime  | Date/time of payment                           |
| `cancelled_at`     | datetime  | Date/time of cancellation                      |
| `inserted_at`      | datetime  | Date/time of creation                          |
| `updated_at`       | datetime  | Date/time of last update                       |

## Next Steps

- [Settlements](/en/api/settlements) - Process settlement files
- [Webhooks](/en/webhooks/) - Receive real-time notifications
- [Boleto Flow](/en/guides/boleto-flow) - Understand the complete lifecycle