Me cansé de llenar facturas a mano, así que construí una API que genera facturas proforma, notas de débito y crédito desde JSON

El momento que finalmente rompió la rutina fue una tarde de martes mirando fijamente tres plantillas de facturas separadas abiertas en tres aplicaciones separadas. Una empresa necesitaba una factura de IVA estándar para un cliente en Alemania. Otra necesitaba una factura proforma para un arreglo de prepago con un distribuidor. La tercera necesitaba una nota de crédito para corregir una sobrefacturación del trimestre anterior. Tres empresas, tres tipos de documentos, tres flujos de trabajo completamente diferentes, y aproximadamente dos horas de entrada de datos manual antes de que alguno de ellos estuviera listo para enviar. Los números ya estaban calculados. Los detalles del cliente ya eran conocidos. Los artículos de línea estaban en una hoja de cálculo. Sin embargo, el proceso real de poner esos números en un PDF correctamente formateado y diseñado profesionalmente se sentía como transcribir una novela a mano cuando había una impresora sentada justo en el escritorio.

Esta no fue una molestia de una sola vez. Fue el ritual mensual. Cada ciclo de facturación trajo la misma secuencia tediosa: abrir la plantilla, actualizar el número de factura manualmente (y verificar dos veces que la secuencia no hubiera sido reutilizada accidentalmente), completar la dirección del cliente, copiar artículos de línea uno por uno, verificar los cálculos fiscales, exportar a PDF y enviar. Multiplique eso por tres empresas con marca diferente, tasas de IVA diferentes, secuencias de numeración diferentes y requisitos legales diferentes, y el proceso de facturación mensual consumía la mayor parte de un día de trabajo. Un día completo cada mes dedicado a una tarea que era pura formatización de datos sin valor creativo o estratégico.

Las herramientas que existían no estaban resolviendo el problema correcto. QuickBooks, FreshBooks, Zoho Invoice y el resto todos querían convertirse en la columna vertebral contable completa del negocio. Querían conexiones bancarias, seguimiento de gastos, integración de nómina y una suscripción mensual por el privilegio. Lo que se necesitaba era mucho más simple: enviar datos estructurados, obtener un PDF hermosamente formateado. Nada más. Sin panel de control, sin libro mayor, sin asistente de doce pasos. Solo una función que acepte JSON y devuelva un documento.

Tres empresas y el desorden que crea la facturación mensual

Dirigir múltiples empresas no es tan glamoroso como suenan los posts de LinkedIn. Los gastos operativos se multiplican de formas que no son inmediatamente obvias, y la facturación es uno de los culpables más astutos. Cada empresa tiene su propia entidad legal, su propio número de identificación fiscal, sus propios detalles bancarios, su propio logo y su propia base de clientes. Una herramienta de facturación única que funciona perfectamente para una empresa puede ser completamente incorrecta para otra porque la estructura de IVA es diferente, o porque una empresa factura en euros mientras que otra factura en moneda local, o porque los requisitos del pie de página legal cambian según la jurisdicción de incorporación.

El enfoque manual implicaba mantener plantillas de documentos de Word para cada empresa. Estas plantillas fueron meticulosamente formateadas con logos, opciones de fuentes, acentos de color y campos cuidadosamente posicionados. Actualizarlas fue una pesadilla. Si el número de teléfono de la empresa cambiaba, ese cambio necesitaba propagarse a través de cada variante de plantilla: factura, factura proforma, nota de crédito, nota de débito y recibo. Cinco tipos de documentos multiplicados por tres empresas equivalen a quince plantillas para mantener, y cada una de ellas fue una fuente potencial de errores. Errores tipográficos en detalles bancarios, números de registro de IVA incorrectos, direcciones desactualizadas. Estos no son errores triviales cuando los documentos son registros legales que pueden ser auditados años después.

