The gobl.cfdi package is a specialized converter that transforms GOBL (Go Business Language) invoice documents into Mexico's CFDI (Comprobante Fiscal Digital por Internet) XML format. This package serves as a bridge between the vendor-neutral GOBL invoice schema and the SAT (Servicio de Administración Tributaria) requirements for electronic fiscal receipts in Mexico.
This overview introduces the core concepts, architecture, and usage patterns of the conversion system. For detailed implementation of specific components, see Core CFDI Engine, Document Components, and Document Extensions. For build and deployment information, see Development and Deployment.
Sources: README.md1-14 go.mod1-6
CFDI (Comprobante Fiscal Digital por Internet) is Mexico's mandatory electronic invoicing standard. All fiscal transactions in Mexico must be documented using CFDI XML version 4.0, which conforms to schemas published by SAT. These documents include:
The CFDI format requires strict adherence to SAT catalogs for tax codes, product/service codes (ClaveProdServ), unit of measure codes (ClaveUnidad), and payment methods.
Sources: README.md1-3
The gobl.cfdi package depends on the core GOBL library go.mod6 for fundamental data types including bill.Invoice, org.Party, and num.Amount. The package leverages GOBL's regime system, specifically consuming Mexico-specific tax categories and extension keys defined in the mx regime addon. This architecture ensures that GOBL documents containing Mexico-specific data can be seamlessly converted to CFDI format without requiring manual mapping of codes or validation rules.
Sources: go.mod1-12 README.md18-52
The conversion architecture follows a pipeline pattern with three distinct phases:
validateSupport function checks for unsupported GOBL features, and RemoveIncludedTaxes normalizes tax representationnewEmisor, newReceptor, newConceptos, newImpuestos) extract data from the GOBL invoice and populate CFDI-specific structuresThe Document struct serves as the central data structure, mapping directly to the CFDI XML <cfdi:Comprobante> root element with all required namespaces and schema locations.
Sources: README.md20-52
| Entry Point | Purpose | Input | Output | Reference |
|---|---|---|---|---|
NewDocument(env) | High-level constructor | *gobl.Envelope | *Document, error | Primary programmatic API |
Convert(env) | Low-level converter | *gobl.Envelope | *Document, error | Direct conversion function |
doc.Bytes() | XML serialization | *Document | []byte, error | Produces final XML output |
Stamp(env, doc) | Apply PAC stamp | *gobl.Envelope, *Document | error | Adds TimbreFiscalDigital |
The typical usage pattern involves calling NewDocument with a GOBL envelope, which internally calls Convert to perform the transformation, then calling doc.Bytes() to serialize the result to CFDI XML. The Stamp function is called separately when digital fiscal stamps need to be applied post-conversion.
Sources: README.md30-52
The conversion maps GOBL's vendor-neutral domain model to CFDI's SAT-specific structures:
gobl.Envelope → Entry point containing the invoice and metadatabill.Invoice → Source data for the entire CFDI documentorg.Party (Supplier) → Emisor (Issuer) with RFC and tax regimeorg.Party (Customer) → Receptor (Receiver) with fiscal domicilebill.Line[] → Conceptos with ClaveProdServ and ClaveUnidad mappingsbill.Totals → Impuestos separating Traslados and RetencionesEach CFDI structure includes XML namespace attributes and follows SAT's schema requirements for field ordering, precision, and validation.
Sources: README.md18-52 go.mod6
The Go package provides a direct API for converting GOBL envelopes to CFDI XML:
This pattern is used when integrating CFDI generation into larger systems or when programmatic control over the conversion is needed.
Sources: README.md20-52
The gobl.cfdi CLI tool provides a command-line interface for file-based conversions:
The CLI tool is built using Cobra go.mod10 and provides the convert and parse commands. Pre-built binaries are available in the GitHub releases, or the tool can be installed via go install. For CLI implementation details, see Command-Line Interface.
Sources: README.md68-104 go.mod10
The package supports the following CFDI features:
| Feature | Description | Implementation Reference |
|---|---|---|
| CFDI v4.0 | Current SAT schema version | All document generation |
| Invoices (TipoDeComprobante="I") | Standard commercial invoices | Default invoice type |
| Tax Calculations | IVA, IEPS, ISR with Traslados/Retenciones | Tax Processing System |
| Payment Methods | PUE (immediate) and PPD (deferred) | Payment Information |
| Related Documents | CFDIRelacionados for credit notes | Related Documents |
| Digital Stamps | TimbreFiscalDigital from PACs | Digital Fiscal Stamps |
| Generic Public Receiver | XAXX010101000 for unspecified customers | Party Management |
| Foreign Customers | XEXX010101000 for international buyers | Party Management |
| Company Addendas | MabeFactura custom extensions | MABE Addenda |
| SAT Complements | Fuel accounts, food vouchers | CFDI Complements |
Features not currently supported include nomina (payroll) documents, payment receipts (complemento de pagos), and other specialized CFDI document types.
Sources: README.md1-104
The package includes comprehensive testing infrastructure with test fixtures in test/data/, helper utilities for loading and validating documents, and XSD schema validation using libxml2 go.mod38 The CI/CD pipeline README.md7-8 runs linting and tests automatically on every commit. For detailed testing documentation, see Testing Framework.
Sources: README.md54-63 go.mod38
The package relies on several key external libraries:
| Dependency | Purpose | Version Constraint |
|---|---|---|
github.com/invopop/gobl | Core GOBL types and invoice model | v0.307.0 |
github.com/nbio/xml | XML serialization with namespace support | v0.0.0-20260120185757 |
github.com/spf13/cobra | CLI command framework | v1.9.1 |
github.com/lestrrat-go/libxml2 | XSD validation (test only) | v0.0.0-20201123224832 |
github.com/invopop/validation | Input validation utilities | v0.8.0 |
The core GOBL dependency provides access to the bill, org, num, and tax packages that define the source data model. For complete dependency information, see Module Dependencies.
Sources: go.mod5-41
The package is released under the Apache License Version 2.0 LICENSE1-3 with copyright held by Invopop Ltd. The project is open source and accepts contributions, though copyright transfer to Invopop Ltd. is required for contributions to be accepted README.md5
Pre-built binaries for multiple platforms are automatically generated and published to GitHub releases via GoReleaser README.md70-74 The release process is fully automated through GitHub Actions.
Sources: README.md5 LICENSE1-202