ZeRechnung
Idioma: Português
Esta tradução ainda não foi revista por um falante nativo. Sugerir uma correção

Exemplos

Exemplos, passo a passo

Cada exemplo é um programa Go completo que corre tal como está. Cria uma fatura eletrónica real, verifica-a com as regras do país e depois volta a lê-la. Os testes do repositório executam cada programa e verificam que a saída é a que esta página mostra.

Exemplo 1

Uma fábrica de rolhas de Santa Maria da Feira fatura a um château de Bordéus

Factur-XEN 16931Transmissão intracomunitáriaIVA 0 %Preço ao milheiro

A Rolhas Teixeira & Filhas, em Santa Maria da Feira, transforma em rolhas a cortiça dos montados alentejanos. Portugal produz perto de metade da cortiça do mundo, e é no concelho da Feira que se concentra a indústria. Para engarrafar a colheita de 2024, o Château Mauvesin-Lartigue, em Saint-Émilion, encomendou rolhas naturais com o brasão da casa marcado a fogo.

O programa de faturação certificado da fábrica já emite a fatura em PDF, com o ATCUD e o código QR que a lei portuguesa exige. O ZeRechnung junta-lhe o XML e os metadados Factur-X, o formato franco-alemão que o château lê sem esforço. A comunicação das faturas à AT continua a cargo do programa certificado.

Trata-se de uma transmissão intracomunitária de bens: a fatura não leva IVA português (categoria K).

  1. Ler o PDF da fatura

    O ponto de partida é o PDF que o programa de faturação já produz. O ideal é um PDF/A-3, mas qualquer PDF serve: o ZeRechnung não altera os seus bytes e junta o XML numa atualização incremental.

    Go
    pdf, err := os.ReadFile("fatura.pdf")
    if err != nil {
    	log.Fatal(err)
    }
  2. Descrever o vendedor e o comprador

    Numa transmissão intracomunitária, a fatura indica o número de IVA das duas partes (regra BR-IC-02): o NIF da fábrica, com o prefixo PT, e o número de IVA intracomunitário do château. O capital social e a conservatória do registo comercial, que as sociedades portuguesas indicam nos seus documentos, vão na informação jurídica do vendedor (BT-33).

    Go
    fabrica := invoice.Party{
    	Name:        "Rolhas Teixeira & Filhas, Lda.",
    	VATID:       "PT508361729",
    	Description: "Capital social: 250 000 €. Matriculada na C.R.C. de Santa Maria da Feira.",
    	Address: invoice.Address{
    		Line1: "Rua do Montado, 212", PostCode: "4520-211", City: "Santa Maria da Feira",
    		CountryCode: "PT",
    	},
    	Contact: &invoice.Contact{
    		PersonName: "Marta Teixeira",
    		Phone:      "+351 256 000 000",
    		Email:      "comercial@rolhasteixeira.example",
    	},
    }
    chateau := invoice.Party{
    	Name:              "SCEA Château Mauvesin-Lartigue",
    	VATID:             "FR43438162752",
    	LegalRegistration: invoice.Identifier{ID: "438162752", Scheme: invoice.SchemeSIREN},
    	Address: invoice.Address{
    		Line1: "Lieu-dit Mauvesin", PostCode: "33330", City: "Saint-Émilion", CountryCode: "FR",
    	},
    }
  3. Acrescentar as menções obrigatórias

    O número segue a série do programa certificado (FT 2026/318), e o ATCUD, o código único do documento, vai numa nota com o código REG (informação regulamentar). A isenção cita o artigo 14.º do RITI, o regime do IVA nas transações intracomunitárias, com o código VATEX-EU-IC. A data de entrega (BT-72) e o país de destino (BT-80) são obrigatórios na categoria K.

    Go
    d := invoice.MustDecimal
    inv := &invoice.Invoice{
    	Profile:                invoice.ProfileEN16931,
    	Number:                 "FT 2026/318",
    	TypeCode:               invoice.TypeCommercialInvoice,
    	IssueDate:              invoice.NewDate(2026, time.November, 20),
    	Currency:               "EUR",
    	PurchaseOrderReference: "CMD-2026-044",
    	Seller:                 fabrica,
    	Buyer:                  chateau,
    	DeliveryDate:           invoice.NewDate(2026, time.November, 18),
    	ShipTo: &invoice.Party{
    		Name: "Château Mauvesin-Lartigue, chai d'embouteillage",
    		Address: invoice.Address{
    			Line1: "Lieu-dit Mauvesin", PostCode: "33330", City: "Saint-Émilion", CountryCode: "FR",
    		},
    	},
    	Notes: []invoice.Note{{SubjectCode: "REG", Content: "ATCUD: JJMRT4WK-318"}},
    	VATBreakdown: []invoice.VATBreakdown{{
    		CategoryCode:        invoice.VATIntraCommunity,
    		Rate:                d("0"),
    		ExemptionReason:     "Isento nos termos do artigo 14.º do RITI.",
    		ExemptionReasonCode: invoice.VATEXIntraCommunity,
    	}},
    	PaymentMeans: []invoice.PaymentMeans{{
    		TypeCode:  invoice.PaymentSEPACreditTransfer,
    		PayeeIBAN: "PT50000201231234567890154",
    	}},
    	PaymentTerms: []invoice.PaymentTerms{{
    		Description: "Pagamento a 60 dias da data da fatura, por transferência bancária.",
    		DueDate:     invoice.NewDate(2027, time.January, 19),
    	}},
    }
  4. Listar as rolhas

    As rolhas vendem-se ao milheiro: a quantidade conta-se em peças (código UN/ECE H87) e o preço refere-se a mil rolhas, a quantidade de base do preço (BT-149). A marcação a fogo também se cobra ao milheiro, e o transporte como uma unidade (C62).

    Go
    inv.Lines = []invoice.Line{{
    	ID: "1", Item: invoice.Item{Name: "Rolha natural 49 × 24 mm, classe Flor"},
    	Quantity: d("24000"), UnitCode: "H87", NetPrice: d("980.00"),
    	PriceBaseQuantity: d("1000"), PriceBaseQuantityUnit: "H87",
    	VATCategoryCode: invoice.VATIntraCommunity, VATRate: d("0"),
    }, {
    	ID: "2", Item: invoice.Item{Name: "Rolha natural 45 × 24 mm, classe Extra"},
    	Quantity: d("12000"), UnitCode: "H87", NetPrice: d("620.00"),
    	PriceBaseQuantity: d("1000"), PriceBaseQuantityUnit: "H87",
    	VATCategoryCode: invoice.VATIntraCommunity, VATRate: d("0"),
    }, {
    	ID: "3", Item: invoice.Item{Name: "Marcação a fogo do brasão e do ano de colheita"},
    	Quantity: d("36000"), UnitCode: "H87", NetPrice: d("18.00"),
    	PriceBaseQuantity: d("1000"), PriceBaseQuantityUnit: "H87",
    	VATCategoryCode: invoice.VATIntraCommunity, VATRate: d("0"),
    }, {
    	ID: "4", Item: invoice.Item{Name: "Transporte rodoviário até Saint-Émilion"},
    	Quantity: d("1"), UnitCode: "C62", NetPrice: d("420.00"),
    	VATCategoryCode: invoice.VATIntraCommunity, VATRate: d("0"),
    }}
  5. Criar a fatura Factur-X

    Calculate calcula os montantes das linhas (dividindo pela quantidade de base), os totais e o resumo do IVA, com decimais exatos. Com Auto, a validação acrescentaria as regras nacionais do país do vendedor. Para Portugal não há nenhuma: a CIUS-PT, a especificação portuguesa das faturas ao Estado, não está implementada. Aplicam-se o esquema, as regras EN 16931 e as do perfil Factur-X. Uma fatura inválida é recusada: Create devolve os erros e não escreve nada.

    Go
    out, err := zerechnung.Create(pdf, inv, &zerechnung.CreateOptions{
    	Calculate: true,
    	Validate:  &validate.Options{Auto: true},
    })
    if err != nil {
    	log.Fatal(err)
    }
    if err := os.WriteFile("FT-2026-318.pdf", out, 0o644); err != nil {
    	log.Fatal(err)
    }
  6. Reler e verificar o resultado

    O PDF produzido lê-se como qualquer fatura recebida. Check verifica o contentor PDF, os metadados XMP e o XML, com as mesmas regras.

    Go
    back, att, err := zerechnung.Read(out)
    if err != nil {
    	log.Fatal(err)
    }
    fmt.Println(att.Filename, "·", att.Metadata.ConformanceLevel)
    l := back.Lines[0]
    fmt.Printf("%s: %s × %s €/%s = %s €\n",
    	l.Item.Name, l.Quantity, l.NetPrice, l.PriceBaseQuantity, l.NetAmount)
    vat := back.VATBreakdown[0]
    fmt.Println("IVA", vat.CategoryCode, vat.Rate, "% ·", vat.ExemptionReason)
    fmt.Println("Total:", back.Totals.GrandTotal, "€ · vencimento:", back.PaymentTerms[0].DueDate)
    
    report, _, err := zerechnung.Check(out, &validate.Options{Auto: true})
    if err != nil {
    	log.Fatal(err)
    }
    fmt.Println("Erros:", len(report.Errors()))

