Inicio rápido

Esta página te lleva de una base de datos vacía a un préstamo desembolsado en seis llamadas. Cada llamada envía application/json. Envía cada campo de dinero y de tasa como cadena decimal, nunca como número JSON. Completa primero los Prerrequisitos. Envía el mismo token bearer en las seis llamadas. Lender toma al oficial desde el subject del token. Bajo el perfil genérico, solo ese oficial puede aprobar y desembolsar la solicitud.

Usa la jurisdicción XX para este recorrido. XX es el perfil genérico de Lender, y no calcula retenciones — lo que mantiene simples los montos del paso 6. Un préstamo regulado brasileño lleva divulgación de CET y consentimiento de capitalización. Lee el Paquete regulatorio de Brasil para esa ruta. Un contrato con descuento en nómina pertenece al contexto acotado de consignado privado. Lee Consignado privado para su vocabulario y sus topics de ciclo de vida.

Las seis llamadas

POST /api/v1/loan-products                          → productId
POST /api/v1/loan-products/{productId}/versions     → versionId
POST /api/v1/loan-products/{productId}/accounting-profiles
POST /api/v1/loan-applications                      → pending_approval
POST /api/v1/loan-applications/{id}/approve         → approved
POST /api/v1/loan-applications/{id}/disburse        → disbursed

1. Crea el producto

POST /api/v1/loan-products

{
  "name": "Préstamo personal — genérico",
  "loanType": "personal",
  "jurisdictionCode": "XX"
}

loanType acepta personal, commercial o card. jurisdictionCode acepta un código que lleve el registro: XX o BR. Cualquier otro código devuelve 422. La respuesta lleva el nuevo id. El producto queda en draft, que es todo lo que este recorrido necesita: una solicitud se vincula a una versión, así que no activas el producto para originar.

2. Crea una versión

POST /api/v1/loan-products/{productId}/versions

{
  "jurisdictionCode": "XX",
  "changeReason": "versión inicial",
  "currency": "USD",
  "rateMode": "fixed",
  "fixedAnnualRateBps": 1800
}

La versión es la instantánea inmutable de términos a la que se vincula una solicitud.

currency no tiene valor por defecto. Envía un código ISO-4217 válido en mayúsculas. La versión es la fuente de verdad de la moneda desde aquí hasta el ledger.
Una versión fija no lleva vínculo flotante. Con rateMode: fixed, omite floatingRateTableId, floatingSpreadBps y requiresFloatingRate. Lender rechaza una versión fija que lleve cualquiera de ellos.
jurisdictionCode es obligatorio, y debe coincidir con el del producto. Una versión no puede mover un producto a otra jurisdicción.

La respuesta lleva el versionId.

3. Vincula un perfil contable

POST /api/v1/loan-products/{productId}/accounting-profiles El perfil mapea cada evento contable a cuentas del libro mayor. Lender lo necesita en el desembolso, así que vincúlalo ahora.

