What Is a Double-Entry Ledger API for Marketplaces?
A double-entry ledger API records marketplace money movement as balanced, immutable journal entries so you always know who is owed what and why.
Un marketplace puede parecer saludable en su tabla de orders y aun así equivocarse con su dinero. La orden indica "pagada". El panel del vendedor muestra un saldo. Sin embargo, nada en esa tabla demuestra cuánto efectivo tiene la plataforma, cuánto le debe a cada vendedor, qué parte del pago corresponde a ingresos por comisiones o cuánto IVA se debe ahora. Una API de libro mayor de partida doble (double-entry ledger API) existe para registrar esas consecuencias financieras correctamente, una transacción equilibrada a la vez.
Dicho claramente: una API de libro mayor de partida doble es un sistema contable programable. Su aplicación le envía un evento financiero, como un pago cobrado o un desembolso aprobado, y el libro mayor registra ese evento como un asiento (journal) con débitos y créditos iguales en cuentas con nombre propio. No mueve dinero. Registra la verdad sobre el dinero que se movió a otra parte.
Qué significa "libro mayor de partida doble" en este contexto
Un libro mayor es el registro de los cambios en las cuentas, no una tabla que contiene el saldo más reciente. Un libro mayor operativo se basa en tres conceptos interconectados:
- Cuenta: una posición financiera con nombre propio, como por ejemplo cuenta por cobrar del procesador de pagos, cuenta por pagar al vendedor, ingresos por comisiones o IVA por pagar.
- Transacción (asiento): un evento financiero atómico que contiene múltiples líneas equilibradas.
- Entrada (apunte): una única línea de débito o crédito dentro de esa transacción.
La regla invariable que sostiene todo el diseño es simple: el total de los débitos es igual al total de los créditos, para cada transacción y cada moneda. Por lo general, las API de libros mayores rechazan una escritura desequilibrada antes de que llegue al almacenamiento. La documentación de Modern Treasury define una transacción de libro mayor como aquella que involucra dos o más cuentas con al menos un débito y un crédito de totales iguales, y trata una transacción registrada como inmutable.
Partida doble no significa exactamente dos filas. Una sola venta en un marketplace a menudo requiere un débito y varios créditos. Esa es la parte que la gente suele interpretar mal con mayor frecuencia.
Por qué los marketplaces necesitan un libro mayor y no solo una tabla de pagos
Un marketplace mantiene varias relaciones financieras al mismo tiempo. Un comprador paga. Un procesador liquida. Es posible que la plataforma controle los fondos temporalmente. El vendedor gana una porción. La plataforma se queda con una comisión. Los impuestos se vuelven exigibles. Se puede retener una reserva. Más tarde, un desembolso saca dinero, y los reembolsos (refunds) o devoluciones de cargos (chargebacks) revierten partes de ello.
Una tabla de payments puede indicarle el estado comercial de una orden. No puede indicarle de forma fiable:
- cuánto existe en cuentas por cobrar del procesador o en efectivo
- cuánto se le debe a cada vendedor
- qué parte de los ingresos pertenece a la plataforma
- cuánto IVA se debe y en qué país
- qué parte está reservada contra reembolsos o disputas
- si un desembolso redujo la obligación correcta con el vendedor
- si las liquidaciones del procesador coinciden con lo que esperaba la plataforma
La guía sobre API de libros mayores de partida doble para la contabilidad de marketplaces de Nordlet traza una línea clara: las tablas de la aplicación describen el estado del producto, mientras que el libro mayor registra las consecuencias financieras de ese estado. También señala un punto que vale la pena repetir: los informes de los procesadores de pagos son entradas para la conciliación, no libros completos de partida doble.
Una venta de marketplace en la práctica
Supongamos que un comprador paga 100 €, el vendedor tiene derecho a 85 € y la comisión de la plataforma es de 15 €. Ignoremos el IVA y las comisiones del procesador por motivos de claridad.
| Cuenta | Débito | Crédito | Motivo |
|---|---|---|---|
| Cuenta por cobrar del procesador de pagos | 100 € | El procesador le debe a la plataforma el pago cobrado | |
| Cuenta por pagar al vendedor | 85 € | La plataforma le debe al vendedor | |
| Ingresos por comisiones | 15 € | La plataforma ganó su comisión | |
| Total | 100 € | 100 € | Saldos |
La clasificación importante aquí es que los 85 € adeudados al vendedor son un pasivo, no un ingreso de la plataforma. Según el marco conceptual de las IFRS, un pasivo es una obligación presente de transferir un recurso económico. Un marketplace no debe reportar el producto total de la venta del vendedor como su propio ingreso simplemente porque el comprador pagó a través de él. Actuar como agente, principal o proveedor presunto cambia el tratamiento, pero el mecanismo del libro mayor sigue siendo el mismo.
Cuando el vendedor pasa a ser elegible para el desembolso, no se reconocen nuevos ingresos. Se liquida el pasivo:
| Cuenta | Débito | Crédito |
|---|---|---|
| Cuenta por pagar al vendedor | 85 € | |
| Banco o cámara de compensación de desembolsos | 85 € | |
| Total | 85 € | 85 € |
Si el procesador cobra una comisión de 3 € antes de realizar la liquidación, el movimiento de efectivo se convierte en un asiento de tres líneas: 97 € al efectivo del banco, 3 € a gastos de procesamiento y 100 € que salen de la cuenta por cobrar del procesador. Cada cambio de posición tiene un origen y un destino.
Cómo funciona la API, paso a paso
1. Su aplicación detecta un evento de negocio. Se cobra un pago, se cumple con una orden, se aprueba un desembolso, se emite un reembolso, se abre una disputa de cargos, se recibe una liquidación. Su base de datos sigue controlando el estado operativo. El libro mayor registra el efecto monetario.
2. Envía una solicitud estructurada. Por lo general, incluye el tipo de evento, el monto y la moneda, el ID de la orden o del pago, los identificadores del comprador y del vendedor, la comisión, los datos de impuestos, las cuentas involucradas, las fechas efectiva y de contabilización, una clave de idempotencia (idempotency key) y metadatos que enlazan con los registros del procesador y del producto. El ejemplo de API pública de Nordlet muestra una solicitud de venta conceptual con ID de vendedor, tipo de venta, monto, moneda, además del país y la tasa de IVA.
3. La API valida. Comprueba que los débitos y créditos estén equilibrados, que las cuentas existan y admitan apuntes, que la moneda sea compatible, que el monto utilice un manejo preciso de unidades menores, que la clave de idempotencia no se reutilice para un resultado diferente, que el periodo esté abierto y que los metadatos requeridos estén presentes. Una validación fallida no deja ningún asiento parcial atrás.
4. Se contabiliza de forma atómica. Toda la transacción se registra como una sola unidad. Nunca debe ser posible registrar el débito mientras falla el crédito correspondiente. Para un marketplace, un desglose parcial podría crear un saldo de vendedor aparente sin efectivo correspondiente, o registrar una comisión sin la obligación hacia el vendedor.
5. Los saldos y los informes se derivan del libro mayor. Después de la contabilización, puede leer los saldos de las cuentas, los saldos pendientes y disponibles de los vendedores, un balance de comprobación (trial balance), la actividad del libro mayor general (general ledger), los resúmenes de IVA y el historial a una fecha pasada. El saldo del vendedor debe poder reconstruirse a partir de los apuntes, en lugar de confiar en un campo mutable.
6. Los webhooks notifican a su producto. Eventos como sale_invoice.paid, un asiento contabilizado, un desembolso disponible o una excepción de conciliación se envían a su sistema. Procéselos de forma idempotente. Un webhook es una notificación, no un permiso para aplicar el evento financiero por segunda vez. Las convenciones de la API cubren en detalle los ámbitos (scopes), las claves de idempotencia, las estructuras de error y la firma de webhooks.
Los saldos de los vendedores no son un número único
La mayoría de los marketplaces se meten en problemas al tratar el saldo de un vendedor como una sola cifra. El dinero debe ubicarse en distintos estados:
| Estado | Significado |
|---|---|
| Pendiente (Pending) | Es posible que el vendedor tenga derecho, pero no se cumplen las condiciones de liberación |
| Disponible (Available) | Elegible para desembolso |
| Reservado (Reserved) | Retenido frente a reembolsos, devoluciones o disputas |
| Desembolsado (Paid out) | Obligación saldada mediante una transferencia |
| Negativo (Negative) | Los reembolsos, devoluciones de cargos o comisiones superan los fondos disponibles |
Los modelos de los procesadores reflejan esto. El flujo de cargos y transferencias separadas de Stripe permite que una plataforma cobre en su propia cuenta y luego transfiera porciones a cuentas conectadas, recayendo las comisiones, reembolsos y devoluciones de cargos en el saldo de la plataforma. El modelo de marketplace de Adyen distingue las cuentas de saldo de usuario, que retienen fondos hasta el desembolso, de una cuenta de saldo responsable que puede absorber saldos negativos por reembolsos o devoluciones de cargos. Estas son aportaciones útiles para su libro mayor, pero no constituyen su modelo contable completo.
Los desembolsos y las ganancias de los vendedores ocurren en momentos diferentes
Un vendedor puede generar ingresos el lunes y cobrar el lunes siguiente. Entre esos momentos, se cumple una orden, se retiene una reserva, se genera un lote de desembolsos, el procesador realiza la liquidación neta de comisiones y llega un depósito bancario. Un libro mayor debe preservar cada etapa en lugar de sobrescribir la orden con un estado final de "pagado". Eso es lo que le permite explicar las diferencias de tiempo entre la actividad de la orden, el derecho del vendedor, la liquidación, el inicio del desembolso y la recepción bancaria.
Reembolsos y devoluciones de cargos: revoque, no reescriba
Los reembolsos y las devoluciones de cargos son nuevos eventos vinculados al pago original. En un libro mayor inmutable, usted corrige mediante un asiento de reversión seguido de uno corregido, de modo que el original permanezca visible para la auditoría. Modern Treasury trata las transacciones registradas como inmutables y admite claves de idempotencia para evitar duplicar objetos en los reintentos.
Un reembolso normalmente reduce el efectivo o la cuenta por cobrar del comprador, revierte la cuenta por pagar al vendedor, puede revertir parte de la comisión según la política, ajusta los impuestos y puede consumir una reserva para reembolsos. Una devolución de cargo reduce el efectivo o la cuenta por cobrar del procesador, puede reabrir un monto adeudado por el vendedor o la plataforma, registra un gasto por disputa y una comisión del procesador, y mueve fondos a través de una cuenta de reserva.
Conciliación: conectar el libro mayor con el dinero real
Un libro mayor puede estar equilibrado internamente y aun así estar equivocado respecto al mundo exterior. La conciliación compara los registros internos con la evidencia externa: informes de liquidación del procesador, extractos bancarios, archivos de desembolsos y registros de reembolsos y disputas.
Un ciclo operativo viable funciona así:
- Importe el lote de liquidación o bancario.
- Haga coincidir cada línea con una orden, pago, reembolso, comisión, desembolso o disputa.
- Compare el importe bruto esperado, las deducciones, las reservas y el neto.
- Registre los movimientos confirmados en el libro mayor.
- Envíe los elementos no coincidentes a una cuenta transitoria (suspense account) designada.
- Investigue las excepciones.
- Cierre el periodo.
El material de conciliación de Nordlet describe exactamente esto: importar lotes de liquidación, hacer coincidir las líneas de cargos y reembolsos, y enrutar los recibos sin coincidencia a cuentas transitorias en lugar de adivinar el contenido de una factura. Dos comprobaciones importan y ninguna reemplaza a la otra: la validación de partida doble pregunta si cada asiento está equilibrado, y la conciliación pregunta si coincide con el procesador, el banco y el evento comercial.
Detalles de diseño que determinan si acierta
Idempotencia. Vincule la clave a un evento estable, como payment_captured:pi_123. Un reintento devuelve el resultado original, no un segundo asiento.
Atomicidad. Todas las líneas de un evento se contabilizan juntas o ninguna lo hace.
Inmutabilidad y reversiones. El historial registrado no se puede editar mediante actualizaciones ordinarias. Las correcciones crean entradas vinculadas que preservan el monto original, la fecha, la clasificación, el motivo y el autor.
Dinero preciso. No utilice coma flotante binaria. Utilice unidades menores enteras o decimales exactos, moneda explícita y una regla de redondeo determinista para los desgloses. Si divide 100 € entre vendedores y comisiones sin una regla así, un céntimo perdido arruinará su saldo.
Fechas efectivas frente a fechas de contabilización. El momento en que pagó el comprador, en que ganó el vendedor, en que liquidó el banco y en que se registró el asiento son fechas distintas. Confundirlas hace que los informes por periodos y la sincronización fiscal no sean fiables.
Multidivisa. El débito y el crédito deben estar equilibrados dentro de una misma moneda. La conversión requiere un evento de tipo de cambio explícito con cuentas para la comisión, el redondeo y cualquier ganancia o pérdida cambiaria. Aceptar un campo de currency no convierte a un libro mayor en un motor de divisas.
Lo que una API de libro mayor no hará por usted
No decidirá su plan contable (chart of accounts). Usted todavía tiene que determinar si actúa como principal o como agente, cuándo se gana la comisión, qué parte asume las comisiones del procesador, cómo afectan los reembolsos a la comisión y cómo se calcula y declara el IVA. La propia guía de Nordlet recomienda mapear primero los flujos de dinero, redactar el plan contable, hacer que un contador lo revise y luego implementar un flujo completo desde la orden hasta el desembolso y la conciliación antes de escalar.
No resolverá las cuestiones fiscales. El IVA depende de la ubicación del comprador y del vendedor, del tipo de producto, del estado de registro y de las normas sobre proveedores presuntos; la guía de IVA de la UE establece lo que el motor deduce y lo que señala para la revisión humana. La cobertura de IVA de Nordlet se centra en la UE y el EEE, por lo que no se extiende al impuesto sobre las ventas de EE. UU. ni a la facturación electrónica en América Latina. Y tampoco resolverá la ambigüedad operativa: si un periodo de devolución ha expirado, si un desembolso debe bloquearse o si un pago es fraudulento. Esas son sus decisiones. El libro mayor registra su resultado financiero.
Dónde encaja Nordlet
Nordlet es una API de contabilidad creada para plataformas y marketplaces, con un libro mayor de partida doble inmutable, desembolsos, gestión de IVA de la UE, endpoints REST, SDK con tipos definidos y webhooks accesibles a través de una única interfaz. Su decisión distintiva es la contabilidad integrada dentro de su propio producto en lugar de un proceso de pago de terceros. Al escribir este artículo, el producto se encuentra en acceso anticipado con un entorno de pruebas (sandbox) para socios de diseño, por lo que debe considerarlo como un sólido ejemplo de su categoría y evaluar la madurez de producción, el tiempo de actividad (uptime) y la cobertura jurisdiccional para su propio caso antes de comprometerse.
Para los desarrolladores de marketplaces y plataformas, el modelo mental útil es la división entre el movimiento del pago y la verdad financiera. Su procesador mueve el dinero. Una API de libro mayor de partida doble registra a quién se le debe qué, qué ha ganado, qué impuestos y reservas mantiene, y si el mundo exterior concuerda con sus libros.
FAQ
¿Es una API de libro mayor de partida doble lo mismo que un procesador de pagos?
No. Un procesador autoriza, cobra, liquida y, a veces, desembolsa fondos. Una API de libro mayor registra las consecuencias contables de esos eventos. La mayoría de los marketplaces utilizan ambos: un procesador como Stripe o Adyen para el movimiento y un libro mayor para la contabilidad.
¿Puedo usar simplemente el panel de mi procesador como libro mayor general?
Puede intentarlo, pero eventualmente fallará en una auditoría. Los informes de los procesadores muestran cargos, comisiones, transferencias y liquidaciones, pero por lo general no representan todas sus obligaciones con los vendedores, pasivos fiscales, gastos ajenos al procesador o ajustes contables. Trátelo como una entrada de conciliación.
¿Significa un libro mayor equilibrado que mis libros están correctos?
Solo significa que sus asientos cumplen con la regla de débito y crédito. Una transacción perfectamente equilibrada aún puede registrarse en la cuenta incorrecta, al vendedor equivocado o con el tratamiento fiscal erróneo. El equilibrio es necesario, pero no suficiente. La conciliación es lo que detecta el resto.
Si el libro mayor es inmutable, ¿cómo corrijo los errores?
Se publica un asiento de reversión y luego uno corregido. El original permanece visible, que es precisamente el objetivo. La inmutabilidad protege la pista de auditoría, no atrapa sus errores.
¿Me convierte una API de contabilidad en alguien automáticamente cumplidor de las normativas?
No. Aplica una estructura contable y produce registros utilizables. El cumplimiento legal aún depende de su jurisdicción, su rol contractual, el tratamiento fiscal, las normativas de pagos, los procesos KYC y AML, y sus obligaciones de presentación de informes.