Skip to main content
Cada operación de Lerian BC Correios está bajo la ruta base /api/v1/correios. La Referencia de API documenta cada operación, con su solicitud y su respuesta.

​
Antes de empezar

Un tenant necesita una configuración antes de que Lerian BC Correios pueda sondear BC Correio o enviar un mensaje.
  1. Crea la configuración con POST /settings. Envía el usuario y la contraseña Sisbacen en bcbUsername y bcbPassword.
  2. Prueba la conexión con POST /settings/test-connection. Llama a BC Correio con las credenciales almacenadas.
Un segundo POST /settings para el mismo tenant devuelve 409 BCC-0006. Cambia una configuración existente con PATCH /settings, y el período de retención con PATCH /settings/retention. Lerian BC Correios cifra las credenciales de BC Correio y la clave de API de IA antes de almacenarlas. GET /settings no las devuelve. En su lugar, devuelve hasBcbCredentials y hasAiApiKey.

​
Autenticación y permisos

Cada operación necesita un bearer token de Lerian Access Manager. Lerian BC Correios lee el tenant del claim tenant_id del token. Access Manager otorga el acceso a través de tres grupos: El grupo de administradores de Access Manager tiene el mismo acceso que el grupo editor.

​
Idempotencia

POST /mails/send necesita un header X-Idempotency. Una solicitud sin él devuelve 422. Una solicitud con un valor vacío devuelve 400 BCC-0001. POST /mails/{id}/reanalyze también necesita el header. Una solicitud sin él, o con un valor vacío, devuelve 400 BCC-0001. Las demás operaciones de escritura aceptan un header X-Idempotency opcional. En cada operación que acepta el header, se aplican estas reglas:
  • Una repetición con la misma clave y la misma solicitud devuelve la respuesta de la primera solicitud.
  • La misma clave en una solicitud diferente devuelve 422 BCC-0001.
  • Una repetición mientras la primera solicitud aún se ejecuta devuelve 409 BCC-0012 con un header Retry-After.
  • Una clave de más de 128 bytes devuelve 400 BCC-0001.
Lerian BC Correios conserva una clave durante IDEMPOTENCY_TTL_SEC segundos, 86400 de forma predeterminada. Cómo funciona Lerian BC Correios explica qué devuelve un envío repetido.

​
Errores

Los errores siguen los problem details de RFC 9457. Decide la rama con el campo code, no con el texto de detail. La lista de errores de BC Correios da cada código, su significado y su estado HTTP.

​
Convenciones de integración

  • Límites de envío. subject acepta como máximo 500 caracteres, y body como máximo 102400 caracteres. keywords acepta como máximo 10 entradas de como máximo 100 caracteres cada una. Un cuerpo de solicitud de más de 8 MB devuelve 413 BCC-4003.
  • Conteo de correos. GET /mails/count puede devolver un conteo de hasta 60 segundos de antigüedad.
  • Rate limits. Cuando RATE_LIMIT_ENABLED es true, cada tenant tiene un presupuesto de solicitudes por operación en una ventana de 60 segundos. Al superarlo, la respuesta es 429 BCC-0007 con un header Retry-After.
  • Descargas de adjuntos. Cada tenant puede descargar ATTACHMENT_BANDWIDTH_BUDGET_MB_PER_MIN megabytes de adjuntos por minuto, 500 de forma predeterminada. Al superarlo, la respuesta es 429 BANDWIDTH_LIMIT_EXCEEDED.