El dueño de un hosting concilió 166 movimientos pendientes en QuickBooks con scripts creados en Claude Code

En dos frases

Ryan Davis, propietario de una pequeña empresa de alojamiento WordPress gestionado, usó Claude Code para escribir tres herramientas en Python que convierten cada liquidación de Stripe en un depósito bien estructurado en QuickBooks Online, de forma que la fuente bancaria se concilia con un clic por línea. Según él, le llevó unas ocho horas, resolvió 166 movimientos pendientes antes de la campaña fiscal y ahora lo ejecuta cada semana.

Quién lo hace y por qué interesa

Davis vive en Binghamton (Nueva York) y es dueño de tres empresas web: Lucky Tyke (desarrollo de webs WordPress), WebOps Hosting (alojamiento gestionado, 125 sitios según su web) y Osita (marketing en buscadores). Como muchos pequeños empresarios, lleva él mismo la contabilidad en QuickBooks Online. Sus clientes pagan facturas emitidas desde WHMCS, un sistema de facturación habitual entre proveedores de alojamiento, y la mayoría lo hace con tarjeta a través de Stripe.

Merece estar en este directorio por tres motivos:

• Es un problema que tiene casi cualquier negocio online. Las pasarelas de pago no liquidan factura a factura. Stripe agrupa varios cobros en una sola liquidación, descuenta sus comisiones y transfiere el neto. El banco muestra 1.443,19 dólares; la contabilidad, unas cuantas facturas de importes redondos. Cuadrarlo a mano es lento, y es la razón por la que tantas pymes tienen la bandeja de movimientos bancarios «pendientes de revisar» llena.
• Es de primera mano y concreto. El artículo nombra las herramientas, los comandos, el orden de las llamadas, lo que no funcionó y cuánto tardó. Nadie vende nada: sus negocios son servicios web, no software contable.
• La IA se usa para construir, no para decidir. Claude Code escribió y depuró la integración, pero los scripts son deterministas. Ningún modelo lee el extracto y adivina una cuenta. Es un patrón que conviene copiar en contabilidad, donde la misma entrada debe producir siempre el mismo asiento.

El problema en detalle

Davis explica por qué los ingresos no se podían emparejar directamente:

1. Comisiones. Una factura de 100 dólares pagada con tarjeta llega como 96,80, porque Stripe se queda el 2,9 % más 0,30 dólares (sus cifras, que coinciden con la tarifa estándar de Stripe para tarjetas en Estados Unidos).
2. Agrupación. Varias facturas llegan en una sola liquidación.
3. Devolución de un préstamo. Tiene un préstamo de Stripe Capital, y Stripe retiene parte de sus ventas para devolverlo. La documentación de Stripe confirma el mecanismo: la devolución es un porcentaje de las ventas en Stripe (la «repayment rate»), con pagos mínimos en el caso de los préstamos.

Hacerlo a mano suponía, para cada ingreso: buscarlo en la fuente bancaria, localizar la liquidación en el panel de Stripe, abrir las facturas que incluía, calcular las comisiones y crear en QuickBooks una transacción desglosada. Tenía más de 50 liquidaciones por hacer.

Herramientas y arquitectura

Su primera idea fue que un script trabajara directamente sobre la fuente bancaria de QuickBooks. Claude Code investigó la API y concluyó que los movimientos de la bandeja «For Review» no están disponibles en la API de QuickBooks Online, porque Intuit recibe los datos bancarios a través de agregadores. Nuestra comprobación lo matiza: una pregunta pública en el foro de desarrolladores de Intuit describe un endpoint bankfeedtransaction que responde «Operation bankfeedtransaction is not supported» salvo que Intuit active una beta para la aplicación. En la práctica, para una pyme, la conclusión de Davis se mantiene: no se puede contar con automatizar esa bandeja.

Así que cambió de objetivo. En vez de clasificar las líneas del banco, creó las transacciones que QuickBooks necesita para proponer el emparejamiento. En un fin de semana, trabajando con Claude Code, montó tres herramientas de línea de comandos que se llaman entre sí:

• stripe.py devuelve el desglose completo de una liquidación: qué cobros incluye, las comisiones por tipo y las retenciones de Capital. Stripe documenta exactamente esto: en las liquidaciones automáticas se pueden listar los movimientos de saldo (balance transactions) de un identificador de liquidación (po_…) y expandir cada uno hasta su cobro o devolución.
• mercury.py busca el ingreso correspondiente en su cuenta de empresa de Mercury por importe y fecha, para confirmar que el dinero llegó de verdad.
• qbo.py crea en QuickBooks Online un depósito que enlaza los cobros ya registrados de esas facturas, lleva las comisiones a una cuenta de gasto llamada «Payment Processing Fees» y anota el identificador de la liquidación de Stripe en una nota privada.

