Saltar al contenido principal
La originación es el recorrido desde “un prestatario quiere crédito” hasta “existe una cuenta de préstamo y el desembolso quedó registrado”. Lender lo modela como un ciclo de vida explícito de la solicitud. El ciclo de vida guarda un registro de cada decisión y hace que cada desembolso sea rastreable.

El ciclo de vida de la solicitud

Una solicitud pasa por estados con nombre. Cada transición es una operación distinta, y cada una guarda un registro de decisión o de desembolso:

Pasos

1

Previsualizar el cronograma (opcional)

POST /api/v1/loan-applications/preview-schedule calcula el cronograma de amortización para términos propuestos sin originar nada. Recibe monthlyInterestRate, la tasa mensual como fracción decimal en un string, la misma unidad de requestedInterestRate. Cuando registra la cotización como oferta, devuelve el scheduleOfferSnapshotId de la oferta, que la solicitud puede citar. Úsalo para mostrar cuotas y divulgaciones antes de que alguien se comprometa.
2

Enviar la solicitud

POST /api/v1/loan-applications crea la solicitud contra la versión actual del producto. Lleva el CPF o el CNPJ y el nombre del prestatario, no un id de prestatario. El documento define el tipo de prestatario, y Lender busca o registra al prestatario como titular en el CRM de Midaz. La tasa solicitada debe quedar dentro de la banda de tasa de la versión: consulta Precifica desde tu back office. Indica exactamente uno entre el principal, el neto que recibe el prestatario o la cuota que cabe, y opcionalmente la primera fecha de vencimiento. La solicitud también puede pedir otro cronograma y llevar tu número de contrato: consulta Cronograma y número del contrato.
3

Decidir

Resuelve la solicitud con exactamente una de las siguientes:
  • POST /api/v1/loan-applications/{id}/approve: acéptala, con un registro de decisión.
  • POST /api/v1/loan-applications/{id}/reject: recházala, con un registro de decisión.
  • POST /api/v1/loan-applications/{id}/withdraw: retírala mientras está pendiente de aprobación o, después de la aprobación, antes del desembolso.
4

Emite la CCB (opcional)

La versión del producto define quién emite la CCB: Lender la genera, o la genera tu institución. En ambos casos, registras la CCB firmada en la solicitud. Una versión puede retener la primera liberación de un contrato directo hasta que la registres. Consulta Emite la CCB.
5

Desembolsar

POST /api/v1/loan-applications/{id}/disburse registra los fondos entregados. Lender no envía el pago: tu institución paga al prestatario por su propio canal, y esta llamada registra esa liberación y la contabiliza en el ledger. Consulta Registra una liberación que tu institución hizo. Toma la clave X-Idempotency que toma toda escritura de esta página. Por eso, un reintento con la misma clave repite la primera respuesta y no registra un segundo desembolso.Una sola transacción de base de datos confirma el evento de desembolso, el cronograma de originación y una intención de asiento balanceada. Cuando la llamada retorna, el préstamo es una cuenta de préstamo activa que administras de aquí en adelante.El asiento en el ledger no está en esa transacción. Un despachador del outbox retransmite la intención a Midaz poco después de la respuesta, mediante el perfil contable del producto. Consulta la ruta de asientos.

Precifica desde tu back office

Lender no guarda una tabla de tasa ni de gracia por rango de cuotas. Tu back office mantiene esa tabla, elige una tasa y un período de gracia para cada solicitud y los envía. La versión del producto declara una banda de tasa y, de forma opcional, una ventana para la primera fecha de vencimiento. Lender verifica cada solicitud contra ambas. Una solicitud incluye:
  • requestedInterestRate: la tasa mensual como fracción decimal en un string, con escala 8.
  • firstDueDate o gracePeriodDays (el período de gracia en días corridos), nunca los dos.
Al crear la solicitud, Lender convierte la tasa mensual m en puntos base anuales efectivos, (1 + m)^12 - 1, y la acepta cuando el resultado cae dentro de la banda de la versión. Una tasa de 1.5% al mes da cerca de 1956 bps. Una tasa exactamente en el piso o en el techo se acepta. Fuera de la banda, Lender rechaza con LENDER-0215, y detail imprime el valor anual que comparó y la banda. La primera fecha de vencimiento que eliges, o la que produce el período de gracia, debe caer dentro de la ventana de la versión. Una versión sin ventana solo acepta la fecha que marca el generador de cronograma. Cuando la versión declara límites de principal, de plazo o de número de cuotas, Lender rechaza una solicitud fuera de ellos con LENDER-0250, LENDER-0251 o LENDER-0252.

Cronograma y número del contrato

