Skip to main content
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, 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:
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 y obtener una jurisdicción. 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: 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 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. 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. 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:

​
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. 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. El middleware de autorización y el de idempotencia pueden usar sus propios formatos de respuesta. 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 y anexar una versión construyen los términos a los que se vincula una solicitud. La versión es inmutable. Vincular un perfil contable mapea cada evento contable a cuentas contables generales, y Lender lo necesita en el desembolso. Aplicar un cargo y leer tasas flotantes completan la superficie, junto con listar, obtener y activar. Lee Definir un producto de préstamo.

​
Originar

Seis operaciones llevan una solicitud desde enviada hasta desembolsada: crear, luego una de aprobar, rechazar o retirar, luego desembolsar. Previsualizar un cronograma 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 para la máquina de estados y el Inicio rápido para las seis llamadas de punta a punta.

​
Administrar un préstamo vivo

Cinco lecturas describen la cuenta: la cuenta, su cronograma, sus transacciones, sus cargos y su historial de auditoría. Cinco escrituras mueven dinero o el cronograma: previsualizar un pago antes de registrarlo, pagar por anticipado, reprogramar y revertir una transacción. Nada reescribe la historia. Una reversión asienta una transacción nueva que compensa la original. Lee Administrar un préstamo.

​
Contabilizar y asentar

Iniciar una ejecución de devengo reconoce intereses para un período de competencia. Listar referencias de diario por id de correlación y leer una para encontrar el registro contable que escribió una ejecución. Lee Contabilidad y ejecuciones de devengo.

​
Descubrir jurisdicciones

Las dos lecturas públicas informan qué códigos de jurisdicción lleva este despliegue y qué decide cada perfil. Lee Jurisdicciones.

​
Brasil

El paquete de Brasil agrega lecturas y escrituras reguladas bajo /api/v1/br: divulgación de CET, el descriptor de operación de crédito, la etapa de PDD y sus transiciones, una cotización de pago anticipado con su estado de liquidación, vista previa de impuestos y consentimiento de capitalización. 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. 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.

​
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

Inicio rápido

Seis llamadas desde una base de datos vacía hasta un préstamo desembolsado.

Eventos

Suscríbete al recorrido de crédito en lugar de hacer sondeo.

Referencia de API

Cada operación, con las formas completas de solicitud y respuesta.

Requisitos previos

Los servicios, las migraciones y la configuración que necesita una primera llamada.