O que o programa mostra

go run .
factur-x.xml · EN 16931
Rolha natural 49 × 24 mm, classe Flor: 24000 × 980.00 €/1000 = 23520.00 €
IVA K 0 % · Isento nos termos do artigo 14.º do RITI.
Total: 32028.00 € · vencimento: 2027-01-19
Erros: 0
O programa completo
main.go
package main

import (
	"fmt"
	"log"
	"os"
	"time"

	"github.com/ritoon/zerechnung"
	"github.com/ritoon/zerechnung/invoice"
	"github.com/ritoon/zerechnung/validate"
)

func main() {
	// Ler o PDF da fatura
	pdf, err := os.ReadFile("fatura.pdf")
	if err != nil {
		log.Fatal(err)
	}

	// Descrever o vendedor e o comprador
	fabrica := invoice.Party{
		Name:        "Rolhas Teixeira & Filhas, Lda.",
		VATID:       "PT508361729",
		Description: "Capital social: 250 000 €. Matriculada na C.R.C. de Santa Maria da Feira.",
		Address: invoice.Address{
			Line1: "Rua do Montado, 212", PostCode: "4520-211", City: "Santa Maria da Feira",
			CountryCode: "PT",
		},
		Contact: &invoice.Contact{
			PersonName: "Marta Teixeira",
			Phone:      "+351 256 000 000",
			Email:      "comercial@rolhasteixeira.example",
		},
	}
	chateau := invoice.Party{
		Name:              "SCEA Château Mauvesin-Lartigue",
		VATID:             "FR43438162752",
		LegalRegistration: invoice.Identifier{ID: "438162752", Scheme: invoice.SchemeSIREN},
		Address: invoice.Address{
			Line1: "Lieu-dit Mauvesin", PostCode: "33330", City: "Saint-Émilion", CountryCode: "FR",
		},
	}

	// Acrescentar as menções obrigatórias
	d := invoice.MustDecimal
	inv := &invoice.Invoice{
		Profile:                invoice.ProfileEN16931,
		Number:                 "FT 2026/318",
		TypeCode:               invoice.TypeCommercialInvoice,
		IssueDate:              invoice.NewDate(2026, time.November, 20),
		Currency:               "EUR",
		PurchaseOrderReference: "CMD-2026-044",
		Seller:                 fabrica,
		Buyer:                  chateau,
		DeliveryDate:           invoice.NewDate(2026, time.November, 18),
		ShipTo: &invoice.Party{
			Name: "Château Mauvesin-Lartigue, chai d'embouteillage",
			Address: invoice.Address{
				Line1: "Lieu-dit Mauvesin", PostCode: "33330", City: "Saint-Émilion", CountryCode: "FR",
			},
		},
		Notes: []invoice.Note{{SubjectCode: "REG", Content: "ATCUD: JJMRT4WK-318"}},
		VATBreakdown: []invoice.VATBreakdown{{
			CategoryCode:        invoice.VATIntraCommunity,
			Rate:                d("0"),
			ExemptionReason:     "Isento nos termos do artigo 14.º do RITI.",
			ExemptionReasonCode: invoice.VATEXIntraCommunity,
		}},
		PaymentMeans: []invoice.PaymentMeans{{
			TypeCode:  invoice.PaymentSEPACreditTransfer,
			PayeeIBAN: "PT50000201231234567890154",
		}},
		PaymentTerms: []invoice.PaymentTerms{{
			Description: "Pagamento a 60 dias da data da fatura, por transferência bancária.",
			DueDate:     invoice.NewDate(2027, time.January, 19),
		}},
	}

	// Listar as rolhas
	inv.Lines = []invoice.Line{{
		ID: "1", Item: invoice.Item{Name: "Rolha natural 49 × 24 mm, classe Flor"},
		Quantity: d("24000"), UnitCode: "H87", NetPrice: d("980.00"),
		PriceBaseQuantity: d("1000"), PriceBaseQuantityUnit: "H87",
		VATCategoryCode: invoice.VATIntraCommunity, VATRate: d("0"),
	}, {
		ID: "2", Item: invoice.Item{Name: "Rolha natural 45 × 24 mm, classe Extra"},
		Quantity: d("12000"), UnitCode: "H87", NetPrice: d("620.00"),
		PriceBaseQuantity: d("1000"), PriceBaseQuantityUnit: "H87",
		VATCategoryCode: invoice.VATIntraCommunity, VATRate: d("0"),
	}, {
		ID: "3", Item: invoice.Item{Name: "Marcação a fogo do brasão e do ano de colheita"},
		Quantity: d("36000"), UnitCode: "H87", NetPrice: d("18.00"),
		PriceBaseQuantity: d("1000"), PriceBaseQuantityUnit: "H87",
		VATCategoryCode: invoice.VATIntraCommunity, VATRate: d("0"),
	}, {
		ID: "4", Item: invoice.Item{Name: "Transporte rodoviário até Saint-Émilion"},
		Quantity: d("1"), UnitCode: "C62", NetPrice: d("420.00"),
		VATCategoryCode: invoice.VATIntraCommunity, VATRate: d("0"),
	}}

	// Criar a fatura Factur-X
	out, err := zerechnung.Create(pdf, inv, &zerechnung.CreateOptions{
		Calculate: true,
		Validate:  &validate.Options{Auto: true},
	})
	if err != nil {
		log.Fatal(err)
	}
	if err := os.WriteFile("FT-2026-318.pdf", out, 0o644); err != nil {
		log.Fatal(err)
	}

	// Reler e verificar o resultado
	back, att, err := zerechnung.Read(out)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(att.Filename, "·", att.Metadata.ConformanceLevel)
	l := back.Lines[0]
	fmt.Printf("%s: %s × %s €/%s = %s €\n",
		l.Item.Name, l.Quantity, l.NetPrice, l.PriceBaseQuantity, l.NetAmount)
	vat := back.VATBreakdown[0]
	fmt.Println("IVA", vat.CategoryCode, vat.Rate, "% ·", vat.ExemptionReason)
	fmt.Println("Total:", back.Totals.GrandTotal, "€ · vencimento:", back.PaymentTerms[0].DueDate)

	report, _, err := zerechnung.Check(out, &validate.Options{Auto: true})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Erros:", len(report.Errors()))
}

