gonfe

README

GoNFE

Biblioteca em Go para emissão de documentos fiscais eletrônicos brasileiros, seguindo os padrões da Receita Federal e das Secretarias de Fazenda estaduais.

Documentação: https://mschunke.github.io/gonfe/ · Referência da API: https://pkg.go.dev/github.com/mschunke/gonfe

O que já funciona

Documento	Situação
NF-e — Nota Fiscal Eletrônica, modelo 55, leiaute 4.00	Completo
NFC-e — Nota Fiscal de Consumidor Eletrônica, modelo 65	Completo, com QR Code versão 2
Eventos — cancelamento, carta de correção, manifestação	Completo
Inutilização de faixas de numeração	Completo
CT-e — Conhecimento de Transporte, modelo 57, leiaute 4.00	Modal rodoviário completo, com eventos
CT-e OS — Outros Serviços, modelo 67, leiaute 4.00	Completo, sem rodagem em campo
MDF-e — Manifesto de Documentos Fiscais, modelo 58, leiaute 3.00	Modal rodoviário completo
Documentos auxiliares em PDF — DANFE, cupom, DACTE, DACTE OS e DAMDFE	Completos, sem dependência gráfica
Distribuição de DF-e	Completo

Em NF-e e NFC-e a biblioteca cobre o ciclo inteiro: montagem do documento, cálculo dos totais, validação local, assinatura digital, envio à SEFAZ, espera pelo processamento, montagem do arquivo de distribuição, o documento auxiliar em PDF e o ciclo de vida posterior — correção, cancelamento e inutilização.

Princípios

• Sem dependências pesadas. Uma única dependência externa, para ler arquivos PKCS#12 modernos. Nada de CGO: o mesmo binário roda em Linux, macOS e Windows.
• Nenhum float64 em valor fiscal. Todo campo monetário usa um decimal de precisão fixa com a escala que o leiaute exige. 0.1 + 0.2 dá exatamente 0.3.
• Fiel ao leiaute. As estruturas espelham o XSD campo a campo e na mesma ordem, para que a conferência contra o Manual de Orientação do Contribuinte seja direta.
• Bytes preservados na assinatura. A assinatura é inserida sem reserializar o documento, então o resumo criptográfico calculado aqui é o mesmo que a SEFAZ vai recalcular.

Instalação

go get github.com/mschunke/gonfe

Requer Go 1.23 ou mais recente.

Uso em cinco passos

package main

import (
	"context"
	"log"
	"time"

	"github.com/mschunke/gonfe/certificado"
	"github.com/mschunke/gonfe/nfe"
	"github.com/mschunke/gonfe/sefaz"
	"github.com/mschunke/gonfe/tipos"
	"github.com/mschunke/gonfe/uf"
)

func main() {
	// 1. Carregar o certificado A1.
	cert, err := certificado.CarregarArquivo("certificado.pfx", "senha")
	if err != nil {
		log.Fatal(err)
	}

	// 2. Montar a nota.
	n := nfe.Nova(nfe.ModeloNFe)
	n.InfNFe.Ide.NatOp = "VENDA DE MERCADORIA"
	n.InfNFe.Ide.Serie = 1
	n.InfNFe.Ide.NNF = 57
	n.InfNFe.Ide.DhEmi = tipos.AgoraEm(uf.RS.Fuso())
	n.InfNFe.Ide.CMunFG = 4314902
	n.InfNFe.Ide.TpAmb = nfe.Homologacao
	// ... emitente, destinatário, itens, transporte e pagamento

	// 3. Preparar e validar: normaliza valores, calcula totais, monta a chave.
	if err := n.Preparar(); err != nil {
		log.Fatal(err)
	}
	if err := n.Validar(); err != nil {
		log.Fatal(err)
	}

	// 4. Assinar.
	assinada, err := n.AssinarCom(cert)
	if err != nil {
		log.Fatal(err)
	}

	// 5. Enviar e esperar o protocolo.
	cliente, err := sefaz.NovoCliente(sefaz.Config{
		UF: uf.RS, Ambiente: nfe.Homologacao,
		Modelo: nfe.ModeloNFe, Certificado: cert,
	})
	if err != nil {
		log.Fatal(err)
	}

	ctx, cancelar := context.WithTimeout(context.Background(), 2*time.Minute)
	defer cancelar()

	lote, _ := nfe.MontarLote("1", false, assinada)
	envio, err := cliente.Autorizar(ctx, lote)
	if err != nil {
		log.Fatal(err)
	}

	resultado, err := cliente.EsperarProcessamento(ctx, envio.Recibo(), 3*time.Second, 20)
	if err != nil {
		log.Fatal(err)
	}
	prot := resultado.ProtocoloDa(n.Chave())
	log.Println(prot.Resumo())

	// O arquivo de distribuição, que deve ser guardado e enviado ao destinatário.
	proc, _ := nfe.MontarNFeProc(assinada, prot)
	_ = proc
}

