Skip to main content
Key: pt-saft-v1 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

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:
CodeNameGOBL TypeGOBL Tax Tag
FTStandard Invoicestandard
FSSimplified Invoicestandardsimplified
FRInvoice-Receiptstandardinvoice-receipt
NDDebit Notedebit-note
NCCredit Notecredit-note
Example:
{
	"$schema": "https://gobl.org/draft-0/bill/invoice",
	"$tags": [
		"invoice-receipt"
	],
	// ...
	"type": "standard",
	// ...
	"tax": {
		"ext": {
			"pt-saft-invoice-type": "FR"
		}
	},
	// ...
CodeName
FTStandard Invoice
FSSimplified Invoice
FRInvoice-Receipt
NDDebit Note
NCCredit 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:
CodeNameGOBL TypeGOBL Tax Tag
RGOutro Reciboreceipt
RCRecibo no âmbito do regime de IVA de Caixareceiptvat-cash
For example:
{
	"$schema": "https://gobl.org/draft-0/bill/payment",
	// ...
	"type": "receipt",
	// ...
	"ext": {
		"pt-saft-receipt-type": "RG"
	},
	// ...
CodeName
RCReceipt under the VAT Cash scheme
RGOther Receipt

Tax Rate Code

The SAF-T’s TaxCode (Có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:
CodeNameGOBL Tax Rate
NORTipo Geralstandard
INTTaxa Intermédiaintermediate
REDTaxa Reduzidareduced
ISEIsentaexempt
CodeName
REDReduced
INTIntermediate
NORNormal
ISEExempt
OUTOther

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"
			}
		]
	]
}
CodeName
M01Article 16, No. 6, paragraphs a) to d) of the VAT code
M02Article 6 of Decree-Law No. 198/90 of 19th June
M04Article 13 of the VAT code
M05Article 14 of the VAT code
M06Article 15 of the VAT code
M07Article 9 of the VAT code
M09Article 62 paragraph b) of the VAT code
M10Article 57 of the VAT code
M11Decree-Law No. 346/85 of 23rd August
M12Decree-Law No. 221/85 of 3rd July
M13Decree-Law No. 199/96 of 18th October
M14Decree-Law No. 199/96 of 18th October
M15Decree-Law No. 199/96 of 18th October
M16Article 14 of the RITI
M19Other exemptions
M20Article 59-D No. 2 of the VAT code
M21Article 72 No. 4 of the VAT code
M25Article 38 No. 1 paragraph a) of the VAT code
M26Law No. 17/2023 of 14th April
M30Article 2 No. 1 paragraph i) of the VAT code
M31Article 2 No. 1 paragraph j) of the VAT code
M32Article 2 No. 1 paragraph l) of the VAT code
M33Article 2 No. 1 paragraph m) of the VAT code
M34Article 2 No. 1 paragraph n) of the VAT code
M40Article 6 No. 6 paragraph a) of the VAT code, to the contrary
M41Article 8 No. 3 of the RITI
M42Decree-Law No. 21/2007 of 29th January
M43Decree-Law No. 362/99 of 16th September
M99Not 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"
				}
			},
			// ...
		}
	]
}
CodeName
PGoods
SServices
OOther
EExcise Duties
ITaxes/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:
CodeNameGOBL DocGOBL Type
PFPró-formaInvoiceproforma
FCFatura de consignaçãoInvoice
CCCredito de consignaçãoInvoice
CMConsultas de mesaOrder
FOFolhas de obraOrder
NENota de EncomendaOrderpurchase
OUOutrosOrder
OROrçamentosOrderquote
DCDocumentos de conferênciaOrder
RPPrémio ou recibo de prémioOrder
REEstorno ou recibo de estornoOrder
CSImputação a co-seguradorasOrder
LDImputação a co-seguradora líderOrder
RAResseguro aceiteOrder
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"
		}
	},
	// ...
CodeName
CMTable orders
CCConsignment credit note
FCVAT-compliant consignment invoice (Article 38)
FOWork orders
NEPurchase order
OUOther documents
ORQuotations
PFPro forma invoice
DCDelivery verification documents
RPPremium Receipt
REChargeback Receipt
CSCo-insurers Allocation
LDLead Co-insurer Allocation
RAAccepted 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 you bill.Payment method. GOBL maps certain payment mean keys automatically to this extension:
CodeNameGOBL Payment Means
CCCartão créditocard
CDCartão débito(*)
CHCheque bancáriocheque
CILetter of credit(*)
COCheque ou cartão oferta(*)
CSCompensação de saldos em conta correntenetting
DEDinheiro eletrónicoonline
LCLetra comercialpromissory-note
MBReferências de pagamento para Multibanco(*)
NUNumeráriocash
OUOutroother
PRPermuta de bens(*)
TBTransferência bancária ou débito direto autorizadocredit-transfer, debit-transfer or direct-debit
TRTítulos de compensação extrassalarial(*)
(*) For codes not mapped from a GOBL Payment Mean, use other and explicitly set the extension. For example, in an 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"
		}
	},
	// ...
}
CodeName
CCCredit card
CDDebit card
CHBank cheque
CIInternational documentary credit
COGift cheque or card
CSSettlement of balances in current account
DEElectronic money
LCCommercial bill
MBMultibanco payment references
NUCash
OUOther
PRBarter
TBBank transfer or direct debit
TRSupplementary 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:
CodeNameDescription
PProducedDocument produced by the application
IIntegratedIntegrated document produced by another application
MManualDocument from recovery or issued manually
Example:
{
	"$schema": "https://gobl.org/draft-0/bill/invoice",
	// ...
	"ext": {
		"pt-saft-source": "P"
	},
	// ...
}
CodeName
PProduced
IIntegrated
MManual

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"
	},
	// ...
}

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 of your delivery document. The table below shows how this mapping is done:
CodeNameGOBL Type
GRDelivery notenote
GTWaybillwaybill
Example:
{
	"$schema": "https://gobl.org/draft-0/bill/delivery",
	// ...
	"type": "note",
	// ...
	"ext": {
		"pt-saft-movement-type": "GR"
	},
	// ...
CodeName
GRDelivery note
GTWaybill
GAGuide to the movement own fixed assets
GCConsignment note
GDReturns slip or note
I