Modelo de dados de fatura GST: campos mínimos para HSN e pedidos

O que geralmente dá errado com faturas GST

A maioria dos problemas com faturas GST não são problemas de "impostos complexos". São problemas de dados ausentes ou inconsistentes. Uma auditoria falha quando a fatura não pode ser ligada de forma clara ao que foi vendido, para quem, onde foi fornecido e como o imposto foi calculado.

Um gatilho comum é o HSN ausente, desatualizado ou aplicado no nível errado. Equipes podem armazenar um HSN no produto, mas a linha da fatura é criada a partir de outro nome de SKU ou variante, então o HSN nunca chega ao documento final. Outro problema frequente é a divisão incorreta de impostos: cobrar IGST quando deveria ser CGST e SGST (ou o contrário) porque o place of supply foi estimado a partir do endereço de entrega sem armazenar os códigos de estado usados para a decisão.

As equipes de finanças sentem isso imediatamente. A reconciliação vira um trabalho de limpeza diário: totais da fatura não batem com o pedido, o pedido não bate com a liquidação da gateway de pagamento e reembolsos viram uma cadeia de notas manuais. Mesmo pequenas diferenças de arredondamento entre itens podem criar divergências entre o PDF da fatura, relatórios GST e o razão contábil.

Aqui estão os padrões que causam a maior parte da dor de divergência:

• Produto e linhas da fatura não compartilham o mesmo HSN, taxa de GST e campos de valor tributável.
• Imposto é calculado em mais de um lugar (carrinho vs fatura) e os resultados diferem.
• Totais são armazenados apenas como "valor bruto" sem detalhamento para valor tributável e cada componente de imposto.
• Numeração de faturas é editável ou duplicada entre séries.
• Reembolsos são registrados como pedidos negativos em vez de notas de crédito apropriadas.

O objetivo de um modelo de dados de fatura GST é simples: armazenar um conjunto mínimo de campos de pedido, produto, parte, imposto, fatura e nota de crédito para que todo número possa ser reproduzido e explicado depois. Mantenha enxuto, mas não elimine campos legalmente importantes que decidem tipo de imposto, alíquota e obrigações de relatório.

O menor conjunto de registros que você precisa

Se você quer que faturas GST sejam fáceis de gerar e fáceis de reconciliar depois, comece com um conjunto pequeno de objetos e faça cada um cumprir uma função única. Um modelo de dados de fatura GST limpo é menos sobre ter muitas tabelas e mais sobre manter fatos estáveis ao longo do tempo.

Aqui estão os registros principais que a maioria das equipes precisa no primeiro dia:

• Cliente: quem comprou (nome, telefone/email, GSTIN se B2B)
• Endereço: entrega e faturamento, além de estado e sinais de place of supply
• Produto (ou Serviço): o que foi vendido, com unidade, preço base e HSN/SAC padrão
• Pedido: o evento comercial (carrinho, descontos, frete, status)
• Pagamento: como o dinheiro se moveu (referência da gateway, método, valor capturado, data)

Uma Fatura deve ser separada de um Pedido. Pedidos podem mudar (endereço editado, itens cancelados, atendimento parcial). Faturas não deveriam. Elas precisam de numeração estável, datas e totais que nunca "flutuem" porque alguém atualizou o pedido depois.

A âncora para precisão tributária são os Itens de Linha. Cada item de linha do pedido (e depois cada item de linha da fatura) deve conter a quantidade exata, preço unitário, desconto e detalhamento de taxa para aquele item específico. É ali que o HSN/SAC e as alíquotas GST realmente são aplicados.

Um detalhe que salva as equipes de finanças: armazene snapshots. Ao gerar uma fatura, copie a descrição do produto, HSN/SAC, taxa e precificação para os itens da fatura. Não confie no cadastro atual do produto, porque taxas e nomes mudam.

Opcional, mas frequentemente útil desde cedo, são Devoluções, Reembolsos e Notas de Crédito como registros separados. Exemplo: se um cliente devolve um item de um pedido de dois itens, você quer uma nota de crédito que faça referência à linha original da fatura, enquanto o registro de reembolso referencia a transação da gateway. Manter esses objetos explícitos evita ajustes manuais no fechamento do mês nos registros GST.

