Skip to main content
Every Lerian BC Correios operation sits under the /api/v1/correios base path. The API Reference 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. Lerian BC Correios reads the tenant from the tenant_id claim of the token. Access Manager grants access through three groups: 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 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 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.