Portugal SAF-T

Key: pt-saft-v1 Module: github.com/invopop/gobl.pt.saft Portugal doesn’t have an e-invoicing format per se. Tax information is reported electronically to the AT (Autoridade Tributária e Aduaneira) either periodically in batches via a SAF-T (PT) report or individually in real time via a web service. This addon ensures that the GOBL documents have all the required fields to be able to be reported to the AT.

Sources

Correction Definitions

Auto-generation of corrective invoices or credit and debit notes is supported. A reason is required in the reason field when submitting the correction options.

Scenarios

bill/invoice

standard

Filters:

Types: standard

Output:

Extensions: pt-saft-invoice-type:FT

standard, #simplified

Filters:

Types: standard
Tags: simplified

Output:

Extensions: pt-saft-invoice-type:FS

standard

Filters:

Types: standard
Filter: (custom)

Output:

Extensions: pt-saft-invoice-type:FR

debit-note

Filters:

Types: debit-note

Output:

Extensions: pt-saft-invoice-type:ND

credit-note

Filters:

Types: credit-note

Output:

Extensions: pt-saft-invoice-type:NC

proforma

Filters:

Types: proforma

Output:

Extensions: pt-saft-work-type:PF

Extensions

Invoice Type

SAF-T’s InvoiceType (Tipo de documento) specifies the type of a sales invoice. In GOBL, this type can be set using the pt-saft-invoice-type extension in the tax section. GOBL will set the extension for you based on the type and the tax tags you set in your invoice. The table below shows how this mapping is done:

Code	Name	GOBL Type	GOBL Tax Tag
`FT`	Standard Invoice	`standard`
`FS`	Simplified Invoice	`standard`	`simplified`
`FR`	Invoice-Receipt	`standard`	`invoice-receipt`
`ND`	Debit Note	`debit-note`
`NC`	Credit Note	`credit-note`

Example:

