Saltar al contenido principal
Lender contabiliza cada evento de dinero de un producto en el del producto, en Midaz. Mapeas esos eventos a tus cuentas una vez, en un plan. Las cuentas son tuyas. Lender define la forma de cada asiento de y rechaza un plan que no cuadra. Esta guía es para el back office y el contador del cliente. Cubre el ledger, los eventos contables y las cuentas que defines. Contabilidad y corridas de devengo cubre cómo llega un asiento al ledger.

Antes de empezar


  • Crea primero el producto de préstamo y una versión. Consulta Definir un producto de préstamo.
  • Para configurar un plan, tu rol necesita loan_product write y accounting write. Los roles operator, editor y admin tienen ambos.
  • Para cambiar un plan, o para designar una cuenta de suspenso, tu rol necesita accounting supersede. Solo el rol admin lo tiene.

El ledger del producto


Un plan nombra la organización de Midaz y el ledger de Midaz en los que se contabilizan los asientos del producto.
  • En modo multi-tenant, la organización es obligatoria. En modo single-tenant, un plan sin destino usa el valor predeterminado del entorno.
  • Nombra solo la organización, y Lender reutiliza el ledger en el que el producto ya contabiliza allí. Si el producto no tiene ninguno, Lender busca o crea un ledger llamado lender-product-<loan product id>. La respuesta nombra el ledger elegido.
  • Toda versión de un producto contabiliza en el ledger que eligió la primera versión configurada (LENDER-0453). Varios productos pueden compartir un ledger.
  • Lender rechaza un ledger con validación de rutas activada (LENDER-0452). Lender no envía ninguna ruta contable a Midaz.
  • Lender rechaza una organización o un ledger que Midaz no conoce (LENDER-0442). Si Midaz no responde, Lender responde 503 con LENDER-0441. Repite la solicitud.
MIDAZ_LEDGER_ACCOUNT_PROVISIONING_ENABLED es true por defecto. Consulta Configuración y despliegue. Lender entonces adopta el activo por código o lo crea. Crea cada cuenta antes del primer asiento en ella.
  • La naturaleza de una pierna define el tipo de cuenta. Una naturaleza de crédito crea una cuenta deposit. Una naturaleza de débito crea una cuenta lender_debit.
  • La dirección de una cuenta queda fija cuando se crea la cuenta.
  • Lender adopta una cuenta que ya existe. Compara la dirección de la cuenta con la naturaleza de la pierna y rechaza el asiento si difieren.
Una cuenta por contrato tiene el alias <prefix>:<id>. El prefijo es tuyo, con como máximo 17 caracteres. El id son los 32 dígitos hexadecimales del id de la cuenta de préstamo. Lender crea una cuenta por contrato para una posición del prestatario con el titular del CRM del contrato como dueño.

Anatomía de una regla de asiento


Una regla de asiento mapea un evento contable a 2 a 16 piernas. Una regla también puede llevar metadata, un mapa de valores de texto. Cada pierna mueve dinero en una cuenta.

Posiciones por contrato

Una pierna que contabiliza lo que debe un prestatario debe ser por contrato (LENDER-0408). Estos son los códigos de monto: principal, interest, fees, penalties, unapplied_cash, assignment_retained y returned_payment. Dos tipos de pierna son la excepción:
  • Una pierna de ingreso o de gasto.
  • El crédito de accrual_withholding en rendas a apropriar.
La comisión de originación retenida es por contrato en los dos extremos, en una sola cuenta: el crédito origination_fee en disbursement y el débito de accrual_fee_amortization. Una cuenta de comisión compartida se acepta, pero bloquea toda baja por pérdida (LENDER-0411), y ningún cambio de plan lo corrige. Algunas cuentas nunca son por contrato:
  • La cuenta del impuesto sobre el ingreso, porque es un pasivo de la institución con la autoridad fiscal (LENDER-0419).
  • Una cuenta de ingreso o de gasto (LENDER-0987).
  • La cuenta de contrapartida de renegotiation_derecognition y renegotiation_recognition. Esta cuenta puente es una sola cuenta para el producto.

