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

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

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

Tax exemption reason code

AT’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-exemption-code property is required. For example, you could define an invoice line exempt of tax 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": "M19"
						}
				}
			]
		}
	]
}

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

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

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

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