Execute-o a partir de um clone do repositório:

Shell
git clone https://github.com/ritoon/zerechnung
cd zerechnung/site/examples/pt-1-rolhas
go run .

Este exemplo no GitHub

Exemplo 2

Uma oficina de azulejos de Lisboa fatura a uma loja de Bruxelas por Peppol

Peppol BIS Billing 3.0UBLBélgicaTransmissão intracomunitáriaIVA 0 %

Na oficina de Leonor Bastos, em Alfama, os azulejos ainda se pintam à mão, um a um, na tradição dos padrões pombalinos e das figuras avulsas do século XVIII. A Maison Lemaire & Benali, uma loja de decoração de Ixelles, em Bruxelas, encomendou-lhe azulejos para revenda e um painel com uma vista do Tejo, pintado por encomenda.

Desde 1 de janeiro de 2026, a fatura eletrónica em Peppol é obrigatória entre empresas belgas, e a loja recebe as faturas por essa rede. A oficina, que não tem essa obrigação, segue o mesmo caminho: uma fatura Peppol BIS Billing 3.0 em UBL, validada com as regras Peppol, sem IVA português por se tratar de uma transmissão intracomunitária.

  1. Identificar as partes na rede Peppol

    Na rede Peppol, cada parte tem um endereço eletrónico (BT-34, BT-49) com o seu esquema. A oficina usa o seu número de IVA português (esquema 9946). A loja usa o número de empresa belga (esquema 0208), cujos dois últimos algarismos são 97 menos o resto da divisão por 97 dos oito primeiros: a regra PEPPOL-COMMON-R043 verifica-o.

    Go
    oficina := invoice.Party{
    	Name:  "Oficina de Azulejos Leonor Bastos, Lda.",
    	VATID: "PT514729384",
    	Address: invoice.Address{
    		Line1: "Rua dos Remédios, 87", PostCode: "1100-443", City: "Lisboa", CountryCode: "PT",
    	},
    	Contact: &invoice.Contact{
    		PersonName: "Leonor Bastos", Email: "encomendas@leonorbastos.example",
    	},
    	ElectronicAddress: invoice.Identifier{ID: "PT514729384", Scheme: invoice.SchemePTVAT},
    }
    loja := invoice.Party{
    	Name:              "Maison Lemaire & Benali SRL",
    	VATID:             "BE0728391608",
    	LegalRegistration: invoice.Identifier{ID: "0728391608", Scheme: invoice.SchemeBEEnterprise},
    	Address: invoice.Address{
    		Line1: "Rue du Bailli 54", PostCode: "1050", City: "Ixelles", CountryCode: "BE",
    	},
    	ElectronicAddress: invoice.Identifier{ID: "0728391608", Scheme: invoice.SchemeBEEnterprise},
    }
  2. Preencher o cabeçalho Peppol

    O Peppol exige o processo de negócio (BT-23) e uma referência do comprador ou da sua encomenda (BT-10 ou BT-13), e só admite uma nota no cabeçalho: aqui o ATCUD, o código único do documento. O perfil ProfilePeppol escreve o identificador da especificação (BT-24). A isenção cita o artigo 14.º do RITI; a data e o local de entrega são obrigatórios numa transmissão intracomunitária.

    Go
    d := invoice.MustDecimal
    inv := &invoice.Invoice{
    	Profile:                invoice.ProfilePeppol,
    	BusinessProcess:        invoice.ProcessPeppolBilling,
    	Number:                 "FT 2026/1209",
    	TypeCode:               invoice.TypeCommercialInvoice,
    	IssueDate:              invoice.NewDate(2026, time.November, 20),
    	Currency:               "EUR",
    	BuyerReference:         "ACHATS-DECO",
    	PurchaseOrderReference: "BC-2026-0093",
    	Seller:                 oficina,
    	Buyer:                  loja,
    	DeliveryDate:           invoice.NewDate(2026, time.November, 16),
    	ShipTo: &invoice.Party{
    		Name: "Maison Lemaire & Benali",
    		Address: invoice.Address{
    			Line1: "Rue du Bailli 54", PostCode: "1050", City: "Ixelles", CountryCode: "BE",
    		},
    	},
    	Notes: []invoice.Note{{SubjectCode: "REG", Content: "ATCUD: KD7Q2MPA-1209"}},
    	VATBreakdown: []invoice.VATBreakdown{{
    		CategoryCode:        invoice.VATIntraCommunity,
    		Rate:                d("0"),
    		ExemptionReason:     "Isento nos termos do artigo 14.º do RITI.",
    		ExemptionReasonCode: invoice.VATEXIntraCommunity,
    	}},
    	PaymentMeans: []invoice.PaymentMeans{{
    		TypeCode:         invoice.PaymentSEPACreditTransfer,
    		PayeeIBAN:        "PT50000201231234567890154",
    		PayeeAccountName: "Oficina de Azulejos Leonor Bastos",
    	}},
    	PaymentTerms: []invoice.PaymentTerms{{
    		Description: "Pagamento a 30 dias, por transferência bancária.",
    		DueDate:     invoice.NewDate(2026, time.December, 20),
    	}},
    }
  3. Listar os azulejos

    Os azulejos contam-se à peça (código UN/ECE H87) e o painel como uma unidade (C62). Todas as linhas levam a categoria K e a taxa de 0 %.

    Go
    inv.Lines = []invoice.Line{{
    	ID: "1", Item: invoice.Item{Name: "Azulejo pintado à mão, padrão pombalino, 14 × 14 cm"},
    	Quantity: d("800"), UnitCode: "H87", NetPrice: d("6.80"),
    	VATCategoryCode: invoice.VATIntraCommunity, VATRate: d("0"),
    }, {
    	ID: "2", Item: invoice.Item{Name: "Azulejo de figura avulsa, aves e flores, 14 × 14 cm"},
    	Quantity: d("240"), UnitCode: "H87", NetPrice: d("9.50"),
    	VATCategoryCode: invoice.VATIntraCommunity, VATRate: d("0"),
    }, {
    	ID: "3", Item: invoice.Item{Name: "Painel «Vista do Tejo», 6 × 8 azulejos, por encomenda"},
    	Quantity: d("1"), UnitCode: "C62", NetPrice: d("1450.00"),
    	VATCategoryCode: invoice.VATIntraCommunity, VATRate: d("0"),
    }}
  4. Acrescentar a embalagem e o transporte

    A embalagem em grades de madeira e o transporte até Bruxelas são encargos ao nível do documento (BG-21), com o motivo em texto e o seu código UNTDID 7161: PC para a embalagem, FC para o frete. Levam a mesma categoria de IVA que os azulejos e entram no total dos encargos (BT-108).

    Go
    inv.AllowancesCharges = []invoice.AllowanceCharge{{
    	Charge: true, Amount: d("185.00"),
    	Reason: "Embalagem em grades de madeira", ReasonCode: "PC",
    	VATCategoryCode: invoice.VATIntraCommunity, VATRate: d("0"),
    }, {
    	Charge: true, Amount: d("320.00"),
    	Reason: "Transporte Lisboa-Bruxelas", ReasonCode: "FC",
    	VATCategoryCode: invoice.VATIntraCommunity, VATRate: d("0"),
    }}
  5. Calcular e escrever o UBL

    Calculate calcula os montantes das linhas, os totais e o resumo do IVA, com decimais exatos. ubl.Marshal escreve a fatura em UBL 2.1, a sintaxe que circula na rede Peppol.

    Go
    inv.Calculate()
    xml, err := ubl.Marshal(inv, &ubl.MarshalOptions{Indent: true})
    if err != nil {
    	log.Fatal(err)
    }
    if err := os.WriteFile("FT-2026-1209.xml", xml, 0o644); err != nil {
    	log.Fatal(err)
    }
  6. Validar com as regras Peppol e reler

    As regras Peppol juntam-se ao esquema UBL e às regras EN 16931. Uma fatura com erros não deve sair: o programa mostra-os e para. A loja lerá o UBL com ubl.Parse, ou com o seu próprio programa.

    Go
    report := validate.XML(xml, &validate.Options{Rules: validate.Default | validate.Peppol})
    if !report.Valid() {
    	for _, f := range report.Errors() {
    		fmt.Println(f)
    	}
    	os.Exit(1)
    }
    back, err := ubl.Parse(xml)
    if err != nil {
    	log.Fatal(err)
    }
    from, to := back.Seller.ElectronicAddress, back.Buyer.ElectronicAddress
    fmt.Println(report.Profile, "·", from.Scheme+":"+from.ID, "→", to.Scheme+":"+to.ID)
    t := back.Totals
    fmt.Println("Linhas:", t.LineTotal, "€ · embalagem e transporte:", t.ChargeTotal, "€")
    fmt.Println("Total:", t.GrandTotal, "€ ·", back.VATBreakdown[0].ExemptionReason)
    fmt.Println("Erros:", len(report.Errors()), "· avisos:", len(report.Warnings()))