{
	"$schema": "https://gobl.org/draft-0/bill/invoice",
	"$tags": [
		"invoice-receipt"
	],
	// ...
	"type": "standard",
	// ...
	"tax": {
		"ext": {
			"pt-saft-invoice-type": "FR"
		}
	},
	// ...

pt-saft-invoice-type

Code	Name
`FT`	Standard Invoice
`FS`	Simplified Invoice
`FR`	Invoice-Receipt
`ND`	Debit Note
`NC`	Credit Note

Payment Type

To report payment receipts to the AT, GOBL provides conversion from bill.Payment documents. In a payment, the SAF-T’s PaymentType (Tipo de documento) field specifies its type. In GOBL, this type can be set using the pt-saft-payment-type extension. GOBL will set the extension automatically based on the type and the tax tags you set. The table below shows how this mapping is done:

Code	Name	GOBL Type	GOBL Tax Tag
RG	Outro Recibo	`receipt`
RC	Recibo no âmbito do regime de IVA de Caixa	`receipt`	`vat-cash`

For example:

{
	"$schema": "https://gobl.org/draft-0/bill/payment",
	// ...
	"type": "receipt",
	// ...
	"ext": {
		"pt-saft-receipt-type": "RG"
	},
	// ...

pt-saft-payment-type

Code	Name
`RC`	Receipt under the VAT Cash scheme
`RG`	Other Receipt

Tax Rate Code

The SAF-T’s TaxCode (Código do imposto) is required for invoice items that apply VAT. GOBL provides the pt-saft-tax-rate extension to set this code at line tax level. It also determines it automatically this code using the rate field (when present). The following table lists the supported tax codes and how GOBL will map them:

Code	Name	GOBL Tax Rate
`NOR`	Tipo Geral	`standard`
`INT`	Taxa Intermédia	`intermediate`
`RED`	Taxa Reduzida	`reduced`
`ISE`	Isenta	`exempt`

pt-saft-tax-rate

Code	Name
`RED`	Reduced
`INT`	Intermediate
`NOR`	Normal
`ISE`	Exempt
`OUT`	Other

Tax exemption reason code

The SAF-T’s TaxExemptionCode (Código do motivo de isenção de imposto) is a code that specifies the reason the VAT tax is exempt in a Portuguese invoice. When the exempt tag is used in a tax combo, the ext map’s pt-saft-exemption property is required. The SAF-T’s TaxExemptionReason (Motivo da isenção de imposto) is a text that justifies the exemption referencing the relevant legislation. In GOBL, this is provided with a special line-level note. By default, if no note is provided, GOBL will automatically assign a default one consistent with the exemption code. However, note that default texts are generic and not always sufficiently precise to comply with the regulations. The invoice issuer should be given the option to provide a custom note with the appropriate descriptive text. For example, you could define an invoice line exempt of tax with the exemption code and the reason as follows:

{
	"$schema": "https://gobl.org/draft-0/bill/invoice",
	// ...
	"lines": [
		{
			// ...
		"item": {
				"name": "Some service exempt of tax",
				"price": "25.00"
			},
			"tax": [
				{
						"cat": "VAT",
						"rate": "exempt",
						"ext": {
							"pt-saft-tax-rate": "ISE",
							"pt-saft-exemption": "M40"
						}
				}
			]
		},
		"notes": [
			{
				"key": "legal",
				"code": "M40",
				"src": "pt-saft-exemption",
				"text": "Artigo 6.º n.º 6 alínea a) do CIVA, a contrário"
			}
		]
	]
}

pt-saft-exemption

Code	Name
`M01`	Article 16, No. 6, paragraphs a) to d) of the VAT code
`M02`	Article 6 of Decree-Law No. 198/90 of 19th June
`M04`	Article 13 of the VAT code
`M05`	Article 14 of the VAT code
`M06`	Article 15 of the VAT code
`M07`	Article 9 of the VAT code
`M09`	Article 62 paragraph b) of the VAT code
`M10`	Article 57 of the VAT code
`M11`	Decree-Law No. 346/85 of 23rd August
`M12`	Decree-Law No. 221/85 of 3rd July
`M13`	Decree-Law No. 199/96 of 18th October
`M14`	Decree-Law No. 199/96 of 18th October
`M15`	Decree-Law No. 199/96 of 18th October
`M16`	Article 14 of the RITI
`M19`	Other exemptions
`M20`	Article 59-D No. 2 of the VAT code
`M21`	Article 72 No. 4 of the VAT code
`M25`	Article 38 No. 1 paragraph a) of the VAT code
`M26`	Law No. 17/2023 of 14th April
`M30`	Article 2 No. 1 paragraph i) of the VAT code
`M31`	Article 2 No. 1 paragraph j) of the VAT code
`M32`	Article 2 No. 1 paragraph l) of the VAT code
`M33`	Article 2 No. 1 paragraph m) of the VAT code
`M34`	Article 2 No. 1 paragraph n) of the VAT code
`M40`	Article 6 No. 6 paragraph a) of the VAT code, to the contrary
`M41`	Article 8 No. 3 of the RITI
`M42`	Decree-Law No. 21/2007 of 29th January
`M43`	Decree-Law No. 362/99 of 16th September
`M44`	Article 6.º of the CIVA – Specific rules
`M45`	Art 58º-A of the CIVA (IVA - cross-border exemption regime)
`M46`	Decree-Law No. 19/2017, of February 14
`M99`	Not subject to tax or not taxed

Product Type

SAF-T’s ProductType (Indicador de produto ou serviço) indicates the type of each line item in an invoice. The pt-saft-product-type extension used at line item level allows to set the product type to one of the allowed values. Example:

{
	"$schema": "https://gobl.org/draft-0/bill/invoice",
	// ...
	"lines": [
		{
			// ...
			"item": {
				"name": "Some service",
				"price": "25.00",
				"ext": {
					"pt-saft-product-type": "S"
				}
			},
			// ...
		}
	]
}

pt-saft-product-type

Code	Name
`P`	Goods
`S`	Services
`O`	Other
`E`	Excise Duties
`I`	Taxes/Fees

Document Type

SAF-T’s WorkType (Tipo de documento de conferência) specifies the type of a working document. In GOBL, this type can be set using the pt-saft-work-type extension in either bill.Invoice or bill.Order documents. GOBL will set the extension for you based on the document type in some cases. The table below shows the supported work type codes and their compatibility with GOBL objects:

Code	Name	GOBL Doc	GOBL Type
`PF`	Pró-forma	Invoice	`proforma`
`FC`	Fatura de consignação	Invoice
`CC`	Credito de consignação	Invoice
`CM`	Consultas de mesa	Order
`FO`	Folhas de obra	Order
`NE`	Nota de Encomenda	Order	`purchase`
`OU`	Outros	Order
`OR`	Orçamentos	Order	`quote`
`DC`	Documentos de conferência	Order
`RP`	Prémio ou recibo de prémio	Order
`RE`	Estorno ou recibo de estorno	Order
`CS`	Imputação a co-seguradoras	Order
`LD`	Imputação a co-seguradora líder	Order
`RA`	Resseguro aceite	Order

Example for a proforma invoice:

{
	"$schema": "https://gobl.org/draft-0/bill/invoice",
	"type": "proforma",
	// ...
	"tax": {
		"ext": {
			"pt-saft-work-type": "PF"
		}
	},
	// ...

Example for a purchase order:

{
	"$schema": "https://gobl.org/draft-0/bill/order",
	"type": "purchase",
	// ...
	"tax": {
		"ext": {
			"pt-saft-work-type": "NE"
		}
	},
	// ...

pt-saft-work-type

Code	Name
`CM`	Table orders
`CC`	Consignment credit note
`FC`	VAT-compliant consignment invoice (Article 38)
`FO`	Work orders
`NE`	Purchase order
`OU`	Other documents
`OR`	Quotations
`PF`	Pro forma invoice
`DC`	Delivery verification documents
`RP`	Premium Receipt
`RE`	Chargeback Receipt
`CS`	Co-insurers Allocation
`LD`	Lead Co-insurer Allocation
`RA`	Accepted Reinsurance

Payment Means

The SAF-T’s PaymentMechanism (Meios de pagamento) field specifies the payment means in a sales invoice or payment. GOBL provides the pt-saft-payment-means extension to set this value in your bill.Invoice advances or in your bill.Payment method. GOBL maps certain payment mean keys automatically to this extension:

Code	Name	GOBL Payment Means
`CC`	Cartão crédito	`card` or `card+credit`
`CD`	Cartão débito	`card+debit`
`CH`	Cheque bancário	`cheque`
`CI`	Letter of credit	(*)
`CO`	Cheque ou cartão oferta	(*)
`CS`	Compensação de saldos em conta corrente	`netting`
`DE`	Dinheiro eletrónico	`online`
`LC`	Letra comercial	`promissory-note`
`MB`	Referências de pagamento para Multibanco	(*)
`NU`	Numerário	`cash`
`OU`	Outro	`other`
`PR`	Permuta de bens	(*)
`TB`	Transferência bancária ou débito direto autorizado	`credit-transfer`, `debit-transfer` or `direct-debit`
`TR`	Títulos de compensação extrassalarial	(*)

(*) For codes not mapped from a GOBL Payment Mean, use other and explicitly set the extension. For example, in a GOBL invoice:

{
	"$schema": "https://gobl.org/draft-0/bill/invoice",
	// ...
	"payment": {
		"advances": [
			{
				"date": "2023-01-30",
				"key": "credit-transfer",
				"description": "Adiantamento",
				"amount": "100.00",
				"ext": {
					"pt-saft-payment-means": "TB"
				}
			}
		]
	},
	// ...
}

For example, in a GOBL receipt:

{
	"$schema": "https://gobl.org/draft-0/bill/receipt",
	// ...
	"method": {
		"key": "other",
		"detail": "Compensação extrassalarial",
		"ext": {
			"pt-saft-payment-means": "TR"
		}
	},
	// ...
}

pt-saft-payment-means

Code	Name
`CC`	Credit card
`CD`	Debit card
`CH`	Bank cheque
`CI`	International documentary credit
`CO`	Gift cheque or card
`CS`	Settlement of balances in current account
`DE`	Electronic money
`LC`	Commercial bill
`MB`	Multibanco payment references
`NU`	Cash
`OU`	Other
`PR`	Barter
`TB`	Bank transfer or direct debit
`TR`	Supplementary compensation

Document Source

SAF-T’s SourceBilling (Origem do documento) field specifies the source of the document. GOBL provides the pt-saft-source extension to set this value in your documents. By default, GOBL will set this extension to “P” (Produced). The table below shows the supported source billing codes:

Code	Name	Description
`P`	Produced	Document produced by the application
`I`	Integrated	Integrated document produced by another application
`M`	Manual	Document from recovery or issued manually

Example:

{
	"$schema": "https://gobl.org/draft-0/bill/invoice",
	// ...
	"ext": {
		"pt-saft-source": "P"
	},
	// ...
}

pt-saft-source

Code	Name
`P`	Produced
`I`	Integrated
`M`	Manual

Source Document Reference

GOBL provides the pt-saft-source-ref extension to provide the full reference to a document integrated from another system, recovered or issued manually. This extension is required when the document source (pt-saft-source extension) is “M” (manual) or “I” (integrated). It must contain the complete document reference to be appended to the SAF-T’s HashControl field as stipulated by Despacho n.o 8632/2014. Example with a manual document:

{
	"$schema": "https://gobl.org/draft-0/bill/invoice",
	// ...
	"ext": {
		"pt-saft-source": "M",
		"pt-saft-source-ref": "FTM abc/00001"
	},
	// ...
}

Example with a recovered document:

{
	"$schema": "https://gobl.org/draft-0/bill/invoice",
	// ...
	"ext": {
		"pt-saft-source": "M",
		"pt-saft-source-ref": "FTD FT SERIESA/123"
	},
	// ...
}

pt-saft-source-ref

Movement Type

SAF-T’s MovementType (Tipo de documento de movimentação de mercadorias) specifies the type of a delivery document. In GOBL, this type can be set using the pt-saft-movement-type extension. If not provided explicitly, GOBL will set the extension for you based on the type and tags of your delivery document. The table below shows how this mapping is done:

Code	Name	GOBL Type	GOBL Tag
`GR`	Guia de Remessa (Delivery note)	`note`
`GT`	Guia de Transporte (Transport guide)	`waybill`
`GD`	Guia de Devolução (Return note)	`note`	`return`
`GA`	Guia de Movimentação de Ativos Próprios	(*)
`GC`	Guia de Consignação	(*)

(*) or codes not mapped from a GOBL type or tag; use other as the delivery type and explicitly set the extension. For example, to indicate a return delivery (GD):

{
	"$schema": "https://gobl.org/draft-0/bill/delivery",
	"$tags": ["return"],
	"type": "note",
	// The `pt-saft-movement-type` extension is set automatically to "GD"
	// ...
}

For example, to set a movement type with no GOBL equivalent (e.g. GA):

{
	"$schema": "https://gobl.org/draft-0/bill/delivery",
	// ...
	"type": "other",
	// ...
	"tax": {
		"ext": {
			"pt-saft-movement-type": "GA"
		}
	},
	// ...
}

pt-saft-movement-type

Code	Name
`GR`	Delivery note
`GT`	Waybill
`GA`	Guide to the movement own fixed assets
`GC`	Consignment note
`GD`	Returns slip or note

Validation Rules

bill.Invoice

Field	Test	Validation Code / Message
Invoice	Can convert to [EUR]	`GOBL-PT-SAFT-BILL-INVOICE-15` Invoice must be in EUR or provide exchange rate for conversion
Invoice	Has doc type	`GOBL-PT-SAFT-BILL-INVOICE-01` Either ‘pt-saft-work-type’ or ‘pt-saft-invoice-type’ must be set
Invoice	Not both doc types	`GOBL-PT-SAFT-BILL-INVOICE-02` Either ‘pt-saft-work-type’ or ‘pt-saft-invoice-type’ must be set, but not both
Invoice	Valid invoice work type	`GOBL-PT-SAFT-BILL-INVOICE-03` Invoice work type is not valid
Invoice	Series format	`GOBL-PT-SAFT-BILL-INVOICE-04` Series format must be valid
Invoice	Code format	`GOBL-PT-SAFT-BILL-INVOICE-05` Code format must be valid
Invoice	Tax has source	`GOBL-PT-SAFT-BILL-INVOICE-12` Tax requires ‘pt-saft-source’ extension
Invoice	Source ref format	`GOBL-PT-SAFT-BILL-INVOICE-14` Source ref format is invalid
`value_date`	Present	`GOBL-PT-SAFT-BILL-INVOICE-06` Cannot be blank
`lines[*]`	Line has tax category VAT	`GOBL-PT-SAFT-BILL-INVOICE-07` Line taxes must include VAT category
`payment.advances[*].date`	Present	`GOBL-PT-SAFT-BILL-INVOICE-08` Cannot be blank
`payment.advances[*].amount`	Min 0	`GOBL-PT-SAFT-BILL-INVOICE-16` Must be no less than 0
`totals.payable` Calculated	Min 0	`GOBL-PT-SAFT-BILL-INVOICE-09` Must be no less than 0
`totals.due` Calculated	Is invoice-receipt Equals 0	`GOBL-PT-SAFT-BILL-INVOICE-10` Must be equal to 0
`preceding`	Length between 0 and 1	`GOBL-PT-SAFT-BILL-INVOICE-11` The length must be no more than 1
Invoice	Source not produced Tax has source ref	`GOBL-PT-SAFT-BILL-INVOICE-13` Tax requires ‘pt-saft-source-ref’ extension when source is not produced

bill.Payment

Field	Test	Validation Code / Message
Payment	Series format	`GOBL-PT-SAFT-BILL-PAYMENT-01` Series format must be valid
Payment	Code format	`GOBL-PT-SAFT-BILL-PAYMENT-02` Code format must be valid
Payment	Source ref format	`GOBL-PT-SAFT-BILL-PAYMENT-06` Source ref format is invalid
Payment	Customer name present	`GOBL-PT-SAFT-BILL-PAYMENT-09` Customer name is required when customer has tax ID code
`ext`	Ext require [pt-saft-payment-type]	`GOBL-PT-SAFT-BILL-PAYMENT-03` ’pt-saft-payment-type’ extension is required
`ext`	Ext require [pt-saft-source]	`GOBL-PT-SAFT-BILL-PAYMENT-04` ’pt-saft-source’ extension is required
`ext`	Source not produced Ext require [pt-saft-source-ref]	`GOBL-PT-SAFT-BILL-PAYMENT-05` ’pt-saft-source-ref’ extension is required when source is not produced
`supplier.tax_id`	Present	`GOBL-PT-SAFT-BILL-PAYMENT-07` Supplier tax ID is required
`supplier.tax_id.code`	Present	`GOBL-PT-SAFT-BILL-PAYMENT-08` Supplier tax ID code is required
`total`	Min 0	`GOBL-PT-SAFT-BILL-PAYMENT-10` Must be no less than 0

bill.Delivery

Field	Test	Validation Code / Message
Delivery	Has movement type	`GOBL-PT-SAFT-BILL-DELIVERY-01` Delivery tax requires ‘pt-saft-movement-type’ extension
Delivery	Series format	`GOBL-PT-SAFT-BILL-DELIVERY-02` Delivery series format must be valid
Delivery	Code format	`GOBL-PT-SAFT-BILL-DELIVERY-03` Delivery code format must be valid
`supplier.tax_id`	Present	`GOBL-PT-SAFT-BILL-DELIVERY-04` Delivery supplier tax ID is required
`supplier.tax_id.code`	Present	`GOBL-PT-SAFT-BILL-DELIVERY-05` Delivery supplier tax ID code is required
`despatch_date`	Present	`GOBL-PT-SAFT-BILL-DELIVERY-06` Delivery despatch date is required
`preceding`	Length between 0 and 1	`GOBL-PT-SAFT-BILL-DELIVERY-07` Delivery preceding must have at most one entry
`preceding[*].series`	Present	`GOBL-PT-SAFT-BILL-DELIVERY-08` Delivery preceding series is required
`preceding[*].code`	Present	`GOBL-PT-SAFT-BILL-DELIVERY-09` Delivery preceding code is required

bill.Order

Field	Test	Validation Code / Message
Order	Has work type	`GOBL-PT-SAFT-BILL-ORDER-01` Tax requires ‘pt-saft-work-type’ extension
Order	Order work type valid	`GOBL-PT-SAFT-BILL-ORDER-02` Work type must not be an invoice work type
Order	Series format	`GOBL-PT-SAFT-BILL-ORDER-03` Series format must be valid
Order	Code format	`GOBL-PT-SAFT-BILL-ORDER-04` Code format must be valid
`value_date`	Present	`GOBL-PT-SAFT-BILL-ORDER-05` Cannot be blank
`lines[*]`	Line has tax category VAT	`GOBL-PT-SAFT-BILL-ORDER-06` Line taxes must include VAT category

tax.Combo

Field	Test	Validation Code / Message
`ext`	Is VAT Ext require [pt-region, pt-saft-tax-rate]	`GOBL-PT-SAFT-TAX-COMBO-01` Region and tax rate are required
`ext`	Is VAT Exempt requires exemption	`GOBL-PT-SAFT-TAX-COMBO-02` Exemption is required when tax rate is exempt

tax.RateTotal

Field	Test	Validation Code / Message
`ext`	Ext require [pt-region, pt-saft-tax-rate]	`GOBL-PT-SAFT-TAX-RATETOTAL-01` Region and tax rate are required
`ext`	Exempt requires exemption	`GOBL-PT-SAFT-TAX-RATETOTAL-02` Exemption is required when tax rate is exempt

org.Item

Field	Test	Validation Code / Message
`unit`	Present	`GOBL-PT-SAFT-ORG-ITEM-01` Cannot be blank
`ext`	Ext require [pt-saft-product-type]	`GOBL-PT-SAFT-ORG-ITEM-02` Product type is required

org.Note

Field	Test	Validation Code / Message
`text`	Legal exemption note Length between 6 and 60	`GOBL-PT-SAFT-ORG-NOTE-01` The length must be between 6 and 60

bill.Line

Field	Test	Validation Code / Message
Line	Exemption notes	`GOBL-PT-SAFT-BILL-LINE-05` Exemption notes invalid
`quantity`	Min 0	`GOBL-PT-SAFT-BILL-LINE-01` Must be greater than 0
`sum` Calculated	Min 0	`GOBL-PT-SAFT-BILL-LINE-02` Must be no less than 0
`total` Calculated	Min 0	`GOBL-PT-SAFT-BILL-LINE-03` Must be no less than 0
`discounts[*].amount`	Min 0	`GOBL-PT-SAFT-BILL-LINE-04` Must be no less than 0

bill.PaymentLine

Field	Test	Validation Code / Message
PaymentLine	Exemption notes	`GOBL-PT-SAFT-BILL-PAYMENTLINE-06` Exemption notes invalid
`document`	Present	`GOBL-PT-SAFT-BILL-PAYMENTLINE-01` Cannot be blank
`document.issue_date`	Present	`GOBL-PT-SAFT-BILL-PAYMENTLINE-02` Cannot be blank
`tax`	Present	`GOBL-PT-SAFT-BILL-PAYMENTLINE-03` Cannot be blank
`tax`	Has VAT category	`GOBL-PT-SAFT-BILL-PAYMENTLINE-04` Missing category VAT
`tax.categories[*].rates`	Length between 0 and 1	`GOBL-PT-SAFT-BILL-PAYMENTLINE-05` Only one rate allowed per line

Overview

Use Cases

Quick Start

Tax Regimes

Addons

Catalogues

Schemas (Draft 0)

Portugal SAF-T

Sources

Correction Definitions

Scenarios

bill/invoice

Extensions

Invoice Type

Payment Type

Tax Rate Code

Tax exemption reason code

Product Type

Document Type

Payment Means

Document Source

Source Document Reference

Movement Type

Validation Rules

​Sources

​Correction Definitions

​Scenarios

​bill/invoice

​Extensions

​Invoice Type

​Payment Type

​Tax Rate Code

​Tax exemption reason code

​Product Type

​Document Type

​Payment Means

​Document Source

​Source Document Reference

​Movement Type

​Validation Rules

Sources

Correction Definitions

Scenarios

bill/invoice

Extensions

Invoice Type

Payment Type

Tax Rate Code

Tax exemption reason code

Product Type

Document Type

Payment Means

Document Source

Source Document Reference

Movement Type

Validation Rules