Modelagem dos dados

A primeira etapa da integração com a Focus NF-e é a estruturação da modelagem de dados. A arquitetura ideal variará conforme as regras de negócio do seu software, os tipos de documentos fiscais necessários e o schema do seu banco de dados atual.

Abaixo, destacamos as principais diretrizes e pontos de atenção para orientar esse processo:

1) Cadastro de Empresas (Multi-tenant): Se o seu sistema atende a mais de um cliente, você precisará de uma entidade no banco de dados para gerenciar esses emissores. Além dos dados cadastrais básicos (CNPJ, Inscrição Estadual, Inscrição Municipal e endereço), armazene:

• ID na Focus: Identificador único gerado por nossa API no momento do cadastro. Necessário para atualizar dados, gerenciar certificados e configurar numeração.
• Token da Empresa: Credencial de acesso exclusiva do CNPJ, exigida para autenticar as requisições de emissão de notas daquele cliente específico.

2) Configuração e Regras de Tributação: Seu sistema precisa estar preparado para armazenar os parâmetros de cálculo de impostos (CST/CSOSN, CFOP, alíquotas). Dependendo da complexidade do negócio, essa parametrização pode ocorrer em diferentes níveis de abstração:

• Global (Por Empresa): Ideal para operações simples (ex: MEI), onde todas as notas de um cliente seguem exatamente as mesmas regras.
• Por Tipo de Operação (Natureza): Variação de impostos baseada no tipo de transação (ex: Venda Interna, Venda Interestadual, Devolução).
• Por Categoria: Regras agrupadas por tipos de produtos ou serviços.
  Específica (Por Produto/Serviço): Para cenários complexos onde a tributação varia item a item (diferentes NCMs, substituição tributária, etc.).

3) Modelagem de Emissões (Evite relação 1:1): Não adicione as colunas da nota fiscal (número, série, URL do XML) diretamente na tabela da operação comercial (ex: tabela Vendas).

A relação entre uma venda e um documento fiscal deve ser de 1:N (um para muitos). Crie uma entidade separada dedicada ao histórico e às tentativas de emissão (NotasFiscais ou Emissoes). Os principais motivos arquiteturais para isso são:

• Notas Denegadas: Um documento denegado pela SEFAZ fica inutilizado, mas precisa ser registrado em banco. O sistema deverá emitir uma nova nota (com numeração sequencial diferente) vinculada à mesma venda.
• Cancelamentos e Reemissões: O cliente pode emitir uma nota com erro, cancelá-la e emitir um novo documento para acobertar a mesma operação comercial.
• Contingência: Em casos de instabilidade nos servidores da Receita, pode ocorrer a emissão de uma nota em contingência e o cancelamento posterior da nota retida no ambiente normal. Ambas estarão associadas à mesma venda.