O que o programa mostra

go run .
PEPPOL · 9946:PT514729384 → 0208:0728391608
Linhas: 9170.00 € · embalagem e transporte: 505.00 €
Total: 9675.00 € · Isento nos termos do artigo 14.º do RITI.
Erros: 0 · avisos: 0
O programa completo
main.go
package main

import (
	"fmt"
	"log"
	"os"
	"time"

	"github.com/ritoon/zerechnung/invoice"
	"github.com/ritoon/zerechnung/ubl"
	"github.com/ritoon/zerechnung/validate"
)

func main() {
	// Identificar as partes na rede Peppol
	oficina := invoice.Party{
		Name:  "Oficina de Azulejos Leonor Bastos, Lda.",
		VATID: "PT514729384",
		Address: invoice.Address{
			Line1: "Rua dos Remédios, 87", PostCode: "1100-443", City: "Lisboa", CountryCode: "PT",
		},
		Contact: &invoice.Contact{
			PersonName: "Leonor Bastos", Email: "encomendas@leonorbastos.example",
		},
		ElectronicAddress: invoice.Identifier{ID: "PT514729384", Scheme: invoice.SchemePTVAT},
	}
	loja := invoice.Party{
		Name:              "Maison Lemaire & Benali SRL",
		VATID:             "BE0728391608",
		LegalRegistration: invoice.Identifier{ID: "0728391608", Scheme: invoice.SchemeBEEnterprise},
		Address: invoice.Address{
			Line1: "Rue du Bailli 54", PostCode: "1050", City: "Ixelles", CountryCode: "BE",
		},
		ElectronicAddress: invoice.Identifier{ID: "0728391608", Scheme: invoice.SchemeBEEnterprise},
	}

	// Preencher o cabeçalho Peppol
	d := invoice.MustDecimal
	inv := &invoice.Invoice{
		Profile:                invoice.ProfilePeppol,
		BusinessProcess:        invoice.ProcessPeppolBilling,
		Number:                 "FT 2026/1209",
		TypeCode:               invoice.TypeCommercialInvoice,
		IssueDate:              invoice.NewDate(2026, time.November, 20),
		Currency:               "EUR",
		BuyerReference:         "ACHATS-DECO",
		PurchaseOrderReference: "BC-2026-0093",
		Seller:                 oficina,
		Buyer:                  loja,
		DeliveryDate:           invoice.NewDate(2026, time.November, 16),
		ShipTo: &invoice.Party{
			Name: "Maison Lemaire & Benali",
			Address: invoice.Address{
				Line1: "Rue du Bailli 54", PostCode: "1050", City: "Ixelles", CountryCode: "BE",
			},
		},
		Notes: []invoice.Note{{SubjectCode: "REG", Content: "ATCUD: KD7Q2MPA-1209"}},
		VATBreakdown: []invoice.VATBreakdown{{
			CategoryCode:        invoice.VATIntraCommunity,
			Rate:                d("0"),
			ExemptionReason:     "Isento nos termos do artigo 14.º do RITI.",
			ExemptionReasonCode: invoice.VATEXIntraCommunity,
		}},
		PaymentMeans: []invoice.PaymentMeans{{
			TypeCode:         invoice.PaymentSEPACreditTransfer,
			PayeeIBAN:        "PT50000201231234567890154",
			PayeeAccountName: "Oficina de Azulejos Leonor Bastos",
		}},
		PaymentTerms: []invoice.PaymentTerms{{
			Description: "Pagamento a 30 dias, por transferência bancária.",
			DueDate:     invoice.NewDate(2026, time.December, 20),
		}},
	}

	// Listar os azulejos
	inv.Lines = []invoice.Line{{
		ID: "1", Item: invoice.Item{Name: "Azulejo pintado à mão, padrão pombalino, 14 × 14 cm"},
		Quantity: d("800"), UnitCode: "H87", NetPrice: d("6.80"),
		VATCategoryCode: invoice.VATIntraCommunity, VATRate: d("0"),
	}, {
		ID: "2", Item: invoice.Item{Name: "Azulejo de figura avulsa, aves e flores, 14 × 14 cm"},
		Quantity: d("240"), UnitCode: "H87", NetPrice: d("9.50"),
		VATCategoryCode: invoice.VATIntraCommunity, VATRate: d("0"),
	}, {
		ID: "3", Item: invoice.Item{Name: "Painel «Vista do Tejo», 6 × 8 azulejos, por encomenda"},
		Quantity: d("1"), UnitCode: "C62", NetPrice: d("1450.00"),
		VATCategoryCode: invoice.VATIntraCommunity, VATRate: d("0"),
	}}

	// Acrescentar a embalagem e o transporte
	inv.AllowancesCharges = []invoice.AllowanceCharge{{
		Charge: true, Amount: d("185.00"),
		Reason: "Embalagem em grades de madeira", ReasonCode: "PC",
		VATCategoryCode: invoice.VATIntraCommunity, VATRate: d("0"),
	}, {
		Charge: true, Amount: d("320.00"),
		Reason: "Transporte Lisboa-Bruxelas", ReasonCode: "FC",
		VATCategoryCode: invoice.VATIntraCommunity, VATRate: d("0"),
	}}

	// Calcular e escrever o UBL
	inv.Calculate()
	xml, err := ubl.Marshal(inv, &ubl.MarshalOptions{Indent: true})
	if err != nil {
		log.Fatal(err)
	}
	if err := os.WriteFile("FT-2026-1209.xml", xml, 0o644); err != nil {
		log.Fatal(err)
	}

	// Validar com as regras Peppol e reler
	report := validate.XML(xml, &validate.Options{Rules: validate.Default | validate.Peppol})
	if !report.Valid() {
		for _, f := range report.Errors() {
			fmt.Println(f)
		}
		os.Exit(1)
	}
	back, err := ubl.Parse(xml)
	if err != nil {
		log.Fatal(err)
	}
	from, to := back.Seller.ElectronicAddress, back.Buyer.ElectronicAddress
	fmt.Println(report.Profile, "·", from.Scheme+":"+from.ID, "→", to.Scheme+":"+to.ID)
	t := back.Totals
	fmt.Println("Linhas:", t.LineTotal, "€ · embalagem e transporte:", t.ChargeTotal, "€")
	fmt.Println("Total:", t.GrandTotal, "€ ·", back.VATBreakdown[0].ExemptionReason)
	fmt.Println("Erros:", len(report.Errors()), "· avisos:", len(report.Warnings()))
}

