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-manifest:get`	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. Toda solicitud bajo /v1/scr también pasa por la compuerta de licencia de Lerian: una solicitud que la licencia rechaza responde 403 con un código LCS-. /v1/system, /v1/client-system, /v1/streaming/manifest y las sondas no pasan por ella. Consulta Variables de entorno. 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. Uno que no responde a tiempo responde SCR-1003.

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 de más de 1 MB no se almacena. Un reintento bajo la clave de una solicitud completada de ese tipo responde SCR-0007: la solicitud no se ejecuta de nuevo, y no se cobra una segunda tarifa. Lee el resultado original en GET /v1/scr/consultations/{id} o en la pista de auditoría. 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. Un duplicado que no es una repetición de respuesta, porque una solicitud anterior retiene su clave, trae X-Idempotency-Held: true. 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-0007`	409	La primera solicitud con este `X-Idempotency` se completó, y su respuesta era demasiado grande para almacenarse. Esta solicitud no se ejecutó.
`SCR-0201`	401	Token de acceso faltante o inválido.
`SCR-0202`	403	Ámbito faltante para la acción.
`LCS-NNNN`	403	La licencia de Lerian rechaza la solicitud. El cuerpo trae `code`, `title` y `message`, no un documento de problema.
`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. La solicitud también responde con él cuando esperó más allá de su plazo una de las dos conexiones con BACEN. No se envió nada y la clave se libera: reintenta con la misma clave. 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	Un timeout antes de que algo llegara a BACEN: el servicio de autorización no respondió a tiempo, o la conexión con BACEN expiró antes de enviar la solicitud. Reintenta con la misma clave.
`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.

El id del evento es el id de auditoría de la consulta. Para una consulta atendida, es el id que devuelve POST /v1/scr/consultations. 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.