Skip to main content
The business endpoints below use the /api/v1/correios base path. The operator systemplane uses /v1/system. 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. GET /settings does not return credential values. 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. On every operation that takes the header, these rules apply:
  • 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.

​
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. 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 one request budget per row of the table below, in a 60-second window. The operations in one row share that budget. 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.