Execute-o a partir de um clone do repositório:

Shell
git clone https://github.com/ritoon/zerechnung
cd zerechnung/site/examples/pt-2-azulejos
go run .

Este exemplo no GitHub

Exemplo 3

Uma conserveira de Matosinhos envia uma XRechnung a cantinas de Berlim

XRechnungCIILeitweg-IDDesconto de pronto pagamentoTransmissão intracomunitária

Em Matosinhos, as fábricas de conservas trabalham a sardinha desde o fim do século XIX. A Conserveira Marés de Leça mantém o enlatamento à mão: o peixe é limpo, cozido e arrumado em cada lata antes do azeite. O Studierendenwerk Spreebogen, o organismo público que gere cantinas universitárias em Berlim, encomendou-lhe conservas para uma semana de cozinha portuguesa.

Os organismos públicos alemães recebem as faturas em XRechnung: um ficheiro XML, sem PDF, endereçado pela Leitweg-ID do serviço destinatário. O ZeRechnung escreve-a em CII e verifica-a com as regras alemãs (BR-DE), escritas a partir dos artefactos da KoSIT. A fatura não leva IVA português, por se tratar de uma transmissão intracomunitária.

  1. Descrever a conserveira

    A XRechnung pede mais do que a EN 16931: um contacto do vendedor com nome, telefone e endereço de correio eletrónico (BR-DE-2 e BR-DE-5 a BR-DE-7) e um endereço eletrónico (BT-34), aqui um e-mail (esquema EM). O número de IVA, com o prefixo PT, é obrigatório na categoria K.

    Go
    conserveira := invoice.Party{
    	Name:  "Conserveira Marés de Leça, Lda.",
    	VATID: "PT502618477",
    	Address: invoice.Address{
    		Line1: "Rua das Traineiras, 45", PostCode: "4450-208", City: "Matosinhos",
    		CountryCode: "PT",
    	},
    	Contact: &invoice.Contact{
    		PersonName: "Beatriz Monteiro",
    		Phone:      "+351 229 000 000",
    		Email:      "beatriz.monteiro@maresdeleca.example",
    	},
    	ElectronicAddress: invoice.Identifier{
    		ID: "faturas@maresdeleca.example", Scheme: invoice.SchemeEmail,
    	},
    }
  2. Endereçar o comprador público pela Leitweg-ID

    A Leitweg-ID identifica o serviço que recebe a fatura; começa pelo código do Land, 11 para Berlim. Vai na referência do comprador (BT-10, obrigatória pela regra BR-DE-15) e no endereço eletrónico do comprador, com o esquema 0204. O ZeRechnung verifica os seus dois algarismos de controlo (ISO 7064 MOD 97-10). O número de IVA alemão do comprador é obrigatório numa transmissão intracomunitária.

    Go
    leitwegID := "11001234-MENSEN-06"
    cantinas := invoice.Party{
    	Name:  "Studierendenwerk Spreebogen, Anstalt des öffentlichen Rechts",
    	VATID: "DE274193562",
    	Address: invoice.Address{
    		Line1: "Am Spreebogen 5", PostCode: "10557", City: "Berlin", CountryCode: "DE",
    	},
    	ElectronicAddress: invoice.Identifier{ID: leitwegID, Scheme: invoice.SchemeLeitwegID},
    }
  3. Preencher as menções da fatura

    A fatura cita a encomenda (BT-13), a data de entrega (BT-72) e o armazém da cantina (BG-15, com localidade e código postal pelas regras BR-DE-10 e BR-DE-11). O ATCUD vai numa nota; a isenção cita o artigo 14.º do RITI. O desconto de pronto pagamento escreve-se numa linha própria dos termos de pagamento (BT-20), na forma que a XRechnung define e terminada por uma quebra de linha (BR-DE-18): a contabilidade do comprador calcula-o sozinha.

    Go
    d := invoice.MustDecimal
    inv := &invoice.Invoice{
    	Profile:                invoice.ProfileXRechnung,
    	Number:                 "FT 2026/2045",
    	TypeCode:               invoice.TypeCommercialInvoice,
    	IssueDate:              invoice.NewDate(2026, time.November, 20),
    	Currency:               "EUR",
    	BuyerReference:         leitwegID,
    	PurchaseOrderReference: "BEST-2026-3317",
    	Seller:                 conserveira,
    	Buyer:                  cantinas,
    	DeliveryDate:           invoice.NewDate(2026, time.November, 16),
    	ShipTo: &invoice.Party{
    		Name: "Mensa Spreebogen, Wareneingang",
    		Address: invoice.Address{
    			Line1: "Am Spreebogen 5", PostCode: "10557", City: "Berlin", CountryCode: "DE",
    		},
    	},
    	Notes: []invoice.Note{{SubjectCode: "REG", Content: "ATCUD: MR4TQ9XC-2045"}},
    	VATBreakdown: []invoice.VATBreakdown{{
    		CategoryCode:        invoice.VATIntraCommunity,
    		Rate:                d("0"),
    		ExemptionReason:     "Isento nos termos do artigo 14.º do RITI.",
    		ExemptionReasonCode: invoice.VATEXIntraCommunity,
    	}},
    	PaymentMeans: []invoice.PaymentMeans{{
    		TypeCode:         invoice.PaymentSEPACreditTransfer,
    		PayeeIBAN:        "PT50000201231234567890154",
    		PayeeAccountName: "Conserveira Marés de Leça, Lda.",
    	}},
    	PaymentTerms: []invoice.PaymentTerms{{
    		Description: "Pagamento a 30 dias, por transferência bancária.\n" +
    			"#SKONTO#TAGE=10#PROZENT=2.00#\n",
    		DueDate: invoice.NewDate(2026, time.December, 20),
    	}},
    }
  4. Listar as conservas

    As latas contam-se à peça (código UN/ECE H87) e o transporte como uma unidade (C62). Todas as linhas levam a categoria K e a taxa de 0 %; a XRechnung exige que a taxa figure no resumo do IVA mesmo quando é zero (BR-DE-14).

    Go
    inv.Lines = []invoice.Line{{
    	ID: "1", Item: invoice.Item{Name: "Sardinhas em azeite virgem extra, lata de 120 g"},
    	Quantity: d("1200"), UnitCode: "H87", NetPrice: d("1.85"),
    	VATCategoryCode: invoice.VATIntraCommunity, VATRate: d("0"),
    }, {
    	ID: "2", Item: invoice.Item{Name: "Sardinhas em azeite com piri-piri, lata de 120 g"},
    	Quantity: d("600"), UnitCode: "H87", NetPrice: d("1.95"),
    	VATCategoryCode: invoice.VATIntraCommunity, VATRate: d("0"),
    }, {
    	ID: "3", Item: invoice.Item{Name: "Filetes de cavala em azeite, lata de 120 g"},
    	Quantity: d("600"), UnitCode: "H87", NetPrice: d("2.10"),
    	VATCategoryCode: invoice.VATIntraCommunity, VATRate: d("0"),
    }, {
    	ID: "4", Item: invoice.Item{Name: "Paté de sardinha, lata de 75 g"},
    	Quantity: d("480"), UnitCode: "H87", NetPrice: d("1.20"),
    	VATCategoryCode: invoice.VATIntraCommunity, VATRate: d("0"),
    }, {
    	ID: "5", Item: invoice.Item{Name: "Transporte rodoviário, Matosinhos-Berlim"},
    	Quantity: d("1"), UnitCode: "C62", NetPrice: d("380.00"),
    	VATCategoryCode: invoice.VATIntraCommunity, VATRate: d("0"),
    }}
  5. Calcular e escrever a XRechnung

    Calculate calcula os montantes, os totais e o resumo do IVA. cii.Marshal escreve a fatura na sintaxe CII, com o identificador da XRechnung 3.0 (BT-24); ubl.Marshal escreveria a mesma fatura em UBL, que os organismos públicos alemães também aceitam.

    Go
    inv.Calculate()
    xml, err := cii.Marshal(inv, &cii.MarshalOptions{Indent: true})
    if err != nil {
    	log.Fatal(err)
    }
    if err := os.WriteFile("FT-2026-2045.xml", xml, 0o644); err != nil {
    	log.Fatal(err)
    }
  6. Validar com as regras alemãs e reler

    As regras alemãs (o conjunto Germany: as regras BR-DE e a verificação da Leitweg-ID) aplicam-se sozinhas a uma XRechnung, que se declara em BT-24; aqui pedem-se de forma explícita. Uma fatura com erros não deve sair: o programa mostra-os e para. Depois, cii.Parse relê o XML como o comprador o lerá.

    Go
    report := validate.XML(xml, &validate.Options{Rules: validate.Default | validate.Germany})
    if !report.Valid() {
    	for _, f := range report.Errors() {
    		fmt.Println(f)
    	}
    	os.Exit(1)
    }
    back, err := cii.Parse(xml)
    if err != nil {
    	log.Fatal(err)
    }
    t := back.Totals
    fmt.Println(report.Profile, "· Leitweg-ID", back.BuyerReference)
    fmt.Println("Total:", t.GrandTotal, "€ · IVA:", t.TaxTotal, "€ ·",
    	back.VATBreakdown[0].ExemptionReasonCode)
    desconto := t.DuePayable.Mul(d("0.02")).Round(2)
    fmt.Printf("Com 2 %% de desconto até %s: %s €\n",
    	back.IssueDate.AddDays(10), t.DuePayable.Sub(desconto))
    fmt.Println("Erros:", len(report.Errors()), "· avisos:", len(report.Warnings()))

