> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Integración con Lerian SCR

> Integración con Lerian SCR: la superficie de operaciones, los ámbitos del token, la idempotencia, el catálogo de errores, los eventos de consulta, y las convenciones de solicitud.

Lerian SCR expone una única superficie REST. La institución proviene del token.

## 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.            |
| `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.

## Autenticación y tenencia

***

Un consumidor se autentica con un token OAuth2 de client-credentials en `Authorization: Bearer`. Para cada solicitud protegida, el servicio le pide al servidor de autorización un permiso explícito. Nunca confía en una afirmación no verificada. Un ámbito tiene la forma `scr:<resource>:<action>`. Consulta [Access Manager](/es/platform/access-manager).

La institución proviene de las afirmaciones del token, nunca de un campo del cuerpo, un header, una ruta o un parámetro de consulta. Un despliegue dedicado la fija por instancia.

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 aceptan un header `X-Idempotency`. Un reintento dentro de una ventana de cinco minutos repite el primer resultado y no paga una segunda tarifa. Una clave reutilizada con un cuerpo distinto responde `SCR-0003`. Sin Redis, el control falla en modo abierto, y un reintento vuelve a pagar la tarifa.

## Errores

***

Todo fallo responde `application/problem+json` conforme a RFC 9457, con el código, el estado, y un id de traza.

| 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 un cuerpo distinto.                           |
| `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.                   |
| `SCR-1003` | 504    | Timeout del upstream.                                                         |
| `SCR-9000` | 500    | Error interno inesperado.                                                     |
| `SCR-9001` | 503    | La escritura de auditoría no hizo commit. Reintentar es seguro.               |

## 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](/es/platform/streaming-hub/what-is-streaming-hub).

Cuando un operador desactiva la emisión, el despachador no arranca. Las filas permanecen pendientes y se envían en cuanto un broker vuelve a estar disponible.

## Convenciones de integración

***

* **Correlación.** `X-Request-ID` lleva un UUID a través de los logs, las trazas, y el registro de auditoría.
* **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.
* **Campos codificados.** Un campo codificado responde `{ code, description }`, con una descripción nula para un código desconocido.