Qué define una API de libro mayor inmutable por partida doble

El libro mayor de un 'marketplace' no se define por el hecho de almacenar movimientos de dinero; la mayoría de los sistemas hacen eso. Se define por lo que ocurre cuando un proveedor de pagos envía el mismo 'webhook' dos veces, cuando un reembolso llega después de que al vendedor ya se le haya realizado una liquidación, o cuando un auditor pregunta cómo el saldo de un vendedor alcanzó su cifra actual. Esos momentos revelan si cuenta con un libro mayor inmutable por partida doble o con un campo modificable con un nombre optimista.

Para una plataforma de 'marketplace', la respuesta breve es la siguiente: una API de libro mayor inmutable por partida doble registra cada evento con consecuencias financieras como una transacción de diario equilibrada, la publica de forma atómica, nunca la sobrescribe y le permite derivar saldos, conciliar con sistemas externos y exportar el historial mediante programación. Todo lo demás son detalles que dependen de ese núcleo.

Asientos de diario equilibrados, no un campo de saldo acumulado

La prueba más clara es cómo la API representa el saldo de un vendedor. Si el saldo es un número que su aplicación incrementa directamente, no es un libro mayor por partida doble. Si el saldo es una vista derivada de líneas de diario asentadas, es posible que sí lo sea.

Cada transacción debe incluir débitos y créditos iguales. Cuando un comprador paga 100 € por un pedido en el que el 'marketplace' retiene una comisión de 15 €, el libro mayor registra la cuenta de compensación debitada por 100 €, frente a una cuenta por pagar al vendedor acreditada por 85 € y unos ingresos por comisiones acreditados por 15 €. Ambas partes siempre suman la misma cantidad. Esa regla estructural detecta una gran cantidad de errores antes de que lleguen a un informe.

Una transacción de diario debe exponer, como mínimo:

• Un identificador de transacción único e inmutable
• Líneas de débito y crédito, cada una con una cuenta, un importe y una divisa
• Una fecha efectiva y una marca temporal de asiento
• Un tipo de evento de negocio (venta, reembolso, liquidación, devolución de cargo o chargeback)
• Una clave de idempotencia
• Una referencia de origen al pedido, pago o evento del proveedor
• Un estado (pendiente, asentado, revertido)
• El servicio o credencial que lo creó

Los fondos disponibles de un vendedor se obtienen entonces mediante una consulta a esas líneas, y no a partir de un valor que alguien actualizó en el código de la aplicación. Esto es importante porque un saldo modificado directamente pierde el motivo de cada movimiento. El modelo de Nordlet trata el libro mayor por partida doble como la ruta de escritura autorizada: cada documento registra asientos de diario equilibrados, y la base de datos misma rechaza los que no estén equilibrados. Esa es la opción predeterminada correcta para cualquiera que integre la contabilidad en un 'marketplace'.

Asentamiento de solo adición con correcciones compensatorias

"Inmutable" debe significar que un diario asentado no se puede editar en el mismo lugar. Los errores se corrigen hacia adelante, no se borran. Una entrada de comisión errónea recibe una reversión que anula la original, y luego una entrada corregida que registra el resultado deseado. Ambas se vinculan con la original, y el historial de auditoría muestra quién inició el cambio y cuándo.

La API debe rechazar las operaciones de actualización (UPDATE) y eliminación (DELETE) directas en los registros contables asentados. Puede permitirle adjuntar metadatos no financieros, como una referencia de caso de soporte, siempre y cuando los importes, las cuentas y las marcas temporales permanezcan intactos.

Ayuda separar tres conceptos que la gente suele confundir:

• Inmutabilidad operativa: los usuarios de la aplicación no pueden alterar ni eliminar las filas asentadas.
• Inmutabilidad de auditoría: el sistema puede demostrar que el historial no ha cambiado.
• Retención legal: los registros se conservan durante el período que exige la legislación aplicable.

Una base de datos relacional de solo adición con permisos estrictos, copias de seguridad y flujos de trabajo de reversión disciplinados proporciona un libro mayor genuinamente inmutable. La tecnología 'blockchain' no es un requisito aquí y, para los datos contables de la UE, suele introducir problemas de privacidad y corrección que superan la evidencia de manipulación que aporta.

Atomicidad e idempotencia

