Skip to main content
Esta guía te muestra cómo configurar la contabilidad en el Módulo Midaz de la Lerian Console. Usas solo las pantallas y los formularios de la Console, y no escribes código. Es el complemento en la Console del Recorrido de contabilidad, orientado a desarrolladores. Llegas al mismo resultado con formularios de la Console en lugar de llamadas a la API. Está dirigida a gerentes de producto, equipos de implementación y desarrolladores que prefieren modelar su contabilidad en la interfaz.
No verás ningún JSON ni llamadas a la API aquí. Todo lo de abajo lo haces con formularios de la Console. Para automatizar la misma configuración más adelante, sigue la referencia técnica que enlaza cada sección.

​
Qué vas a construir

Configura tus rutas contables con criterio. Una ruta define las Rutas de operación de origen y destino para una transacción directa, o una Ruta de operación Bidirectional que cubre ambos lados. Con Validate Routes habilitado, Midaz valida las reglas de ruta configuradas para las transacciones directas. La validación de rutas está deshabilitada de forma predeterminada. Habilítala solo después de configurar las rutas que necesita tu Ledger. La cancelación es una acción de ciclo de vida solo del origen: libera los fondos retenidos en la Cuenta de origen y no involucra una Cuenta de destino. Cada capa se apoya en la anterior:
1

Planifica tu plan de cuentas

Decide qué saldos necesita tu producto (fondos de clientes, comisiones, liquidación, tesorería, ingresos).
2

Crea los Tipos de cuenta

Define las categorías que clasifican tus cuentas.
3

Crea las Cuentas

Abre los contenedores de saldo reales, cada uno con un Type y un Activo. Seleccionas el Type para las Cuentas no externas. Cuando habilitas External account, el Type pasa a external automáticamente. Cuando Validate Account Type está habilitado, el Type de cada Cuenta no externa debe coincidir con un Tipo de cuenta registrado.
4

Crea las Rutas contables

Define las reglas sobre qué cuentas pueden participar en cada transacción y cómo el ledger registra los asientos.
Trabaja de arriba hacia abajo. Las rutas son mucho más fáciles de construir cuando ya sabes qué cuentas representan clientes, tesorería, comisiones y liquidación.

​
Paso 1: Planifica tu plan de cuentas

En la contabilidad tradicional, un plan de cuentas (CoA) es la lista maestra de cada categoría de cuenta que usa tu negocio: activos, pasivos, ingresos y gastos. También define cómo clasificas cada movimiento contra esas categorías. En Midaz no hay una sola pantalla de “plan de cuentas” para llenar. En cambio, tu CoA surge de los bloques que creas en la Console: Activos, Tipos de cuenta y Cuentas. Lo planificas por adelantado, casi siempre como un ejercicio en papel (o en pizarra). Antes de abrir la Console, lista los saldos que necesita tu producto. Para un producto de pagos típico podrían ser: Esta lista es tu esquema. Los siguientes pasos convierten cada línea en algo concreto dentro de la Console.
Antes de que pueda existir cualquier cuenta, necesita un Activo, la unidad de valor que guarda (por ejemplo BRL). Si todavía no creaste tus activos, empieza por Crear un Activo.

​
Paso 2: Crea tus Tipos de cuenta

Los Tipos de cuenta son las categorías que clasifican tus cuentas. Piénsalos como etiquetas tipo customer, treasury o fee que agrupan cuentas por su rol. Después, las Rutas contables usan esas etiquetas para decidir qué cuentas puede usar una transacción. En la Console creas un Tipo de cuenta por cada categoría de tu esquema, no uno por cada cliente individual.

Crear un Tipo de cuenta

Abre el formulario New Account Type y define una categoría con un nombre claro y un valor de clave estable.
Una configuración de pagos típica usa estos Tipos de cuenta:
El Key Value de un Tipo de cuenta (por ejemplo customer) es aquello de lo que dependen las rutas y las cuentas. Mantenlo corto, en minúsculas y estable. Si lo cambias después, debes volver a crear las cuentas y las rutas que dependen de él.
El menú Account Types aparece solo después de que habilitas Validate Account Type en la configuración de tu Ledger. Para activarlo, consulta Gestionar Ledgers.

​
Paso 3: Crea tus Cuentas

Las Cuentas son los contenedores de saldo que guardan valor y entre los que se mueve el dinero. Cada cuenta tiene un Type y un Activo (su moneda). Seleccionas el Type para las Cuentas no externas. Cuando habilitas External account, el Type pasa a external automáticamente. Cuando Validate Account Type está habilitado, el Type de una Cuenta no externa debe coincidir con un Tipo de cuenta registrado (las Cuentas externas se saltan esa verificación). Un alias legible la identifica. @customer_123_brl es una convención común. Por cada línea de tu esquema, crea una Cuenta en la Console.

Crear una Cuenta

Abre el formulario New Account, elige su Type y su Asset, y dale un alias claro.
Cuando llenas el formulario, algunas decisiones son permanentes y conviene acertar a la primera:
La Console bloquea Alias, Type y Asset cuando guardas la cuenta. Para cambiar cualquiera de ellos, crea una cuenta nueva. Revísalo dos veces antes de guardar.

​
Entender qué muestra realmente un saldo

Cuando abres una cuenta en la Console, Midaz divide su saldo en dos grupos. Siempre sabes qué puedes gastar y qué retiene el ledger: Ambos montos aparecen como valores decimales exactos (por ejemplo, 12.50). No hay un factor de escala que aplicar cuando los lees.
On hold hace funcionar los pagos en dos pasos. Cuando autorizas un pago pero todavía no lo capturas, el monto pasa de Available a On hold. Confirmar el pago lo libera hacia el destino. Cancelar lo devuelve a Available. Ves cada uno de estos movimientos en la cuenta en cada etapa.