El problema de la numeración de facturas merece su propio párrafo porque causó consecuencias comerciales reales. La numeración secuencial de facturas es un requisito legal en muchas jurisdicciones. Las brechas en la secuencia generan banderas rojas durante las auditorías. Los duplicados son peores. Mantener secuencias de numeración separadas para tres empresas en cinco tipos de documentos significaba rastrear quince contadores diferentes manualmente. Una hoja de cálculo compartida sirvió como el "sistema de registro" para estas secuencias, y más de una vez la hoja de cálculo se actualizó después de que la factura ya había sido enviada, creando confusión sobre si el número de factura 2024-0047 había sido realmente emitido o aún estaba pendiente. El generador de facturas que finalmente reemplazó este caos maneja la numeración automática por empresa y por tipo de documento, eliminando una categoría completa de errores contables.

También estaba el problema de las relaciones entre documentos. Una factura proforma se emite antes de que comience el trabajo. La factura final hace referencia a esa proforma. Si se necesita una corrección, una nota de crédito hace referencia a la factura original. Una nota de débito hace lo mismo para la subfacturación. Estos documentos forman una cadena, y mantener esa cadena manualmente en documentos de Word y hojas de cálculo es un ejercicio en caos controlado. Un número de referencia mal escrito y el rastro de auditoría se rompe.

Lo que hace la API y por qué JSON cambia todo

La API de facturación acepta una carga útil JSON que contiene todos los datos estructurados que una factura requiere: detalles del vendedor, detalles del comprador, artículos de línea con cantidades y precios unitarios, tasas impositivas, moneda, condiciones de pago, notas y metadatos de documentos como el número de factura y la fecha de emisión. Procesa esa carga útil y devuelve un documento PDF completamente renderizado. El viaje completo toma segundos. Sin plantillas para abrir, sin campos para completar, sin cálculos manuales para verificar.

Cinco tipos de documentos se admiten desde la misma familia de endpoints. Una factura estándar es la más común, pero el generador de facturas proforma maneja escenarios de prepago donde el documento necesita verse y sentirse como una factura sin llevar el peso legal de una. Las notas de crédito manejan reembolsos y correcciones haciendo referencia al número de factura original y mostrando los montos ajustados. Las notas de débito manejan el caso opuesto, donde se deben documentar cargos adicionales después de que se emitió la factura original. Los recibos confirman que se recibió el pago, cerrando el ciclo de la transacción. Los cinco tipos comparten la misma estructura JSON con variaciones menores, lo que significa que el trabajo de integración se realiza una vez y cada tipo de documento viene de forma gratuita.

El enfoque JSON es lo que hace que el sistema sea genuinamente útil en lugar de ser solo otra herramienta de facturación con una API atornillada como pensamiento tardío. Debido a que la entrada son datos estructurados en lugar de campos de formulario, puede venir de cualquier lugar. Una plataforma de comercio electrónico puede generar automáticamente facturas cuando se envía un pedido. Un CRM puede desencadenar una factura proforma cuando un trato se mueve a una etapa específica. Un exportación de hoja de cálculo puede transformarse en un lote de facturas con un script simple. La fuente de datos no importa. Siempre que pueda producir JSON válido, la API producirá documentos válidos. Esta composabilidad es la ventaja fundamental sobre el software de facturación tradicional, que asume que un humano siempre estará sentado frente a un formulario haciendo clic en botones.

Una de las integraciones más satisfactorias conecta la API de facturación con un escáner de documentos. Las facturas entrantes de los proveedores se escanean y se analizan para extraer artículos de línea, montos y detalles del proveedor. Esos datos extraídos se alimentan directamente a la API de facturación para generar los documentos salientes correspondientes, ya sea un recibo de pago coincidente o una nota de crédito que dispute un cargo. El bucle desde papel a datos estructurados a documento generado se cierra sin entrada de datos manual en ningún punto de la cadena.

Cinco tipos de documentos y cuándo importa cada uno

