Software de contabilidade: SPED e NF-e integrados

Nenhum país do mundo tem um ambiente tributário mais complexo do que o Brasil. São 27 legislações estaduais de ICMS, 5.000 municípios com regimes distintos de ISS, mais de 90 obrigações acessórias ativas e uma Receita Federal que exige envio de arquivos digitais estruturados para praticamente toda movimentação fiscal relevante. Construir software contábil ou fiscal no Brasil não é uma questão de preferência tecnológica — é uma batalha contínua contra a complexidade regulatória.

Para quem está desenvolvendo um sistema que precisa lidar com obrigações fiscais brasileiras, este artigo cobre os pilares técnicos: emissão de documentos fiscais eletrônicos (NF-e, NFS-e, NFC-e), integração com o SEFAZ via certificado digital, geração de arquivos SPED e estratégias de contingência quando a infraestrutura do governo falha.

NF-e, NFS-e e NFC-e: Diferenças e APIs Disponíveis

Os três principais documentos fiscais eletrônicos têm origens, gestores e APIs completamente distintas:

Documento	Âmbito	Gestor	Operação
NF-e (Modelo 55)	Estadual	SEFAZ Estadual + Receita Federal	Venda de mercadorias entre empresas
NFC-e (Modelo 65)	Estadual	SEFAZ Estadual	Venda de mercadorias ao consumidor final (PDV)
NFS-e	Municipal	Prefeitura	Prestação de serviços

A NF-e e NFC-e seguem um schema XML padronizado pela SEFAZ Nacional, mas cada estado pode ter particularidades. A NFS-e não tem padronização nacional — cada prefeitura define seu próprio webservice e schema XML. Existem iniciativas de padronização (como o padrão Betha e o padrão Abrasf) que cobrem centenas de municípios, mas grandes capitais como São Paulo e Rio de Janeiro têm schemas proprietários.

Para simplificar essa complexidade, o mercado oferece SDKs e serviços intermediários:

• NFe.io / Focus NF-e: APIs REST que abstraem os webservices SOAP da SEFAZ e das prefeituras. Cobram por emissão, mas reduzem drasticamente a complexidade.
• PyNFe / nfelib: bibliotecas Python open source para NF-e com suporte a múltiplos estados.
• sped-fiscal: biblioteca Node.js para geração de arquivos SPED.

Para sistemas de médio porte, a combinação de uma biblioteca open source para NF-e + API de terceiros para NFS-e (dado o número de schemas municipais) costuma ser o equilíbrio mais racional entre custo e manutenibilidade.

Emissão via SEFAZ: Certificado A1/A3 e Ambiente de Homologação

A comunicação com o SEFAZ é feita via webservice SOAP com autenticação mútua TLS usando certificado digital ICP-Brasil. Existem dois tipos de certificado relevantes:

Certificado A1: arquivo digital (.pfx ou .p12) armazenado no servidor. Mais simples de implementar — basta carregar o arquivo e a senha para assinar os XMLs. Tem validade de 1 ano e precisa ser renovado.

Certificado A3: token físico (cartão inteligente ou USB) que armazena a chave privada em hardware. A chave nunca sai do dispositivo, o que aumenta a segurança. Mais complexo para automação em servidor — exige drivers do fabricante e comunicação com o hardware.

Para sistemas SaaS onde múltiplas empresas emitem notas, a arquitetura mais comum é:

[Empresa A] → [Backend SaaS] → [Serviço de Assinatura] → [SEFAZ]
                                      ↑
                          Certificados A1 por empresa
                          armazenados criptografados (AES-256)
                          com chave derivada do CNPJ + segredo

O ambiente de homologação do SEFAZ é obrigatório durante o desenvolvimento. Em homologação, as notas emitidas não têm validade fiscal, mas o processo técnico é idêntico ao de produção. A troca de ambiente é feita alterando o endpoint do webservice e o campo tpAmb no XML (1 = produção, 2 = homologação).

Um detalhe crítico: em homologação, o CNPJ do destinatário deve ser um CNPJ válido (geralmente usado CNPJ de teste da própria empresa), mas o valor do campo nNF (número da nota) deve ser diferente do ambiente de produção para evitar problemas na numeração sequencial.

<!-- Trecho do XML NF-e mostrando campos de ambiente e série -->
<ide>
  <cUF>35</cUF>           <!-- 35 = São Paulo -->
  <cNF>12345678</cNF>     <!-- código numérico aleatório -->
  <natOp>Venda de produto</natOp>
  <mod>55</mod>            <!-- 55 = NF-e, 65 = NFC-e -->
  <serie>1</serie>
  <nNF>000001234</nNF>    <!-- número sequencial por série -->
  <dhEmi>2024-09-17T10:30:00-03:00</dhEmi>
  <tpNF>1</tpNF>          <!-- 0 = entrada, 1 = saída -->
  <tpAmb>1</tpAmb>        <!-- 1 = produção, 2 = homologação -->
