Inicio rápido

Siete llamadas desde una base de datos vacía hasta un préstamo desembolsado: un producto, una versión, un perfil contable, una activación, una solicitud, una aprobación y un desembolso.

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 registra el sujeto del token como el oficial asignado de la solicitud. Ninguna decisión lo comprueba: cualquier operador o admin que tenga el permiso de la ruta puede aprobar, rechazar, retirar o desembolsar una solicitud directa.

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

---

1. POST /api/v1/loan-products                          → productId
2. POST /api/v1/loan-products/{productId}/versions     → versionId
3. POST /api/v1/loan-products/{productId}/accounting-profiles
4. POST /api/v1/loan-products/{productId}/activate     → active
5. POST /api/v1/loan-applications                      → pending_approval
6. POST /api/v1/loan-applications/{id}/approve         → approved
7. 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",
  "fixedMonthlyRate": "0.01500000",
  "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.
• fixedMonthlyRate es la tasa mensual, como cadena decimal: "0.01500000" es 1.5% al mes.
• rateBand es obligatorio. Es la banda de precio que la versión autoriza, en puntos básicos anuales efectivos. Lender convierte una tasa mensual m en (1 + m)^12 - 1 antes de compararla con la banda. Una solicitud cuya tasa queda fuera de la banda se rechaza, y una tasa fija fuera de la banda de la propia versión también.
• 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 asigna cada evento contable a cuentas del ledger. La activación rechaza un producto sin perfil, así que vincúlalo ahora.

{
  "loanProductVersionId": "<versionId>",
  "accountingMode": "accrual",
  "postingRules": [
    {
      "eventType": "disbursement",
      "legs": [
        { "account": "principal", "role": "principal", "side": "debit", "nature": "debit", "perOperation": true },
        { "account": "1000-10-001", "role": "cash", "side": "credit", "nature": "debit" }
      ]
    },
    {
      "eventType": "repayment",
      "legs": [
        { "account": "1000-10-001", "role": "cash", "side": "debit", "nature": "debit" },
        { "account": "principal", "role": "principal", "side": "credit", "nature": "debit", "perOperation": true },
        { "account": "interest", "role": "interest", "side": "credit", "nature": "debit", "perOperation": true }
      ]
    },
    {
      "eventType": "prepayment",
      "legs": [
        { "account": "1000-10-001", "role": "cash", "side": "debit", "nature": "debit" },
        { "account": "4200-10-001", "component": "charge_rebate", "side": "debit", "nature": "debit", "optional": true },
        { "account": "4300-10-001", "component": "iof_refund", "side": "debit", "nature": "debit", "optional": true },
        { "account": "principal", "role": "principal", "side": "credit", "nature": "debit", "perOperation": true },
        { "account": "2400-10-001", "component": "iof_due", "side": "credit", "nature": "credit", "optional": true }
      ]
    },
    {
      "eventType": "accrual",
      "legs": [
        { "account": "interest", "role": "interest", "side": "debit", "nature": "debit", "perOperation": true },
        { "account": "4100-10-001", "role": "interest", "side": "credit", "nature": "credit" }
      ]
    },
    {
      "eventType": "accrual_withholding",
      "legs": [
        { "account": "interest", "role": "interest", "side": "debit", "nature": "debit", "perOperation": true },
        { "account": "2900-10-001", "role": "interest", "side": "credit", "nature": "credit" }
      ]
    },
    {
      "eventType": "renegotiation_gain",
      "legs": [
        { "account": "reneg_adj", "component": "renegotiation_adjustment", "side": "debit", "nature": "credit", "perOperation": true },
        { "account": "4400-10-001", "component": "renegotiation_gain", "side": "credit", "nature": "credit" }
      ]
    },
    {
      "eventType": "renegotiation_loss",
      "legs": [
        { "account": "5100-10-001", "component": "renegotiation_loss", "side": "debit", "nature": "debit" },
        { "account": "reneg_adj", "component": "renegotiation_adjustment", "side": "credit", "nature": "credit", "perOperation": true }
      ]
    },
    {
      "eventType": "collection_unapplied",
      "legs": [
        { "account": "1000-10-001", "role": "cash", "side": "debit", "nature": "debit" },
        { "account": "unapplied", "role": "unapplied_cash", "side": "credit", "nature": "credit", "perOperation": true }
      ]
    },
    {
      "eventType": "collection_reapply",
      "legs": [
        { "account": "unapplied", "role": "unapplied_cash", "side": "debit", "nature": "credit", "perOperation": true },
        { "account": "principal", "role": "principal", "side": "credit", "nature": "debit", "perOperation": true }
      ]
    },
    {
      "eventType": "collection_refund",
      "legs": [
        { "account": "unapplied", "role": "unapplied_cash", "side": "debit", "nature": "credit", "perOperation": true },
        { "account": "1000-10-001", "role": "cash", "side": "credit", "nature": "debit" }
      ]
    },
    {
      "eventType": "provision_constitution",
      "legs": [
        { "account": "8180-10-001", "component": "provision", "side": "debit", "nature": "debit" },
        { "account": "1890-10-001", "component": "provision", "side": "credit", "nature": "credit" }
      ]
    },
    {
      "eventType": "provision_reversal",
      "legs": [
        { "account": "1890-10-001", "component": "provision", "side": "debit", "nature": "credit" },
        { "account": "8180-10-001", "component": "provision", "side": "credit", "nature": "debit" }
      ]
    },
    {
      "eventType": "provision_incurred_constitution",
      "legs": [
        { "account": "8180-10-001", "component": "provision_incurred", "side": "debit", "nature": "debit" },
        { "account": "1891-10-001", "component": "provision_incurred", "side": "credit", "nature": "credit" }
      ]
    },
    {
      "eventType": "provision_incurred_reversal",
      "legs": [
        { "account": "1891-10-001", "component": "provision_incurred", "side": "debit", "nature": "credit" },
        { "account": "8180-10-001", "component": "provision_incurred", "side": "credit", "nature": "debit" }
      ]
    }
  ]
}

