Integración con Lerian SCR

Lerian SCR expone una única superficie REST. Una instalación atiende a una institución.

Superficie de la API

Operación	Ámbito	Propósito
`POST /v1/scr/consultations`	`scr:consultation:write`	Consultar la posición de un prestatario. Tarifado.
`GET /v1/scr/consultations/{id}`	`scr:audit:read`	Releer una consulta, sin tarifa.
`GET /v1/scr/audit`	`scr:audit:read`	Listar el registro de auditoría.
`GET /v1/scr/credential`	`scr:credential:read`	Leer el estado de la credencial, nunca el secreto.
`PUT /v1/scr/credential`	`scr:credential:write`	Establecer o rotar la credencial.
`GET /v1/scr/operations/summary`	`scr:dashboard:read`	Resumen agregado, sin datos personales.
`/v1/system/{namespace}/{key}`	`scr:system:write`	Leer o cambiar la configuración en tiempo de ejecución.
`/v1/client-system/{namespace}/{key}`	`scr:client-system:read`, `scr:client-system:write`	Leer o cambiar las definiciones propias de la institución.
`GET /v1/streaming/manifest`	`scr:streaming:read`	El manifiesto de eventos.
`GET /health`	Ninguno	Sonda de liveness.
`GET /readyz`	Ninguno	Sonda de readiness, por dependencia.
`GET /version`	Ninguno	Marca de compilación.

Las operaciones de credencial existen solo cuando un vault de escritura respalda el despliegue. De lo contrario, la credencial proviene del entorno. GET /v1/scr/audit y GET /v1/scr/consultations/{id} pueden devolver el CPF o la raíz del CNPJ consultado completo, en el campo document. Concede scr:audit:read solo a las personas que puedan verlo.

Autenticación

Un consumidor se autentica con un token OAuth2 de client-credentials en Authorization: Bearer. Con PLUGIN_AUTH_ENABLED=true, el servidor de autorización decide cada solicitud protegida. Un ámbito tiene la forma scr:<resource>:<action>. Consulta Access Manager. Un token faltante responde SCR-0201, y un ámbito faltante SCR-0202. Un servidor de autorización inalcanzable responde SCR-1002, porque el control falla en modo cerrado.

Idempotencia

Las dos operaciones con efectos exigen un header X-Idempotency, y una solicitud sin él responde SCR-0004. Cuando Lerian SCR almacena un resultado 2xx o 4xx, un reintento dentro de una ventana de cinco minutos repite ese resultado y no paga una segunda tarifa. Un reintento mientras la primera solicitud sigue en ejecución responde SCR-0006. Envíalo de nuevo después de Retry-After. Una clave reutilizada con una solicitud distinta responde SCR-0003. Una respuesta con X-Idempotency-Fenced: true retiene su clave durante la ventana, y un reintento con esa clave responde SCR-0005 sin ejecutarse. Un 5xx sin ese header libera la clave, y un reintento vuelve a ejecutar la operación. Con X-Idempotency-Fenced: false, la solicitud puede haberse ejecutado y la clave no está protegida. Concilia el resultado antes de enviar la solicitud de nuevo. Sin Redis, ambas operaciones responden SCR-9002.

Errores

Un fallo responde application/problem+json conforme a RFC 9457, con el código y el estado.

Código	Estado	Cuándo
`SCR-0001`	400	Cuerpo o parámetros de consulta malformados.
`SCR-0002`	422	Documento, rango de fechas, o declaración de autorización inválidos.
`SCR-0003`	409	`X-Idempotency` reutilizado con una solicitud distinta.
`SCR-0004`	422	Falta `X-Idempotency`.
`SCR-0005`	422	Una solicitud anterior con este `X-Idempotency` no tiene un resultado registrado. Esta solicitud no se ejecutó.
`SCR-0006`	409	La primera solicitud con este `X-Idempotency` sigue en ejecución. Esta solicitud no se ejecutó.
`SCR-0201`	401	Token de acceso faltante o inválido.
`SCR-0202`	403	Ámbito faltante para la acción.
`SCR-0301`	404	No existe esa consulta o registro de auditoría.
`SCR-0401`	429	Limitado por tasa. `Retry-After` indica la espera.
`SCR-1001`	502	Error de la plataforma de BACEN, transmitido en `details.upstreamViolations`.
`SCR-1002`	503	Canal no disponible, breaker abierto, o vault inalcanzable. Cuando el breaker rechaza la llamada o el canal con BACEN no está disponible, el detail dice `BACEN SCR is unavailable; the consultation was not sent.`
`SCR-1003`	504	La solicitud no llegó a BACEN a tiempo.
`SCR-1004`	502	La solicitud pudo llegar a BACEN, y BACEN no dio una respuesta utilizable.
`SCR-9000`	500	Error interno inesperado.
`SCR-9001`	503	La escritura de auditoría no hizo commit, y la solicitud nunca llegó a BACEN.
`SCR-9002`	503	El almacén de idempotencia no está disponible, y la operación no se ejecutó.

Eventos

Lerian SCR emite un evento por cada consulta terminal a través de un outbox transaccional. La fila de auditoría y el evento hacen commit juntos.

studio.lerian.br-scr.consulta.completed: la consulta devolvió una respuesta, una posición o ninguna.
studio.lerian.br-scr.consulta.failed: la consulta no devolvió ninguna respuesta.

Ambos tipos viajan por el topic lerian.streaming.br-scr, y los mensajes envenenados por lerian.streaming.br-scr.dlq. Ninguna variable establece el topic, así que aprovisiona ambos. Consulta Streaming Hub. Cuando un operador desactiva la emisión, el despachador no arranca. Las filas permanecen pendientes y se envían después de que la emisión vuelve a activarse y el servicio se reinicia.

Convenciones de integración

Correlación. X-Request-ID lleva un UUID a través de los logs y las trazas.
Fechas de referencia. Los rangos de consulta y los filtros de auditoría usan AAAAMM, un año y mes de seis dígitos. El resumen operativo toma en cambio un rango de fecha y hora.
Filtros. El filtro de documento toma de 8 a 14 dígitos, comparados a través del índice ciego. El tipo de cliente 1 es una persona, 2 una empresa.
Paginación. El listado de auditoría toma un cursor opaco y un limit de 1 a 200, con valor por defecto 50.

​Superficie de la API

​Autenticación

​Idempotencia

​Errores

​Eventos

​Convenciones de integración