</ide>

SPED Fiscal e Contábil: Geração de Arquivos

O SPED (Sistema Público de Escrituração Digital) é um conjunto de obrigações acessórias que substituiu a entrega de documentos físicos. Os principais módulos são:

EFD ICMS/IPI (SPED Fiscal): escrituração fiscal mensal com todas as entradas, saídas, apurações de ICMS e IPI. Entregue via sistema da Receita Federal (Sped).

EFD Contribuições: apuração mensal de PIS e COFINS. Empresas do Lucro Presumido e Real são obrigadas.

ECD (Escrituração Contábil Digital): balanço patrimonial, demonstração de resultados e razão contábil em formato digital. Obrigatório para empresas do Lucro Real e certas empresas do Lucro Presumido.

ECF (Escrituração Contábil Fiscal): declaração anual do imposto de renda da pessoa jurídica, substituiu a DIPJ.

O formato do SPED é um arquivo TXT com registros identificados por código (C100, C170, E110, etc.). Cada registro tem posições fixas de campos separados por pipe (|).

Gerar arquivos SPED corretamente exige:

1. Conhecer os layouts atualizados (a Receita publica novos guias a cada ano)
2. Validar o arquivo gerado com o validador oficial (PVA - Programa Validador e Assinador) antes de transmitir
3. Manter versionamento dos layouts para reprocessar períodos anteriores se necessário

A estratégia recomendada é separar a lógica de geração de SPED em um módulo isolado com testes automatizados contra os validadores de schema, e gerar relatórios intermediários que facilitam auditoria antes da geração do arquivo final.

Contingência: o Que Fazer Quando o SEFAZ Está Fora

O SEFAZ não está sempre disponível. Manutenções programadas, instabilidades e falhas acontecem, e o sistema precisa ter uma estratégia clara para cada cenário.

A NF-e prevê dois modos de contingência:

EPEC (Evento Prévio de Emissão em Contingência): o emitente registra um evento no ambiente nacional da SEFAZ informando que emitirá em contingência. A nota é emitida com indicador de contingência e, após a normalização do sistema, é transmitida normalmente.

Formulário de Segurança - Impressor Autônomo (FS-DA): impressão do DANFE em formulário de segurança especial para situações de contingência sem acesso à internet. Menos comum em sistemas modernos.

Para NFS-e, não existe protocolo nacional de contingência — depende de cada prefeitura. O padrão é gerar um "recibo" interno durante a indisponibilidade e transmitir a nota retroativamente quando o sistema da prefeitura voltar.

A implementação de contingência no sistema deve incluir:

• Detecção automática de indisponibilidade do SEFAZ (timeout ou código de erro específico)
• Fila de reenvio com backoff exponencial para notas pendentes de transmissão
• Dashboard de notas em contingência para acompanhamento pelo usuário
• Alertas para o responsável fiscal quando o volume de notas em contingência ultrapassa um limite

# Padrão de fila para reenvio de notas com falha
from enum import Enum
import time

class StatusNota(Enum):
    PENDENTE = "pendente"
    EM_PROCESSAMENTO = "em_processamento"
    AUTORIZADA = "autorizada"
    REJEITADA = "rejeitada"
    CONTINGENCIA = "contingencia"
    CANCELADA = "cancelada"

def reenviar_notas_contingencia(session, max_tentativas=3):
    notas = session.query(NotaFiscal).filter(
        NotaFiscal.status == StatusNota.CONTINGENCIA,
        NotaFiscal.tentativas < max_tentativas
    ).all()

    for nota in notas:
        try:
            resultado = transmitir_sefaz(nota)
            if resultado.autorizada:
                nota.status = StatusNota.AUTORIZADA
                nota.protocolo = resultado.protocolo
            else:
                nota.tentativas += 1
                nota.ultimo_erro = resultado.mensagem
        except TimeoutError:
            nota.tentativas += 1
            time.sleep(2 ** nota.tentativas)  # backoff exponencial

    session.commit()

Conclusão

Software contábil e fiscal no Brasil exige um nível de especialização técnica e domínio regulatório que vai muito além do desenvolvimento web convencional. Cada versão do layout do SPED, cada nova obrigação acessória da Receita Federal e cada atualização de schema de NFS-e em municípios relevantes é um ponto de atenção que precisa de acompanhamento contínuo.

Para empresas que estão construindo sistemas com necessidades fiscais, a decisão crítica é onde investir em implementação própria e onde usar serviços de terceiros para abstrair a complexidade. Não existe resposta universal — depende do volume de emissões, da variedade de UFs atendidas e da criticidade da operação fiscal para o negócio.

A SystemForge tem experiência na construção de sistemas com integrações fiscais completas, desde a configuração do certificado digital até a geração de arquivos SPED auditáveis. Se seu projeto envolve obrigações fiscais, fale conosco antes de começar o escopo técnico.