# Boleto

A boleto is a method you can use to charge your customers or load your Stark Bank account. Here we will teach you how to create and manage boletos.

You can also split a Boleto between different receivers, you need to create a [Split Receiver](https://docs.starkbank.com/api/v2/split-receiver.md), and add the receiver into the Splits array.

### The Boleto object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the boleto. |
| `amount` | INTEGER | Amount in cents to be charged. Example: 100 (R$1.00). |
| `barCode` | STRING | Boleto bar code. |
| `city` | STRING | Customer city name. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `descriptions` | LIST OF OBJECTS | List of description objects. |
| `discounts` | LIST OF OBJECTS | List of discount objects. |
| `district` | STRING | Customer district name. |
| `due` | STRING | Due date of the boleto. Example: "2020-04-23". |
| `fee` | INTEGER | Fee charged in cents. |
| `fine` | FLOAT | Percentage charged if paid after due date. |
| `interest` | FLOAT | Monthly percentage charged if paid after due date. |
| `line` | STRING | Boleto line number. |
| `name` | STRING | Customer full name. |
| `ourNumber` | STRING | Boleto control number (nosso numero). |
| `overdueLimit` | INTEGER | Number of days after due date until boleto expires. |
| `receiverName` | STRING | Name of the credit receiver (Sacador Avalista). |
| `receiverTaxId` | STRING | Tax ID of the credit receiver. |
| `stateCode` | STRING | Customer state code. |
| `status` | STRING | Current boleto status. Options: "created", "overdue", "paid", "canceled". |
| `streetLine1` | STRING | Customer street address. |
| `streetLine2` | STRING | Customer street address complement. |
| `tags` | LIST OF STRINGS | Tags associated with the boleto. |
| `taxId` | STRING | Customer CPF or CNPJ. |
| `transactionIds` | LIST OF STRINGS | Ledger transaction IDs linked to the boleto. |
| `workspaceId` | STRING | ID of the workspace that created the boleto. |
| `zipCode` | STRING | Customer zip code. |

### Create Boletos

`POST /v2/boleto`

This is how you create a new list of boletos. You can create up to 100 boletos per request. In case a boleto is paid after its due date and there is fine or interest, its amount will be updated with the paid amount. The same is valid if the boleto is paid with a discount.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `amount` | REQUIRED | A positive integer that represents the amount in cents to be charged, with a minimum of 200 (R$2.00). Example: 1234 (R$12.34). |
| `city` | REQUIRED | Customer city name. Example: "São Paulo". |
| `district` | REQUIRED | Customer district name. Example: "Itaim Bibi". |
| `name` | REQUIRED | Customer full name. Example: "Anthony Edward Stark". |
| `stateCode` | REQUIRED | Customer state code. Example: "SP". |
| `streetLine1` | REQUIRED | Customer street address. Example: "Av. Faria Lima, 1844". |
| `streetLine2` | REQUIRED | Customer street address complement. Example: "CJ 13". |
| `taxId` | REQUIRED | Customer CPF (11 digits formatted or unformatted) or CNPJ (14 digits formatted or unformatted). Example: 012.345.678-90. |
| `zipCode` | REQUIRED | Customer zip code. Example: 01500-000. |
| `descriptions` | OPTIONAL | List of up to 15 descriptions containing information to help the customer understand why he is being charged. You can add text and amount to create a table or you can just add text. When generating PDFs, if the 'booklet' layout is selected, only the text field of the first description will be considered and it will be used to fill the installment cell in the PDF. Example: ``` [{"text": "Explaining first part of the value", "amount": 20000}, {"text": "More text to explaining something to the customer"}] ``` |
| `discounts` | OPTIONAL | List of up to 2 discounts specifying the discount percentage and the limit date up to when the discount is valid. Example: ``` [{"percentage": 5, "date": "2020-04-01"}, {"percentage": 3.5, "date": "2020-04-02"}] ``` |
| `due` | OPTIONAL | Due date of the boleto. Example: 2020-06-27. The default value is set to two days after creation date. |
| `fine` | OPTIONAL | Percentage of the boleto amount charged if customer pays after the due date. Default value = 2.00 (2%). |
| `interest` | OPTIONAL | Monthly interest, in percentage, charged if customer pays after the due date. Default value = 1.00 (1%). |
| `overdueLimit` | OPTIONAL | Number of days after due date after which the boleto will no longer be payable. 0<=overdueLimit<=59. Default value=59. |
| `receiverName` | OPTIONAL | Name of the credit receiver (Sacador Avalista). If none is informed, workspace owner name will be used. If informed, receiverTaxId must also be informed. |
| `receiverTaxId` | OPTIONAL | Tax ID (CPF/CNPJ) of the credit receiver (Sacador Avalista). If none is informed, workspace owner tax ID will be used. If informed, receiverName must also be informed. |
| `splits` | OPTIONAL | Array of Split objects to indicate payment receivers. Example: ``` [{"receiverId": "5742447426535424", "amount": 100}, {"receiverId": "5743243941642240", "amount": 200}] ``` |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |

**Request**

```python
import starkbank

boletos = starkbank.boleto.create([
    starkbank.Boleto(
        amount=400000,
        due="2020-05-20",
        name="Iron Bank S.A.",
        tax_id="20.018.183/0001-80",
        fine=2.5,
        interest=1.3,
        overdue_limit=5,
        street_line_1="Av. Faria Lima, 1844",
        street_line_2="CJ 13",
        district="Itaim Bibi",
        city="São Paulo",
        state_code="SP",
        zip_code="01500-000",
        tags=["War supply", "Invoice #1234"],
        discounts=[
            {"percentage": 10, "date": "2020-04-25"}
        ],
        splits=[
            Split(amount=3000, receiverId="5742447426535424"), Split(amount=5000, receiverId="5743243941642240")
        ]
    )
])

for boleto in boletos:
    print(boleto)
```

**Response**

```python
Boleto(
    id=6655767935451136,
    amount=400000,
    bar_code=34191826100004000001091007175647307144464000,
    city=São Paulo,
    created=2020-04-23 23:36:08.129614,
    descriptions=[],
    discounts=[{'date': '2020-04-26T02:59:59.999999+00:00', 'percentage': 10.0}],
    district=Itaim Bibi,
    due=2020-05-21,
    fee=0,
    fine=2.5,
    interest=1.3,
    line=34191.09107 07175.647309 71444.640008 1 82610000400000,
    name=Iron Bank S.A.,
    our_number=10445145,
    transaction_ids=[],
    overdue_limit=5,
    receiver_name=Winterfell S. A.,
    receiver_tax_id=71.735.814/0001-12,
    state_code=SP,
    status=created,
    street_line_1=Av. Faria Lima, 1844,
    street_line_2=CJ 13,
    tags=['war supply', 'invoice #1234'],
    tax_id=20.018.183/0001-80,
    zip_code=01500-000,
    workspace_id=5083989094170624,
    splits=[
        Split(
            amount=3000,
            created=None,
            external_id=None,
            id=None,
            receiver_id=5742447426535424,
            scheduled=None,
            source=None,
            status=None,
            tags=None,
            updated=None
        ),
        Split(
            amount=5000,
            created=None,
            external_id=None,
            id=None,
            receiver_id=5743243941642240,
            scheduled=None,
            source=None,
            status=None,
            tags=None,
            updated=None
        )
    ]
)
```

### List Boletos

`GET /v2/boleto`

Get a list of non-deleted boletos in chunks of at most 100. If you need smaller chunks, use the limit parameter.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `status` | OPTIONAL | Filter boletos by the specified status. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |

**Request**

```python
import starkbank

boletos = starkbank.boleto.query(
    after="2020-04-01",
    before="2020-04-30"
)

for boleto in boletos:
    print(boleto)
```

**Response**

```python
Boleto(
    id=6655767935451136,
    amount=400000,
    bar_code=34191826100004000001091007175647307144464000,
    city=São Paulo,
    created=2020-04-23 23:36:08.129614,
    descriptions=[],
    discounts=[{'date': '2020-04-26T02:59:59.999999+00:00', 'percentage': 10.0}],
    district=Itaim Bibi,
    due=2020-05-21,
    fee=0,
    fine=2.5,
    interest=1.3,
    line=34191.09107 07175.647309 71444.640008 1 82610000400000,
    name=Iron Bank S.A.,
    our_number=10445145,
    transaction_ids=[],
    overdue_limit=5,
    receiver_name=Winterfell S. A.,
    receiver_tax_id=71.735.814/0001-12,
    state_code=SP,
    status=created,
    street_line_1=Av. Faria Lima, 1844,
    street_line_2=CJ 13,
    tags=['war supply', 'invoice #1234'],
    tax_id=20.018.183/0001-80,
    zip_code=01500-000
    workspace_id=5083989094170624
)
```

### Get a Boleto

`GET /v2/boleto/:id`

Get a single boleto by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the boleto entity. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkbank

boleto = starkbank.boleto.get("6655767935451136")

print(boleto)
```

**Response**

```python
Boleto(
    id=6655767935451136,
    amount=400000,
    bar_code=34191826100004000001091007175647307144464000,
    city=São Paulo,
    created=2020-04-23 23:36:08.129614,
    descriptions=[],
    discounts=[{'date': '2020-04-26T02:59:59.999999+00:00', 'percentage': 10.0}],
    district=Itaim Bibi,
    due=2020-05-21,
    fee=0,
    fine=2.5,
    interest=1.3,
    line=34191.09107 07175.647309 71444.640008 1 82610000400000,
    name=Iron Bank S.A.,
    our_number=10445145,
    transaction_ids=[],
    overdue_limit=5,
    receiver_name=Winterfell S. A.,
    receiver_tax_id=71.735.814/0001-12,
    state_code=SP,
    status=created,
    street_line_1=Av. Faria Lima, 1844,
    street_line_2=CJ 13,
    tags=['war supply', 'invoice #1234'],
    tax_id=20.018.183/0001-80,
    zip_code=01500-000,
    workspace_id=5083989094170624
)
```

### Delete a Boleto

`DELETE /v2/boleto/:id`

Delete a single boleto. We will send a request to CIP to cancel the boleto registration. After the boleto registration is canceled, it won't be possible to pay it anymore.

**NOTE:** This action cannot be undone.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the boleto entity. |

**Request**

```python
import starkbank

boleto = starkbank.boleto.delete("6655767935451136")

print(boleto)
```

**Response**

```python
Boleto(
    id=6655767935451136,
    amount=400000,
    bar_code=34191826100004000001091007175647307144464000,
    city=São Paulo,
    created=2020-04-23 23:36:08.129614,
    descriptions=[],
    discounts=[{'date': '2020-04-26T02:59:59.999999+00:00', 'percentage': 10.0}],
    district=Itaim Bibi,
    due=2020-05-21,
    fee=0,
    fine=2.5,
    interest=1.3,
    line=34191.09107 07175.647309 71444.640008 1 82610000400000,
    name=Iron Bank S.A.,
    our_number=10445145,
    transaction_ids=[],
    overdue_limit=5,
    receiver_name=Winterfell S. A.,
    receiver_tax_id=71.735.814/0001-12,
    state_code=SP,
    status=created,
    street_line_1=Av. Faria Lima, 1844,
    street_line_2=CJ 13,
    tags=['war supply', 'invoice #1234'],
    tax_id=20.018.183/0001-80,
    zip_code=01500-000,
    workspace_id=5083989094170624
)
```

### Get a Boleto PDF

`GET /v2/boleto/:id/pdf`

Get a downloadable boleto PDF file. This route is public and does not require the usual authentication headers. However, if you request an invalid boleto ID too many times, your IP will be blocked for this specific route.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the boleto entity |
| `hiddenFields` | OPTIONAL | List of fields to be hidden in Boleto pdf. Example: ["customerAddress"]. |
| `layout` | OPTIONAL | PDF layout. Available options are "default" (full page) and "booklet" ("carnê"). |

**Request**

```python
import starkbank

pdf = starkbank.boleto.pdf("6655767935451136")

with open("boleto.pdf", "wb") as file:
    file.write(pdf)
```

### List Boleto logs

`GET /v2/boleto/log`

Get a paged list of boleto logs. A log tracks a change in the boleto entity according to its life cycle.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `boletoIds` | OPTIONAL | Array of boleto ids that are linked to the logs you desire. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `types` | OPTIONAL | Filters logs by log types. |

**Request**

```python
import starkbank

logs = starkbank.boleto.log.query(
    after="2020-04-01",
    before="2020-04-30"
)

for log in logs:
    print(log)
```

**Response**

```python
Log(
    id=6465045294743552,
    created=2020-04-24 23:46:14.703951,
    errors=[],
    type=paid,
    boleto=Boleto(
        id=6655767935451136,
        amount=400000,
        bar_code=34191826100004000001091007175647307144464000,
        city=São Paulo,
        created=2020-04-23 23:36:08.129614,
        descriptions=[],
        discounts=[{'date': '2020-04-26T02:59:59.999999+00:00', 'percentage': 10.0}],
        district=Itaim Bibi,
        due=2020-05-21,
        fee=0,
        fine=2.5,
        interest=1.3,
        line=34191.09107 07175.647309 71444.640008 1 82610000400000,
        name=Iron Bank S.A.,
        our_number=10445145,
        transaction_ids=[],
        overdue_limit=5,
        receiver_name=Winterfell S. A.,
        receiver_tax_id=71.735.814/0001-12,
        state_code=SP,
        status=created,
        street_line_1=Av. Faria Lima, 1844,
        street_line_2=CJ 13,
        tags=['war supply', 'invoice #1234'],
        tax_id=20.018.183/0001-80,
        zip_code=01500-000
        workspace_id=5083989094170624
    )
)
```

### Get a Boleto Log

`GET /v2/boleto/log/:id`

Get a single boleto log by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the log entity |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkbank

log = starkbank.boleto.log.get("6465045294743552")

print(log)
```

**Response**

```python
Log(
    id=6465045294743552,
    created=2020-04-24 23:46:14.703951,
    errors=[],
    type=paid,
    boleto=Boleto(
        id=6655767935451136,
        amount=400000,
        bar_code=34191826100004000001091007175647307144464000,
        city=São Paulo,
        created=2020-04-23 23:36:08.129614,
        descriptions=[],
        discounts=[{'date': '2020-04-26T02:59:59.999999+00:00', 'percentage': 10.0}],
        district=Itaim Bibi,
        due=2020-05-21,
        fee=0,
        fine=2.5,
        interest=1.3,
        line=34191.09107 07175.647309 71444.640008 1 82610000400000,
        name=Iron Bank S.A.,
        our_number=10445145,
        transaction_ids=[],
        overdue_limit=5,
        receiver_name=Winterfell S. A.,
        receiver_tax_id=71.735.814/0001-12,
        state_code=SP,
        status=created,
        street_line_1=Av. Faria Lima, 1844,
        street_line_2=CJ 13,
        tags=['war supply', 'invoice #1234'],
        tax_id=20.018.183/0001-80,
        zip_code=01500-000,
        workspace_id=5083989094170624
    )
)
```

## Available Languages

Code samples on this page are in Python. The same content is available with samples in:

- [Python](https://docs.starkbank.com/api/v2/boleto-python.md)
- [Node.js](https://docs.starkbank.com/api/v2/boleto-node.md)
- [PHP](https://docs.starkbank.com/api/v2/boleto-php.md)
- [Java](https://docs.starkbank.com/api/v2/boleto-java.md)
- [Ruby](https://docs.starkbank.com/api/v2/boleto-ruby.md)
- [Elixir](https://docs.starkbank.com/api/v2/boleto-elixir.md)
- [.NET](https://docs.starkbank.com/api/v2/boleto-dotnet.md)
- [Go](https://docs.starkbank.com/api/v2/boleto-go.md)
- [Clojure](https://docs.starkbank.com/api/v2/boleto-clojure.md)
- [cURL](https://docs.starkbank.com/api/v2/boleto-curl.md)