La distinción entre estos cinco tipos de documentos es algo que muchos dueños de pequeños negocios aprenden de la manera difícil, generalmente cuando un contador o autoridad fiscal señala que se usó el tipo incorrecto. Una factura proforma no es un documento fiscal. Emitir una cuando se requería una factura estándar puede crear problemas de cumplimiento. Conversamente, emitir una factura completa antes de que se entreguen los bienes o se presten los servicios puede crear problemas de reconocimiento de ingresos. Entender qué tipo usar y cuándo es esencial, y tener un sistema que admita los cinco sin requerir cinco herramientas separadas o cinco flujos de trabajo separados elimina una fuente significativa de fricción.

Una factura estándar es el documento que la mayoría de las personas piensan cuando escuchan la palabra "factura". Es una solicitud legal de pago que registra una transacción completada. Lleva un número secuencial único, los detalles legales completos de ambas partes, un desglose de artículos de línea, impuestos aplicables e instrucciones de pago. Es el documento que se presenta con declaraciones de impuestos y se produce durante auditorías. La API de facturación genera estos con todos los campos requeridos completados a partir de la entrada JSON, incluidos totales calculados, desgloses fiscales y valores de moneda formateados. Nada se deja para que el usuario calcule manualmente.

Una factura proforma se ve casi idéntica pero sirve un propósito diferente. Es una cotización disfrazada de factura, utilizada para formalizar un acuerdo de precio antes de que ocurra la transacción. El comercio internacional se basa en gran medida en facturas proforma para declaraciones aduanales y permisos de importación. Los autónomos las utilizan para solicitar depósitos antes de comenzar el trabajo. La diferencia clave es que una proforma no entra en el libro mayor de contabilidad como ingresos hasta que se emite una factura final correspondiente. La API maneja esta distinción marcando claramente el tipo de documento en el encabezado y ajustando el lenguaje de los términos de pago en consecuencia, por lo que nunca hay ambigüedad sobre si un documento es una factura vinculante o una estimación preliminar.

Las notas de crédito y las notas de débito son documentos correctivos, y son donde los procesos de facturación manual se colapsan más espectacularmente. Una nota de crédito reduce el monto adeudado por el comprador, típicamente porque se devolvió un producto, hay un error de precio o se aplicó un descuento negociado después de que se emitió la factura original. Una nota de débito aumenta el monto adeudado, tal vez porque se prestaron servicios adicionales o porque la factura original bajo facturación debido a un error de cálculo. Ambos tipos deben hacer referencia al número de factura original, y ambos deben fluir a través del sistema contable para ajustar el saldo pendiente. Generar estos manualmente significa abrir la factura original, encontrar su número, crear un nuevo documento con el formato correcto, ingresar los montos de ajuste y asegurarse de que la cadena de referencia esté intacta. La API maneja todo esto a partir de una única carga útil JSON que incluye la referencia del documento original.

Los recibos son el tipo más simple pero sorprendentemente ausentes de la mayoría de las herramientas de facturación. Un recibo confirma que se recibió el pago. Hace referencia a la factura que se pagó, establece el monto y la fecha del pago, y sirve como prueba de transacción para el comprador. Muchos negocios saltan los recibos por completo y se basan en confirmaciones de transferencia bancaria, pero en industrias intensivas en efectivo o en jurisdicciones donde se requieren recibos oficiales para deducciones fiscales, tener una capacidad adecuada de generación de recibos no es opcional. La API genera recibos que coinciden con la marca visual de las facturas correspondientes, manteniendo una apariencia consistente en todos los documentos emitidos por la misma empresa.

Numeración automática y la cordura que preserva