Ejemplo

Esta es la regla disbursement de un plan. Los códigos de cuenta son solo una ilustración.
@external/<ASSET> es la cuenta que Midaz crea para cada activo. Registra el dinero que entra al ledger o sale de él. Consulta Cuentas. Tu cuenta de tesorería puede estar en el mismo ledger. Entonces la pierna cash puede nombrarla. Lender activa el saldo negativo solo para las cuentas de crédito que lista para eso, y nunca para la cuenta cash. Consulta Sobregiro de Saldo. Por eso Midaz rechaza un desembolso mayor que el saldo de esa cuenta. El asiento queda estacionado como un caso (LENDER-0458). Mantén el efectivo en la cuenta.

Los eventos contables


Un plan puede llevar tres tipos de evento: eventos que todo plan necesita, eventos opcionales y eventos que Lender deriva.

Eventos obligatorios

Lender rechaza un plan que no tiene uno de estos eventos. Las dos constituciones acreditan dos cuentas de provisión distintas. Lender rechaza un plan que acredita una sola cuenta para ambas (LENDER-0455).

Eventos opcionales

La última columna dice qué pasa si la dejas fuera. Para los eventos de cesión, consulta Ceder cuentas por cobrar.

Eventos que no configuras

Lender deriva estos eventos de las reglas anteriores. Un plan no puede llevarlos. Si envías uno, Lender responde 422.

Verificaciones que Lender hace a tu plan


Lender verifica el plan cuando lo configuras o lo cambias. No escribe nada cuando una verificación falla. Configurar un plan para una versión que ya tiene uno responde 409 Conflict. La lista de errores de Lender trae el texto completo de cada código.

Lee un plan de vuelta


La lista muestra, para cada plan, eventTypes, missingEventTypes, effectiveFrom y createdAt. missingEventTypes nombra los eventos obligatorios para los que el plan no tiene regla. Queda vacía cuando el plan está completo. La lectura por id devuelve el plan completo. Trae postingRules con las piernas, midazOrganizationId, midazLedgerId, effectiveFrom y createdAt. No tiene campo de cobertura. Un id que Lender no conoce responde 404 con LENDER-0454.

Cambia el plan


Configuras una versión una vez. Su primer plan rige desde 1900-01-01, y una segunda llamada de configuración responde 409. Todo plan es inmutable. Una versión guarda una cadena de planes con fecha, y un cambio agrega un plan con fecha a toda versión configurada del producto. Un cambio pertenece al producto, no a una versión. POST /api/v1/loan-products/{id}/accounting-profiles/supersessions El cuerpo trae el plan nuevo completo y effectiveFrom. effectiveFrom es siempre el primer día de un mes que aún no ha abierto mañana. El último día de un mes, la opción más temprana es el primer día del mes después del siguiente. El plan nuevo contabiliza en el mismo ledger que el anterior (LENDER-0443). El plan nuevo mantiene toda posición por contrato del plan anterior. Una cuenta compartida de saldo mantiene su cuenta y su modo: una provisión, un valor por pagar o el efectivo. Las cuentas de ingreso y de gasto pueden cambiar. Lender rechaza un cambio que envía dos posiciones de una cuenta por contrato a cuentas distintas (LENDER-0986). El plan vigente en un día es el plan con el mayor effectiveFrom hasta ese día. Un contrato queda en el plan que guarda su saldo hasta que el saldo se transfiere.
1

Registra el cambio

Envía el cambio. Lee movedPositions en la respuesta. Lista cada posición cuyo saldo cambia de cuenta.
2

Deja que los saldos se muevan

El saldo de un contrato se mueve dentro de su primer asiento después del cambio. El cierre del mes de vigencia mueve los contratos que no tuvieron asiento. No hace falta nada más.
3

Opcional: barre los contratos que aún esperan

