Skip to main content
Os endpoints de negócio abaixo usam o caminho base /api/v1/correios. O systemplane do operador usa /v1/system. 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. GET /settings não retorna os valores das credenciais. Em vez disso, 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. Em cada operação que recebe o header, valem estas regras:
  • Uma repetição enquanto a primeira requisição ainda roda retorna 409 BCC-0012 com um header Retry-After.
  • Enquanto o cache guarda uma chave, a mesma chave em uma requisição diferente retorna 422 BCC-0001.
  • Uma chave com mais de 128 bytes retorna 400 BCC-0001.

​
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 bytes, e body no máximo 102400 bytes. 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 linha da tabela abaixo, em uma janela de 60 segundos. As operações de uma mesma linha compartilham essa cota. 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.