Se você construir isso em Koder.ai, trate cada objeto primeiro como uma tela simples (criar, ver, editar), depois adicione geração de fatura apenas depois que snapshots e campos por linha estiverem implementados.

HSN e SAC: onde eles se encaixam no modelo

HSN (para bens) e SAC (para serviços) não são detalhes "apenas da fatura". Eles começam na definição do produto ou serviço e então são copiados para cada linha da fatura no momento da emissão. Isso mantém carrinhos mistos corretos e facilita auditorias porque cada linha é autossuficiente.

Um modelo de dados mínimo prático é:

• Product: id, name, SKU, unit (UOM), base_price, tax_category_id, hsn_or_sac_type, hsn_or_sac_code
• InvoiceLine: id, invoice_id, product_id (opcional para linhas manuais), description, unit, qty, unit_price, tax_category_id, hsn_or_sac_type, hsn_or_sac_code

Colocar HSN/SAC no Product ajuda sua equipe administrativa a mantê-lo em um lugar. Copiar para InvoiceLine é o que torna faturas passadas estáveis. Mesmo que o produto mude depois, a fatura ainda mostra o que era verdadeiro no momento da venda. Este é o cerne de um modelo de dados de fatura GST que não quebra durante a reconciliação.

Para armazenamento de HSN, mantenha simples: código é obrigatório, descrição é opcional e uma data_de_entrada_em_vigor é opcional se você quiser histórico de alterações. A maioria das equipes não precisa da descrição em cada linha, mas ela pode ajudar quando o financeiro checa exceções.

Carrinhos mistos são normais: uma fatura pode ter múltiplas linhas e portanto múltiplos códigos HSN/SAC. Não tente forçar um código por fatura. Totais somam no nível da fatura, enquanto a classificação fica no nível da linha.

Gerenciamento de mudanças é onde as pessoas se metem em problemas. Use um conjunto pequeno de regras:

• Nunca sobrescrever HSN/SAC em linhas de fatura já emitidas.
• Se o HSN/SAC do produto mudar, atualize o Product apenas para pedidos futuros.
• Se você rastrear histórico, adicione um novo registro effective_from em vez de editar o antigo.

Na tela administrativa, você só precisa de um lugar para editar campos fiscais do Product, mais uma visão somente leitura na linha da fatura para confirmar o que foi capturado no momento da emissão. Se você estiver construindo essas telas rapidamente, ferramentas como Koder.ai podem gerar páginas CRUD básicas e tabelas de dados a partir deste modelo com esforço mínimo.

Detalhes das partes: GSTIN, endereços e place of supply

Um modelo de dados de fatura GST costuma falhar mais nos detalhes das partes. Se a identidade do comprador ou vendedor estiver minimamente errada, sua fatura pode ser válida no papel, mas problemática nas declarações e na reconciliação.

Comece tratando "vendedor", "comprador" e "destinatário" como partes separadas, mesmo quando são a mesma pessoa. Isso evita gambiarras posteriores quando um cliente adiciona um endereço de entrega diferente ou quando você vende a partir de mais de um registro GST.

Campos mínimos a armazenar (comprador e vendedor)

Mantenha os campos simples e explícitos. Estes são os que geralmente aparecem na fatura e nos relatórios:

• Nome legal (como deve aparecer na fatura)
• Nome comercial (opcional, mas útil)
• GSTIN (vendedor obrigatório; comprador pode ser nulo)
• Telefone/email (nem sempre obrigatório, mas útil para suporte)
• Linhas de endereço, cidade, estado, país, CEP

Armazene o estado tanto como nome legível quanto como código do estado, pois relatórios e regras de place of supply frequentemente dependem do código.

Faturamento vs entrega e place of supply

Capture tanto endereços de faturamento quanto de entrega no pedido, não apenas no perfil do cliente. Perfis mudam; faturas não deveriam.

Place of supply deve ser armazenado como um código de estado específico na fatura (copiado do pedido no momento da emissão). Não "recalcule" depois. Se sua regra é "ship-to state", armazene esse resultado, mais o estado usado para decidir. Isso facilita auditorias e disputas.

B2B vs B2C: quando GSTIN é obrigatório

Para B2B, o GSTIN do comprador normalmente é obrigatório e deve ser validado quanto ao comprimento e formato na entrada. Para B2C, o GSTIN pode ficar vazio, mas você ainda precisa de um endereço completo e estado para determinar se se aplica CGST/SGST ou IGST.

