BrFiscalFaker

Overview

brfiscalfaker is a Go-based command-line tool designed to generate mock Brazilian fiscal invoices (NF-e, NFC-e, CFe, NFeDevolucao) for testing and development purposes. It allows users to create realistic invoice XML files with customizable data, facilitating the development of applications that interact with Brazilian fiscal systems.

Features

• Supports Multiple Invoice Types: Generate NF-e, NFC-e, CFe, and NFeDevolucao invoices.
• Customizable Data: Provide custom CPF and CNPJ numbers.
• Block Specific Tags: Remove or block specific XML tags using the --block-tags flag.
• Dependency Management: Ensures dependent placeholders are processed in the correct order.
• Cross-Platform: Works seamlessly on various operating systems.
• Comprehensive Logging: Provides detailed logs for debugging and transparency.
• Br documents: This project includes utilities to generate random yet valid Brazilian fiscal identifiers such as Access Key (Chave de Acesso), CPF, and CNPJ. These are essential for creating mock data for testing purposes.
• Unit Tested: Robust unit tests to ensure reliability.

Installation

Ensure you have Go installed on your system (version 1.16 or higher).

1. Clone the Repository:

   git clone https://github.com/mayckol/brfiscalfaker.git
   cd brfiscalfaker

2. Build the Application:

   go build -o bfiscalfaker ./cmd/bfiscalfaker/main.go

Usage

