Skip to main content
Toda operação do Lerian BC Correios fica sob o caminho base /api/v1/correios. A Referência da API documenta cada operação, com sua requisição e sua resposta.

​
Antes de começar

Um tenant precisa de configurações antes que o Lerian BC Correios possa fazer polling no BC Correio ou enviar uma mensagem.
  1. Crie as configurações com POST /settings. Envie o usuário e a senha Sisbacen em bcbUsername e bcbPassword.
  2. Teste a conexão com POST /settings/test-connection. Essa operação chama o BC Correio com as credenciais armazenadas.
Um segundo POST /settings para o mesmo tenant retorna 409 BCC-0006. Mude as configurações existentes com PATCH /settings, e o período de retenção com PATCH /settings/retention. O Lerian BC Correios criptografa as credenciais do BC Correio e a chave de API de IA antes de armazená-las. GET /settings não as retorna. Em vez delas, retorna hasBcbCredentials e hasAiApiKey.

​
Autenticação e permissões

Toda operação precisa de um bearer token do Lerian Access Manager. O Lerian BC Correios lê o tenant do claim tenant_id do token. O Access Manager concede acesso por meio de três grupos: O grupo de administradores do Access Manager tem o mesmo acesso que o grupo editor.

​
Idempotência

POST /mails/send precisa de um header X-Idempotency. Uma requisição sem ele retorna 422. Uma requisição com valor vazio retorna 400 BCC-0001. POST /mails/{id}/reanalyze também precisa do header. Uma requisição sem ele, ou com valor vazio, retorna 400 BCC-0001. As outras operações de escrita aceitam um header X-Idempotency opcional. Em cada operação que recebe o header, valem estas regras:
  • Uma repetição com a mesma chave e a mesma requisição retorna a resposta da primeira requisição.
  • A mesma chave em uma requisição diferente retorna 422 BCC-0001.
  • Uma repetição enquanto a primeira requisição ainda roda retorna 409 BCC-0012 com um header Retry-After.
  • Uma chave com mais de 128 bytes retorna 400 BCC-0001.
O Lerian BC Correios guarda uma chave por IDEMPOTENCY_TTL_SEC segundos, 86400 por padrão. Como o Lerian BC Correios funciona explica o que um envio repetido retorna.

​
Erros

Os erros seguem os problem details da RFC 9457. Decida com base no campo code, não no texto de detail. A lista de erros do BC Correios traz cada código, seu significado e seu status HTTP.

​
Convenções de integração

  • Limites de envio. subject aceita no máximo 500 caracteres, e body no máximo 102400 caracteres. keywords aceita no máximo 10 entradas de no máximo 100 caracteres cada. Um corpo de requisição maior que 8 MB retorna 413 BCC-4003.
  • Contagem de correspondências. GET /mails/count pode retornar uma contagem com até 60 segundos de defasagem.
  • Rate limits. Quando RATE_LIMIT_ENABLED é true, cada tenant tem uma cota de requisições por operação em uma janela de 60 segundos. Acima dela, a resposta é 429 BCC-0007 com um header Retry-After.
  • Downloads de anexos. Cada tenant pode baixar ATTACHMENT_BANDWIDTH_BUDGET_MB_PER_MIN megabytes de anexos por minuto, 500 por padrão. Acima disso, a resposta é 429 BANDWIDTH_LIMIT_EXCEEDED.