Después del cierre del mes anterior a la vigencia, POST /api/v1/loan-products/{id}/accounting-profiles/supersessions/sweeps los mueve ahora, con un asiento por contrato. Exige el header X-Idempotency. Cada repetición exige una clave nueva, porque la misma clave devuelve la respuesta anterior.
4

Resuelve lo que detiene a un contrato

LENDER-0450 lista las causas posibles, no la que vale para un contrato, y todo contrato que estaba listo se movió. Revisa en este orden: el cierre del mes anterior a la vigencia; un cambio anterior que sigue abierto (barre ese primero); asientos estacionados (consulta Contabilidad y corridas de devengo); un monto que el ledger retiene. Luego repite el barrido con una clave X-Idempotency nueva. No repitas en bucle.
En el Console, consulta Chart of accounts changes y Move waiting contracts en Crédito.

Cuentas de suspenso


Algunos asientos necesitan una cuenta de suspenso. Un desembolso en partes y un ajuste compensatorio las usan. Designas una cuenta para cada moneda y rol. PUT /api/v1/internal/accounting/suspense-accounts/{currency}/{role} designa la cuenta, con gl_account en el cuerpo. Una cuenta designada debe existir ya en el ledger. Lender nunca la crea, a menos que tenga el nombre exacto del valor predeterminado. Un contrato conserva la cuenta que guarda su primer monto en un rol. Una cuenta nueva rige para los contratos que aún no tienen ninguna. Cuando Lender aprovisiona las cuentas del ledger, un rol en BRL sin cuenta designada contabiliza en el valor predeterminado. GET en la misma ruta responde 404 con LENDER-0449 cuando no designaste ninguna. Consulta Contabilidad.

En el Console


La pantalla para configurar un plan exige los mismos dos permisos que la API. Abre Credit, abre el producto y la versión, y elige la acción de configurar el perfil contable. Consulta Crédito.
1

Elige la institución financiera

Financial institution nombra la organización. Lender crea en ella el ledger del producto, o reutiliza el ledger que ya creó.
2

Revisa la hoja

La hoja empieza como una copia del plan más reciente del producto, cuando la pantalla puede editar todas sus reglas. Revisa cada cuenta antes de registrar.
3

Marca las piernas por contrato

Marca como Per contract cada pierna que contabiliza una posición del prestatario.
4

Registra el plan

Record accounting profile guarda el plan de forma definitiva. Cerrar la página descarta una hoja que no registraste.
La pantalla registra estos eventos: los eventos obligatorios, payroll_payer_provision_constitution, payroll_payer_provision_reversal, refinance_payoff, refinance_payoff_reversal, assignment_derecognition, assignment_retained_settlement, assignment_repurchase, credit_loss_recovery y compensation_control. La pantalla no registra estos eventos: accrual_fee_amortization, charge_appropriation, renegotiation_derecognition, renegotiation_recognition, assignment_secured_borrowing, assignment_funding_amortization, assignment_funding_payoff y los cuatro eventos returned_payment_*. Para llevar uno de ellos, envía el plan con POST /api/v1/loan-products/{id}/accounting-profiles, con los mismos dos permisos. Un producto solo renegocia de forma sustancial con el par renegotiation_derecognition y renegotiation_recognition, así que envías ese plan por la API. La pantalla no copia un plan que tiene una regla que ella no edita. La hoja abre entonces vacía, y el aviso This chart has rules this screen cannot edit nombra esas reglas.

Concilia con Midaz


Cada asiento es una transacción de Midaz. Usa estos campos para encontrarla. Consulta Contabilidad y corridas de devengo para recibos, referencias de diario y asientos estacionados.

Próximos pasos


Contabilidad y corridas de devengo

Mira cómo llega un asiento al ledger y cómo las corridas de devengo contabilizan intereses.

Definir un producto de préstamo

Crea el producto y la versión que el plan atiende.

Crédito en el Console

Configura el plan y ejecuta cambios de plan en el Console.

Paquete regulatorio de Brasil

Superpón CET, IOF y etapas de PDD sobre el modelo contable.