El comando reconcile los encadena en cinco pasos: obtener la liquidación de Stripe; leer los números de factura de WHMCS en la descripción de cada cobro; conectarse por SSH a su servidor WHMCS para obtener los identificadores de cobro de QuickBooks de esas facturas; saltarse los cobros que ya estén depositados; y crear el depósito con la API de QuickBooks.

Un módulo común, lib/credentials.py, desbloquea una vez por sesión una bóveda de Bitwarden y entrega las claves de API a todos los scripts, de modo que ninguna clave queda escrita en el código.

Paso a paso para replicarlo

Davis comparte el diseño, no el código. Los pasos siguientes siguen su diseño; cuando añadimos algo, lo indicamos.

1. Asegúrate de que las facturas y los cobros ya están en la contabilidad. Su flujo da por hecho que cada factura cobrada ya existe en QuickBooks como cobro pendiente de depositar (en su caso lo vuelca WHMCS). Si tus cobros no están registrados, resuelve eso antes.
2. Usa un entorno de pruebas y credenciales limitadas (añadido nuestro). Crea una empresa de pruebas (sandbox) en QuickBooks y claves restringidas de Stripe antes de dejar que un agente de programación llame a nada. Guarda las claves en un gestor, como hace Davis, no en archivos.
3. Escribe el desglose de Stripe. Para cada liquidación automática, lista sus movimientos, expande el objeto de origen y clasifica cada línea: cobro, devolución, comisión, retención del préstamo u otra. Stripe no puede hacerlo con las liquidaciones manuales.
4. Encuentra el vínculo con tus facturas. Davis extrae el número de factura de la descripción del cobro. Si tus descripciones o metadatos no lo llevan, corrígelo primero en tu sistema de facturación: es la clave de todo lo demás.
5. Confirma el ingreso en el banco. Busca el neto y la fecha en el banco (con la API de Mercury en su caso; un extracto exportado también sirve) y detente si no coinciden.
6. Crea un depósito por liquidación. Líneas enlazadas a los cobros existentes, más líneas negativas para comisiones y cualquier otra retención, de modo que el total del depósito sea igual al importe del banco. Anota el identificador de la liquidación en el concepto o la nota privada.
7. Hazlo idempotente. Comprueba si cada cobro ya está en un depósito antes de crear otro; Davis lo hace para evitar duplicados.
8. Deja el emparejamiento final a una persona. En QuickBooks, la fuente bancaria propone el depósito que acabas de crear y tú lo confirmas con un clic. Ese clic es la revisión.
9. Prográmalo. Davis ejecuta ahora reconcile cada semana y genera cada mes la cuenta de resultados con qbo.py pnl.

Un encargo inicial para Claude Code (nuestro, no de Davis)

Davis no ha publicado sus prompts. Este encargo es nuestro y está pensado para adaptarlo; los valores entre corchetes son tuyos.

Objetivo: una herramienta de línea de comandos en Python que convierta cada
liquidación automática de Stripe en un único depósito de QuickBooks Online.
Trabaja SOLO contra la empresa de PRUEBAS [ID DE LA EMPRESA SANDBOX] hasta
que yo diga lo contrario.

Entradas
- Clave restringida de Stripe (solo lectura) en [ELEMENTO DE LA BÓVEDA].
- Credenciales OAuth de QuickBooks en [ELEMENTO DE LA BÓVEDA].
- Extracto o API del banco para la cuenta [NOMBRE DE LA CUENTA].

Para cada liquidación entre [FECHA INICIO] y [FECHA FIN]:
1. Lista sus movimientos de saldo y expande el origen de cada uno.
2. Clasifica cada línea: cobro, devolución, comisión de Stripe, retención
   del préstamo, otra. Detente e informa de cualquier tipo nuevo.
3. Asocia cada cobro a un cobro ya registrado en QuickBooks usando
   [CAMPO QUE CONTIENE EL NÚMERO DE FACTURA]. Detente si falta alguno.
4. Omite los cobros que ya estén en un depósito.
5. Comprueba que cobros − devoluciones − comisiones − retenciones = importe
   de la liquidación, y que el banco muestra ese importe en [N] días.
   Detente si no cuadra.
6. Construye el depósito: líneas de cobro enlazadas; líneas negativas para
   comisiones en [CUENTA DE COMISIONES] y para retenciones en
   [CUENTA DEL PRÉSTAMO]; nota privada "Liquidación Stripe [ID]".
7. Por defecto, --dry-run: muestra el depósito como tabla y no lo crees.
   Créalo solo con --apply.