Uma regra simples que funciona na maioria dos sistemas: se GSTIN do comprador está presente, trate como B2B; se não, trate como B2C. Se precisar de exceções, armazene um campo customer_type explícito.

Vendedores multi-entidade (vários GSTIN)

Se você tem filiais ou unidades de negócio com diferentes registros GST, modele "Seller Entity" como um registro próprio com seu próprio GSTIN e endereço. Cada pedido deve referenciar exatamente uma seller entity e cada fatura deve copiar esses dados para que faturas históricas permaneçam precisas mesmo se o endereço do vendedor mudar depois.

Ferramentas como Koder.ai podem gerar os formulários administrativos para esses registros rapidamente, mas a chave é a estrutura: entidade vendedora separada, snapshots no momento do pedido e um código de estado de place-of-supply explícito.

Campos de cálculo de imposto que você deve armazenar

A divisão mais comum é simples: se o place of supply está no mesmo estado que o fornecedor, o imposto é CGST + SGST. Se for em outro estado, o imposto é IGST. Seu sistema não deve "recalcular depois a partir dos totais" porque pequenas diferenças (arredondamento, descontos, frete) são exatamente o que causa divergências.

No mínimo, armazene números de imposto no nível da linha da fatura, não apenas no cabeçalho. Assim você pode explicar cada centavo na fatura e vinculá-lo ao produto, HSN e receita.

Um mínimo prático por linha de fatura no seu modelo de dados GST parece com isto:

• taxable_value (após alocação de desconto por linha)
• gst_rate_percent
• cgst_rate_percent, sgst_rate_percent, igst_rate_percent (armazene a divisão usada)
• cgst_amount, sgst_amount, igst_amount (armazene os valores calculados)
• line_total (taxable_value + valores de imposto)

Descontos são onde os sistemas ficam confusos. Decida uma regra e armazene claramente. Se descontos reduzem o preço antes do imposto (típico para descontos por item e cupons), armazene o valor bruto original, o valor do desconto e o valor tributável resultante. Se você tem um cupom a nível de pedido, aloque-o entre as linhas (geralmente proporcional ao valor tributável pré-desconto de cada linha) e armazene o desconto alocado de cada linha para que a matemática tributária permaneça explicável.

O arredondamento deve ser consistente e registrado. Escolha se arredonda no nível de linha ou apenas no nível da fatura, então armazene os resultados arredondados que você imprimiu. Muitas equipes calculam imposto por linha, arredondam para 2 decimais, somam, então aplicam um campo invoice_rounding_adjustment final para alcançar o valor exato a pagar.

Frete e manuseio não devem ser um adicional oculto. Trate-os como uma linha separada da fatura com seu próprio código HSN/serviço e regras de taxa. Por exemplo, um pedido com dois produtos e uma taxa de frete vira três linhas, cada uma com valor tributável e componentes de imposto armazenados, facilitando a reconciliação financeira.

Dados do documento da fatura: numeração, datas, totais, status

Depois do cálculo do imposto, a fatura ainda precisa de campos de documento que a tornem válida, auditável e fácil de reconciliar depois. Em um modelo de dados de fatura GST, trate o cabeçalho da fatura como um registro legal: ele deve ser estável mesmo se produto ou dados do cliente mudarem no futuro.

Comece com o básico do cabeçalho: número da fatura, data de emissão (a data na fatura), tipo de fatura (tax invoice, export, B2B, B2C, etc.) e moeda. Mesmo que você facture principalmente em INR, armazenar a moeda evita casos de borda para exportações ou marketplaces multicurrency.

Numeração é onde as equipes se queimam. Mantenha uma série ou prefixo (por exemplo "FY25-INV-"), armazene o ano fiscal e imponha unicidade no nível do banco de dados. Também armazene controles de "próximo número" por série no admin para que dois administradores não possam emitir o mesmo número ao mesmo tempo.

Totais devem ser armazenados explicitamente, não apenas derivados. Salve subtotal (valor tributável), total de impostos, total geral e um valor separado de arredondamento. Se você recalcular depois a partir dos itens, uma pequena mudança de regra pode fazer faturas antigas deixarem de bater com a declaração já enviada.

Statuses devem refletir o ciclo de vida real e bloquear o registro quando necessário:

• Draft (editável)
• Issued (número atribuído, PDF gerado)
• Cancelled (mantida para auditoria, não deletada)
• Refunded (pagamento revertido, pode requerer nota de crédito)
• Credit noted (nota de crédito vinculada emitida)

Por fim, armazene metadados dos artefatos gerados: versão do template de PDF, timestamp de geração e um identificador de arquivo. Um hash é opcional, mas útil se precisar provar que o PDF não foi alterado.

Exemplo: se um agente de suporte regenera um PDF após uma atualização de template, os totais e o número da fatura devem permanecer idênticos, mas a versão do template armazenada explica por que o layout do PDF é diferente.

Telas administrativas para produtos, impostos e dados de clientes

Se você quer faturas GST limpas, não comece pela tela de fatura. Comece pelas páginas administrativas que a alimentam. Um bom modelo de dados de fatura GST se mantém enxuto quando essas entradas são controladas e consistentes.

Cadastro de produto (SKU para HSN/SAC)

O cadastro de produto é onde a maioria das divergências futuras começa, então mantenha-o rígido. Cada SKU deve ter exatamente um HSN padrão (ou SAC para serviços), além de uma alíquota GST padrão e quaisquer exceções que se apliquem apenas para certas datas.

Uma tela prática de produto geralmente precisa de:

• SKU e nome do produto (como você deseja que apareça impresso)
• Código HSN/SAC, taxa GST e categoria fiscal (se usar)
• Datas active from/to (para que mudanças não reescrevam faturas antigas)
• Overrides de preço (MRPs especiais ou preços por canal)
• Status (ativo/inativo) com motivo claro para desativação

Configuração de impostos (taxas e entradas intra vs inter-state)

Evite uma UI "calculadora". Em vez disso, armazene entradas que seu sistema pode aplicar de forma consistente: tabelas de alíquotas, regras de place of supply que você segue e como decide intra-state vs inter-state (geralmente comparando estado do fornecedor e estado do destinatário).

Mantenha a tela de impostos focada em: taxa por categoria/grupo HSN, datas de vigência e o que deve acontecer quando o comprador fornece um GSTIN válido vs não fornece.

Perfil do cliente e da empresa (quem aparece na fatura)

A tela de cliente deve capturar o GSTIN e seu status de validação, além de endereços padrão de faturamento e entrega. Não permita que usuários digitem estados livremente; use uma lista controlada para que "KA" e "Karnataka" não virem dois valores distintos.

Sua tela de perfil da empresa é igualmente importante: nome legal, GSTIN, endereço registrado e configurações de série de fatura (prefixo, próximo número e limites do ano fiscal). Bloqueie isso com permissões porque mudanças afetam todos os documentos futuros.

Básico de log de auditoria (confiança e rastreabilidade)

Você não precisa de um sistema complexo, mas precisa de trilha. Registre quem alterou HSN/SAC, taxas de GST, configurações de série de fatura ou GSTIN da empresa, junto com valor antigo, novo valor, timestamp e motivo.

Se estiver construindo essas telas em uma ferramenta como Koder.ai, trate audit logging e datas efetivas como campos de primeira classe desde o dia um. Custam pouco para adicionar cedo e economizam horas durante revisões financeiras mais tarde.

Passo a passo: do pedido à fatura em conformidade

Uma fatura conformante é menos sobre formatação bonita e mais sobre congelar os fatos certos no momento certo. Se você desenhar seu modelo de dados de fatura GST em torno deste fluxo, o trabalho do financeiro vira um simples casamento, não uma investigação semanal.

1) Congele o que o cliente realmente comprou

Antes de calcular impostos, trave um snapshot do pedido: itens, quantidades, preços unitários, descontos, encargos de frete/manuseio, GSTIN do cliente (se houver), endereços de faturamento e entrega e sinais de place of supply. O snapshot não deve mudar mesmo que o preço do produto ou o mapeamento HSN mude depois.

2) Converta o snapshot em linhas de fatura (com atributos fiscais copiados)

Calcule impostos e gere linhas de fatura a partir do snapshot. Cada linha da fatura deve copiar HSN/SAC, taxa(s) aplicada(s), valor tributável e valores de imposto usados naquele momento, em vez de consultá-los ao vivo mais tarde.