Envía una regla por evento contable. Catorce eventos necesitan regla: disbursement, repayment, prepayment, accrual, accrual_withholding, renegotiation_gain, renegotiation_loss, collection_unapplied, collection_reapply, collection_refund, provision_constitution, provision_reversal, provision_incurred_constitution y provision_incurred_reversal. El array acepta como máximo 40 reglas, y Lender rechaza un plan sin las catorce. Los demás tipos de evento son opcionales. La provisión adicional (provision_constitution) y la pérdida incurrida (provision_incurred_constitution) acreditan dos cuentas de provisión distintas, o Lender rechaza el plan con LENDER-0455.

Cada pierna declara exactamente uno entre role y component, un side y una nature. nature es la naturaleza propia de la cuenta, no el lado de la pierna: debit para un activo o un gasto, credit para un pasivo, un patrimonio o un ingreso. Midaz fija la dirección del saldo de la cuenta a partir de ella. Una pierna que contabiliza una posición del prestatario (principal, interest, unapplied_cash y similares) define perOperation: true. Su account pasa a ser un prefijo de hasta 17 letras, dígitos, _ o -, y Lender abre una cuenta por cuenta de préstamo bajo ese prefijo. Cualquier otro account es un alias de hasta 50 letras, dígitos, :, _ o -, así que un punto se rechaza (LENDER-0429). Una posición del prestatario contabilizada en una cuenta compartida se rechaza (LENDER-0408). Las piernas de ingreso y el crédito de accrual_withholding siguen compartidos. Ninguna cuenta aparece en los dos lados de la misma regla. Los siguientes eventos también tienen una forma fija de piernas:

Evento	Piernas
accrual	Exactamente un débito y un crédito.
accrual_withholding	Exactamente dos piernas interest: un débito en la cuenta que accrual debita y un crédito en una cuenta compartida que no es el ingreso de accrual.
renegotiation_gain	Exactamente dos: un débito del componente renegotiation_adjustment, por operación, y un crédito del componente renegotiation_gain.
renegotiation_loss	Exactamente dos: un débito del componente renegotiation_loss y un crédito del componente renegotiation_adjustment, por operación.
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 acepta unapplied_cash como ú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 rol. disbursement y repayment necesitan al menos un débito y un crédito cada uno, y repayment debe acreditar una pierna interest en la cuenta que accrual debita (LENDER-0440).

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>",
  "borrowerDocument": "111.444.777-35",
  "borrowerName": "Maria Souza",
  "requestedPrincipalAmount": "50000.00",
  "requestedInterestRate": "0.01500000",
  "requestedInstallments": 24,
  "expectedDisbursementDate": "<the day you disburse, RFC3339>"
}

• borrowerDocument es el CPF o el CNPJ del prestatario, con o sin máscara. Los dígitos verificadores deben ser válidos. Un CPF hace al prestatario pessoaFisica, un CNPJ lo hace pessoaJuridica, y la versión debe admitir ese tipo. borrowerName es obligatorio. Lender busca al prestatario como titular en el CRM de Midaz de la institución del producto y registra uno cuando no existe. El borrowerId de la respuesta es ese titular, y la solicitud guarda solo ese id.
• 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 efectivos: "0.01500000" al mes son cerca de 1956 bps efectivos 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.
• Una solicitud indica exactamente uno entre requestedPrincipalAmount, requestedNetAmount y requestedInstallmentAmount. No existe el campo assignedOfficerId: Lender define al oficial a partir del sujeto del token.
• firstDueDate y gracePeriodDays son opcionales. Omite ambos, y la solicitud registra la primera fecha de vencimiento que el generador de cronograma define para expectedDisbursementDate. Todo cronograma y la liberación dependen de esa fecha.

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"
}

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 tú proporcionas. Lender no lo genera. Identifica la cuenta de préstamo bajo la cual se administra este contrato, y es inmutable en las tramos posteriores de la misma solicitud. Omite disbursedAt y Lender usa el ahora de negocio del tenant. La primera liberación mantiene la primera fecha de vencimiento que registró la solicitud, así que envía expectedDisbursementDate en el paso 5 como el día en que desembolsas. Una versión sin ventana de primer vencimiento rechaza una liberación en cualquier otro día (LENDER-0951) y un firstDueDate distinto del registrado (LENDER-0950). Lender calcula el IOF y congela el CET de todo desembolso en efectivo a partir del régimen tributario de la versión. jurisdictionExtensions es opcional, y Lender lee de él solo el consentimiento de la cláusula de capitalización.

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, cuando los envías, no son anteriores a la creación de la solicitud, y disbursedAt no es 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.

El asiento del desembolso llega al ledger de Midaz cuando el despachador del outbox retransmite la intención. Eso ocurre 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.