{
  "loanProductVersionId": "<versionId>",
  "accountingMode": "accrual",
  "postingRules": [
    {
      "eventType": "disbursement",
      "legs": [
        { "account": "1100.10.001", "role": "principal", "side": "debit" },
        { "account": "1000.10.001", "role": "cash", "side": "credit" }
      ]
    },
    {
      "eventType": "repayment",
      "legs": [
        { "account": "1000.10.001", "role": "cash", "side": "debit" },
        { "account": "1100.10.001", "role": "principal", "side": "credit" }
      ]
    },
    {
      "eventType": "prepayment",
      "legs": [
        { "account": "1000.10.001", "role": "cash", "side": "debit" },
        { "account": "4200.10.001", "component": "charge_rebate", "side": "debit", "optional": true },
        { "account": "4300.10.001", "component": "iof_refund", "side": "debit", "optional": true },
        { "account": "1100.10.001", "role": "principal", "side": "credit" },
        { "account": "2400.10.001", "component": "iof_due", "side": "credit", "optional": true }
      ]
    },
    {
      "eventType": "accrual",
      "legs": [
        { "account": "1200.10.001", "role": "interest", "side": "debit" },
        { "account": "4100.10.001", "role": "interest", "side": "credit" }
      ]
    },
    {
      "eventType": "collection_unapplied",
      "legs": [
        { "account": "1000.10.001", "role": "cash", "side": "debit" },
        { "account": "2100.10.001", "role": "unapplied_cash", "side": "credit" }
      ]
    },
    {
      "eventType": "collection_reapply",
      "legs": [
        { "account": "2100.10.001", "role": "unapplied_cash", "side": "debit" },
        { "account": "1100.10.001", "role": "principal", "side": "credit" }
      ]
    },
    {
      "eventType": "collection_refund",
      "legs": [
        { "account": "2100.10.001", "role": "unapplied_cash", "side": "debit" },
        { "account": "1000.10.001", "role": "cash", "side": "credit" }
      ]
    }
  ]
}

Envía siete u ocho reglas, una por evento contable. Siete eventos necesitan regla: disbursement, repayment, prepayment, accrual, collection_unapplied, collection_reapply y collection_refund. accrual_tax es la octava opcional. Menos de siete reglas se rechaza antes de que corra el handler. Cada pierna declara exactamente uno de role o component, y ninguna cuenta aparece en los dos lados de una misma regla. Cuatro eventos además llevan una forma de piernas fija:

Evento	Piernas
`accrual`	Exactamente un débito y un crédito.
`prepayment`	Exactamente cinco, en este orden: débito `cash`, débito `charge_rebate` opcional, débito `iof_refund` opcional, crédito `principal`, crédito `iof_due` opcional.
`collection_unapplied`	Exactamente dos: débito `cash`, crédito `unapplied_cash`.
`collection_refund`	Exactamente dos: débito `unapplied_cash`, crédito `cash`.

collection_reapply toma unapplied_cash como su único débito. Cada crédito que lleva también debe aparecer como crédito en repayment o prepayment, con la misma cuenta y el mismo role. disbursement y repayment necesitan cada uno al menos un débito y un crédito. Mantén la regla disbursement en dos piernas, como arriba. Lender llena la pierna cash con el monto neto y cada otra pierna estructural con el monto bruto. Una pierna component toma una retención calculada, y el perfil genérico no calcula ninguna, así que la regla de dos piernas es la que cuadra bajo XX. En modo multi-tenant el perfil también necesita midazOrganizationId y midazLedgerId. Lee Definir un producto de préstamo para la superficie de producto más amplia.

4. Crea la solicitud

POST /api/v1/loan-applications