O exemplo completo e executável está em exemplos/emitir-nfe. Há também exemplos/emitir-nfce, exemplos/eventos e exemplos/status-servico, que serve para conferir a instalação:

go run ./exemplos/status-servico -cert ./certificado.pfx -uf RS

Depois de autorizada, a nota tem um ciclo de vida:

// Corrigir o que não altera valor nem partes.
cc, _ := evento.NovaCartaCorrecao(evento.DadosCartaCorrecao{
    Chave: chave, CNPJ: cnpj, UF: uf.RS, Ambiente: nfe.Producao,
    Correcao: "Fica corrigido o endereco de entrega para Rua Nova, 100",
})
assinada, _ := cc.AssinarCom(cert)
ret, _ := cliente.EnviarEvento(ctx, assinada)

// Cancelar dentro do prazo.
canc, _ := evento.NovoCancelamento(evento.DadosCancelamento{
    Chave: chave, CNPJ: cnpj, UF: uf.RS, Ambiente: nfe.Producao,
    Protocolo: prot.InfProt.NProt, Justificativa: "Pedido cancelado pelo cliente",
})

Pacotes

Pacote	Responsabilidade
nfe	Modelo de dados 4.00, cálculo de totais, validação, montagem de lote e de nfeProc
nfce	QR Code versão 2 e URLs de consulta da NFC-e
evento	Cancelamento, carta de correção, manifestação do destinatário e inutilização
cte	Conhecimento de Transporte modelo 57, leiaute 4.00
cteos	CT-e Outros Serviços modelo 67: pessoas, valores e excesso de bagagem
mdfe	Manifesto de Documentos Fiscais modelo 58, com encerramento de viagem
danfe	DANFE, cupom da NFC-e, DACTE e DAMDFE em PDF
dfe	Distribuição de DF-e: documentos de interesse do CNPJ
sefaz	Endereços por UF, cliente SOAP 1.2 com TLS mútuo e operações
xmldsig	Assinatura e verificação no perfil da SEFAZ
certificado	Certificados A1 em PKCS#12, com extração dos OIDs da ICP-Brasil
chave	Chave de acesso de 44 dígitos
tipos	Decimal de precisão fixa, data e data/hora do leiaute
validacao	CPF, CNPJ (inclusive alfanumérico) e formato de inscrição estadual
uf	Códigos do IBGE, nomes e fusos horários

Antes de usar em produção

Três avisos que valem mais que qualquer documentação:

1. Confira os endereços dos serviços. A tabela de endpoints reproduz o que está publicado no Portal da NF-e, mas os estados mudam endereços sem aviso. Rode exemplos/status-servico para a sua UF e sobreponha o que divergir em sefaz.Config.Endpoints. O mesmo vale para as URLs de QR Code da NFC-e.
2. A validação local não substitui a SEFAZ. NFe.Validar cobre estrutura, dígitos verificadores e somatórios; a SEFAZ aplica centenas de regras de negócio a mais. Homologue com notas reais do seu cenário tributário antes de ir para produção.
3. Guarde o certificado e o CSC fora do código. Ambos são segredos; quem os tem consegue emitir documentos em seu nome.

Roteiro

A arquitetura já separa o que é comum a todos os documentos — chave de acesso, canonicalização, assinatura, cliente SOAP — do que é específico da NF-e. Os próximos passos, nesta ordem:

