Skip to content

GoNFE

A Go library for issuing Brazilian electronic fiscal documents, following the standards published by the Receita Federal and the state tax authorities (SEFAZ).

go get github.com/mschunke/gonfe

About this translation

The documentation is available in English, but the API identifiers stay in Portuguese — nfe.Nova, Preparar, Validar, chave, emitente. That is deliberate: the types mirror the official XSD field by field, with the same names, so that checking the code against the Manual de Orientação do Contribuinte is a matter of reading the two side by side. Translating the identifiers would break that correspondence.

What already works

  • NF-e — model 55

    Layout 4.00 in full: building the document, computing totals, validation, signing, transmission and the distribution file.

    Issuing an NF-e

  • NFC-e — model 65

    Everything the NF-e has, plus the version 2 QR Code and the lookup URL, with the rules specific to the consumer receipt.

    Issuing an NFC-e

  • A1 certificates

    Modern PKCS#12, no CGO, extracting the CNPJ from the ICP-Brasil OIDs and setting up mutual TLS authentication.

    Digital certificate

  • XML-DSig signing

    Our own C14N 1.0 canonicalisation, signing in the SEFAZ profile, and verification of documents received from third parties.

    Digital signature

  • Events

    Cancellation, letter of correction, recipient acknowledgement and voiding of number ranges.

    Events

  • Transport documents

    CT-e (57), CT-e OS (67) and MDF-e (58), with the road modal complete, events, and closing out a trip.

    CT-e and MDF-e

  • Auxiliary documents

    DANFE, NFC-e receipt, DACTE, DACTE OS and DAMDFE as PDFs, written in pure Go with no graphics library.

    Auxiliary documents

  • DF-e distribution

    The queue of documents issued against your CNPJ, with the care needed to avoid the one-hour block for excessive polling.

    DF-e distribution

  • Homologation

    A test script for the SEFAZ sandbox, from first contact to the full lifecycle, with the most common rejection codes.

    Testing against homologation

Every document the library issues can also be transmitted, corrected, cancelled and printed. What is still missing is recorded in the HANDOFF, with a plan for each item.

Why another library

No float64 anywhere near a fiscal value. Every monetary field uses tipos.Decimal, a fixed-point decimal that honours the scale the layout demands. Adding one hundred instalments of seven cents gives exactly seven reais.

Faithful to the layout. The structures mirror the XSD field by field, with the same names and in the same order. Checking them against the Manual de Orientação do Contribuinte is a matter of reading the two side by side.

No CGO, and almost no dependencies. A single external dependency, for reading modern PKCS#12 files. The same binary runs on Linux, macOS and Windows, and compiles into a scratch container.

Bytes preserved when signing. The signature is inserted into the document without re-serialising it. The digest computed here is exactly the one SEFAZ recomputes on arrival — the most common cause of "invalid signature" rejections simply cannot happen.

The issuing cycle

flowchart LR
    A[Build the NFe] --> B[Preparar]
    B --> C[Validar]
    C --> D[Assinar]
    D --> E[Build the batch]
    E --> F[Authorise]
    F --> G{Synchronous?}
    G -- yes --> I[Protocol]
    G -- no --> H[Wait for processing]
    H --> I
    I --> J[Build nfeProc]

Preparar does three things: it normalises text fields and the scale of every decimal, computes the totals group from the line items, and builds the access key with its check digit. Validar checks structure, check digits and sums before you spend a round trip to SEFAZ.

Start with your first invoice API reference

Before going to production

Three warnings worth more than the rest of this documentation

Check the service endpoints. The endpoint table reproduces what is published on the NF-e portal, but states change addresses without notice. Run exemplos/status-servico for your state and override whatever differs in sefaz.Config.Endpoints.

Local validation does not replace SEFAZ. NFe.Validar covers structure, check digits and sums; SEFAZ applies hundreds of additional business rules.

Keep the certificate and the CSC out of your source code. Both are secrets: whoever holds them can issue documents in your name.

This project is not affiliated with the Receita Federal do Brasil or with any state tax authority. The layouts, technical notes and service endpoints are authored by those public bodies and are published on the NF-e portal. Responsibility for the documents issued lies with whoever issues them.