O labirinto fiscal brasileiro: o que ninguém te conta sobre integrar NF-e no seu sistema

Se você já tentou emitir uma nota fiscal eletrônica por código no Brasil, sabe que a documentação oficial parece ter sido escrita por alguém que não queria que você entendesse. Eu gastei 3 meses da minha vida nesse buraco e quero poupar um pouco do sofrimento de quem vier depois.
Esse texto é sobre o que eu aprendi integrando NF-e, NFC-e e NFS-e num sistema de gestão que estou construindo. Não é tutorial passo a passo — é mais um mapa de onde estão as armadilhas.

O problema que ninguém avisa

A primeira coisa que você descobre é que "nota fiscal eletrônica" não é uma coisa só. São pelo menos três mundos diferentes:

• NF-e (modelo 55): nota de venda de produto. Comunicação com a SEFAZ estadual.
• NFC-e (modelo 65): cupom fiscal do consumidor. Também SEFAZ estadual, mas com regras próprias.
• NFS-e (nota de serviço): cada prefeitura tem seu próprio web service, seu próprio layout XML, sua própria autenticação. São literalmente milhares de padrões diferentes.
  Quando li isso pela primeira vez, achei que era exagero. Não é. O município de São Paulo usa um layout. Florianópolis usa outro. Curitiba outro. E por aí vai. Não existe um padrão nacional obrigatório para NFS-e (o padrão ABRASF é uma "recomendação" que cada prefeitura implementa como bem entende).

Certificado digital: a primeira parede

Para emitir NF-e e NFC-e, você precisa de um certificado digital A1 (arquivo .pfx). Parece simples, mas:

• O certificado precisa ser convertido para que seu código consiga assinar o XML
• Em Python, a lib signxml funciona, mas você precisa extrair a chave privada e o certificado do .pfx separadamente usando cryptography
• O XML precisa ser assinado com Canonical XML (C14N), e se você errar o namespace, a SEFAZ rejeita silenciosamente — sem mensagem de erro útil
  Gastei dois dias num bug onde o XML estava correto visualmente, mas a assinatura era inválida. O problema? Um espaço em branco extra dentro de uma tag que o C14N não normalizava do jeito que a SEFAZ esperava.

O XML da NF-e: um campo minado

O schema da NF-e tem centenas de campos. Muitos são obrigatórios dependendo do contexto. Alguns exemplos que me pegaram:
O campo indPag (indicador de pagamento) foi removido na versão 4.0, mas alguns validadores ainda esperam ele. O campo CST muda de significado dependendo se a empresa é Simples Nacional ou Regime Normal. E o famigerado CFOP — são centenas de códigos que definem a natureza da operação, e usar o errado pode gerar multa.
Uma coisa que me ajudou muito: pegar XMLs de notas reais (você pode baixar pelo portal da SEFAZ) e comparar campo por campo com o que seu código gera. É tedioso, mas é o debug mais eficiente.

Ambientes de homologação: não confie cegamente

A SEFAZ oferece ambiente de homologação para testes. Em teoria, funciona igual ao de produção. Na prática:

• O ambiente de homologação costuma ficar fora do ar em horários aleatórios
• Algumas validações que existem em produção não existem em homologação (e vice-versa)
• O tempo de resposta em homologação pode ser 10x maior que em produção
  Minha recomendação: teste em homologação, mas não assuma que "se passou lá, vai passar em produção". Tenha um bom tratamento de erros e logging detalhado para os primeiros dias em produção.

A decisão que salvou o projeto

Depois de tentar fazer tudo na mão por 6 semanas, tomei uma decisão pragmática: usei componentes de terceiros para a parte de comunicação com a SEFAZ. Especificamente, componentes em Delphi/Lazarus que fazem a parte pesada — assinatura, transmissão, tratamento de retorno.
Não é a solução mais elegante do ponto de vista arquitetural. Mas é o que funciona. E é o que praticamente todos os softwares fiscais brasileiros fazem por baixo dos panos, mesmo os que se vendem como "100% cloud native".
O ponto é: a legislação fiscal brasileira é tão complexa e muda com tanta frequência que manter uma lib própria de comunicação com a SEFAZ é praticamente um produto em si. A menos que seu core business seja justamente esse, não vale o investimento.

O que eu faria diferente

Se fosse começar de novo:

1. Não tentaria fazer a comunicação SEFAZ do zero. Usaria um serviço de terceiro desde o dia 1. O tempo que gastei tentando foi tempo que podia ter ido pra features que o usuário realmente vê.
2. Começaria pela NFC-e, não pela NF-e. A NFC-e é mais simples (menos campos obrigatórios, sem necessidade de manifesto do destinatário) e te dá um ciclo de feedback mais rápido.
3. Montaria uma suíte de testes com XMLs reais antes de escrever qualquer código. Baixaria umas 50 notas de diferentes estados e tipos de operação e usaria como fixture.
4. Não subestimaria a NFS-e. Achei que seria mais fácil por ser "só serviço". É o oposto — a fragmentação municipal torna tudo mais caótico.

Algumas referências que me ajudaram

• A documentação técnica do portal da NF-e (nfe.fazenda.gov.br) é densa mas é a fonte da verdade
• O repositório do projeto ACBr (mesmo sendo Delphi) tem a melhor documentação não-oficial sobre os schemas
• O grupo do ACBr no fórum é surpreendentemente ativo e prestativo
• Para NFS-e, o site da ABRASF tem o layout padrão, mas sempre confira com a prefeitura específica

---

Se alguém aqui já passou por isso ou está planejando integrar emissão fiscal no seu sistema, fico à disposição nos comentários. É um daqueles assuntos que quase ninguém escreve sobre porque é tedioso demais — mas justamente por isso, qualquer documentação ajuda.