Skip to main content
Los endpoints de negocio siguientes usan la ruta base /api/v1/correios. El systemplane del operador usa /v1/system. 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. GET /settings no devuelve los valores de las credenciales. 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. En cada operación que acepta el header, se aplican estas reglas:
  • Una repetición mientras la primera solicitud aún se ejecuta devuelve 409 BCC-0012 con un header Retry-After.
  • Mientras la cache guarda una clave, la misma clave en una solicitud diferente devuelve 422 BCC-0001.
  • Una clave de más de 128 bytes devuelve 400 BCC-0001.

​
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 bytes, y body como máximo 102400 bytes. 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 fila de la tabla siguiente, en una ventana de 60 segundos. Las operaciones de una misma fila comparten ese presupuesto. 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.