# Brazil Boleto Validator & Parser (Boleto) (`br_data_hub/br-boleto-parser`) Actor

Validate Brazilian boletos in bulk (digitable line or barcode, bank and utility/tax slips): check digits per field, line-barcode conversion, bank, amount and due date, with the 2025 due-date factor rollover handled.

- **URL**: https://apify.com/br_data_hub/br-boleto-parser.md
- **Developed by:** [br_data_hub](https://apify.com/br_data_hub) (community)
- **Categories:** Developer tools, Automation, Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.70 / 1,000 valid boletos

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Brazil Boleto Validator & Parser (Boleto)

Validate and parse **Brazilian boletos in bulk**, offline and in milliseconds. Paste digitable lines (*linha digitável*) or barcodes (*código de barras*) and get, for each one: whether it is valid, **which field and which digit failed** if it is not, the conversion between digitable line and barcode, the **bank** (code, ISPB and name from the Banco Central list), currency, **amount** and **due date**.

Built for accounts-payable automation, ERP imports, payment bots and AI agents that read boletos from e-mails and PDFs and must not pay a mistyped code.

- **Bank boletos** (47-digit line or 44-digit barcode): check digit of each field (modulo 10) and the general check digit (modulo 11).
- **Utility bills, taxes and fines** (*arrecadação / convênio*, 48-digit line starting with 8): segment (water, electricity, telecom, city taxes, government, traffic fines…), value identifier, modulo 10 or 11 per block, company/agency code (FEBRABAN) or CNPJ root. Most libraries ignore these.
- **The 2025 due-date factor rollover handled.** The factor reached 9999 on 21/02/2025 and restarted at 1000 on 22/02/2025, so the same four digits now mean two dates 9,000 days apart. The Actor returns the right one (the one closest to the reference date, today by default) and the other cycle's date for audit.
- Accepts dots, spaces and hyphens, one code per line, up to 100,000 codes per run.
- Duplicates in the same run are flagged (`duplicateOf`) and charged once: handy to catch a boleto about to be paid twice.

### Input

| Field | Description |
|---|---|
| `codes` | Digitable lines (47 or 48 digits) or barcodes (44 digits), one per line. Dots, spaces and hyphens are ignored. Up to 100,000 per run. |
| `referenceDate` | Optional `YYYY-MM-DD`. Each due-date factor matches two dates (before and after the 2025 rollover); the Actor picks the one closest to this date. Empty = today in Brasília. Set it when you reprocess old boletos. |
| `includeInvalid` | Also return invalid codes with their errors (default `true`). Invalid codes are never charged. |

The default input has six sample codes (published test vectors and synthetic examples, one with a wrong check digit) and finishes in about a second.

### Output

One dataset item per code, in input order (`index`). A valid bank boleto:

```json
{
  "index": 0,
  "input": "10492.00650 61000.100042 00997.263900 9 89810000021403",
  "status": "valid",
  "type": "bank",
  "format": "digitableLine",
  "barcode": "10499898100000214032006561000100040099726390",
  "digitableLine": "10492006506100010004200997263900989810000021403",
  "digitableLineFormatted": "10492.00650 61000.100042 00997.263900 9 89810000021403",
  "bank": {"code": "104", "ispb": "00360305", "name": "Caixa Econômica Federal", "shortName": "CAIXA ECONOMICA FEDERAL"},
  "currency": "BRL",
  "amount": 214.03,
  "dueDateFactor": 8981,
  "dueDate": "2022-05-10",
  "dueDateOtherCycle": "2046-12-30",
  "freeField": "2006561000100040099726390",
  "duplicateOf": null,
  "errors": [],
  "warnings": []
}
```

A utility bill (*arrecadação*) also has `segment`, `segmentName`, `valueId` (6 to 9), `valueIdName`, `checkDigitModulo` (10 or 11), `companyCode` (4-digit FEBRABAN code) or `companyCnpjRoot` (segment 6) and `referenceValue` when the value is an index quantity instead of BRL. Its `dueDate` is `null`: FEBRABAN does not standardize where a utility bill keeps its due date.

An invalid code says exactly what failed:

```json
{
  "status": "invalid",
  "errors": [
    {"field": "field2", "message": "Check digit of field2 (positions 11-20, modulo 10) is wrong at position 21: expected 2, found 3.",
     "position": 21, "expected": "2", "found": "3"}
  ]
}
```

`field` is one of `input` (unexpected character), `length`, `product`, `field1`/`field2`/`field3` (bank line), `block1`…`block4` (utility line), `valueId` or `generalCheckDigit`. Positions are 1-based over the digits you typed. `warnings` covers valid but unusual codes: no due date (factor 0000), open amount (0), currency other than real, bank code not in the Banco Central list.

The run's `OUTPUT` record has the totals: codes, valid, invalid, duplicates, reference date and the date of the bank list.

### How much does it cost?

Pay per event, nothing else (no usage-based fees):

- **`boleto`**: US$ 0.001 per **valid** boleto (US$ 1 per 1,000). Invalid codes and repeated codes in the same run are free.

**$0.001 per valid boleto** (`boleto` event, pay per event). Charged once per valid boleto. Invalid codes and repeated codes in the same run are free.

| You get | Free tier | Bronze tier (10% off) | Gold tier (30% off) |
|---|---|---|---|
| 100 valid boletos | $0.10 | $0.09 | $0.07 |
| 1,000 valid boletos | $1.00 | $0.90 | $0.70 |
| 10,000 valid boletos | $10.00 | $9.00 | $7.00 |

Discounts follow your Apify subscription tier: Bronze 10%, Silver 20%, Gold and above 30%. No subscription to this Actor and no charge for platform usage: you pay only for results.
The Apify Free plan includes $5 of monthly credit, enough for about **5,000 valid boletos** at the list price.
You can cap the cost of any run with **Maximum cost per run**; the Actor stops when it is reached.

### Data source

- **Validation and parsing** follow the FEBRABAN layouts for bank boletos and for collection slips (*arrecadação*). They are computed inside the Actor: no network, no external API, nothing you send leaves the run.
- **Banks**: the Banco Central do Brasil list of STR participants (*Lista de participantes do STR*, `participantes_str.csv`), with COMPE code, ISPB, short and full name. A copy is stored in the Actor with its date (`src/banks.json`, field `retrievedAt`) and refreshed with `scripts/build_banks.py`. The current copy is dated 2026-10-30 and has 515 banks.
- **Due-date factor**: days since 07/10/1997. 9999 was 21/02/2025; 1000 is 22/02/2025 and the count goes on by one per day (FEBRABAN communication FB-009/2023). The next restart will be after 13/10/2049.

The Actor does not collect personal data. A boleto's barcode carries the bank, amount, due date and the issuer's own reference numbers (free field), which are returned as they are. Not affiliated with FEBRABAN or the Banco Central do Brasil.

### More questions

#### Does it tell me whether a boleto was paid or registered at the bank?

No. The Actor checks the code itself (length, check digits, bank, amount, due date) without any network access. Payment status and registration only exist at the issuing bank (or in the DDA of your bank), which is not public.

#### What is the difference between the digitable line and the barcode?

The digitable line (*linha digitável*) is the number printed above the barcode, with check digits per field: 47 digits for bank boletos and 48 for utility bills and taxes. The barcode (*código de barras*) has 44 digits in a different order. You can send either one; the output always has both (`digitableLine`, `digitableLineFormatted` and `barcode`).

#### Which due date is right after the February 2025 factor rollover?

Each factor now matches two dates 9,000 days apart (for example 2022 and 2046). The Actor picks the date closest to the reference date (today in Brasília by default) in `dueDate` and puts the other one in `dueDateOtherCycle`. When you reprocess old boletos, set `referenceDate` to a date near when they were issued.

#### Why do utility bills come without a due date?

FEBRABAN's layout for utility bills, taxes and fines (*arrecadação*, line starting with 8) has no standard due-date field: each company writes it its own way inside the free field. So `dueDate` is `null` for them; the amount, segment and company code (`companyCode`, or `companyCnpjRoot` in segment 6) are returned.

#### How do I find the typo in a code someone typed?

Invalid codes come with `errors`, each one naming the `field` (`field1` to `field3` in bank lines, `block1` to `block4` in utility lines, `generalCheckDigit`, `length`, `input`), the 1-based `position` over the digits you typed, and the `expected` and `found` digit. Turn off `includeInvalid` if you only want valid ones in the dataset.

#### Can I paste a spreadsheet column or a list from an e-mail?

Yes. Each line of the input may hold one code or several separated by line breaks, commas or semicolons. Spaces, dots and hyphens inside a code are ignored; any other character is reported as an `input` error with its position. Up to 100,000 codes per run.

#### What do the warnings mean?

They flag valid but unusual codes: factor `0000` (no due date in the barcode), amount 0 (open amount defined at payment), currency other than real, a bank code not in the Banco Central list stored in the Actor, or a utility bill whose value is a quantity of an index instead of BRL (value identifier 7 or 9, returned in `referenceValue`).

#### Does it read boletos from PDF files?

No, it takes the digitable line or barcode as text. To get the line from a PDF first, convert the PDF to text with our **Documents to Markdown for RAG (Docling)** Actor or your own OCR, then send the codes here.

### Use it via API

Run it from any language and get the results as JSON. Replace `<YOUR_API_TOKEN>` with your [Apify API token](https://console.apify.com/settings/integrations).

```bash
curl -X POST "https://api.apify.com/v2/acts/br_data_hub~br-boleto-parser/run-sync-get-dataset-items?token=<YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"codes": ["10492.00650 61000.100042 00997.263900 9 89810000021403", "34191.09123 34567.812341 56789.010008 8 10000000098765", "83860000005-0 09600019000-9 00080178230-9 00034306271-2", "10492.46802 13579.246805 13579.246805 3 16260000032990", "84630000000299902962020041013600000200644114", "10492006506100010004200997263900989810000021413"]}'
```

```python
from apify_client import ApifyClient

client = ApifyClient("<YOUR_API_TOKEN>")
run = client.actor("br_data_hub/br-boleto-parser").call(run_input={'codes': ['10492.00650 61000.100042 00997.263900 9 89810000021403',
                                                '34191.09123 34567.812341 56789.010008 8 10000000098765',
                                                '83860000005-0 09600019000-9 00080178230-9 00034306271-2',
                                                '10492.46802 13579.246805 13579.246805 3 16260000032990',
                                                '84630000000299902962020041013600000200644114',
                                                '10492006506100010004200997263900989810000021413']})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)
```

You can also schedule runs, send results to webhooks, or connect the Actor to Make, Zapier, n8n, Google Sheets and other [integrations](https://docs.apify.com/platform/integrations).

### Use it with AI agents (MCP)

This Actor is ready for AI agents: typed input and output schemas, pay-per-event pricing, limited permissions and short runs.

- **Apify MCP server:** add `https://mcp.apify.com/?tools=br_data_hub/br-boleto-parser` to Claude, ChatGPT, Cursor, VS Code or any MCP client, and the agent can call this Actor as a tool.
- **Agent frameworks:** call it from LangChain, LlamaIndex, CrewAI or the OpenAI Agents SDK through the Apify integrations, or with the API call above.
- Results come as structured JSON with stable field names, documented in the **Output** tab.

### FAQ

#### Where does the data come from?

- **Validation and parsing** follow the FEBRABAN layouts for bank boletos and for collection slips (*arrecadação*). They are computed inside the Actor: no network, no external API, nothing you send leaves the run. - **Banks**: the Banco Central do Brasil list of STR participants (*Lista de participantes do STR*, `participantes_str.csv`), with COMPE code, ISPB, short and full name. A copy is stored in the Actor with its date (`src/banks.json`, field `retrievedAt`) and refreshed with `scripts/build_banks.py`. The current copy is dated 2026-10-30 and has 515 banks. - **Due-date factor**: days since 07/10/1997. 9999 was 21/02/2025; 1000 is 22/02/2025 and the count goes on by one per day (FEBRABAN communication FB-009/2023). The next restart will be after 13/10/2049.

#### How much does it cost?

$0.001 per valid boleto. Discounts follow your Apify subscription tier: Bronze 10%, Silver 20%, Gold and above 30%. See **How much does it cost?** above for examples.

#### Do I pay for errors or empty results?

No. Charged once per valid boleto. Invalid codes and repeated codes in the same run are free.

#### Can I run it on a schedule or connect it to other tools?

Yes. Use Apify schedules to run it daily or weekly, webhooks to get notified, and integrations such as Make, Zapier, n8n and Google Sheets. Everything also works through the API.

#### Can AI agents use it?

Yes. It works as a tool in the Apify MCP server and in agent frameworks, and AI agents can pay per event. See **Use it with AI agents (MCP)**.

#### Is it legal to use this data?

The Actor reads only public, official sources and keeps personal data masked as the source publishes it. You are responsible for how you use the data, including LGPD compliance.

#### I found a bug or need a feature. What should I do?

Open an issue in the **Issues** tab. We answer within 14 days, usually much sooner.

### More Actors from BR Data Hub

| Actor | What it does |
|---|---|
| [Brazil CNPJ Lookup API (Consulta CNPJ)](https://apify.com/br_data_hub/br-cnpj-lookup) | Look up Brazilian companies by CNPJ: registration status, partners (masked CPF), activities, tax regime and sc |
| [Brazil Public Contracts API (PNCP Contratos)](https://apify.com/br_data_hub/br-pncp-contracts) | Get Brazilian government contracts from PNCP, the official national procurement portal: buyer, supplier, objec |
| [Brazil Open Tenders API (Licitações Abertas)](https://apify.com/br_data_hub/br-pncp-open-tenders) | Find Brazilian government tenders that are open for proposals right now, from PNCP, the official national proc |
| [Brazil Municipalities & IBGE Codes (Municípios)](https://apify.com/br_data_hub/br-ibge-localities) | List Brazilian municipalities, search them by name (accents and typos tolerated) or resolve IBGE codes |
| [Brazil Holidays & Business Days (Feriados)](https://apify.com/br_data_hub/br-holidays) | Brazilian national and state holidays for all 27 states, with the law behind each one |
| [Brazil Banks & Pix Directory (Bancos e ISPB)](https://apify.com/br_data_hub/br-bank-pix-directory) | Every Brazilian bank and payment institution from official Banco Central lists: ISPB, COMPE bank code, short a |

See all our Actors at [apify.com/br_data_hub](https://apify.com/br_data_hub).

### Usar em português

**Validador de boletos em lote**, sem rede: cole linhas digitáveis (47 dígitos no boleto bancário, 48 nas contas de consumo, tributos e multas) ou códigos de barras (44 dígitos), com ou sem pontos, espaços e hífens. Para cada código, o Actor diz se é válido e, se não for, qual campo e qual dígito falhou; converte linha digitável em código de barras e vice-versa; e devolve banco (código, ISPB e nome pela lista do Banco Central), valor e vencimento.

**Para que serve:** automação de contas a pagar, importação de boletos em ERP, robôs de pagamento e agentes de IA que leem boletos de e-mails e PDFs e não podem pagar um código digitado errado. Boletos repetidos no mesmo lote são marcados em `duplicateOf`, o que ajuda a evitar pagamento em dobro.

**Como usar em 3 passos:**

1. Clique em **Try for free** e cole os códigos em **Digitable lines or barcodes**, um por linha (ou separados por vírgula ou ponto e vírgula), até 100 mil por execução.
2. Se for reprocessar boletos antigos, preencha **Reference date** (veja a virada do fator abaixo). Desligue **Return invalid codes** se quiser só os válidos.
3. Clique em **Start** e baixe na aba **Output** (JSON, CSV, Excel) ou leia pela API. O registro `OUTPUT` traz os totais da execução.

**Exemplo de entrada:**

```json
{ "codes": ["10492.00650 61000.100042 00997.263900 9 89810000021403", "83860000005-0 09600019000-9 00080178230-9 00034306271-2"], "includeInvalid": true }
```

**Campos principais:** `status` (`valid` ou `invalid`), `type` (`bank` ou `collection`), `barcode`, `digitableLine`, `digitableLineFormatted`, `bank` (código, ISPB e nome), `amount` (valor em reais), `dueDate` (vencimento), `dueDateOtherCycle`, `dueDateFactor`, `freeField` (campo livre), `segment` e `segmentName` (arrecadação), `companyCode` ou `companyCnpjRoot`, `duplicateOf`, `errors` (campo, posição, dígito esperado e encontrado) e `warnings`.

**Virada do fator de vencimento:** o fator chegou a 9999 em 21/02/2025 e voltou a 1000 em 22/02/2025, então os mesmos quatro dígitos valem duas datas com 9.000 dias de diferença. O Actor escolhe a mais próxima da data de referência (hoje, se vazia) e mostra a outra em `dueDateOtherCycle`. Boletos de arrecadação não têm vencimento padronizado e vêm com `dueDate` nulo. O Actor não consulta se o boleto foi pago: isso só o banco emissor sabe.

**O que é grátis:** códigos inválidos e boletos repetidos no mesmo lote não são cobrados. Você paga por boleto válido.

**Quanto custa:** $0.001 por resultado (`boleto`); 1.000 resultados saem por $1.00. Desconto pelo nível da assinatura Apify: Bronze 10%, Silver 20%, Gold ou acima 30%. Erros e consultas sem resultado não são cobrados. Use também pela API ou por agentes de IA no servidor MCP da Apify (`https://mcp.apify.com/?tools=br_data_hub/br-boleto-parser`).

# Actor input Schema

## `codes` (type: `array`):

Paste digitable lines (47 digits for bank boletos, 48 for utility bills and taxes) or 44-digit barcodes, one per line, up to 100,000 per run. Dots, spaces and hyphens are ignored.

## `includeInvalid` (type: `boolean`):

Keep on to also save invalid codes, with the field and digit that failed. Invalid codes are never charged.

## `referenceDate` (type: `string`):

Pick a date (YYYY-MM-DD) only when processing old boletos. The due-date factor restarted at 1000 on 2025-02-22, so each factor matches two dates 9,000 days apart; the Actor picks the one closest to this date. Leave empty to use today in Brasília.

## Actor input object example

```json
{
  "codes": [
    "10492.00650 61000.100042 00997.263900 9 89810000021403",
    "34191.09123 34567.812341 56789.010008 8 10000000098765",
    "83860000005-0 09600019000-9 00080178230-9 00034306271-2",
    "10492.46802 13579.246805 13579.246805 3 16260000032990",
    "84630000000299902962020041013600000200644114",
    "10492006506100010004200997263900989810000021413"
  ],
  "includeInvalid": true
}
```

# Actor output Schema

## `dataset` (type: `string`):

Dataset with all results

## `summary` (type: `string`):

Run totals: codes, valid, invalid, duplicates, reference date and bank list date

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "codes": [
        "10492.00650 61000.100042 00997.263900 9 89810000021403",
        "34191.09123 34567.812341 56789.010008 8 10000000098765",
        "83860000005-0 09600019000-9 00080178230-9 00034306271-2",
        "10492.46802 13579.246805 13579.246805 3 16260000032990",
        "84630000000299902962020041013600000200644114",
        "10492006506100010004200997263900989810000021413"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("br_data_hub/br-boleto-parser").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "codes": [
        "10492.00650 61000.100042 00997.263900 9 89810000021403",
        "34191.09123 34567.812341 56789.010008 8 10000000098765",
        "83860000005-0 09600019000-9 00080178230-9 00034306271-2",
        "10492.46802 13579.246805 13579.246805 3 16260000032990",
        "84630000000299902962020041013600000200644114",
        "10492006506100010004200997263900989810000021413",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("br_data_hub/br-boleto-parser").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "codes": [
    "10492.00650 61000.100042 00997.263900 9 89810000021403",
    "34191.09123 34567.812341 56789.010008 8 10000000098765",
    "83860000005-0 09600019000-9 00080178230-9 00034306271-2",
    "10492.46802 13579.246805 13579.246805 3 16260000032990",
    "84630000000299902962020041013600000200644114",
    "10492006506100010004200997263900989810000021413"
  ]
}' |
apify call br_data_hub/br-boleto-parser --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,br_data_hub/br-boleto-parser"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/AM8ZPOUWvtEushz4g/builds/DyuPyTCzR6jl7AoOn/openapi.json