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.
As empresas, as pessoas e os identificadores destes exemplos são fictícios. Os identificadores têm dígitos de controlo válidos, para que as regras nacionais os aceitem.
Exemplo 1
Uma fábrica de rolhas de Santa Maria da Feira fatura a um château de Bordéus
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).
-
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.
Gopdf, err := os.ReadFile("fatura.pdf") if err != nil { log.Fatal(err) } -
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).
Gofabrica := 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
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.
God := 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
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).
Goinv.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
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.
Goout, 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
O PDF produzido lê-se como qualquer fatura recebida. Check verifica o contentor PDF, os metadados XMP e o XML, com as mesmas regras.
Goback, 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
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: 0O programa completo
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:
git clone https://github.com/ritoon/zerechnung
cd zerechnung/site/examples/pt-1-rolhas
go run .Exemplo 2
Uma oficina de azulejos de Lisboa fatura a uma loja de Bruxelas por Peppol
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.
-
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.
Gooficina := 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
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.
God := 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
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 %.
Goinv.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
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).
Goinv.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
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.
Goinv.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
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.
Goreport := 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
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: 0O programa completo
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:
git clone https://github.com/ritoon/zerechnung
cd zerechnung/site/examples/pt-2-azulejos
go run .Exemplo 3
Uma conserveira de Matosinhos envia uma XRechnung a cantinas de Berlim
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.
-
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.
Goconserveira := 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
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.
GoleitwegID := "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
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.
God := 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
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).
Goinv.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
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.
Goinv.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
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á.
Goreport := 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
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: 0O programa completo
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:
git clone https://github.com/ritoon/zerechnung
cd zerechnung/site/examples/pt-3-conservas
go run .Mais exemplos, para cada funcionalidade do pacote: Exemplos completos no README · Referência da API