{
  "loanProductVersionId": "<versionId>",
  "borrowerId": "borrower-0001",
  "requestedPrincipalAmount": "50000.00",
  "requestedInterestRate": "0.01500000",
  "requestedInstallments": 24,
  "expectedDisbursementDate": "2026-08-01T12:00:00Z",
  "previewScheduleSnapshotId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}

requestedInterestRate es la tasa mensual como cadena decimal en escala 8. Debe ser mayor que 0 y no mayor que 1. Lender arma el cronograma con esta tasa: "0.01500000" al mes son 1800 bps al año.
requestedInstallments va de 1 a 600.
previewScheduleSnapshotId es un UUID que tú generas para identificar la cotización que le mostraste al deudor. Lender lo guarda en la solicitud. Calcula el cronograma que muestras con POST /api/v1/loan-applications/preview-schedule. Esa llamada no persiste nada ni devuelve un identificador. Genera el identificador de tu lado y guárdalo con tu propio registro de cotización.
No hay campo assignedOfficerId. Lender lo fija desde el subject del token.

La solicitud vuelve en pending_approval, y lleva el código de jurisdicción y la versión de perfil que Lender resolvió desde la versión del producto.

5. Aprueba

POST /api/v1/loan-applications/{id}/approve

{
  "approvedAmount": "48000.00",
  "decisionAt": "2026-08-01T12:00:00Z",
  "note": "dentro de política"
}

approvedAmount se convierte en el techo de todo lo que desembolses. Bajo XX, solo el oficial que creó la solicitud puede aprobarla. La solicitud pasa a approved y lleva el registro de decisión.

6. Desembolsa

POST /api/v1/loan-applications/{id}/disburse Envía el header X-Idempotency. Lender lo exige. Un reintento con el mismo valor repite la primera respuesta, y no registra un segundo desembolso.

{
  "loanAccountId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "grossRequestedAmount": "48000.00",
  "netDeliveredAmount": "48000.00",
  "disbursedAt": "2026-08-01T13:00:00Z"
}

Bajo XX, netDeliveredAmount debe ser igual a grossRequestedAmount. El posting del desembolso cuadra como neto igual a bruto menos retenciones, y el perfil genérico no calcula retenciones. Cualquier neto menor deja el posting descuadrado y Lender rechaza el desembolso.

loanAccountId es un UUID que tú envías — Lender no lo genera. Identifica la cuenta de préstamo bajo la que se hace servicing de este contrato, y es inmutable en los tramos posteriores de la misma solicitud. Lender también verifica que:

netDeliveredAmount no exceda grossRequestedAmount.
grossRequestedAmount, y el total acumulado entre tramos, no exceda approvedAmount.
disbursedAt no sea anterior a la decisión de aprobación.
La jurisdicción y la versión de perfil sigan coincidiendo con el par que Lender resolvió en el paso 4.

originationFeeAmount es opcional. Lleva metadatos de costo que lee el devengo. Lender no lo trata como retención, así que no cambia la relación entre neto y bruto.

Confirma que el préstamo existe

La respuesta del desembolso lleva la solicitud en disbursed con su evento de desembolso. Después lee la cuenta de préstamo:

Llamada	Qué devuelve
`GET /api/v1/loan-accounts/{loanAccountId}`	La cuenta de préstamo activa: estado, saldo de principal, saldo abierto y fecha de desembolso.
`GET /api/v1/loan-accounts/{loanAccountId}/schedule`	El cronograma de originación — una entrada por cuota, todas impagas.

La respuesta también lleva profileVersion — la versión del perfil de jurisdicción, no una versión de producto. No lleva moneda. El préstamo usa la currency que fijaste en la versión del producto de préstamo en el paso 1. Guarda ese valor con tu propio registro de producto. Si configuraste Midaz, el posting del desembolso llega al ledger cuando el despachador del outbox relaya la intención. Eso pasa poco después de la llamada, no dentro de ella.

Próximos pasos

Servicing de un préstamo

Registra pagos, prepaga, reprograma y corrige una cuenta de préstamo viva.

Cómo funciona el devengo

El reconocimiento de interés corre en su propio calendario. Arranca una ejecución de devengo, o activa el heartbeat.

Resumen

Primeros pasos

Conceptos

Guías

Integración

Operaciones

Inicio rápido

Las seis llamadas

1. Crea el producto

2. Crea una versión

3. Vincula un perfil contable

4. Crea la solicitud

5. Aprueba

6. Desembolsa

Confirma que el préstamo existe

Próximos pasos

Servicing de un préstamo

Cómo funciona el devengo

​Las seis llamadas

​1. Crea el producto

​2. Crea una versión

​3. Vincula un perfil contable

​4. Crea la solicitud

​5. Aprueba

​6. Desembolsa

​Confirma que el préstamo existe

​Próximos pasos

Servicing de un préstamo

Cómo funciona el devengo

Las seis llamadas

1. Crea el producto

2. Crea una versión

3. Vincula un perfil contable

4. Crea la solicitud

5. Aprueba

6. Desembolsa

Confirma que el préstamo existe

Próximos pasos