# Boleto Holmes

Honoring the famous Sherlock Holmes, this feature allows your application to investigate updated boleto status according to CIP in less than an hour.

Here we will teach you how to create and manage your Boleto Holmes. Ideally, since results are asynchronous, you should register a [Boleto Holmes webhook subscription](https://docs.starkbank.com/api/v2/webhook.md) in order to receive the investigation results instead of polling.

### The Boleto Holmes object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the boleto holmes. |
| `boletoId` | STRING | Investigated boleto entity ID. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `result` | STRING | Result of the investigation. Options: "paid", "canceled", "registered". |
| `status` | STRING | Current holmes status. Options: "created", "solving", "solved". |
| `tags` | LIST OF STRINGS | Tags associated with the boleto holmes. |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### Create Boleto Holmes

`POST /v2/boleto-holmes`

Use this route to verify the updated status of boletos generated at Stark Bank according to CIP.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `boletoId` | REQUIRED | Investigated boleto entity ID. ex: '5656565656565656' |
| `tags` | OPTIONAL | Array of strings to tag the entity for future queries. All tags will be converted to lowercase. |

**Request**

```python
import starkbank

holmes = starkbank.boletoholmes.create([
    starkbank.BoletoHolmes(
        boleto_id="5656565656565656",
        tags=["sherlock", "holmes"],
    )
])

for holmes in holmes:
    print(holmes)
```

**Response**

```python
BoletoHolmes(
    boleto_id=5656565656565656,
    created=2020-07-23 00:07:51.069587,
    id=3232323232323232,
    result=,
    status=solving,
    tags=["sherlock", "holmes"],
    updated=2020-07-23 00:07:51.069597
)
```

### List Boleto Holmes

`GET /v2/boleto-holmes`

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. |
| `boletoId` | OPTIONAL | String to get boletos holmes that refer to a specific boleto ID. |
| `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 ids to filter retrieved objects. ex: ['5656565656565656', '4545454545454545'] |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `status` | OPTIONAL | Filter holmes by the specified status. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |

**Request**

```python
import starkbank

holmes = starkbank.boletoholmes.query(
    boleto_id="5656565656565656",
    after="2020-07-01",
    before="2020-07-30"
)

for holmes in holmes:
    print(holmes)
```

**Response**

```python
BoletoHolmes(
    boleto_id=5656565656565656,
    created=2020-07-23 00:07:51.069587,
    id=3232323232323232,
    result=paid,
    status=solved,
    tags=["sherlock", "holmes"],
    updated=2020-07-23 00:07:51.069597
)
```

### Get a Boleto Holmes

`GET /v2/boleto-holmes/:id`

Get a single boleto holmes by its id.

**Parameters**

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

**Request**

```python
import starkbank

holmes = starkbank.boletoholmes.get("3232323232323232")

print(holmes)
```

**Response**

```python
BoletoHolmes(
    boleto_id=5656565656565656,
    created=2020-07-23 00:07:51.069587,
    id=3232323232323232,
    result=,
    status=solving,
    tags=["sherlock", "holmes"],
    updated=2020-07-23 00:07:51.069597
)
```

### List Boleto Holmes Logs

`GET /v2/boleto-holmes/log`

Get a paged list of all boleto holmes logs. A log tracks a change in the holmes 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. |
| `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. |
| `holmesIds` | OPTIONAL | Filter logs by Holmes IDs |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `types` | OPTIONAL | Filters logs by log types. |

**Request**

```python
import starkbank

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

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

**Response**

```python
Log(
    id=1010101010101010,
    created=2020-07-24 17:58:32.075347,
    type=solved,
    holmes=BoletoHolmes(
        boleto_id=5656565656565656,
        created=2020-07-23 00:07:51.069587,
        id=3232323232323232,
        result=paid,
        status=solved,
        tags=["sherlock", "holmes"],
        updated=2020-07-23 00:07:51.069597
    ),
    updated=2020-07-24 17:58:32.075347,
)
```

### Get a Boleto Holmes Log

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

Get a single boleto holmes 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.boletoholmes.log.get("1010101010101010")

print(log)
```

**Response**

```python
Log(
    id=1010101010101010,
    created=2020-07-24 17:58:32.075347,
    updated=2020-07-24 17:58:32.075347,
    type=solved,
    holmes=BoletoHolmes(
        boleto_id=5656565656565656,
        created=2020-07-23 00:07:51.069587,
        id=3232323232323232,
        result=paid,
        status=solved,
        tags=["sherlock", "holmes"],
        updated=2020-07-23 00:07:51.069597
    )
)
```

## 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-holmes-python.md)
- [Node.js](https://docs.starkbank.com/api/v2/boleto-holmes-node.md)
- [PHP](https://docs.starkbank.com/api/v2/boleto-holmes-php.md)
- [Java](https://docs.starkbank.com/api/v2/boleto-holmes-java.md)
- [Ruby](https://docs.starkbank.com/api/v2/boleto-holmes-ruby.md)
- [Elixir](https://docs.starkbank.com/api/v2/boleto-holmes-elixir.md)
- [.NET](https://docs.starkbank.com/api/v2/boleto-holmes-dotnet.md)
- [Go](https://docs.starkbank.com/api/v2/boleto-holmes-go.md)
- [Clojure](https://docs.starkbank.com/api/v2/boleto-holmes-clojure.md)
- [cURL](https://docs.starkbank.com/api/v2/boleto-holmes-curl.md)