canonical: https://jentic.com/apis/cnab-online.herokuapp.com/cnab-online

# Cnab Online

Cnab Online parses Brazilian CNAB return files (arquivos de retorno) so finance teams and integrators can read boleto payment confirmations, write-offs, and other bank occurrences without writing a custom parser. Callers upload a CNAB file, receive a fileId, and then query for the recognised lines and occurrences. The API focuses purely on parsing CNAB 240/400 return files into structured JSON - it does not generate boletos or transmit instructions to banks.

## For AI agents

Parse Brazilian CNAB return files into structured JSON to read boleto write-offs and bank occurrences from a single file upload.

## Scope

Does not generate boletos, transmit CNAB remessa files to banks, or process card or PIX payments - use for parsing CNAB return files only.

## Capabilities

- Upload a CNAB return file via POST /file and receive a parse identifier
- Retrieve basic metadata for an uploaded file via GET `/file/{fileId}`
- List every recognised line and its parsed fields with GET `/file/{fileId}/lines`
- Extract boleto write-offs and other bank occurrences via GET `/file/{fileId}/occurrences`
- Process CNAB 240 and CNAB 400 return formats from Brazilian banks without local parser code

## Use cases

### Boleto Reconciliation

Reconcile paid boletos against open invoices by uploading the daily CNAB return file from the bank and reading the parsed occurrences. POST /file accepts the raw CNAB file, then GET `/file/{fileId}/occurrences` returns the structured payment events so accounts receivable can mark invoices as paid. Replacing an in-house CNAB parser with this flow saves the multi-week effort of supporting bank-specific layouts.

Example prompt: Upload a CNAB 240 return file via POST /file, then call GET `/file/{fileId}/occurrences` and return all paid boletos.

### Bank File Auditing

Audit incoming CNAB return files line by line to verify that the bank applied the expected events to each transaction. GET `/file/{fileId}/lines` returns every recognised line with its parsed fields, so a controller can compare totals and flag mismatches before posting to the ledger. Useful when integrating a new bank or when a layout version change introduces unexpected occurrences.

Example prompt: Call GET `/file/{fileId}/lines` for a previously uploaded CNAB file and return the count of lines per recognised record type.

### Multi-Bank Boleto Aggregation

Accept CNAB return files from several Brazilian banks (Itaú, Bradesco, Santander, Caixa, Banco do Brasil) into one workflow. The API recognises common CNAB 240 and 400 layouts so a treasury system can normalise occurrences without maintaining a parser per bank. GET `/file/{fileId}` confirms that the upload was processed before downstream queries are issued.

Example prompt: Upload a CNAB return file from Banco do Brasil, then call GET `/file/{fileId}` and confirm processing succeeded before parsing occurrences.

### AI Agent Boleto Workflow via Jentic

An AI agent in a finance ops workflow uses Jentic to upload a CNAB return file and pull occurrences without integrating directly with the Heroku-hosted parser. Because the API is unauthenticated, the agent can chain POST /file and GET `/file/{fileId}/occurrences` in a single workflow while Jentic handles retries and error handling.

Example prompt: Use Jentic to search for 'parse CNAB return file', upload the file via POST /file, then return occurrences from GET `/file/{fileId}/occurrences.`

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/file` | Upload a CNAB return file for parsing |
| GET | `/file/{fileId}` | Retrieve metadata for a parsed file |
| GET | `/file/{fileId}/lines` | List all recognised lines and their parsed fields |
| GET | `/file/{fileId}/occurrences` | Retrieve structured boleto and bank occurrences |

## Key resources

- **File** — Upload CNAB return files and retrieve metadata about a parsed file
- **Lines** — Read every recognised line in a parsed CNAB file with its field-level breakdown
- **Occurrences** — Read structured boleto write-offs and other bank occurrences extracted from the file

## Why Jentic

- **Setup:** Wiring Cnab Online by hand means targeting cnab-online.herokuapp.com/v1, chaining the file upload and line-read calls, and handling retries yourself against Portuguese-language docs. Through Jentic you install once, import the Cnab Online API from the API Directory, and your agent calls it with no key to manage.
- **Permission scoping:** Cnab Online is unauthenticated, so scope the agent to the operations it needs, such as uploading a return file and reading its parsed lines. You choose that set, so operations like reading occurrences are not included unless you add them.
- **Credential handling:** Cnab Online needs no credentials, so there is nothing to store. Your Jentic One instance still proxies each call and applies retry policy, keeping the agent's prompt, logs, and context free of secrets.
- **Discovery method:** Agents search Jentic by intent such as 'parse a CNAB return file', and Jentic returns the upload and read operations with their input schemas so the agent builds a multi-step parse-and-read flow without reading the Portuguese-language documentation.

## Related APIs

- **Boleto.cloud** — Boleto.cloud handles boleto generation and management for Brazilian payments.
- **Open Finance Brasil** — Open Finance Brasil exposes regulated bank account and payment data via standardised APIs.
- **Plaid** — Plaid provides bank account aggregation primarily for North American institutions.

## FAQ

### What authentication does the Cnab Online API use?

The OpenAPI spec declares no security schemes - the API is open and accepts file uploads without an API key. Through Jentic the call is still proxied for observability and retry handling, so an agent does not need to manage any credentials.

### Can I parse both CNAB 240 and CNAB 400 files with this API?

Yes. POST /file accepts CNAB return files and the parser recognises both CNAB 240 and CNAB 400 layouts used by major Brazilian banks. The recognised fields are available via GET `/file/{fileId}/lines` after upload.

### What are the rate limits for the Cnab Online API?

The OpenAPI spec does not declare numeric rate limits. The service runs on a single Heroku dyno, so high-volume callers should serialise uploads and avoid concurrent calls to /file from the same IP to prevent timeouts.

### How do I retrieve boleto write-offs from a CNAB file through Jentic?

Search Jentic for 'parse CNAB return file', upload the file with POST /file to get a fileId, then call GET `/file/{fileId}/occurrences` to receive structured write-offs and other occurrences. Install the SDK with pip install jentic and call it via the async client.

### Does this API generate boletos or transmit instructions to banks?

No. The API only parses CNAB return files. Generation of boletos (CNAB remessa) and transmission to banks must be handled by a separate service. Use this API when you already have a return file from the bank and need to extract structured data.

### Is the API suitable for production reconciliation workloads?

It works well for prototypes and low-to-mid volume reconciliation. For high-throughput or strict SLA workloads consider hosting your own parser, since this service runs on a Heroku free-tier-style dyno and provides no published uptime guarantee.

### Can I limit what my agent is allowed to do with the Cnab Online API?

Yes. Because you run Jentic One yourself, your own rules decide which Cnab Online operations the agent may call, and the API needs no credentials to manage. You can scope the agent to just what it needs, such as uploading a return file with POST /file and reading its parsed lines with GET `/file/{fileId}/lines`, while leaving out operations like GET `/file/{fileId}/occurrences` unless you add them. Each call still passes through your Jentic One instance, so the agent only ever reaches the operations you allow.