La función de numeración automática por sí sola justificó todo el esfuerzo de desarrollo. Cada empresa mantiene su propia secuencia de numeración. Cada tipo de documento dentro de esa empresa mantiene su propia subsecuencia. Los números de factura siguen un patrón, las facturas proforma siguen otro, y las notas de crédito siguen un tercero. Las secuencias se incrementan automáticamente con cada documento generado, y el formato es configurable: algunas empresas prefieren una secuencia numérica simple como 001, 002, 003, mientras que otras quieren un prefijo de año como 2026-001, y aún otras quieren un prefijo de código de empresa como ABC-INV-001. La API acomoda todos estos formatos a través de una cadena de plantilla en la configuración de la empresa, y el contador real se gestiona del lado del servidor, por lo que hay cero riesgo de números duplicados o brechas accidentales.

Esto puede sonar como un detalle menor, pero para cualquiera que alguna vez haya tenido que explicar una brecha en su secuencia de facturación a un inspector fiscal, es cualquier cosa menos menor. En varios países europeos, las brechas en la numeración de facturas se tratan como evidencia presuntiva de ingresos no declarados. La carga de la prueba se desplaza hacia el negocio para demostrar que la brecha fue accidental en lugar de un intento de ocultar una transacción. Un contador automatizado y gestionado por el servidor elimina completamente este riesgo. Cada número es secuencial, cada número se usa, y el rastro de auditoría se mantiene por el sistema en lugar de por un humano con una hoja de cálculo y una memoria imperfecta.

El sistema de numeración también maneja la relación entre tipos de documentos. Cuando se emite una nota de crédito contra la factura 2026-042, la nota de crédito lleva su propio número en su propia secuencia (digamos, CN-2026-008), pero también almacena la referencia a la factura original. Esta referencias cruzada es automática cuando el ID de la factura original se incluye en la carga útil JSON. El PDF de nota de crédito generado muestra ambos números de manera prominente, haciendo que el rastro de papel sea inmediatamente claro para cualquiera que revise los documentos más tarde, ya sea el departamento de cuentas por pagar del comprador, un auditor externo o el propietario del negocio tratando de reconciliar los libros seis meses después.

Por qué esto se convirtió en más que una solución personal

Lo que comenzó como una solución a una molestia personal de facturación se convirtió en algo considerablemente más amplio cuando quedó claro que el problema era universal. Cada autónomo, cada pequeña agencia, cada fundador solitario que dirige múltiples empresas enfrenta alguna versión del mismo desafío. Las herramientas existentes son demasiado complejas (suites de contabilidad completas que requieren semanas de configuración y mantenimiento continuo) o demasiado simples (plantillas de facturas gratuitas que son esencialmente documentos de Word glorificados sin automatización). El punto medio, una herramienta que sea lo suficientemente poderosa para manejar múltiples empresas y tipos de documentos pero lo suficientemente simple para integrarse con una única llamada de API, simplemente no existía.

La API se encuentra en ese punto medio por diseño. No intenta ser un sistema de contabilidad. No rastrea pagos, gestiona gastos ni concilia extractos bancarios. Hace exactamente una cosa: transformar datos estructurados en documentos financieros formateados profesionalmente. Ese enfoque estrecho es lo que la hace confiable y lo que la hace composable con cualquier otro sistema que un negocio ya está usando. Canaliza datos de Notion, de Airtable, de un CRM personalizado, de un webhook de Shopify, de un trabajo cron que lee una base de datos. La API no importa de dónde vienen los datos. Le importa que los datos sean JSON válido con los campos requeridos, y devuelve un PDF que está listo para enviar.

El plan a futuro implica construir una aplicación SaaS de facturación completa sobre esta API, completa con un panel para administrar empresas, clientes e historial de documentos. Pero la API seguirá siendo la base, porque la lección aprendida de años de frustración con otras herramientas es que la interfaz nunca debería ser el cuello de botella. Cuando los datos están listos, el documento debe estar listo. Sin hacer clic en formularios, sin seleccionar valores desplegables que el sistema ya conoce, sin esperar a que se cargue una página para que se pueda presionar el botón "Generar PDF". JSON adentro, PDF afuera, factura lista.