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

::: warning 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

::: 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())
```

:::

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

::: 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())
```

:::

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

::: warning Restricao de Status
Apenas boletos com status `draft` podem ser atualizados. Boletos ja registrados na Nuclea nao podem ser modificados.
:::

### Exemplo de Requisicao

::: 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())
```

:::

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

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

### Exemplo de Requisicao

::: 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())
```

:::

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

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

### Exemplo de Requisicao

::: 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())
```

:::

### 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](/api/settlements) - Processar arquivos de liquidacao
- [Webhooks](/webhooks/) - Receber notificacoes em tempo real
- [Fluxo de Boleto](/guides/boleto-flow) - Entenda o ciclo de vida completo