Run the application using the `go run command or the built binary.

Command-Line Flags

• --cpf (optional): --cpf: (Optional) Provide a custom CPF number to include in the invoice.
• --cnpj (optional): --cnpj: (Optional) Provide a custom CNPJ number to include in the invoice.
• --block-tags (optional): --block-tags: (Optional) Block specific XML tags from being included in the invoice.
• --type (default NFCe): --type: (Optional) Specify the type of invoice to generate (NF-e, NFC-e, CFe, NFeDevolucao).

Examples

• Generate a Basic NFC-e Invoice:

  go run cmd/bfiscalfaker/main.go

• Generate an NF-e Invoice with Custom CPF and CNPJ:

   go run cmd/bfiscalfaker/main.go --type NFe --cpf 12345678900 --cnpj 12345678901234

• Generate a CFe Invoice with Blocked Tags:

  go run cmd/bfiscalfaker/main.go --type CFe --block-tags "nItem, vProd"

• Generate an NFCe Invoice with Custom Data and Blocked Tags:

  go run cmd/bfiscalfaker/main.go --type NFCe --cpf 12345678900 --cnpj 12345678901234 --block-tags "nItem, vProd"

Library Usage

Download the Library

go get github.com/mayckol/brfiscalfaker

Testing Utilities

For test code, use the convenient test helper from the nfs package:

package mypackage_test

import (
    "testing"
    "github.com/mayckol/brfiscalfaker/pkg/nfs"
)

func TestInvoiceProcessing(t *testing.T) {
    // Generate a valid NFe XML for testing
    xml := nfs.GenerateValidInvoiceXML(t, nfs.NFe)

    // Or with custom options
    xml = nfs.GenerateValidInvoiceXML(t, nfs.NFCe,
        nfs.WithCPF("12345678900"),
        nfs.WithCNPJ("12345678901234"),
    )

    // Use the XML in your tests...
}

Create a Template Generator

• Random CNPJ, CPF, and Access Key Generation:

  package main
   import (
       "fmt"
       "github.com/mayckol/brfiscalfaker/pkg/br_documents"
   )
   func main() {
       cpf := br_documents.CPF()
       cnpj := br_documents.CNPJ()
       accessKey := br_documents.AccessKey()
       fmt.Println("CPF:", cpf)
       fmt.Println("CNPJ:", cnpj)
       fmt.Println("Access Key:", accessKey)
   }

Parameters Description:

• CPF()

  • Config: Optional parameter to control output format.
    • Masked: bool. If true, the CPF is formatted as XXX.XXX.XXX-XX. Default is false (raw digits).

• CNPJ()

  • Config: Optional parameter to control output format.
    • Masked: bool. If true, the CNPJ is formatted as XX.XXX.XXX/XXXX-XX. Default is false (raw digits).

• AccessKey()

  • Config: Optional parameter to customize the generated key.
    • Masked: bool. If true, the Access Key is formatted with separators for readability. Default is false (raw digits).

package main

import (
   "log"
   "github.com/mayckol/brfiscalfaker/pkg/nfs"
   "fmt"
)

func main() {
   // Define the desired template type
   templateType := nfs.NFCe

   // Create the generator using the helper
   generator, err := nfs.CreateTemplateGenerator(templateType)
   if err != nil {
      log.Fatalf("Failed to create generator: %v", err)
   }
   options := []nfs.Option{
	   nfs.WithCPF("01234567890"),
	   nfs.WithCNPJ("12345678901234"),
   }

   // Generate the XML template
   xmlBytes, err := generator.Generate(options...)
   if err != nil {
      log.Fatalf("Failed to generate XML template: %v", err)
   }

   fmt.Println(string(xmlBytes))

}

Alphanumeric CNPJ (v2) — July 2026 Format

Brazil's new alphanumeric CNPJ format becomes effective in July 2026. This package includes a v2 module with full support for the new Módulo 11 algorithm with dual check digits.

v2 Features:

• 14-character alphanumeric CNPJ format (8 root + 4 branch + 2 numeric check digits)
• Automatic check digit calculation using Módulo 11 with specified weight arrays
• Input validation for both numeric (legacy) and alphanumeric (new) formats
• Configurable character set (blacklist I, O, Q, U, F by default to avoid visual ambiguity)
• Masked format support: XX.XXX.XXX/YYYY-ZZ

Generate Raw Alphanumeric CNPJ:

package main

import (
	"fmt"
	"github.com/mayckol/brfiscalfaker/pkg/br_documents/v2"
)

func main() {
	// Generate a valid raw alphanumeric CNPJ
	cnpj := v2.CNPJ()
	fmt.Println("CNPJ:", cnpj) // Output: AB1CD2E3F4GH90
}

Generate Masked CNPJ:

package main

import (
	"fmt"
	"github.com/mayckol/brfiscalfaker/pkg/br_documents/v2"
)

func main() {
	// Generate a masked alphanumeric CNPJ
	cnpj := v2.CNPJ(v2.CNPJv2Config{Masked: true})
	fmt.Println("CNPJ:", cnpj) // Output: AB.1CD.2E3/F4GH-90
}

Allow Ambiguous Letters (I, O, Q, U, F):

package main

import (
	"fmt"
	"github.com/mayckol/brfiscalfaker/pkg/br_documents/v2"
)

func main() {
	// Generate CNPJ allowing previously blacklisted letters
	cnpj := v2.CNPJ(v2.CNPJv2Config{AllowAmbiguousLetters: true})
	fmt.Println("CNPJ:", cnpj) // May contain I, O, Q, U, or F
	
	// Combine with masked format
	maskedCNPJ := v2.CNPJ(v2.CNPJv2Config{
		Masked:                true,
		AllowAmbiguousLetters: true,
	})
	fmt.Println("Masked CNPJ:", maskedCNPJ)
}

Validate CNPJ (v1 and v2 formats):

package main

import (
	"fmt"
	"github.com/mayckol/brfiscalfaker/pkg/br_documents/v2"
)

func main() {
	// Validate alphanumeric CNPJ
	cnpj := v2.CNPJ()
	if v2.ValidateCNPJ(cnpj) {
		fmt.Println("Valid CNPJ:", cnpj)
	}
	
	// Validate masked CNPJ (automatically sanitized)
	maskedCNPJ := "AB.1CD.2E3/F4GH-90"
	if v2.ValidateCNPJ(maskedCNPJ) {
		fmt.Println("Valid masked CNPJ")
	}
	
	// Backward compatibility: numeric-only CNPJs also validate
	numericCNPJ := "12345678901234"
	if v2.ValidateCNPJ(numericCNPJ) {
		fmt.Println("Valid numeric CNPJ (backward compatible)")
	}
}

Parameters:

• v2.CNPJ()

  • Config (CNPJv2Config): Optional parameter to customize generation.
    • Masked: bool. If true, format as XX.XXX.XXX/YYYY-ZZ. Default is false (raw 14 characters).
    • AllowAmbiguousLetters: bool. If true, allow letters I, O, Q, U, F in generation. Default is false (excluded to reduce visual ambiguity).

• v2.ValidateCNPJ()

  • Accepts both raw and masked formats.
  • Handles mixed case and whitespace automatically.
  • Returns true if CNPJ passes structural and algorithmic validation (check digits).
  • Works with both numeric (legacy) and alphanumeric (v2) formats.

Status: This module is ready for testing and development. The new alphanumeric CNPJ format becomes official in July 2026.

Docker

You can also run the application using Docker.

docker pull mayckol/bfiscalfaker

docker run mayckol/bfiscalfaker --type NFe --cpf 12345678900 --cnpj 12345678901234

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests to help improve this project.

License

This project is licensed under the MIT License. See the LICENSE file for more information.