3) Emita a fatura e torne-a imutável

Atribua número da fatura e data de emissão, então marque a fatura como emitida. A partir desse ponto, bloqueie edições em preços, taxas, códigos HSN e endereços no registro da fatura. Se precisar permitir algo, limite a notas não financeiras e tags internas.

4) Produza o documento final e armazene os totais

Gere o PDF/visualização de impressão a partir da fatura emitida, então armazene os totais finais que você irá reportar: total tributável, totais CGST/SGST/IGST, arredondamento e total a pagar. Se quiser segurança extra, armazene versão do documento ou checksum para provar que a impressão corresponde aos números armazenados.

5) Trate mudanças da forma legal

Depois da emissão, mudanças devem seguir regras, não edições:

• Cliente quer correção de preço: emita nota de crédito (ou débito) referenciando a fatura original.
• Pedido cancelado após emissão: cancele a fatura se permitido; caso contrário, emita nota de crédito.
• Cliente atualiza endereço após emissão: não reescreva a fatura; corrija via documento adequado e mantenha trilha de auditoria.
• Reembolso parcial: nota de crédito apenas para as linhas/valor reembolsado.
• Envio de substituição: novo pedido/fatura, não edição silenciosa.

Se você incorporar esse fluxo nas telas administrativas (modo de planejamento Koder.ai é útil para mapear passos antes de construir), sua equipe conseguirá gerar faturas rapidamente sem quebrar reconciliação depois.

Torne a reconciliação indolor: pagamentos, reembolsos e registros

A reconciliação fica bagunçada quando pagamentos são tratados como um simples flag pago/não pago no pedido. Mantenha pagamentos e reembolsos como registros separados que apontam para o pedido e a fatura, assim o financeiro pode casar liquidações bancárias sem reescrever o histórico.

Pagamentos e reembolsos separados (não edite a fatura)

Uma fatura emitida deve permanecer estável após a emissão. Se um cliente paga em partes, ou você reembolsa depois, registre esse movimento como entrada de pagamento ou reembolso, não como alteração dos totais da fatura.

Campos mínimos que geralmente facilitam a reconciliação:

• Payment: payment_id, order_id, invoice_id, method, gateway_name, gateway_payment_id, amount, currency, authorized_at, captured_at, settlement_date, status
• Settlement (opcional mas útil): settlement_id, gateway_payout_id, settlement_date, gross_amount, fees, net_amount
• Refund: refund_id, order_id, invoice_id, payment_id, credit_note_id (se emitida), gateway_refund_id, amount, reason, refunded_at, status
• Chaves de reconciliação que você nunca deve reutilizar: order_id, invoice_id, payment_id, refund_id, credit_note_id

Se o cliente devolve um item, não "reduza a fatura." Emita uma nota de crédito e vincule-a à fatura original. O registro de faturas fica limpo e o reembolso se liga à nota de crédito.

Visão financeira e exportações que salvam horas

Dê ao financeiro uma tela única que responda: o que foi emitido, o que foi pago, o que ainda está aberto e o que foi revertido. Inclua ageing (0-7, 8-30, 31-60, 60+ dias) e possibilite detalhamento para entradas de pagamento e reembolso relacionadas.

Exportações que a maioria das equipes precisa todo mês:

• Registro de faturas (emitidas, canceladas, com nota de crédito)
• Resumo de impostos por alíquota e HSN/SAC (suporta seu modelo de dados GST)
• Reconciliação pagamento vs fatura (invoice_id, totais de pagamento, saldo)
• Registro de reembolsos e notas de crédito
• Relatório de liquidação da gateway (mapeamento payout_id para invoice/payment)

Exemplo: um pedido é Rs 10.000, pago Rs 6.000 hoje e Rs 4.000 na semana seguinte. A fatura permanece Rs 10.000. Sua visão financeira mostra saldo Rs 4.000 até a segunda liquidação chegar, então marca como totalmente paga sem alterar o documento emitido.

Armadilhas comuns que causam problemas de conformidade e divergência

A maioria dos problemas com faturas GST não são problemas de lógica tributária. São problemas de manutenção de registros: os números no PDF não batem com o que o financeiro exporta ou a fatura não pode ser explicada meses depois.