Una solicitud puede pedir un cronograma distinto del predeterminado y llevar tu propio número para el contrato:
  • amortizationSystem: price (el predeterminado), sac o american.
  • paymentPeriodicity: monthly (el predeterminado), fortnightly o weekly.
  • paymentRules: filas que pagas por regla, en lugar de la cuota del sistema, como una gracia (interestOnly) o una cuota balloon (fixedAmount). Una solicitud con reglas acepta price o sac, monthly y un principal (requestedPrincipalAmount). La última fila no puede ser interestOnly.
  • periods: una solicitud de flujo libre da un fin de devengo para cada cuota, en orden estrictamente creciente. La versión debe admitir freeFlow en paymentRuleKinds (LENDER-0260). La solicitud no puede enviar también firstDueDate, gracePeriodDays, un monto de cuota ni un monto neto, y el total de cada cuota debe superar los intereses de su período: cada infracción responde LENDER-0263. La ventana de la versión juzga el primer fin, llevado a un día hábil (LENDER-0235). La previsualización de cronograma y la previsualización de impuestos BR también aceptan periods, y las filas del cronograma muestran period.
  • clientContractNumber: tu propio número para el contrato, de 1 a 40 caracteres. Lo escribes una vez, al crear. Es único entre los contratos vivos de tu institución, que son las solicitudes pendientes de aprobación, aprobadas o desembolsadas. Una solicitud rechazada o retirada libera el número, y la sustituta que genera una renegociación sustancial lo conserva. GET /api/v1/loan-applications filtra por él.
La versión del producto debe admitir cada sistema, periodicidad y tipo de regla. La vista previa del cronograma y la vista previa de impuestos aceptan los mismos tres campos de cronograma.

Registra una liberación que tu institución hizo

Lender no envía el pago. Tu institución paga al prestatario por su propio canal, y POST /api/v1/loan-applications/{id}/disburse registra esa liberación y la contabiliza en el ledger. Como el registro llega después del pago, el orden de los pasos importa: la solicitud y su aprobación deben existir antes de que salga el dinero.
1

Crea la solicitud antes de pagar

Lender fecha la solicitud en el momento de la llamada, y no puedes fecharla en el pasado. Un pago hecho antes de que exista la solicitud no se puede registrar con su fecha real. Envía expectedDisbursementDate con el día en que tu institución va a pagar, y paga ese día. Un día posterior al día de São Paulo tres meses calendario por delante de hoy responde LENDER-0212. Un día pasado se acepta.
2

Aprueba la solicitud

Si tu back office aprobó la solicitud antes, envía ese momento como decisionAt. No puede ser anterior a la creación de la solicitud ni posterior a hoy en São Paulo. disbursedAt no puede quedar antes de la aprobación.
3

Cotiza el neto y paga exactamente ese valor

POST /api/v1/br/tax/preview con los términos de la propia solicitud:
  • grossAmount: el monto aprobado.
  • disbursementDate: el momento del pago.
  • finalDueDate: el vencimiento de la última cuota de la solicitud.
  • requestedInstallments y requestedInterestRate, como en la solicitud.
  • amortizationSystem, paymentPeriodicity y paymentRules, como en la solicitud. Sin ellos, la cotización valora price, monthly y ninguna regla.
  • firstDueDate: la fecha que registró la solicitud.
  • borrowerKind, como en la solicitud, y taxRegime cuando la solicitud declaró uno. Una pessoaJuridica en una versión que admite dos regímenes debe declarar uno, o Lender rechaza con LENDER-0962.
  • loanProductVersionId, y jurisdictionCode con el valor BR.
Deja fuera netDeliveredAmount, para que la cotización calcule el neto. Sin las cuotas y la tasa, la cotización valora una sola ventana, del día del pago al vencimiento final. Eso sirve para un bullet y falla para un contrato amortizado, y Lender entonces rechaza el neto con LENDER-0208. El mismo rechazo sigue a una cotización sin los campos de cronograma de una solicitud sac, american, quincenal, semanal o pagada por regla. La cotización valora el día de disbursementDate: si el pago cambia de día, cotiza de nuevo antes de que salga. Paga al prestatario exactamente el neto cotizado.
4

Registra el consentimiento de capitalización, cuando la versión lo exija

En una versión que exige la cláusula de capitalización, registra el consentimiento del prestatario con POST /api/v1/br/loan-applications/{id}/capitalization-consents antes de llamar a /disburse. acceptedAt puede ser como máximo el momento del pago. Consulta Consentimiento de capitalización.
5

Registra la CCB firmada, cuando la versión lo exija

En una versión con terms.releaseRequiresSignedInstrument activado, la primera liberación de un contrato directo espera la CCB firmada. Regístrala con POST /api/v1/loan-applications/{applicationId}/signed-credit-instrument antes de llamar a /disburse. Cuando Lender emitió esa CCB, la primera liberación debe caer en el money day de la CCB, o responde LENDER-0264. Consulta Emite la CCB.
6

Registra la liberación

