Inicio rápido

Esta página te lleva desde una base de datos vacía hasta un préstamo desembolsado en siete 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 siete llamadas. Lender toma al oficial del sujeto del token, y solo ese oficial puede aprobar y desembolsar la solicitud.

Este recorrido registra un préstamo brasileño con el régimen tributario none, que no calcula IOF y mantiene simples los montos del paso 7. Lee el Paquete regulatorio de Brasil para un producto que retiene IOF. 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 siete 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-products/{productId}/activate     → active
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",
  "loanType": "personal",
  "jurisdictionCode": "BR"
}

loanType toma personal, commercial o card. jurisdictionCode es BR. Cualquier otro código devuelve 422. La respuesta lleva el nuevo id. El producto está en draft.

2. Crear una versión

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

{
  "jurisdictionCode": "BR",
  "changeReason": "initial version",
  "currency": "BRL",
  "rateMode": "fixed",
  "fixedAnnualRateBps": 1800,
  "rateBand": { "minAnnualRateBps": 1200, "maxAnnualRateBps": 4800 },
  "admittedBorrowerKinds": ["pessoaFisica"],
  "jurisdictionExtensions": {
    "taxRegime": "none",
    "normPortfolioClass": "C5"
  }
}

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.
rateBand es obligatorio. Es la banda de precio que la versión autoriza, en puntos básicos anuales. Una solicitud cuya tasa queda fuera de ella se rechaza.
admittedBorrowerKinds nombra a quién le presta la versión. Una lista vacía u omitida no admite a ningún prestatario.
normPortfolioClass es la carteira. Una versión brasileña sin carteira no se puede activar en el paso 4.
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. La activación rechaza un producto sin perfil, 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 una regla por evento contable. Siete eventos necesitan una regla: disbursement, repayment, prepayment, accrual, collection_unapplied, collection_reapply y collection_refund. Los otros tipos de evento son opcionales. Menos de siete reglas se rechaza antes de que corra el handler. Un producto bajo las reglas brasileñas de pérdida crediticia también necesita provision_constitution y provision_reversal, o su provisión medida no se asienta en el ledger. La activación no las verifica. 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 régimen tributario none no calcula ninguna, así que la regla de dos patas es la que balancea en este recorrido. Lee Definir un producto de préstamo para la superficie de producto más amplia.

4. Activar el producto

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

{ "versionId": "<versionId>" }

La activación fija la versión en la que se originan las nuevas solicitudes. Rechaza un producto que no tiene perfil contable, y una versión brasileña que no tiene carteira. Una solicitud sobre un producto que no está activo se rechaza.

5. Crear la solicitud

POST /api/v1/loan-applications Envía el header X-Idempotency. Lender lo requiere en esta llamada y en los pasos 6 y 7. Un reintento con el mismo valor repite la primera respuesta y no escribe nada nuevo.

{
  "loanProductVersionId": "<versionId>",
  "borrowerId": "3f2b8c1e-7a4d-4e9b-9c2a-5d6e7f8a9b0c",
  "borrowerKind": "pessoaFisica",
  "requestedPrincipalAmount": "50000.00",
  "requestedInterestRate": "0.01500000",
  "requestedInstallments": 24,
  "expectedDisbursementDate": "2026-08-01T12:00:00Z"
}

borrowerId es un UUID. borrowerKind toma pessoaFisica o pessoaJuridica, y la versión debe admitirlo.
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 y la compara con la banda de tasa de la versión en puntos básicos anuales: "0.01500000" al mes son 1800 bps al año, dentro de la banda del paso 2.
requestedInstallments está entre 1 y 600.
previewScheduleSnapshotId es opcional. Para citar la cotización que le mostraste al prestatario, envía el scheduleOfferSnapshotId que devolvió POST /api/v1/loan-applications/preview-schedule.
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.

6. Aprobar

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

{
  "approvedAmount": "48000.00",
  "decisionAt": "<current time, RFC3339>",
  "note": "within policy"
}

approvedAmount se vuelve el techo de todo lo que desembolsas. La solicitud pasa a approved y lleva el registro de decisión.

7. Desembolsar

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

{
  "loanAccountId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "grossRequestedAmount": "48000.00",
  "netDeliveredAmount": "48000.00",
  "disbursedAt": "<current time, RFC3339>",
  "jurisdictionExtensions": {
    "disbursedAt": "<the same instant>",
    "loanProductVersionId": "<versionId>",
    "requestId": "<the X-Idempotency value of this call>"
  }
}

Con el régimen tributario none, netDeliveredAmount debe ser igual a grossRequestedAmount. Lender acepta un desembolso solo cuando el neto es igual al bruto menos las retenciones, menos la comisión de originación retenida. Este régimen no calcula retenciones, y este recorrido no retiene comisión.

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. jurisdictionExtensions lleva lo que lee el pipeline brasileño: el instante del desembolso, la versión del paso 2 y el valor de X-Idempotency de esta llamada como requestId. El desembolso falla cuando falta uno. Lender también verifica que:

netDeliveredAmount no exceda grossRequestedAmount.
grossRequestedAmount sea igual a approvedAmount, porque este es el único desembolso de la solicitud. Una liberación en tramos declara trancheNumber, y su total acumulado no excede approvedAmount.
decisionAt y disbursedAt no sean anteriores a la creación de la solicitud, y 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 5.

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. Si configuraste el relay del ledger de Midaz, el asiento de desembolso llega al ledger cuando el despachador del outbox transmite la intención. Eso pasa poco después de la llamada, no dentro de ella. En caso contrario, la intención permanece en el outbox.

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 siete llamadas

1. Crear el producto

2. Crear una versión

3. Vincular un perfil contable

4. Activar el producto

5. Crear la solicitud

6. Aprobar

7. Desembolsar

Confirmar que el préstamo existe

Próximos pasos

Administrar un préstamo

Cómo funciona el devengo

​Las siete llamadas

​1. Crear el producto

​2. Crear una versión

​3. Vincular un perfil contable

​4. Activar el producto

​5. Crear la solicitud

​6. Aprobar

​7. Desembolsar

​Confirmar que el préstamo existe

​Próximos pasos

Administrar un préstamo

Cómo funciona el devengo

Las siete llamadas

1. Crear el producto

2. Crear una versión

3. Vincular un perfil contable

4. Activar el producto

5. Crear la solicitud

6. Aprobar

7. Desembolsar

Confirmar que el préstamo existe

Próximos pasos