Un evento de 'marketplace' debe asentarse de forma atómica. O todas las líneas del diario se confirman o ninguna lo hace. Registrar el cobro de 100 € pero no registrar la comisión de 15 € produce un resultado desequilibrado y engañoso que alguien tendrá que resolver más tarde. Nordlet aplica esto por debajo de la capa de aplicación: un activador (trigger) diferido en la base de datos comprueba que cada asiento esté equilibrado en el momento de la confirmación (commit), de modo que una transacción desequilibrada no se puede confirmar bajo ningún concepto.

La idempotencia es el aspecto donde la mayoría de las integraciones fallan silenciosamente. Los sistemas de pago reintentan las operaciones ante fallos de red y los archivos de liquidación se vuelven a procesar. Sin una clave de idempotencia delimitada al inquilino o a la cuenta, una única solicitud reintentada crea una contabilidad duplicada. Una solicitud repetida con la misma clave debe devolver la transacción original, no una segunda.

La clave debe vincularse al evento de origen, al tipo de evento, al ID de evento del proveedor, a la entidad jurídica y a 'hash' de la carga útil (payload) de la solicitud. Si llega la misma clave con un importe o una divisa diferentes, la API debe tratarlo como una colisión y rechazarlo en lugar de aceptar silenciosamente la nueva carga útil. La aceptación silenciosa es la causa por la que se corrompen las pistas de auditoría. La cabecera Idempotency-Key de Nordlet funciona de esta manera: un reintento con la misma clave y carga útil reproduce la respuesta almacenada, y la misma clave con una carga útil diferente se rechaza con el código idempotency_key_reuse. Es una función pequeña con un efecto desproporcionado en la conciliación.

Contabilidad de división multipartita

El pedido de un 'marketplace' no es un único movimiento. Una sola venta puede afectar a los fondos del comprador, los ingresos del vendedor, la comisión del 'marketplace', las comisiones de procesamiento de pagos, el IVA de la comisión, los gastos de envío y las reservas. El libro mayor necesita estructuras de cuentas que mantengan estos conceptos separados en lugar de fusionarlos en una sola cifra neta.

Existe una suposición común que conviene rebatir: la función de "liquidación dividida" (split payout) de un proveedor de pagos no es lo mismo que la contabilidad de un 'marketplace'. Dividir el dinero entre los beneficiarios enruta efectivo. No le proporciona un registro completo e inmutable de la comisión ganada, el IVA recaudado, los reembolsos adeudados o las reservas retenidas. Todavía necesita su propio libro mayor y todavía necesita conciliarlo con el proveedor.

El libro mayor de un 'marketplace' también debe distinguir más de un saldo de vendedor:

Estado del saldo	Lo que representa
Pendiente (Pending)	Fondos vinculados a un evento pero que aún no cumplen los requisitos para su retirada
Disponible (Available)	Fondos que superan las reglas de liberación, reserva, reembolso y disputa
Retenido / reservado (Held / reserved)	Importes retenidos para devoluciones de cargo, devoluciones de mercancías o controles de fraude
Liquidado (Paid out)	Importes transferidos al vendedor
Negativo / recuperable (Negative / recoverable)	Importes que el vendedor debe después de que los reembolsos o comisiones superen los fondos disponibles

Mover fondos de pendiente a disponible debe ser en sí mismo una transacción de diario equilibrada, no un campo al que se le cambie la etiqueta.

Reversiones, reembolsos y saldos negativos

Los flujos de dinero en los 'marketplaces' van en ambas direcciones, a menudo fuera de orden. Los casos difíciles son los reembolsos posteriores a la liquidación y las devoluciones de cargo que llegan semanas después. Un libro mayor serio define lo que sucede cuando el saldo disponible de un vendedor no puede cubrir un reembolso: crear un saldo negativo, trasladar el importe a cuentas por cobrar del vendedor, recurrir a una reserva o restringir futuros pagos.

Cada uno de estos eventos debe hacer referencia a la transacción original y conservarla. El libro mayor registra la consecuencia contable de un reembolso. No decide la política de reembolsos ni la responsabilidad legal del 'marketplace'. Mantener esa frontera clara evita una gran cantidad de conversaciones de diseño confusas.

Divisas y precisión

Los 'marketplaces' transfronterizos necesitan una gestión explícita del dinero. Los importes deben utilizar códigos de divisa ISO 4217 y una representación exacta, ya sea mediante unidades menores enteras o cadenas decimales de precisión fija, pero nunca números de coma flotante (floats). Sin redondeos silenciosos. Cuando se produce una conversión, el libro mayor debe conservar el importe original, el tipo de cambio, la fuente del tipo de cambio, la marca temporal y el importe resultante, registrando las diferencias de redondeo en una cuenta definida.