POST /api/v1/loan-applications/{id}/disburse con disbursedAt en el momento en que salió el dinero y netDeliveredAmount con lo que recibió el prestatario. disbursedAt es opcional: si lo omites, Lender usa el ahora de negocio del tenant. Una llamada sin respuesta vuelve con la misma clave X-Idempotency. La sección de idempotencia cubre el caso de resultado incierto. Una llamada que Lender rechaza con un código de la tabla siguiente no liberó nada y gastó la clave, así que envía la solicitud corregida con una clave nueva.
disbursedAt y netDeliveredAmount registran cuándo y cuánto recibió el prestatario. Ningún rechazo se resuelve cambiando uno de los dos.

Toda escritura toma una clave de idempotencia

Crear una solicitud y moverla (aprobar, rechazar, desistir, desembolsar) exigen todas el encabezado X-Idempotency. Lender lee la clave con esa grafía y con ninguna otra. Rechaza Idempotency-Key y X-Idempotency-Key por nombre, para que un cliente nunca quede desprotegido en silencio por haber adivinado el encabezado. Enviar una de esas junto con el encabezado del contrato no es problema. El rechazo solo se dispara cuando X-Idempotency está ausente. La guarda falla cerrada. Cuando el almacén de idempotencia no puede responder, Lender rechaza el pedido con 503 en vez de dejarlo pasar sin protección. Crear cuesta una clave a propósito: sin ella, un cliente que agota el tiempo al crear y llama de nuevo abre una segunda solicitud para el mismo prestatario. Es el duplicado más barato de producir en el servicio y el más caro de deshacer. Es caro porque las dos copias se ven legítimas y solo una persona sabe decir cuál es la verdadera.
En las cuatro escrituras de ciclo de vida, puedes conciliar un pedido que termina sin resolverse y reenviarlo bajo una clave nueva. Lee la solicitud por id y pregunta si ya sostiene el estado que querías. En el desembolso, concilia primero: lee la solicitud y mira el disbursementEvent más reciente. Si la liberación no está ahí, reenvía la misma solicitud sin cambios bajo una clave nueva, trancheNumber incluido (o todavía ausente). La posición que declara es lo que impide una segunda liberación.

El producto tiene que estar activo

La originación lee el estado de activación del producto de préstamo y rechaza un producto que no está activo, con LENDER-0225 y un 422. El rechazo se ubica en los tres pasos que deciden crédito nuevo: crear la solicitud, aprobarla y liberar el dinero por la API. La cotización del consignado y la vista previa de cronograma que nombra una versión de producto fijan precio al mismo crédito, así que rechazan un producto inactivo del mismo modo. Un producto archivado no está activo. Por eso, un producto apagado después de presentada la solicitud la detiene antes de que salga el dinero. Crear una solicitud también tiene que nombrar la versión vigente del producto, o Lender la rechaza con LENDER-0226 y un 422. Esa comprobación corre en la creación y en ningún otro lado, porque una solicitud se queda de por vida en la versión en que nació. Promover una versión nueva nunca mata entonces las solicitudes detenidas en la anterior, y cada una sigue contabilizando en la versión que nombró. Mira Definir un producto de préstamo. Tres caminos quedan fuera de esta puerta a propósito:
  • El carril del consignado, que registra un contrato que los sistemas del propio cliente ya inscribieron en la nómina. Rechazar un hecho que ya ocurrió dejaría al libro negando un contrato que el prestatario tiene en la mano.
  • Una renegociación sustancial, cuyo contrato de reemplazo hereda la versión de producto del contrato al que reemplaza. El contrato de reemplazo hereda esa versión esté ese producto activo o no y sea esa versión la vigente o no. Renegociar es servicing de crédito ya escrito. Solo una solicitud nueva es crédito nuevo.
  • Una tranche posterior de una solicitud que ya tiene un desembolso. Esa solicitud ya es un contrato, así que un producto apagado después no detiene la siguiente tranche.
Lender no cerca nada posterior a la originación. Rechazo, desistimiento, servicing y contabilidad siguen funcionando contra un producto retirado años después.

Lo que obtienes

El desembolso produce una cuenta de préstamo, la vista de administración del contrato vivo, que lleva su cronograma, sus transacciones, sus cargos y su historial de auditoría. Continúa en Administrar un préstamo.

Lo que ocurre downstream

El ciclo de vida emite loan_application.submitted, loan_application.approved, loan_application.rejected, loan_application.withdrawn y loan_application.disbursed, cada uno en la versión de esquema 2.0.0. El desembolso registra una intención de asiento durable y la transmite al ledger. Consulta la ruta de asiento.
La originación brasileña agrega pasos regulados (divulgación de CET y consentimiento de capitalización) que cubre el Paquete regulatorio de Brasil. El flujo de consignado con descuento en nómina forma su propio contexto delimitado brasileño. Consulta Consignado privado.

Próximos pasos

Administrar un préstamo

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