Inicio rápido

Esta página te lleva desde una base de datos vacía hasta un préstamo desembolsado en seis llamadas. Cada llamada envía application/json. Envía cada campo de dinero y de tasa como una cadena decimal, nunca como un número JSON. Completa primero los Requisitos previos. Envía el mismo Bearer token en las seis llamadas. Lender toma al oficial del sujeto 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 brasileño regulado lleva divulgación de CET y consentimiento de capitalización. Lee el Paquete regulatorio de Brasil para ese camino. Un contrato con descuento en nómina pertenece al contexto delimitado de consignado privado. Lee Consignado privado para su vocabulario y sus temas 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. Crear el producto

POST /api/v1/loan-products

{
  "name": "Personal loan — generic",
  "loanType": "personal",
  "jurisdictionCode": "XX"
}

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

2. Crear una versión

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

{
  "jurisdictionCode": "XX",
  "changeReason": "initial version",
  "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 predeterminado. Aporta 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 alguno 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. Vincular un perfil contable

POST /api/v1/loan-products/{productId}/accounting-profiles El perfil mapea cada evento contable a cuentas contables generales. 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 una 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 pata declara exactamente uno de role o component, y ninguna cuenta aparece en ambos lados de la misma regla. Cuatro eventos también llevan una forma de pata fija:

Evento	Patas
`accrual`	Exactamente un débito y un crédito.
`prepayment`	Exactamente cinco, en este orden: débito `cash`, débito opcional `charge_rebate`, débito opcional `iof_refund`, crédito `principal`, crédito opcional `iof_due`.
`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 debe aparecer también como crédito en repayment o prepayment, con la misma cuenta y el mismo rol. disbursement y repayment necesitan cada uno al menos un débito y un crédito. Mantén la regla disbursement en dos patas, como arriba. Lender llena la pata cash con el monto neto y cada otra pata estructural con el monto bruto. Una pata component toma una retención calculada, y el perfil genérico no calcula ninguna, así que la regla de dos patas es la que balancea 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. Crear 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 a escala 8. Debe ser mayor que 0 y no mayor que 1. Lender construye el cronograma a partir de esta tasa: "0.01500000" al mes es 1800 bps al año.
requestedInstallments está entre 1 y 600.
previewScheduleSnapshotId es un UUID que generas tú para identificar la cotización que le mostraste al prestatario. Lender lo registra en la solicitud. Calcula el cronograma que muestras con POST /api/v1/loan-applications/preview-schedule. Esa llamada no persiste nada y no devuelve ningún identificador. Acuña el identificador de tu lado y consérvalo con tu propio registro de cotización.
No hay campo assignedOfficerId. Lender lo define desde el sujeto del token.

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

5. Aprobar

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

{
  "approvedAmount": "48000.00",
  "decisionAt": "2026-08-01T12:00:00Z",
  "note": "within policy"
}

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

6. Desembolsar

POST /api/v1/loan-applications/{id}/disburse Envía el header X-Idempotency. Lender lo requiere. 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 asiento de desembolso balancea porque el neto es igual al bruto menos las retenciones, y el perfil genérico no calcula retenciones. Cualquier neto menor deja el asiento sin balancear y Lender rechaza el desembolso.

loanAccountId es un UUID que aportas tú. Lender no lo acuña. Identifica la cuenta de préstamo bajo la que se administra este contrato, y es inmutable a lo largo de tramos posteriores de la misma solicitud. Lender también verifica que:

netDeliveredAmount no exceda grossRequestedAmount.
grossRequestedAmount, y el total acumulado de todos los tramos, no exceda approvedAmount.
disbursedAt no sea anterior a la decisión de aprobación.
La jurisdicción y la versión de perfil todavía coincidan 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 una retención, así que no cambia la relación entre neto y bruto.

Confirmar que el préstamo existe

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

Llamada	Qué devuelve
`GET /api/v1/loan-accounts/{loanAccountId}`	La cuenta de préstamo activa: estado, saldo de capital, 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 el currency que definiste en la versión de producto de préstamo en el paso 2. Conserva ese valor con tu propio registro de producto. Si configuraste Midaz, el asiento de desembolso llega al ledger una vez que el despachador del outbox transmite la intención. Eso pasa poco después de la llamada, no dentro de ella.

Próximos pasos

Administrar un préstamo

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

Cómo funciona el devengo

El reconocimiento de intereses corre con su propia programación. Inicia una ejecución de devengo, o habilita el heartbeat.

Resumen

Primeros pasos

Conceptos

Guías

Integración

Operaciones

Inicio rápido

Las seis llamadas

1. Crear el producto

2. Crear una versión

3. Vincular un perfil contable

4. Crear la solicitud

5. Aprobar

6. Desembolsar

Confirmar que el préstamo existe

Próximos pasos

Administrar un préstamo

Cómo funciona el devengo

​Las seis llamadas

​1. Crear el producto

​2. Crear una versión

​3. Vincular un perfil contable

​4. Crear la solicitud

​5. Aprobar

​6. Desembolsar

​Confirmar que el préstamo existe

​Próximos pasos

Administrar un préstamo

Cómo funciona el devengo

Las seis llamadas

1. Crear el producto

2. Crear una versión

3. Vincular un perfil contable

4. Crear la solicitud

5. Aprobar

6. Desembolsar

Confirmar que el préstamo existe

Próximos pasos