Una única transacción equilibrada no debe mezclar divisas sin un mecanismo de tipo de cambio explícito. Si lo hace, sus informes no coincidirán con la realidad de formas difíciles de rastrear al cierre del mes.

Conciliación con sistemas externos

Un libro mayor equilibrado internamente no es definitivo por sí solo. Debe coincidir con el mundo exterior: transacciones de proveedores de pagos, comisiones de proveedores, informes de liquidación, extractos bancarios, archivos de liquidación e informes de devoluciones de cargo.

Una API madura admite eventos externos importados y estados de coincidencia como coincidente (matched), coincidente parcialmente (partially matched), no coincidente (unmatched), duplicado (duplicate), discrepancia de importe (amount mismatch) y requiere revisión (needs review). Las diferencias de conciliación deben generar registros de excepciones explícitos o asientos contables. Nunca deben reescribir silenciosamente el historial del libro mayor. El enfoque de Nordlet para la conciliación bancaria y el emparejamiento de pagos se basa en este principio: los extractos importados y las exportaciones de Stripe omiten todo lo que ya se haya importado, las sugerencias de pago se puntúan por importe, referencia, contraparte y código IBAN, el emparejamiento con un solo clic gestiona los casos rutinarios y las excepciones se muestran de forma destacada en lugar de quedar ocultas.

Límites de la UE que la API debe respetar y los que no puede

Aquí es donde las afirmaciones comerciales tienden a distanciarse de la realidad. Un libro mayor ayuda a cumplir las obligaciones con la UE, pero no las satisface por sí solo.

IVA. El libro mayor debe preservar las dimensiones relevantes para los impuestos: jurisdicción, tipo impositivo, categoría fiscal y la forma en que se determinó el tipo. Debe distinguir la venta del vendedor al comprador de la comisión del 'marketplace', y separar el IVA de las comisiones de los importes que simplemente están de paso. Nordlet gestiona los cálculos de IVA por país, la validación en el sistema VIES y la generación del registro i.SAF, junto con los escenarios OSS e IOSS con los que se encuentran los 'marketplaces' en la UE. Considere el libro mayor como un registro probatorio y un motor fiscal, no como asesoramiento fiscal.

DAC7. Las normas de información para plataformas exigen vínculos fiables entre la identidad del vendedor, la jurisdicción, los totales de las transacciones, las comisiones, los reembolsos y las liquidaciones. Un libro mayor equilibrado produce la prueba de la transacción. No determina si un vendedor está sujeto a declaración y no sustituye los procesos de conocimiento del cliente (KYC), incorporación (onboarding) ni el flujo de trabajo de presentación de informes. Mantenga la contabilidad de transacciones y la presentación de informes normativos como asuntos separados.

PSD2 y custodia de fondos. Registrar movimientos de dinero no es lo mismo que ser un proveedor de servicios de pago autorizado o custodiar fondos. El libro mayor debe explicitar el flujo de fondos y las partes implicadas. No puede proporcionar por sí solo la autorización para servicios de pago ni demostrar que el efectivo se encuentra en una cuenta determinada. Eso sigue siendo una cuestión de su papel regulador y de su proveedor de servicios de pago (PSP).

RGPD. La inmutabilidad genera una tensión real con los principios de protección de datos. La arquitectura más segura mantiene los datos monetarios en el núcleo inmutable y los datos personales fuera de él. Utilice referencias estables y seudónimas de vendedores y clientes en las líneas de diario. Almacene los datos personales modificables en un sistema independiente con control de acceso y su propio flujo de trabajo de retención y eliminación. "Inmutable" no es una licencia para conservar cada carga útil de pago para siempre.

Una lista de comprobación para evaluar una API de libro mayor

Las etiquetas de las funciones son económicas. Pruebe el comportamiento en un entorno de pruebas (sandbox) en su lugar. Ejecute estos escenarios y verifique los resultados:

• Registre un pedido de 100 € dividido entre el vendedor y el 'marketplace', y confirme que el diario está equilibrado con cuentas explícitas.
• Envíe la misma solicitud dos veces y confirme que se genera una sola transacción, sin duplicados.
• Intente editar un asiento asentado y confirme que se rechaza o que se limita a metadatos no financieros.
• Corrija una comisión errónea y confirme que se genera una reversión vinculada junto con la entrada corregida.
• Emita un reembolso parcial después de la liquidación y confirme que se genera un reembolso rastreable con una cuenta por cobrar del vendedor o un saldo negativo cuando sea necesario.
• Vuelva a enviar un 'webhook' de un proveedor y confirme que se detecta el duplicado.
• Procese una liquidación multidivisa y confirme los detalles del tipo de cambio y la contabilidad de conversión.
• Consulte el saldo de un vendedor al cierre de un periodo y confirme que se obtiene un resultado reproducible con una fecha de corte documentada.
• Importe una liquidación de un proveedor y confirme el emparejamiento con un estado de excepción que deja el historial intacto.
• Exporte un mes de actividad y confirme que se obtiene un extracto completo, paginado y repetible.

La prueba más sólida es la documentación combinada con una prueba reproducible. Palabras como "en tiempo real", "preparado para auditoría" e "inmutable" no significan nada sin el modelo de datos, la semántica de errores y el comportamiento de retención que hay detrás.

Qué comprobaríamos primero

Si tuviéramos que evaluar mañana una API de libro mayor para un 'marketplace', empezaríamos por dos cosas antes de examinar cualquier otra característica. En primer lugar, demostrar que el saldo de un vendedor se deriva de las líneas de diario y no de un campo modificable, ya que todo lo demás depende de ello. En segundo lugar, volver a enviar el mismo 'webhook' y confirmar que se produce exactamente un único resultado contable. Esas dos pruebas revelan más sobre la calidad del diseño subyacente que cualquier lista de funciones.

A partir de ahí, las consideraciones centradas en la API son importantes para determinar la rapidez con la que su equipo lanza el producto: SDK con tipos definidos, 'webhooks' para eventos como sale_invoice.paid, un entorno de pruebas funcional y el bloqueo de periodos para proteger los meses cerrados. Nordlet se diseñó en torno a este modelo, exponiendo a través de la API el mismo conjunto de funciones que a través de la aplicación, lo que permite a una plataforma gestionar contabilidades listas para auditoría dentro de su propio producto en lugar de acoplar un sistema de pago de terceros. Para obtener una visión más amplia de cómo encaja un libro mayor de este tipo en la infraestructura de un 'marketplace', consulte nuestra guía sobre APIs de libro mayor por partida doble para la contabilidad de 'marketplaces'.

FAQ

¿Garantiza la partida doble que mi contabilidad es correcta?

No. Un libro mayor puede estar perfectamente equilibrado mientras registra asientos en las cuentas incorrectas, aplica el tratamiento de IVA erróneo o atribuye fondos al vendedor equivocado. El equilibrio es un control estructural que detecta errores aritméticos y partes faltantes de una transacción. No dice nada acerca de si la lógica de su negocio asignó el evento correctamente. Por eso las pruebas en el entorno de pruebas (sandbox) con escenarios reales importan más que la mera comprobación del saldo.

¿Es suficiente el libro mayor de un proveedor de pagos para un 'marketplace'?

Por lo general, no. Un PSP realiza un seguimiento de los fondos dentro de su propio sistema, lo que resulta útil para los movimientos y las liquidaciones. Su 'marketplace' todavía necesita sus propios registros de ingresos por comisiones, pasivos con los vendedores, IVA sobre comisiones, reembolsos, reservas, disputas e informes de gestión. Ambos sistemas deben conciliarse, y tratar la perspectiva del proveedor como su contabilidad deja lagunas que salen a la luz en el momento de la auditoría.

¿Necesito 'blockchain' para hacer que un libro mayor sea inmutable?

No. Un almacén relacional de solo adición con permisos de escritura estrictos, flujos de trabajo de corrección controlados, registros de auditoría y copias de seguridad fiables le proporciona inmutabilidad operativa y de auditoría. La tecnología 'blockchain' añade evidencia de manipulación distribuida, pero introduce dificultades de privacidad, rendimiento y corrección que van en contra de los requisitos de contabilidad de la UE y del RGPD. Para la mayoría de los 'marketplaces', resuelve un problema que no tienen.

¿Puede un libro mayor inmutable conservar los datos para siempre en virtud del RGPD?

Conservar los registros contables durante el período exigido por la ley es correcto. Conservar indefinidamente los datos personales completos o las cargas útiles de pago porque el libro mayor es inmutable, no lo es. Mantenga los datos monetarios y las referencias seudónimas en el núcleo inmutable y conserve los datos personales en un sistema independiente con los procedimientos adecuados de retención y eliminación. La inmutabilidad se aplica al evento financiero, no a cada fragmento de datos adjunto a él.