A primeira armadilha é calcular GST apenas em tempo de visualização. Se você computa CGST/SGST/IGST toda vez que alguém abre uma fatura, eventualmente terá resultados diferentes após uma mudança de taxa, regra de arredondamento ou correção de bug. Armazene o detalhamento de imposto computado usado quando a fatura foi emitida, mesmo que também armazene os insumos.

Uma segunda armadilha é permitir edições em uma fatura emitida. Uma vez finalizada, mudanças devem ocorrer através de nota de crédito ou fluxo de substituição com trilha de auditoria. Caso contrário, você verá "por que o PDF do cliente difere dos livros?".

Aqui estão os padrões de divergência que aparecem com mais frequência em um modelo de dados de fatura GST:

• Place of supply ausente ou código de estado errado, então IGST é aplicado quando deveria ser CGST+SGST (ou o oposto).
• HSN/SAC do produto ou taxa é atualizado e pedidos antigos são recalculados usando o novo valor.
• Imposto é armazenado, mas regras de arredondamento diferem entre UI, geração de PDF e exportações CSV.
• Descontos são aplicados após imposto em um lugar e antes do imposto em outro.
• Reembolsos são registrados como itens negativos sem ligação clara à fatura original.

Um exemplo rápido: você vende para um cliente em Karnataka, mas o endereço de entrega está em Maharashtra. Se seu sistema escolher por engano o estado de faturamento como place of supply, você pode cobrar CGST+SGST em vez de IGST. Se você também recalcula imposto em tempo de visualização, esse erro pode "se consertar" silenciosamente depois, deixando o financeiro com números que não batem com o documento emitido.

Ao construir telas administrativas (sejam customizadas ou via plataforma como Koder.ai), adicione pequenas salvaguardas: bloqueie faturas emitidas, mostre inputs de place-of-supply ao lado do tipo de imposto calculado e mantenha um snapshot imutável de HSN, taxa e arredondamento usados na emissão.

Checklist rápido e próximos passos

Antes de enviar uma fatura ao cliente ou marcá-la como "emitida", faça um conjunto rápido de verificações. É aí que a maioria dos pequenos erros vira grandes dores de reconciliação depois. Se você estiver construindo um modelo de dados de fatura GST, vale a pena incorporar essas verificações tanto nas regras de validação quanto na UI administrativa.

Verificações por fatura (antes de emitir)

• HSN/SAC está presente em cada linha e corresponde ao produto ou serviço realmente vendido.
• Regras de GSTIN são aplicadas corretamente (B2B vs B2C) e os detalhes de faturamento e entrega não se contradizem.
• Place of supply está armazenado e a divisão de impostos faz sentido (CGST/SGST vs IGST).
• Totais somam exatamente: valor tributável, cada componente de imposto, arredondamento e total geral.
• Uma vez emitida, a fatura é travada (sem edições silenciosas). Correções ocorrem via nota de crédito ou cancelamento, não reescrevendo o histórico.

Um exemplo simples: um cliente atualiza o endereço de entrega após o pagamento e o estado muda. Se você reemitir o mesmo número de fatura com novo imposto, seu registro e registros de pagamento deixam de bater. A abordagem mais segura é manter a fatura original imutável e criar um documento de ajuste.

Verificações de dados + fluxo (para manter o financeiro limpo)

• Numeração de faturas é única, sequencial conforme sua política e gerada somente no momento de "emissão".
• Armazene os valores de imposto computados que você usou, não apenas as taxas, para que relatórios permaneçam estáveis mesmo se taxas mudarem depois.
• Passos de status claros existem: draft -> issued -> cancelled (e documentos de nota de crédito separados).
• Relatórios reconciliam por período: totais do registro de faturas devem bater com pagamentos capturados, reembolsos processados e recebíveis pendentes.
• Campos de auditoria estão sempre presentes: criado por, emitido em e motivo para cancelamentos ou notas de crédito.

Próximos passos: implemente as telas e validações primeiro, depois itere. Em Koder.ai, comece com o Planning Mode para esboçar os registros e telas administrativas (produtos com mapeamento HSN/SAC, detalhes de cliente/GSTIN, regras de impostos e faturas). Gere o app, teste alguns pedidos reais de ponta a ponta e então use snapshots e rollback para refinar o fluxo com segurança. Quando precisar de customizações mais profundas, exporte o código-fonte e continue evoluindo com seu processo habitual.