Escribe pruebas con respuestas grabadas de la API para: una liquidación con
un cobro, una con una devolución, una con retención del préstamo y una que
no cuadra. Registra en un archivo el ID de cada petición y respuesta.

Un ejemplo concreto (cifras ilustrativas)

El artículo solo da un importe real, un ingreso de 1.443,19 dólares, sin su desglose. Las cifras siguientes son inventadas para mostrar cómo debería quedar un depósito.

Tres facturas de 100, 250 y 150 dólares se cobran con tarjeta y llegan en una misma liquidación. Las comisiones de Stripe al 2,9 % + 0,30 son 3,20, 7,55 y 4,65: 15,40 en total. Supongamos que la tasa de devolución de Capital es del 8 %, así que se retienen 40,00 de los 500 dólares de ventas. La liquidación, y el ingreso en Mercury, es de 444,60.

El depósito recoge los tres cobros por su importe íntegro, de modo que ventas y clientes quedan en bruto; las comisiones van a gasto; y la retención va a reducir el préstamo, no a comisiones. El artículo dice dónde lleva las comisiones, pero no dónde registra las retenciones de Capital; las haga como las haga, separarlas es lo que esperará cualquier contable.

Resultados declarados

Todo lo que sigue lo declara Ryan Davis en su artículo; no lo hemos medido nosotros ni un tercero.

• Unas 8 horas de trabajo concentrado para crear las tres herramientas, en un fin de semana.
• Unos 30 segundos para que reconcile procese todas las liquidaciones pendientes de Stripe.
• 166 movimientos conciliados, con la cuenta de resultados lista para su asesor fiscal.
• 20 minutos para obtener y dar formato a la cuenta de resultados anual, una tarea que dice que llevaba semanas aplazando.
• Más de 4 horas al mes de conciliación manual evitadas, según su estimación.
• Lo que falta: número e importe de las liquidaciones, errores detectados después, si un contable revisó los libros y qué modelo o plan usó en Claude Code.

Limitaciones y riesgos

• Una persona, un negocio, un artículo. Es un relato creíble y de primera mano, pero describe una sola empresa estadounidense con una pasarela, un banco y una moneda.
• Acceso de escritura a la contabilidad. Los scripts crean depósitos en su empresa real de QuickBooks. Un fallo genera asientos erróneos a la velocidad de un script. El entorno de pruebas, las ejecuciones en seco y el emparejamiento manual final son los controles.
• El vínculo con las facturas es frágil. Todo depende de que el número de factura aparezca en la descripción del cobro en Stripe. Si un cliente paga fuera del flujo normal o cambia la descripción, la asociación se rompe.
• No todo lo que hay en una liquidación es comisión. También aparecen devoluciones, disputas, retenciones de préstamos y ajustes. Llevarlo todo a «comisiones» falsea los gastos; revisa los tipos de línea en tu propia cuenta.
• Las liquidaciones manuales no se pueden desglosar. Stripe advierte que no puede saber qué transacciones incluye una liquidación manual.
• Particularidades de cada país. La tarifa, Stripe Capital, Mercury y QuickBooks responden al contexto estadounidense. En España, las tarifas de Stripe y el tratamiento fiscal de sus facturas de comisiones son otros: revísalo con tu asesor. La lógica (desglose de la liquidación, cobros enlazados, comisiones aparte, comprobación con el banco) sirve con cualquier programa contable que tenga API para registrar cobros, pero comprueba qué permite la del tuyo antes de diseñar nada.

Errores comunes

• Contabilizar el neto de la liquidación como venta. Oculta las comisiones y deja mal las ventas y los saldos de clientes.
• Dejar que un modelo clasifique libremente las líneas del banco. Para esta tarea son mejores las reglas y los identificadores que las conjeturas; usa la IA para escribir y probar el código.
• No comprobar duplicados. Volver a ejecutar un script sin esa comprobación crea un segundo depósito para la misma liquidación.
• Saltarse la confirmación con el banco. Un depósito contabilizado por un dinero que nunca llegó es peor que una línea sin conciliar.
• Claves escritas en el código. El módulo de credenciales con bóveda de Davis es la opción correcta por defecto.

Conclusiones

Lo valioso de este caso no es que una IA hiciera la contabilidad, sino que un empresario que no es contable usó un agente de programación para construir un puente pequeño y auditable entre su pasarela de pago, su banco y su contabilidad, y se reservó la confirmación final. Cada depósito lleva el identificador de la liquidación, así que cualquier cifra se puede rastrear meses después. Para cualquier negocio que cobre con Stripe u otra pasarela parecida, la receta es reutilizable: obtener el desglose de la liquidación, atarlo a los cobros existentes y al banco, crear un depósito por liquidación y dejar que una persona confirme el emparejamiento.