> ## 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 SRC

> Integración con Lerian SRC: la superficie de la API, los permisos, la idempotencia, el polling y los eventos, los errores y los límites de solicitud.

Cada operación de negocio de Lerian SRC está bajo la ruta base `/v1/src`. La [Referencia de API](/es/reference/rails/src/create-a-consultation) 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](/es/rails/src/src-environment-variables) lista la configuración, y [Operación de Lerian SRC](/es/rails/src/src-operations) cubre la conexión IBM MQ con BACEN.

<h2 id="authentication-and-permissions">
  Autenticación y permisos
</h2>

***

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

| Operaciones | Recurso | Acción |
| - | - | - |
| Crear una consulta | `consultation` | `write` |
| Listar, buscar y obtener consultas | `consultation` | `read` |
| Presentar un registro de la institución | `decision` | `write` |
| Buscar en la pista de evidencias, obtener la pista de evidencias de una consulta y buscar registros de evidencia | `evidence` | `read` |
| Corregir un registro de evidencia | `evidence` | `correct` |
| Obtener el dashboard de consultas | `dashboard` | `read` |
| Obtener el estado de la credencial | `credential` | `read` |
| Listar y obtener casos de operador | `operator` | `read` |
| Cerrar o reconocer un caso de operador | `operator` | `close` |
| Configuración en tiempo de ejecución (`/v1/system`) | `system` | `write` |
| Manifiesto de eventos (`GET /v1/streaming/manifest`) | `streaming` | `read` |

Lerian SRC atiende a una institución, que `SRC_CNPJ_BASE8` define en su configuración.

## Superficie de la API

***

| Área | Operación | Propósito |
| - | - | - |
| Consultas | `POST /v1/src/consultations` | Crear una consulta. |
| Consultas | `GET /v1/src/consultations` | Listar consultas, con filtros. |
| Consultas | `POST /v1/src/consultations/search` | Buscar consultas, también por documento. |
| Consultas | `GET /v1/src/consultations/{id}` | Leer una consulta y su resultado. |
| Registros de la institución | `POST /v1/src/consultations/{id}/institution-record` | Presentar el registro de la institución de una consulta. |
| Evidencias | `POST /v1/src/evidence` | Encontrar las consultas que tienen una pista de evidencias. |
| Evidencias | `GET /v1/src/evidence/consultations/{id}` | Leer la pista de evidencias de una consulta. |
| Evidencias | `POST /v1/src/evidence/consultations/{id}/corrections` | Corregir un registro de evidencia. |
| Evidencias | `POST /v1/src/evidence/records` | Encontrar registros de evidencia individuales. |
| Dashboard | `GET /v1/src/dashboard/consultations` | Leer los totales de consultas de un período. |
| Credenciales | `GET /v1/src/credentials` | Leer el estado de la credencial. |
| Casos de operador | `GET /v1/src/operator/cases` | Listar casos de operador. |
| Casos de operador | `GET /v1/src/operator/cases/{leg}/{caseId}` | Leer un caso de operador. |
| Casos de operador | `POST /v1/src/operator/orphan-responses/{caseId}/closure` | Cerrar un caso de respuesta huérfana. |
| Casos de operador | `POST /v1/src/operator/invalid-dispatches/{caseId}/closure` | Reconocer un caso de envío inválido. |

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

| Endpoint | Propósito |
| - | - |
| `GET /health` | Liveness. |
| `GET /readyz` | Readiness de las dependencias. |
| `GET /version` | Versión del build. |
| `/v1/system` | Configuración en tiempo de ejecución. |
| `GET /v1/streaming/manifest` | El manifiesto de eventos. |

<h2 id="idempotency">
  Idempotencia
</h2>

***

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

<h2 id="polling-and-events">
  Polling y eventos
</h2>

***

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.

| Tipo de evento | Se publica cuando | Campos del payload |
| - | - | - |
| `studio.lerian.br-src.consulta.accepted` | Lerian SRC acepta una consulta. | `consultationId`, `status`, `documentMasked`, `documentType`, `protectionTypes`, `motivationReference`, `acceptedAt`, `occurredAt` |
| `studio.lerian.br-src.consulta.completed` | BACEN responde una consulta. | `consultationId`, `status`, `bcbControlCode`, `bcbProcessedAt`, `concludedAt`, `verdicts`, `occurredAt` |
| `studio.lerian.br-src.consulta.failed` | Una consulta falla. | `consultationId`, `status`, `rejectionCode`, `rejectionClassification`, `rejectionReceivedAt`, `concludedAt`, `occurredAt` |

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](/es/platform/streaming-hub/what-is-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](/es/reference/rails/src/src-error-list) 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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.