O que o programa mostra

go run .
XRECHNUNG · Leitweg-ID 11001234-MENSEN-06
Total: 5606.00 € · IVA: 0.00 € · VATEX-EU-IC
Com 2 % de desconto até 2026-11-30: 5493.88 €
Erros: 0 · avisos: 0
O programa completo
main.go
package main

import (
	"fmt"
	"log"
	"os"
	"time"

	"github.com/ritoon/zerechnung/cii"
	"github.com/ritoon/zerechnung/invoice"
	"github.com/ritoon/zerechnung/validate"
)

func main() {
	// Descrever a conserveira
	conserveira := invoice.Party{
		Name:  "Conserveira Marés de Leça, Lda.",
		VATID: "PT502618477",
		Address: invoice.Address{
			Line1: "Rua das Traineiras, 45", PostCode: "4450-208", City: "Matosinhos",
			CountryCode: "PT",
		},
		Contact: &invoice.Contact{
			PersonName: "Beatriz Monteiro",
			Phone:      "+351 229 000 000",
			Email:      "beatriz.monteiro@maresdeleca.example",
		},
		ElectronicAddress: invoice.Identifier{
			ID: "faturas@maresdeleca.example", Scheme: invoice.SchemeEmail,
		},
	}

	// Endereçar o comprador público pela Leitweg-ID
	leitwegID := "11001234-MENSEN-06"
	cantinas := invoice.Party{
		Name:  "Studierendenwerk Spreebogen, Anstalt des öffentlichen Rechts",
		VATID: "DE274193562",
		Address: invoice.Address{
			Line1: "Am Spreebogen 5", PostCode: "10557", City: "Berlin", CountryCode: "DE",
		},
		ElectronicAddress: invoice.Identifier{ID: leitwegID, Scheme: invoice.SchemeLeitwegID},
	}

	// Preencher as menções da fatura
	d := invoice.MustDecimal
	inv := &invoice.Invoice{
		Profile:                invoice.ProfileXRechnung,
		Number:                 "FT 2026/2045",
		TypeCode:               invoice.TypeCommercialInvoice,
		IssueDate:              invoice.NewDate(2026, time.November, 20),
		Currency:               "EUR",
		BuyerReference:         leitwegID,
		PurchaseOrderReference: "BEST-2026-3317",
		Seller:                 conserveira,
		Buyer:                  cantinas,
		DeliveryDate:           invoice.NewDate(2026, time.November, 16),
		ShipTo: &invoice.Party{
			Name: "Mensa Spreebogen, Wareneingang",
			Address: invoice.Address{
				Line1: "Am Spreebogen 5", PostCode: "10557", City: "Berlin", CountryCode: "DE",
			},
		},
		Notes: []invoice.Note{{SubjectCode: "REG", Content: "ATCUD: MR4TQ9XC-2045"}},
		VATBreakdown: []invoice.VATBreakdown{{
			CategoryCode:        invoice.VATIntraCommunity,
			Rate:                d("0"),
			ExemptionReason:     "Isento nos termos do artigo 14.º do RITI.",
			ExemptionReasonCode: invoice.VATEXIntraCommunity,
		}},
		PaymentMeans: []invoice.PaymentMeans{{
			TypeCode:         invoice.PaymentSEPACreditTransfer,
			PayeeIBAN:        "PT50000201231234567890154",
			PayeeAccountName: "Conserveira Marés de Leça, Lda.",
		}},
		PaymentTerms: []invoice.PaymentTerms{{
			Description: "Pagamento a 30 dias, por transferência bancária.\n" +
				"#SKONTO#TAGE=10#PROZENT=2.00#\n",
			DueDate: invoice.NewDate(2026, time.December, 20),
		}},
	}

	// Listar as conservas
	inv.Lines = []invoice.Line{{
		ID: "1", Item: invoice.Item{Name: "Sardinhas em azeite virgem extra, lata de 120 g"},
		Quantity: d("1200"), UnitCode: "H87", NetPrice: d("1.85"),
		VATCategoryCode: invoice.VATIntraCommunity, VATRate: d("0"),
	}, {
		ID: "2", Item: invoice.Item{Name: "Sardinhas em azeite com piri-piri, lata de 120 g"},
		Quantity: d("600"), UnitCode: "H87", NetPrice: d("1.95"),
		VATCategoryCode: invoice.VATIntraCommunity, VATRate: d("0"),
	}, {
		ID: "3", Item: invoice.Item{Name: "Filetes de cavala em azeite, lata de 120 g"},
		Quantity: d("600"), UnitCode: "H87", NetPrice: d("2.10"),
		VATCategoryCode: invoice.VATIntraCommunity, VATRate: d("0"),
	}, {
		ID: "4", Item: invoice.Item{Name: "Paté de sardinha, lata de 75 g"},
		Quantity: d("480"), UnitCode: "H87", NetPrice: d("1.20"),
		VATCategoryCode: invoice.VATIntraCommunity, VATRate: d("0"),
	}, {
		ID: "5", Item: invoice.Item{Name: "Transporte rodoviário, Matosinhos-Berlim"},
		Quantity: d("1"), UnitCode: "C62", NetPrice: d("380.00"),
		VATCategoryCode: invoice.VATIntraCommunity, VATRate: d("0"),
	}}

	// Calcular e escrever a XRechnung
	inv.Calculate()
	xml, err := cii.Marshal(inv, &cii.MarshalOptions{Indent: true})
	if err != nil {
		log.Fatal(err)
	}
	if err := os.WriteFile("FT-2026-2045.xml", xml, 0o644); err != nil {
		log.Fatal(err)
	}

	// Validar com as regras alemãs e reler
	report := validate.XML(xml, &validate.Options{Rules: validate.Default | validate.Germany})
	if !report.Valid() {
		for _, f := range report.Errors() {
			fmt.Println(f)
		}
		os.Exit(1)
	}
	back, err := cii.Parse(xml)
	if err != nil {
		log.Fatal(err)
	}
	t := back.Totals
	fmt.Println(report.Profile, "· Leitweg-ID", back.BuyerReference)
	fmt.Println("Total:", t.GrandTotal, "€ · IVA:", t.TaxTotal, "€ ·",
		back.VATBreakdown[0].ExemptionReasonCode)
	desconto := t.DuePayable.Mul(d("0.02")).Round(2)
	fmt.Printf("Com 2 %% de desconto até %s: %s €\n",
		back.IssueDate.AddDays(10), t.DuePayable.Sub(desconto))
	fmt.Println("Erros:", len(report.Errors()), "· avisos:", len(report.Warnings()))
}

Execute-o a partir de um clone do repositório:

Shell
git clone https://github.com/ritoon/zerechnung
cd zerechnung/site/examples/pt-3-conservas
go run .

Este exemplo no GitHub

Mais exemplos, para cada funcionalidade do pacote: Exemplos completos no README · Referência da API