/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:
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
Las escrituras de dinero y de cronograma aceptan un header de solicitud
X-Idempotency.
Envía tu propia clave. Con un almacén de idempotencia accesible, las cinco operaciones que requieren
X-Idempotency comparten un comportamiento:
- Un reintento de una llamada completada repite la primera respuesta y le estampa
X-Idempotency-Replayed: true. Nada se registra por segunda vez. - Un reintento mientras la primera llamada sigue en vuelo responde
409. - La clave tiene alcance por tenant y expira después de la ventana que define
IDEMPOTENCY_RETRY_WINDOW_SEC, que de forma predeterminada es 300 segundos.
X-Request-ID primero y recurren a X-Idempotency cuando no está. Envía uno de los dos: una llamada que no lleva ninguno responde 422.
Lender guarda el id de 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 de respuesta normal, sin header de repetición. El mismo id de solicitud con hechos distintos responde 409 en lugar de repetir, así un id nunca puede registrar dos montos distintos. Ese registro no expira.
Los hechos que compara Lender 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.
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.