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

​
Antes de empezar

Un operador despliega y configura Lerian SRC para tu institución. Variables de entorno lista la configuración, y Operación de Lerian SRC cubre la conexión IBM MQ con BACEN.

​
Autenticación y permisos

Cada llamada a /v1/src necesita un bearer token de Access Manager. Usa un token de aplicación para tus sistemas de onboarding y un token de usuario para tu back office. Una solicitud sin un token válido devuelve 401. Un token de otro tipo devuelve 401 con el código SRC-0201. Cada operación necesita un permiso en el producto src. Un token sin ese permiso devuelve 403 con el código SRC-0202. Lerian SRC atiende a una institución, que SRC_CNPJ_BASE8 define en su configuración.

​
Superficie de la API

Los endpoints operativos están fuera de /v1/src.

​
Idempotencia

POST /v1/src/consultations necesita un header X-Idempotency, de 255 caracteres como máximo. Una solicitud sin él devuelve 400 con el código SRC-0001.
  • La misma clave con el mismo cuerpo devuelve 202 con el id de la consulta original. La respuesta muestra el estado actual de esa consulta, así que puede ser completed o failed.
  • La misma clave con un cuerpo diferente devuelve 409 con el código SRC-0003.
Estas dos reglas valen mientras Lerian SRC guarda la clave. La limpieza de retención puede eliminar una clave más antigua que src.retention.transient_purge_age, 24 horas de forma predeterminada. Una solicitud que reutiliza una clave eliminada inicia una nueva consulta. POST /v1/src/consultations/{id}/institution-record no recibe una clave de idempotencia. Una consulta guarda un registro, así que un reintento devuelve 409 con el código SRC-0101. Una corrección de evidencia no es idempotente. Una solicitud reintentada agrega una segunda corrección. Antes de reintentar después de una falla que no puedes confirmar, lee la pista de evidencias.

​
Polling y eventos

Una consulta empieza en pending, y pending es un estado normal. Lee el resultado de una de dos formas:
  • Consulta periódicamente GET /v1/src/consultations/{id}. Una consulta completed lleva verdicts y bcbControlCode. Una consulta failed lleva rejection.
  • Consume los eventos que publica Lerian SRC.
Los eventos viajan en el tema lerian.streaming.br-src, con el source de CloudEvents br-src. Ninguna variable cambia el tema. Consulta Streaming Hub. Lerian SRC escribe cada evento en un outbox en la misma transacción que el cambio que informa. Sin broker, los eventos quedan pendientes en el outbox.

​
Errores

Los errores siguen los problem details de RFC 9457, con el tipo de medio application/problem+json. Decide la rama con el campo code, no con el texto de detail. La lista de errores de SRC da cada código, su significado y su estado HTTP.

​
Convenciones de integración

  • Tamaño de la solicitud. Un cuerpo de solicitud de más de 1 MiB devuelve 413.
  • Presupuesto de tiempo. Una solicitud que no se completa en 15 segundos devuelve 503 con el código SRC-1004.
  • Paginación. Una lista o búsqueda devuelve una página con nextCursor. Para leer la página siguiente, envía ese valor como cursor. nextCursor es null en la última página.
  • Rate limit. Lerian SRC cuenta las solicitudes de cada dirección IP de cliente en cada réplica. El valor predeterminado es 6000 solicitudes por minuto, definido por src.rate_limit.ip_max y src.rate_limit.ip_window. Por encima del límite, la respuesta es 429 con el código SRC-0401.