• Eventos: cancelamento, carta de correção, manifestação do destinatário e inutilização de numeração
• Distribuição de DF-e (NFeDistribuicaoDFe)
• CT-e modelo 57, com o modal rodoviário
• MDF-e modelo 58, com encerramento de viagem
• Geração do DANFE e do cupom da NFC-e em PDF
• DACTE e DAMDFE em PDF
• CT-e OS, modelo 67
• Cliente SEFAZ do MDF-e
• Eventos do CT-e e DACTE OS em PDF
• Demais modais de CT-e e MDF-e com rodagem em produção
• Distribuição de DF-e do CT-e e do MDF-e

Contribuições são bem-vindas; veja CONTRIBUTING.md.

Aviso legal

Este projeto não tem vínculo com a Receita Federal do Brasil nem com nenhuma Secretaria de Fazenda estadual. Os leiautes, as notas técnicas e os endereços dos serviços são de autoria dos órgãos públicos e estão disponíveis no Portal da NF-e. A responsabilidade pelos documentos emitidos é de quem os emite.

Licença

MIT.

Documentation

Overview

Package gonfe é a raiz de uma biblioteca para emissão de documentos fiscais eletrônicos brasileiros, seguindo os padrões da Receita Federal e das Secretarias de Fazenda estaduais.

Este pacote não contém funcionalidade: serve de porta de entrada para a documentação. O código está nos subpacotes, cada um com uma responsabilidade:

• github.com/mschunke/gonfe/nfe — modelo de dados da NF-e e da NFC-e no leiaute 4.00, cálculo de totais, validação e montagem de lote.
• github.com/mschunke/gonfe/nfce — QR Code e URLs de consulta da NFC-e.
• github.com/mschunke/gonfe/cte — Conhecimento de Transporte modelo 57.
• github.com/mschunke/gonfe/cteos — CT-e Outros Serviços, modelo 67.
• github.com/mschunke/gonfe/mdfe — Manifesto de Documentos Fiscais 58.
• github.com/mschunke/gonfe/danfe — DANFE, cupom da NFC-e, DACTE e DAMDFE em PDF.
• github.com/mschunke/gonfe/dfe — distribuição de DF-e.
• github.com/mschunke/gonfe/evento — cancelamento, carta de correção, manifestação do destinatário e inutilização de numeração.
• github.com/mschunke/gonfe/sefaz — endereços dos serviços por unidade da federação e cliente SOAP com autenticação mútua TLS.
• github.com/mschunke/gonfe/xmldsig — assinatura e verificação no perfil de XML Signature da SEFAZ.
• github.com/mschunke/gonfe/certificado — certificados A1 em PKCS#12.
• github.com/mschunke/gonfe/chave — chave de acesso de 44 dígitos.
• github.com/mschunke/gonfe/tipos — decimal de precisão fixa, data e data/hora nos formatos do leiaute.
• github.com/mschunke/gonfe/validacao — CPF, CNPJ e inscrição estadual.
• github.com/mschunke/gonfe/uf — códigos do IBGE, nomes e fusos horários.

Emissão em cinco passos

cert, _ := certificado.CarregarArquivo("certificado.pfx", senha)

n := nfe.Nova(nfe.ModeloNFe)
// ... preencher identificação, emitente, destinatário, itens e pagamento

n.Preparar()            // normaliza, calcula totais e monta a chave
n.Validar()             // confere antes de gastar uma ida à SEFAZ
assinada, _ := n.AssinarCom(cert)

cliente, _ := sefaz.NovoCliente(sefaz.Config{
	UF: uf.RS, Ambiente: nfe.Homologacao,
	Modelo: nfe.ModeloNFe, Certificado: cert,
})
lote, _ := nfe.MontarLote("1", false, assinada)
envio, _ := cliente.Autorizar(ctx, lote)
resultado, _ := cliente.EsperarProcessamento(ctx, envio.Recibo(), 3*time.Second, 20)
proc, _ := nfe.MontarNFeProc(assinada, resultado.ProtocoloDa(n.Chave()))

O guia completo está em https://mschunke.github.io/gonfe/ e os exemplos executáveis, no diretório exemplos do repositório.

Aviso legal

Este projeto não tem vínculo com a Receita Federal do Brasil nem com nenhuma Secretaria de Fazenda estadual. A responsabilidade pelos documentos emitidos é de quem os emite.

Index

• Constants

Constants

const Versao = "0.5.0"

Versao é a versão desta biblioteca.

const VersaoLeiaute = "4.00"

VersaoLeiaute é a versão do leiaute dos documentos fiscais implementada.