​
Paso 4: Crea tus Rutas contables

Con Validate Routes habilitado, cada transacción debe indicar una Ruta contable válida en el ledger. Una Ruta contable es una regla reutilizable para un tipo de transacción, como una transferencia Pix o un cobro de comisión. Responde tres preguntas:
  • ¿Qué cuentas pueden enviar del lado origen?
  • ¿Qué cuentas pueden recibir del lado destino?
  • ¿Qué asientos de débito y crédito debe registrar el ledger cuando se ejecuta?
La Console las construye con un asistente guiado de 3 pasos, así no tienes que armar nada a mano.

Gestionar Rutas contables

Conoce cómo funciona la página Accounting Routes y qué hace cada parte del asistente.

Crear una ruta contable

Recorre el asistente de 3 pasos para definir una ruta, sus reglas de operación y sus asientos.
Para decidir cómo dar forma a una ruta, consulta Reglas contables. Explica las opciones en términos claros.
Cada regla dentro de una ruta aplica a un lado de la transacción:
  • Source: el lado que envía (de dónde viene el valor).
  • Destination: el lado que recibe (a dónde llega el valor).
  • Bidirectional: la misma regla aplica a ambos lados, para casos donde un tipo de cuenta puede enviar y recibir.
Una ruta válida necesita al menos un Source y un Destination, o una sola regla Bidirectional.
Cada regla verifica las cuentas de una de dos formas:
  • Account Type: la regla acepta cualquier cuenta de una categoría dada (por ejemplo, cualquier cuenta customer puede enviar). Usa esto para flujos flexibles y escalables.
  • @Alias: la regla acepta solo una cuenta exacta (por ejemplo, solo @fee_revenue puede recibir). Usa esto para cuentas operativas fijas como tesorería, comisiones o liquidación.
Los escenarios deciden cómo se registran los asientos de débito y crédito:
  • Direct: un movimiento de un solo paso, registrado de inmediato.
  • Two-Step: un flujo de retención y luego confirmación. Usa asientos separados para reservar, confirmar y cancelar fondos, y alimenta el grupo On hold.
  • Reversal: asientos que el ledger registra para deshacer una transacción completada.
  • Overdraft: asientos que el ledger registra cuando un débito supera los fondos disponibles de la cuenta y usa una línea de sobregiro.
  • Block: asientos que el ledger registra cuando los fondos de una cuenta se bloquean o se desbloquean.
Activa Validate Routes en la configuración del Ledger solo después de que ya existan las rutas que necesitas. Si la validación está activa pero falta una ruta que coincida, esas transacciones fallarán.

​
Ejemplo: un pago Pix simple

Vamos a recorrer todo el flujo en la Console para un Pix cash-out básico: un cliente envía BRL desde su billetera hacia una cuenta de liquidación. Supón que tu activo BRL ya existe.
1

Crea los Tipos de cuenta

Desde la página Account Types, crea:
  • customer: para saldos de clientes finales.
  • settlement: para fondos que salen al mundo exterior.
Consulta Crear un Tipo de cuenta.
2

Crea las Cuentas

Desde la página Accounts, crea:
  • @customer_123_brl: Type customer, Asset BRL. La billetera del cliente.
  • @external_brl: Type settlement, Asset BRL. Donde se liquidan los fondos cuando salen del ledger.
Consulta Crear una Cuenta.
@external_brl es una Cuenta de liquidación normal, propiedad del ledger. Este ejemplo la usa para que la ruta pueda validar el Tipo de cuenta settlement. No es la Cuenta externa canónica @external/BRL, que Midaz crea automáticamente junto con el Activo BRL. El prefijo de alias @external/ está reservado, así que no puedes crear esa Cuenta tú mismo. Para el dinero que de verdad entra o sale de Midaz, usa @external/BRL. Consulta Errores comunes que debes evitar.
3

Crea la Ruta contable

Desde la página Accounting Routes, empieza el asistente y construye una ruta Pix cash-out:
  • Una regla de operación Source que valida el Tipo de cuenta customer (la billetera envía).
  • Una regla de operación Destination que valida el Tipo de cuenta settlement (la cuenta de liquidación recibe).
  • Un escenario contable Direct, con un asiento de débito en el origen y un asiento de crédito en el destino.
Consulta Crear una Ruta contable.
4

Ejecuta una transacción

Crea una transacción que mueva, digamos, 100.00 BRL de @customer_123_brl a @external_brl con tu ruta Pix cash-out. Consulta Crear una Transacción.
5

Revisa el resultado

Abre cada cuenta y mira el saldo:
  • @customer_123_brl: Available baja 100.00.
  • @external_brl: Available sube 100.00.
Ambos movimientos pertenecen a la misma transacción, así que el registro de auditoría queda balanceado.
Para un flujo de autorización y luego captura, usa un escenario Two-Step en la ruta. Ves el monto entrar en On hold cuando se reserva, y salir de ahí cuando confirmas o cancelas.

​
Qué hacer a continuación

Para profundizar, usa estas referencias técnicas. Cubren cómo automatizar la configuración, entender las entidades y convertir la actividad del ledger en informes:

Recorrido de contabilidad (desarrollador)

La versión de esta guía para desarrolladores, de extremo a extremo, con el modelo de datos y el detalle de partida doble.

Resumen de contabilidad

Cómo se relacionan entre sí las primitivas contables centrales.

Entidades de enrutamiento de transacciones

El modelo técnico detrás de las Rutas contables, las rutas de operación y los asientos.

Saldos

El modelo de saldos completo detrás de los montos disponibles y retenidos.