Conceptos básicos del modelo de datos para facturas GST: campos mínimos, manejo de HSN y pantallas administrativas necesarias para generar facturas conformes y simplificar la conciliación.

La mayoría de los problemas con facturas GST no son problemas de "impuesto complejo". Son problemas de datos faltantes o inconsistentes. Una auditoría falla cuando la factura no puede vincularse claramente con lo vendido, a quién, dónde se suministró y cómo se calculó el impuesto.
Un desencadenante común es que el HSN esté ausente, desactualizado o aplicado al nivel equivocado. Los equipos pueden almacenar un HSN en el producto, pero la línea de la factura se crea a partir de un nombre de SKU o variante diferente, por lo que el HSN nunca llega al documento final. Otro problema frecuente es la división de impuestos incorrecta: cobrar IGST cuando debería ser CGST y SGST (o al revés) porque el “lugar de suministro” se adivinó a partir de la dirección de envío sin guardar los códigos de estado usados para la decisión.
Los equipos de finanzas lo sienten de inmediato. La conciliación se convierte en un trabajo diario de limpieza: los totales de la factura no coinciden con el pedido, el pedido no coincide con el resumen de liquidación del gateway de pagos y los reembolsos se transforman en una cadena de notas manuales. Incluso pequeñas diferencias por redondeo entre líneas pueden crear desajustes entre el PDF de la factura, los informes GST y el libro contable.
Estos son los patrones que causan la mayoría de los dolores por desajustes:
El objetivo de un modelo de datos de factura GST es simple: almacenar un conjunto mínimo de campos de pedido, producto, partes, impuestos, factura y nota de crédito para que cada número pueda reproducirse y explicarse después. Mantenlo pequeño, pero no elimines campos legalmente importantes que determinan tipo de impuesto, tasa e informes.
Si quieres que las facturas GST sean fáciles de generar y conciliar más tarde, empieza con un conjunto pequeño de objetos y haz que cada uno haga una sola tarea. Un modelo de datos limpio para facturas GST tiene menos que ver con muchas tablas y más con mantener los hechos estables a lo largo del tiempo.
Estos son los registros principales que la mayoría de equipos necesita desde el día uno:
Una Invoice debe estar separada de un Order. Los pedidos pueden cambiar (dirección editada, ítems cancelados, cumplimiento parcial). Las facturas no deberían. Necesitan numeración estable, fechas y totales que nunca “deriven” porque alguien actualizó un pedido después.
El ancla para la precisión fiscal son las Line Items. Cada línea de pedido (y luego cada línea de factura) debe tener la cantidad exacta, precio unitario, descuento y desglose de impuestos para ese artículo específico. Ahí es donde se aplican realmente HSN/SAC y las tasas GST.
Un detalle que ahorra trabajo al equipo financiero: guarda snapshots. Cuando generes una factura, copia la descripción del producto, HSN/SAC, la tasa de impuesto y el precio en las líneas de la factura. No dependas del maestro de producto actual, porque las tasas y nombres cambian.
Opcional pero a menudo recomendable: añadir pronto registros separados para Returns, Refunds y Credit Notes. Ejemplo: si un cliente devuelve un artículo de un pedido de dos artículos, quieres una nota de crédito que haga referencia a la línea de la factura original, mientras que el registro de reembolso referencia la transacción del gateway. Mantener estos como objetos explícitos evita “arreglos manuales” al cierre de mes en los registros GST.
Si construyes esto en Koder.ai, trata cada objeto como una pantalla simple primero (crear, ver, editar) y añade la generación de facturas sólo después de que los snapshots y campos a nivel de línea estén en su lugar.
HSN (para bienes) y SAC (para servicios) no son detalles “solo de factura”. Empiezan en la definición del producto o servicio y luego se copian a cada línea de factura en el momento de emitirla. Esto mantiene correctos los carritos mixtos y facilita las auditorías porque cada línea se sostiene por sí misma.
Un modelo de datos mínimo práctico es:
Poner HSN/SAC en el Product ayuda a tu equipo administrativo a mantenerlo en un solo lugar. Copiarlo a InvoiceLine es lo que hace que las facturas pasadas sean estables. Incluso si el producto cambia después, la factura sigue mostrando lo que fue cierto en el momento de la venta. Este es el corazón de un modelo de datos de factura GST que no se rompe durante la conciliación.
Para el almacenamiento de HSN, mantenlo simple: code es obligatorio, description es opcional y una effective_from date es opcional si quieres un historial de cambios. La mayoría de equipos no necesita la descripción en cada línea, pero puede ayudar cuando finanzas revisa excepciones.
Los carritos mixtos son normales: una factura puede tener múltiples líneas y por tanto múltiples códigos HSN/SAC. No trates de forzar un código por factura. Los totales se consolidan a nivel de factura, mientras la clasificación permanece a nivel de línea.
La gestión de cambios es donde la gente se complica. Usa un conjunto de reglas pequeñas:
En pantallas administrativas, sólo necesitas un lugar para editar los campos fiscales del Product, más una vista de solo lectura en la línea de la factura para confirmar lo que se capturó al crear la factura. Si construyes estas pantallas rápidamente, herramientas como Koder.ai pueden generar las páginas CRUD básicas y tablas de datos desde este modelo con esfuerzo mínimo.
Un modelo de datos de factura GST falla con mayor frecuencia en los detalles de las partes. Si la identidad del comprador o vendedor está aunque sea ligeramente equivocada, tu factura puede ser válida en papel pero problemática en las declaraciones y conciliaciones.
Empieza tratando a “seller”, “buyer” y “ship-to” como partes separadas, aunque sean la misma persona. Esto evita soluciones improvisadas cuando un cliente añade una dirección de envío diferente o cuando vendes desde más de una inscripción GST.
Mantén los campos aburridos y explícitos. Estos son los que normalmente se necesitan en la factura y en los informes:
Almacena el estado tanto como nombre legible como código de estado, porque los informes y las reglas de lugar de suministro a menudo dependen del código.
Captura direcciones de facturación y envío en el pedido, no sólo en el perfil del cliente. Los perfiles cambian; las facturas no deberían.
El lugar de suministro debe guardarse como un código de estado específico en la factura (copiado del pedido al momento de facturar). No lo “recalcules” luego. Si tu regla es “estado del envío”, guarda ese resultado, además del estado usado para decidirlo. Esto facilita auditorías y disputas.
Para B2B, el GSTIN del comprador normalmente es obligatorio y debe validarse en longitud y formato al ingresarlo. Para B2C, el GSTIN puede quedarse vacío, pero aún necesitas una dirección completa y el estado para determinar si aplica CGST/SGST o IGST.
Una regla simple que funciona en la mayoría de sistemas: si el GSTIN del comprador está presente, trata como B2B; si no, trata como B2C. Si necesitas excepciones, almacena un campo explícito customer_type.
Si tienes sucursales o unidades con diferentes registros GST, modela “Seller Entity” como su propio registro con su GSTIN y dirección. Cada pedido debe referenciar exactamente una entidad vendedora, y cada factura debe copiar esos detalles para que las facturas históricas sigan siendo exactas aunque la dirección del vendedor cambie más tarde.
Herramientas como Koder.ai pueden generar rápidamente los formularios administrativos para estos registros, pero la clave es la estructura: entidad vendedora separada, snapshots al tiempo del pedido y un código de estado explícito para lugar de suministro.
La división más común es simple: si el lugar de suministro está en el mismo estado que el proveedor, el impuesto es CGST + SGST. Si está en un estado diferente, el impuesto es IGST. Tu sistema no debería “recalcular más tarde a partir de totales” porque pequeñas diferencias (redondeo, descuentos, envío) son precisamente las que causan desajustes.
Como mínimo, almacena números de impuestos a nivel de línea de factura, no sólo en el encabezado. Así podrás explicar cada rupia en la factura y vincularla al producto, HSN y la cuenta de ingresos.
Un mínimo práctico por línea de factura en tu modelo de datos GST se ve así:
Los descuentos son donde los sistemas se enredan. Decide una regla y guárdala claramente. Si los descuentos reducen el precio antes de impuestos (típico para descuentos por artículo y cupones), guarda el importe bruto original, el monto del descuento y el valor imponible resultante. Si tienes un cupón a nivel de pedido, asígnalo a las líneas (habitualmente proporcional al valor imponible previo de cada línea) y almacena el descuento asignado a cada línea para que la matemática fiscal siga siendo explicable.
El redondeo debe ser consistente y registrado. Elige si redondeas a nivel de línea o sólo a nivel de factura, luego almacena los resultados redondeados que imprimiste. Muchos equipos calculan impuestos por línea, redondean a 2 decimales, suman y luego aplican un campo final invoice_rounding_adjustment para alcanzar el importe exacto a pagar.
Envío y manipulación no deben ser un complemento oculto. Trátalos como una línea de factura separada con su propio HSN/código de servicio y reglas de tasa impositiva. Por ejemplo, un pedido con dos productos y una tarifa de envío se convierte en tres líneas, cada una con valor imponible y componentes de impuestos almacenados, haciendo la conciliación financiera mucho más sencilla.
Una vez calculado el impuesto, la factura todavía necesita campos de “documento” que la validen, la hagan auditable y fácil de conciliar más tarde. En un modelo de datos de factura GST, trata el encabezado de la factura como un registro legal: debe ser estable aunque cambien datos de producto o cliente en el futuro.
Comienza con lo básico del encabezado: número de factura, fecha de emisión (la fecha que aparece en la factura), tipo de factura (tax invoice, export, B2B, B2C, etc.) y moneda. Incluso si facturas mayoritariamente en INR, almacenar la moneda evita casos engorrosos en exportaciones o marketplaces multimoneda.
La numeración es donde los equipos se queman. Mantén una serie o prefijo (por ejemplo “FY25-INV-”), almacena el año fiscal y aplica unicidad en la base de datos. También guarda controles de “next number” por serie en admin para que dos administradores no puedan emitir el mismo número al mismo tiempo.
Los totales deben almacenarse explícitamente, no solo derivados. Guarda subtotal (valor imponible), impuesto total y total general, además de un monto separado de redondeo. Si vuelves a recalcular desde las líneas, un pequeño cambio de regla puede hacer que facturas antiguas dejen de coincidir con la declaración presentada.
Los estados deben reflejar el ciclo real y bloquear el registro cuando sea necesario:
Finalmente, almacena metadatos del artefacto generado: versión de la plantilla PDF, timestamp de generación e identificador de archivo. Un hash es opcional, pero útil si necesitas probar que el PDF no fue alterado.
Ejemplo: si un agente de soporte regenera un PDF tras una actualización de la plantilla, los totales y el número de la factura deben permanecer idénticos, pero la versión de plantilla almacenada explica por qué el diseño del PDF se ve diferente.
Si quieres facturas GST limpias, no empieces en la pantalla de facturas. Empieza por las páginas administrativas que la alimentan. Un buen modelo de datos de factura GST se mantiene pequeño cuando estas entradas están controladas y son consistentes.
El maestro de producto es donde nacen la mayoría de desajustes futuros, así que mantenlo estricto. Cada SKU debería tener exactamente un HSN por defecto (o SAC para servicios), además de una tasa GST por defecto y cualquier excepción que aplique sólo en determinadas fechas.
Una pantalla práctica de producto suele necesitar:
Evita una UI tipo “calculadora”. En su lugar, guarda entradas que tu sistema pueda aplicar de forma consistente: tablas de tasas, reglas de lugar de suministro que sigues y cómo decides intra-state vs inter-state (habitualmente comparando el estado del proveedor y el estado del envío).
Mantén la pantalla de impuestos enfocada en: tasa por categoría/grupo HSN, fechas efectivas y qué debe pasar cuando el comprador proporciona un GSTIN válido vs no lo hace.
La pantalla de cliente debe capturar GSTIN y su estado de validación, además de direcciones de facturación y envío por defecto. No permitas que los usuarios escriban estados libremente; usa una lista controlada para que “KA” y “Karnataka” no se conviertan en dos valores distintos.
La pantalla de perfil de la empresa es igual de importante: nombre legal, GSTIN, dirección registrada y ajustes de serie de facturación (prefijo, siguiente número y límites del año fiscal). Bloquea esto con permisos porque los cambios afectan a todos los documentos futuros.
No necesitas un sistema complejo, pero sí una traza. Registra quién cambió HSN/SAC, tasas GST, ajustes de series de facturas o GSTIN de la empresa, junto con el valor antiguo, el nuevo, timestamp y motivo.
Si construyes estas pantallas en una herramienta como Koder.ai, trata el logging de auditoría y las fechas efectivas como campos de primera clase desde el día uno. Cuestan poco agregarlos temprano y ahorran horas durante la revisión financiera.
Una factura conforme tiene menos que ver con formato bonito y más con congelar los hechos correctos en el momento adecuado. Si diseñas tu modelo de datos de factura GST alrededor de este flujo, el trabajo de finanzas se convierte en una simple conciliación, no en una investigación semanal.
Antes de calcular impuestos, fija un snapshot del pedido: ítems, cantidades, precios unitarios, descuentos, cargos de envío/manipulación, GSTIN del cliente (si lo hay), direcciones de facturación y envío y señales de lugar de suministro. El snapshot no debe cambiar aunque el precio del producto o el mapeo HSN cambien después.
Calcula impuestos y genera líneas de factura desde el snapshot. Cada línea de factura debe copiar el HSN/SAC, la(s) tasa(s) de impuesto, el valor imponible y los importes de impuestos usados en ese momento, en lugar de buscarlos en vivo más tarde.
Asigna el número de factura y la fecha de emisión, luego marca la factura como emitida. A partir de ese punto, bloquea ediciones en precios, tasas impositivas, códigos HSN y direcciones sobre el registro de la factura. Si necesitas permitir algo, limítalo a notas no financieras y etiquetas internas.
Genera el PDF/vista de impresión desde la factura emitida, luego almacena los totales finales que reportarás: total imponible, totales CGST/SGST/IGST, redondeo y total general. Si quieres seguridad extra, guarda una versión del documento o checksum para poder probar que la impresión coincide con los números almacenados.
Después de la emisión, los cambios deben seguir reglas, no ediciones:
Si integras este flujo en tus pantallas administrativas (el modo Planning de Koder.ai es útil para mapear pasos antes de construir), tu equipo podrá generar facturas rápido sin romper la conciliación más adelante.
La conciliación se complica cuando los pagos se tratan como una simple bandera “pagado/no pagado” en el pedido. Mantén pagos y reembolsos como registros separados que apunten al pedido y a la factura, para que finanzas pueda emparejar las liquidaciones bancarias sin reescribir la historia.
Una factura conforme debe permanecer estable tras su emisión. Si un cliente paga en partes o devuelves dinero después, registra ese movimiento como una entrada de pago o reembolso, no como un cambio en los totales de la factura.
Campos mínimos que suelen facilitar la conciliación:
Si el cliente devuelve un artículo, no “reduzcas la factura”. Emite una nota de crédito y enlázala a la factura original. El registro de facturas se mantiene limpio y el reembolso se vincula a la nota de crédito.
Dale a finanzas una pantalla única que responda: qué se emitió, qué se pagó, qué sigue abierto y qué se revirtió. Incluye ageing (0-7, 8-30, 31-60, 60+ días) y la posibilidad de profundizar en los pagos y reembolsos relacionados.
Exportes que la mayoría de equipos necesita cada mes:
Ejemplo: un pedido es Rs 10,000, se paga Rs 6,000 hoy y Rs 4,000 la próxima semana. La factura queda en Rs 10,000. Tu vista financiera muestra saldo Rs 4,000 hasta la segunda liquidación, luego marca como pagada sin alterar el documento emitido.
La mayoría de problemas con facturas GST no son de lógica fiscal. Son de mantenimiento de registros: los números en el PDF no coinciden con lo que exporta finanzas o la factura no puede explicarse meses después.
La primera trampa es calcular GST sólo al verlo. Si calculas CGST/SGST/IGST cada vez que alguien abre una factura, eventualmente obtendrás resultados distintos tras un cambio de tasas, una modificación de redondeo o la corrección de un bug. Almacena el desglose fiscal calculado que se usó cuando se emitió la factura, incluso si también almacenas las entradas.
Una segunda trampa es permitir ediciones a una factura emitida. Una vez finalizada, los cambios deben hacerse mediante una nota de crédito o un flujo de reemplazo con trazabilidad. Si no, verás “¿por qué el PDF del cliente difiere de los libros?”.
Estos son los patrones de desajuste que aparecen con más frecuencia en un modelo de datos de factura GST:
Un ejemplo rápido: vendes a un cliente en Karnataka, pero la dirección de envío está en Maharashtra. Si tu sistema toma por error el estado de facturación para el lugar de suministro, podrías cobrar CGST+SGST en lugar de IGST. Si además recalculas el impuesto dinámicamente, ese error puede “arreglarse” silenciosamente después, dejando a finanzas con números que no coinciden con el documento emitido.
Cuando construyas pantallas administrativas (ya sean personalizadas o con una plataforma como Koder.ai), añade pequeñas salvaguardas: bloquea facturas emitidas, muestra las entradas de lugar de suministro junto al tipo de impuesto calculado y mantén un snapshot inmutable de HSN, tasa y redondeo usados en el momento de la emisión.
Antes de enviar una factura a un cliente o marcarla como “emitida”, ejecuta un conjunto rápido de comprobaciones. Aquí es donde la mayoría de pequeños errores se convierten en grandes dolores de cabeza de conciliación. Si estás construyendo un modelo de datos de factura GST, vale la pena incluir estas comprobaciones tanto en las reglas de validación como en la UI administrativa.
Un ejemplo simple: un cliente actualiza su dirección de envío después del pago y cambia el estado. Si vuelves a emitir la misma factura con nuevo impuesto, tu registro y los pagos dejan de coincidir. El enfoque más seguro es mantener la factura original inmutable y crear un documento de ajuste.
Siguientes pasos: implementa las pantallas y validaciones primero, luego itera. En Koder.ai, comienza en Planning Mode para bosquejar los registros y pantallas administrativas (productos con mapeo HSN/SAC, detalles de cliente/GSTIN, reglas fiscales y facturas). Genera la app, prueba algunos pedidos reales de punta a punta y luego usa snapshots y rollback para refinar el flujo con seguridad. Cuando necesites personalizaciones más profundas o revisiones, exporta el código fuente y continúa evolucionándolo con tu proceso habitual.