> ## 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.
# API REST de Lender
> Oriéntate en la API de Lender: la ruta base /api/v1, la autenticación bearer, la autorización por recurso y acción, el dinero como cadena decimal, la idempotencia con alcance, la paginación, la forma de error problem+json y las operaciones agrupadas por trabajo.
Lender sirve una sola API HTTP. Cada operación está bajo la ruta base `/api/v1`, y nada se versiona en el host. Una lista de productos es `GET /api/v1/loan-products`.
Esta página cubre lo que comparten las operaciones, y luego las agrupa por el trabajo que hacen. Cada operación tiene su propia página bajo el ancla **Lender** en la [Referencia de API](/es/reference/introduction), con las formas completas de solicitud y respuesta.
Los documentos OpenAPI de este portal son fuentes de render para las páginas de referencia. No son contratos de cliente, y no son base para la generación de SDK.
## Autenticación
***
La autenticación se configura en el despliegue. `PLUGIN_AUTH_ENABLED` es `false` de forma predeterminada. Cuando está habilitada, las rutas protegidas requieren un Bearer token JWT:
```http theme={null}
Authorization: Bearer
```
El valor predeterminado solo sirve para despliegues single-tenant: el arranque rechaza `MULTI_TENANT_ENABLED=true` con `PLUGIN_AUTH_ENABLED=false`, porque Lender resuelve el tenant desde el claim `tenantId` de la identidad validada.
Dos lecturas son públicas y no toman token: [listar jurisdicciones](/es/reference/products/lender/list-jurisdictions) y [obtener una jurisdicción](/es/reference/products/lender/get-jurisdiction). El registro son metadatos del despliegue, así que un cliente puede leerlo antes de tener una identidad.
Las sondas quedan fuera de la autenticación para que un orquestador las alcance sin token: `/health`, `/readyz` y `/version`.
### Autorización
***
Lender autoriza cada solicitud contra la aplicación `lender`, un recurso y una acción. El recurso sigue la superficie, y las acciones son granulares en lugar de una sola escritura:
| Recurso | Acciones |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `loan_product` | `read`, `write` |
| `loan_applications` | `preview:schedule`, `create`, `approve`, `reject`, `withdraw`, `disburse`, `capitalization-consent:ingest`, `preview:tax` |
| `loan_accounts` | `read`, `audit:read`, `charge:apply`, `repayment:preview`, `repayment:record`, `repayment:reverse`, `prepayment:record`, `reschedule`, `cet:read`, `pdd:transition` |
| `accounting` | `read`, `write` |
| `streaming_manifest` | `read` |
Otorga al rol de oficial solo las acciones que necesita su trabajo. Lender define sus roles y permisos en un archivo de semilla que cargas en tu proveedor de identidad. [Requisitos previos](/es/products/lender/lender-prerequisites) muestra el conjunto mínimo para la originación.
### Identidad del tenant y del oficial
***
**El tenant nunca es un header, un parámetro de query ni un campo del body.** En modo single-tenant Lender usa `DEFAULT_TENANT_ID`. En modo multi-tenant resuelve el tenant desde la identidad validada. Consulta [Multi-tenancy](/es/platform/multi-tenancy).
El oficial asignado viene del sujeto del token de la misma forma. Ningún body de solicitud de préstamo lleva un campo de oficial, y ningún valor aportado por el cliente anula el sujeto.
## Solicitudes y respuestas
***
Cada operación que lleva un body envía y devuelve `application/json`.
Envía los montos de dinero y las tasas decimales como `requestedInterestRate` en forma de cadenas decimales: `"50000.00"`, `"0.01500000"`. Los valores de versión de producto y de tasa flotante `fixedAnnualRateBps`, `floatingSpreadBps` y `annualRateBps` son puntos base enteros. Las marcas de tiempo son RFC 3339 en UTC.
Idempotencia
***
Lender somete 27 operaciones a un contrato de a lo sumo una vez, en dos clases. La clase decide qué header envías y dónde vive la garantía.
| Clase | Header | Dónde vive la garantía | Operaciones |
| ------------------------------ | ---------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Impuesta en el borde | `X-Idempotency`, obligatorio por el esquema | Un middleware delante del handler, respaldado por el almacén de idempotencia | 24 escrituras: las cinco escrituras de solicitud de préstamo (crear, aprobar, rechazar, retirar, desembolsar), prepago y su alias de Brasil, la cotización de prepago de Brasil, reprogramación, cargos de producto, corridas de devengo y su reintento, el barrido de sucesión del plan de cuentas, hechos de lote de cesión, liquidación de cobro del consignado y las nueve acciones de operación del consignado |
| Confirmada junto con el dinero | `X-Request-ID`, con `X-Idempotency` como alternativa | Una marca escrita en la misma transacción de base de datos que el dinero | 3 escrituras: registrar un pago, revertir una transacción, cobrar una cuenta por cobrar de pago devuelto |
Envía tu propia clave. En las 24 operaciones impuestas en el borde:
* Un reintento de una llamada **completada** repite la primera respuesta y le estampa `X-Idempotency-Replayed: true`. Nada se registra una segunda vez.
* Un reintento mientras la primera llamada sigue **en curso** responde `409`. Espera y lee el recurso; no envíes el comando de nuevo.
* Una solicitud que **no lleva clave** responde `400` con el código `IDEMPOTENCY_KEY_REQUIRED`. La clave es un header obligatorio en el esquema de la operación, así que el rechazo ocurre antes de que corra cualquier lógica del handler.
* Una clave enviada con una grafía que Lender no lee — `Idempotency-Key` o `X-Idempotency-Key` — responde `400` con el código `IDEMPOTENCY_KEY_HEADER_UNKNOWN`, en lugar de ejecutar el comando sin protección. Enviar una de esas junto con el header del contrato no es problema; el rechazo solo se dispara cuando `X-Idempotency` está ausente.
* La clave está delimitada a tu tenant y expira después de la ventana que fija `IDEMPOTENCY_RETRY_WINDOW_SEC`, cuyo valor por defecto es 86400 segundos (24 horas).
**El contrato falla cerrado, en ambas direcciones.** Un despliegue sin almacén de idempotencia accesible no arranca. Si el almacén queda inaccesible mientras corre, una operación protegida responde `503` con el código `IDEMPOTENCY_UNAVAILABLE` en lugar de ejecutar sin protección.
Cada rechazo lleva un código legible por máquina, y el cliente decide con él entre reenviar y conciliar. `IDEMPOTENCY_OUTCOME_UNKNOWN` y `IDEMPOTENCY_OUTCOME_UNKNOWN_UNFENCED` dicen que se alcanzó el handler y que el resultado no puede establecerse: lee el recurso antes de decidir. Los códigos son contrato publicado; renombrar uno es un cambio incompatible.
Las tres operaciones transaccionales funcionan de otra manera. Todas leen `X-Request-ID` primero y recurren a `X-Idempotency` cuando está ausente. Envía uno de los dos: una llamada que no lleva ninguno responde `422`.
Lender guarda el id de la solicitud en la base de datos junto con los hechos de la llamada. Un reintento que lleva el mismo id y los mismos hechos repite la primera respuesta por la ruta normal de respuesta, sin header de repetición. El mismo id de solicitud con hechos **distintos** responde `409` en lugar de repetir, así que un id nunca puede registrar dos montos diferentes. Ese registro no expira.
Los hechos que Lender compara cambian según la operación:
| Operación | Hechos comparados con el id de solicitud guardado |
| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Registrar un pago | La cuenta de préstamo, el monto y la fecha efectiva (`transactionDate` cuando `effectiveDate` está ausente). |
| Revertir una transacción | La transacción que se revierte, la cuenta de préstamo, la fecha efectiva de la reversión, el motivo, la versión del perfil y el código de jurisdicción. El monto viene de la transacción original, así que no se compara. |
| Cobrar una cuenta por cobrar de pago devuelto | La cuenta por cobrar y el cobro mismo. Reentregar el mismo cobro bajo la misma identidad de solicitud responde `200` con la cuenta por cobrar que ya rige; un segundo cobro, distinto, contra una cuenta por cobrar ya cobrada responde `409`. |
## Paginación
***
La paginación es por operación, no global. Lee la página de referencia de la operación que llamas, y envía solo los parámetros que declara.
| Lectura | Parámetros |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| [Listar productos de préstamo](/es/reference/products/lender/list-loan-products) y [listar productos de préstamo brasileños](/es/reference/products/lender/list-loan-products-br) | `limit` (predeterminado 25, tope 100) y `offset` (predeterminado 0, tope 10000) |
| [Eventos de auditoría](/es/reference/products/lender/list-loan-account-audit-events-huma) | `limit` solo (predeterminado 50, tope 100) |
Un valor fuera del rango se rechaza en lugar de ajustarse. Cada otra lectura declara sus propios parámetros, así que acótala con los identificadores y filtros de su página de referencia.
## Errores
***
Los errores de Huma y del handler global responden `application/problem+json` y siguen el [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457). El middleware de autorización y el de idempotencia pueden usar sus propios formatos de respuesta.
| Campo | Qué lleva |
| -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `status` | El código de estado HTTP. |
| `title` | El nombre del estado. |
| `detail` | Qué salió mal en esta ocurrencia. |
| `errors` | Detalles opcionales de validación de esquema. Cada entrada lleva un `location`, un `message` y el `value` que recibió Lender. |
Ramifica por estado y tipo de contenido. Para un `422`, usa `errors` cuando está presente. La validación del handler o del dominio puede devolver solo `detail` de nivel superior. Una falla del lado del servidor responde con un detalle genérico, así que una causa cruda nunca llega a un cliente.
## Las operaciones por trabajo
***
### Catalogar un producto
Ocho operaciones son dueñas del catálogo. [Crear un producto](/es/reference/products/lender/create-loan-product) y [anexar una versión](/es/reference/products/lender/create-loan-product-version) construyen los términos a los que se vincula una solicitud. La versión es inmutable. [Vincular un perfil contable](/es/reference/products/lender/create-loan-product-accounting-profile) mapea cada evento contable a cuentas contables generales, y Lender lo necesita en el desembolso. [Aplicar un cargo](/es/reference/products/lender/create-loan-product-charges) y [leer tasas flotantes](/es/reference/products/lender/list-loan-product-floating-rates) completan la superficie, junto con [listar](/es/reference/products/lender/list-loan-products), [obtener](/es/reference/products/lender/get-loan-product) y [activar](/es/reference/products/lender/activate-loan-product). Lee [Definir un producto de préstamo](/es/products/lender/define-a-loan-product).
### Originar
Seis operaciones llevan una solicitud desde enviada hasta desembolsada: [crear](/es/reference/products/lender/create-loan-application), luego una de [aprobar](/es/reference/products/lender/approve-loan-application), [rechazar](/es/reference/products/lender/reject-loan-application) o [retirar](/es/reference/products/lender/withdraw-loan-application), luego [desembolsar](/es/reference/products/lender/disburse-loan-application). [Previsualizar un cronograma](/es/reference/products/lender/preview-loan-schedule) calcula cuotas para una cotización y no persiste nada.
Las respuestas de creación y de decisión son las únicas lecturas de una solicitud, así que conserva el body que devuelve cada llamada. Lee [Cómo funciona la originación](/es/products/lender/how-origination-works) para la máquina de estados y el [Inicio rápido](/es/products/lender/lender-quick-start) para las seis llamadas de punta a punta.
### Administrar un préstamo vivo
Cinco lecturas describen la cuenta: [la cuenta](/es/reference/products/lender/get-active-loan-account), [su cronograma](/es/reference/products/lender/get-active-loan-schedule), [sus transacciones](/es/reference/products/lender/list-active-loan-transactions), [sus cargos](/es/reference/products/lender/list-active-loan-charges) y [su historial de auditoría](/es/reference/products/lender/list-loan-account-audit-events-huma).
Cinco escrituras mueven dinero o el cronograma: [previsualizar un pago](/es/reference/products/lender/preview-repayment) antes de [registrarlo](/es/reference/products/lender/record-repayment), [pagar por anticipado](/es/reference/products/lender/prepay-loan-account), [reprogramar](/es/reference/products/lender/reschedule-loan-account) y [revertir una transacción](/es/reference/products/lender/reverse-loan-account-transaction). Nada reescribe la historia. Una reversión asienta una transacción nueva que compensa la original. Lee [Administrar un préstamo](/es/products/lender/service-a-loan).
### Contabilizar y asentar
[Iniciar una ejecución de devengo](/es/reference/products/lender/create-accrual-run) reconoce intereses para un período de competencia. [Listar referencias de diario](/es/reference/products/lender/get-journal-reference) por id de correlación y [leer una](/es/reference/products/lender/get-journal-reference-by-id) para encontrar el registro contable que escribió una ejecución. Lee [Contabilidad y ejecuciones de devengo](/es/products/lender/accounting-and-accrual-runs).
### Descubrir jurisdicciones
Las dos lecturas públicas informan qué códigos de jurisdicción lleva este despliegue y qué decide cada perfil. Lee [Jurisdicciones](/es/products/lender/jurisdictions).
### Brasil
El paquete de Brasil agrega lecturas y escrituras reguladas bajo `/api/v1/br`: [divulgación de CET](/es/reference/products/lender/get-loan-account-cet-disclosure), [el descriptor de operación de crédito](/es/reference/products/lender/get-loan-account-credit-operation-descriptor), [la etapa de PDD](/es/reference/products/lender/get-loan-account-pdd-stage) y [sus transiciones](/es/reference/products/lender/apply-loan-account-pdd-stage-transition), [una cotización de pago anticipado](/es/reference/products/lender/create-prepayment-quote) con [su estado de liquidación](/es/reference/products/lender/get-payoff-statement), [vista previa de impuestos](/es/reference/products/lender/preview-tax) y [consentimiento de capitalización](/es/reference/products/lender/ingest-capitalization-clause-consent). El paquete también lleva sus propias rutas de producto, que se comportan como las genéricas bajo reglas brasileñas. Lee [Paquete regulatorio de Brasil](/es/products/lender/brazil-regulatory-pack).
El recorrido con descuento en nómina es una conversación de eventos con el riel de nómina, no un conjunto de llamadas REST. Lee [Consignado privado](/es/products/lender/consignado-privado).
### Las superficies más recientes
Estas familias entraron en la API después de que se escribieran los trabajos de arriba, y cada una tiene sus propias operaciones en la referencia.
* **Cede cuentas por cobrar a un fondo.** `/api/v1/assignment/...` registra fondos, arma y puntúa lotes de cuentas por cobrar contra la regla de elegibilidad de un fondo, los aprueba o descarta, produce el archivo de oferta y el término de endoso, ingiere el archivo de retorno del administrador, registra hechos observados externamente, registra el instrumento de crédito de una cuenta por cobrar en la registradora y trabaja la cola de excepciones.
* **Cobra un pago devuelto.** `/api/v1/returned-payment-receivables` lista y lee las deudas separadas del prestatario que un pago final revertido abre cuando el contrato que cerró ya no puede recibir el dinero de vuelta, y registra un cobro contra una de ellas.
* **Promueve una versión de producto.** `POST /api/v1/loan-products/{id}/promote` reapunta un producto activo a otra de sus versiones, de modo que las nuevas solicitudes se originan en ella mientras los contratos ya escritos se quedan en la versión en que nacieron; `/api/v1/br/loan-products/{id}/promote` es su alias de Brasil.
* **Lee y revisa versiones de producto.** `/api/v1/loan-product-versions` lista y lee las instantáneas de versión, declara una revisión del modelo de cargos en una de ellas y, bajo el paquete de Brasil, declara la clasificación normativa de una versión.
* **Modela los documentos.** `/api/v1/loan-products/{productId}/document-templates` y la superficie equivalente bajo un fondo de cesión redactan, leen y publican las versiones de plantilla desde las que se renderiza un documento generado.
* **Tabula las tasas flotantes.** `/api/v1/rate-tables` crea una tabla de tasa flotante y agrega los períodos de donde se lee la tasa de un producto flotante.
* **Emite un instrumento de crédito.** `/api/v1/loan-applications/{applicationId}/credit-instruments` emite el instrumento que evidencia una solicitud, lista los instrumentos emitidos y descarga uno.
* **Sigue una corrida de devengo.** `/api/v1/accrual-runs` ahora lista corridas, lee una y sus decisiones por ítem, y reenvía al ledger los reconocimientos que no confirmó, mediante `POST /api/v1/accrual-runs/{id}/retry`; `/api/v1/accounting-profiles` lista los perfiles configurados, y el par de sucesión sustituye el plan de cuentas de un producto y liquida el cambio en los saldos de cada contrato vivo.
* **Observa la cartera.** `/api/v1/dashboard/portfolio` y las dos lecturas de morosidad responden desde la instantánea diaria de cartera. El barrido diario de promoción de PDD construye esa instantánea para su fecha base antes de barrer, y viene habilitado, así que un despliegue por defecto tiene una. El job separado `core-daily-portfolio-snapshot` acciona el mismo productor en su propio horario para despliegues que quieran construirla de forma independiente del barrido.
* **Escalona las etapas de provisión.** `/api/v1/br/pdd-stage-ladders` publica una versión de escalera de etapas de PDD y lee la que está en vigor.
* **Trabaja el cobro extraordinario.** `/api/v1/br/consignado/collection-instructions` y el par de liquidación listan las instrucciones abiertas, ingieren el Arquivo de Baixa Extraordinária del agente de cobro y listan las líneas que rechazó; la superficie de operación bajo `/api/v1/internal/br/consignado/...` nombra el canal del agente, trabaja líneas e ítems de bandeja en cuarentena y da destino a devoluciones por descuento en exceso adeudadas a los trabajadores.
* **Inspecciona la identidad y el flujo.** `GET /api/v1/me` informa la sesión a la que resuelve el token, y `GET /api/v1/internal/streaming/discards` lista los registros de entrada puestos en cuarentena por los consumidores.
## Próximos pasos
***
Seis llamadas desde una base de datos vacía hasta un préstamo desembolsado.
Suscríbete al recorrido de crédito en lugar de hacer sondeo.
Cada operación, con las formas completas de solicitud y respuesta.
Los servicios, las migraciones y la configuración que necesita una primera llamada.