> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrating with Lerian BC Correios

> Integrating with Lerian BC Correios: tenant settings, the connection test, Access Manager groups, idempotency, errors, and request limits.

Every Lerian BC Correios operation sits under the `/api/v1/correios` base path. The [API Reference](/en/reference/rails/bc-correios/list-or-search-mails) documents each operation, with its request and response.

## Before you start

***

A tenant needs settings before Lerian BC Correios can poll BC Correio or send a message.

1. Create the settings with `POST /settings`. Send the Sisbacen user and password in `bcbUsername` and `bcbPassword`.
2. Test the connection with `POST /settings/test-connection`. It calls BC Correio with the stored credentials.

A second `POST /settings` for the same tenant returns `409` `BCC-0006`. Change existing settings with `PATCH /settings`, and the retention period with `PATCH /settings/retention`.

Lerian BC Correios encrypts the BC Correio credentials and the AI API key before it stores them. `GET /settings` does not return them. It returns `hasBcbCredentials` and `hasAiApiKey` instead.

## Authentication and permissions

***

Every operation needs a bearer token from [Lerian Access Manager](/en/platform/access-manager). Lerian BC Correios reads the tenant from the `tenant_id` claim of the token.

Access Manager grants access through three groups:

| Group | Access |
| - | - |
| `plugin-bc-correios-viewer-group` | Read mail, attachments, settings, the audit trail, and the dashboard. Mark a mail as read. |
| `plugin-bc-correios-contributor-group` | Viewer access. Also send messages, ask for an AI analysis, and archive or restore mail. |
| `plugin-bc-correios-editor-group` | Contributor access. Also create and change settings, and test the BC Correio and AI connections. |

The Access Manager administrator group has the same access as the editor group.

## Idempotency

***

`POST /mails/send` needs an `X-Idempotency` header. A request without it returns `422`. A request with an empty value returns `400` `BCC-0001`.

`POST /mails/{id}/reanalyze` also needs the header. A request without it, or with an empty value, returns `400` `BCC-0001`.

The other write operations accept an optional `X-Idempotency` header. On every operation that takes the header, these rules apply:

* A repeat with the same key and the same request returns the answer of the first request.
* The same key on a different request returns `422` `BCC-0001`.
* A repeat while the first request still runs returns `409` `BCC-0012` with a `Retry-After` header.
* A key longer than 128 bytes returns `400` `BCC-0001`.

Lerian BC Correios keeps a key for `IDEMPOTENCY_TTL_SEC` seconds, 86400 by default. [How Lerian BC Correios works](/en/rails/bc-correios/how-bc-correios-works#sending-a-message) explains what a repeated send returns.

## Errors

***

Errors follow RFC 9457 problem details. Branch on the `code` field, not on the `detail` text. The [BC Correios error list](/en/reference/rails/bc-correios/bc-correios-error-list) gives each code, its meaning, and its HTTP status.

## Integration conventions

***

* **Send limits.** `subject` takes at most 500 characters, and `body` at most 102400 characters. `keywords` takes at most 10 entries of at most 100 characters each. A request body larger than 8 MB returns `413` `BCC-4003`.
* **Mail count.** `GET /mails/count` can return a count up to 60 seconds old.
* **Rate limits.** When `RATE_LIMIT_ENABLED` is `true`, each tenant has a request budget per operation in a 60-second window. Past it, the answer is `429` `BCC-0007` with a `Retry-After` header.
* **Attachment downloads.** Each tenant can download `ATTACHMENT_BANDWIDTH_BUDGET_MB_PER_MIN` megabytes of attachments per minute, 500 by default. Past it, the answer is `429` `BANDWIDTH_LIMIT_EXCEEDED`.

| Operation | Requests per 60 seconds |
| - | - |
| Get a mail, mark it as read, archive, restore, AI status | 500 |
| List or search mail, download an attachment | 100 |
| Settings, except the AI connection test | 60 |
| Dashboard | 60 |
| Audit trail and export | 50 |
| Count mail | 30 |
| Send a message | 10 |
| Ask for an AI analysis | 10 |
| Test the AI connection | 5 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.