Current Version of the XML Schema

Value is defined (hardcoded) in RetailForce release version

Conditional setting in configuration:

• if a system supports invoices AND receipts, 'F' is indicated for both "[0] = Receipt" and "[1]= Invoice"
• if a system ONLY issues receipts (NO invoices), “R” is indicated for "[0] = Receipt"
  • in this case "[1] = Invoice" must not be issued

CompanyAddress.Street

+

CompanyAddress.StreetNumber

Must contain

• street name,
• building number and
• floor

if applicable

Start date of the file period (StartDate)

Export "FromDate"

End date of the file period (EndDate)

Export "UntilDate"

Name of the application that generates the SAF-T (PT).

The commercial name of the software and that of the producing company in the format “Name of the application/Name of the company producing the software”.

If Partner.IsBusiness: true

• Partner.Id"

If Partner.IsBusiness: false

• 'Consumidor final' (for End consumer) is used

Unique customer identifier (CustomerID)

There cannot be more than one record with the same CustomerID in the customer list.

In the case of end consumers, a generic customer should be created with the designation "End consumer" ("Consumidor final").

As no accounting data (generalLedger) are presented, use value “Unknown”

“Desconhecido”

Account code (AccountID)

The customer's current account in the accounting chart of accounts must be indicated, if defined. Otherwise, it must be filled in with the designation “Unknown” ("Desconhecido").

If isBusiness: true:

• Partner.VatNumber

If isBusiness: false,:

• '999999990' (for End consumer) is used

Customer tax identification number (CustomerTaxID)

This must be indicated without the country prefix.

The generic customer, corresponding to the designated "End consumer" ("Consumidor final"), must be identified with the tax identification number "999999990".

If isBusiness: true:

• Partner.Caption

If isBusiness: false:

• 'Consumidor final' (End consumer) is used

Company name (CompanyName)

The generic customer should be identified as “End consumer” ("Consumidor final").

Billing address (BillingAddress)

Corresponds to the address of the head office or permanent establishment in the national territory.

Partner.Street

+

Partner.StreetNumber

"Desconhecido" is used, if isBusiness: false and no address is indicated

Detailed address (AddressDetail)

Must include the street name, block number and floor, if applicable.

Must be filled in with the designation "Unknown" ("Desconhecido") in the following situations:

• Non-integrated systems, if the information is not known;
• Transactions carried out with “End consumer” (“Consumidor final”).

Partner.City

"Desconhecido" is used, if isBusiness: false and no address is indicated

Location (City)

It must be filled in with the designation “Unknown” (“Desconhecido”) in the following situations:

• Non-integrated systems, if the information is not known;
• Transactions carried out with “End consumer” (“Consumidor final”).

PostalCode

"Desconhecido" is used, if isBusiness: false and no address is indicated

Postcode (PostalCode)

It must be filled in with the designation “Unknown” (“Desconhecido”) in the following situations:

• Non-integrated systems, if the information is not known;
• Transactions carried out with “End consumer” (“Consumidor final”).

If indicated:

• Partner.Community

Partner.CountryCode converted to ISO 3166 ALPHA-2

"Desconhecido" is used, if isBusiness: false and no address is indicated

If known, it must be filled in accordance with ISO 3166 – 1-alpha-2.

It must be filled in with the designation “Unknown” (“Desconhecido”) in the following situations:

• Non-integrated systems, if the information is not known;
• Transactions carried out with “End consumer” (“Consumidor final”).

Shipping address (ShipToAddress)

If more than one reference is required, this structure can be generated as many times as necessary.

street

+

streetNumber

Detailed address (AddressDetail)

Must include the street name, block number and floor, if applicable.

Must be filled in with the designation “Unknown” (“Desconhecido”) in the following situations:

• Non-integrated systems, if the information is not known;
• Transactions carried out with “End consumer” (“Consumidor final”).

Location (City)

It must be filled in with the designation “Unknown” (“Desconhecido”) in the following situations:

• Non-integrated systems, if the information is not known;
• Transactions carried out with “End consumer” (“Consumidor final”).

Postcode (PostalCode)

It must be filled in with the designation “Unknown” (“Desconhecido”) in the following situations:

• Non-integrated systems, if the information is not known;
• Transactions carried out with “End consumer” (“Consumidor final”).

If known, it must be filled in accordance with ISO 3166 – 1-alpha-2.

It must be filled in with the designation “Unknown” (“Desconhecido”) in the following situations:

• Non-integrated systems, if the information is not known;
• Transactions carried out with “End consumer” (“Consumidor final”).

Self-billing indicator (SelfBillingIndicator)

Indicator of the existence of a self-billing agreement between the customer and the supplier.

It should be filled in with “1” if there is an agreement and with “0” (zero) if there is no agreement.

positions.itemType

In case of additional tax:

• AdditionalTaxType

In case of deposits:

• businessTransactionType

Mapping:

• P - [0] = Article (itemType)
• S - [1] = Service (itemType)
• O - if Type: 3 / [3] = Booking 
  AND BusinessTransactionType: 7 / [7] = Deposit
  OR
  2 / [2] = DepositOnEmpties
• E - “alcohol“, "tobacco", "motorVehicle", "gasoline", "energySources", "electricity", "luxuryGoods" (additionalTaxType)
• I - “others“ (additionalTaxType)

Shipping charges are currently supported

Product or service indicator (ProductType)

Must be filled in with:

“P” – Products;

“S” – Services;

“O” – Others (e.g. shipping charges, advances received or disposal of assets);

“E” – Special Consumption Taxes – (e.g. IABA, ISP, IT);

“I” – Taxes, fees and parafiscal charges – except VAT and IS, which should be reflected in table 2.5 – Tax Table (TaxTable) and Special Consumption Taxes, which should be filled in with the code “E”.

Product or service identifier (ProductCode)

Unique product code in the product list.

Description of the product or service (ProductDescription)

This must correspond to the usual name of the goods or services provided, specifying the elements necessary to determine the applicable tax rate.

positions.Gtin if specified

else

positions.ItemId

Product code (ProductNumberCode)

The EAN code (barcode) of the product must be used.

When this does not exist, fill in the value of field 2.4.2. - Product or service identifier (ProductCode).

Combined Nomenclature Code (CNCode)

Fill in with the European Union's goods nomenclature code.

If more than one reference is required, this field can be generated as many times as necessary.

UN Number (UNNumber)

Fill in the UN number for dangerous goods.

If more than one reference is required, this field can be generated as many times as necessary.

Tax type code (TaxType)

The tax type must be indicated in this field.

It must be filled in with:

“IVA” – Value added tax;

“IS” – Stamp duty;

“NS” – Not subject to VAT or ST.

derived from FiscalRegions (of Store)

• Portugal
• Acores
• Madeira

Mapping:

• Portugal - 'PT'
• Acores - 'PT-AC'
• Madeira - 'PT-MA'

Tax country or region (TaxCountryRegion)

Must be completed in accordance with ISO 3166 - 1- alpha-2.

In the case of the Autonomous Regions of Madeira and the Azores, it must be completed with:

“PT-AC” - Tax area of the Autonomous Region of the Azores; and

“PT-MA” - Tax area of the Autonomous Region of Madeira.

vatIdentification

In Portugal the following vat rates apply:

Portugal:

Normal rate: 23%

Reduced rate: 6%

Intermediate rate: 13%

Acores:

Normal rate: 16%

Reduced rate: 4%

Intermediate rate: 9%

Madeira:

Normal rate: 22%

Reduced rate: 4% (valide from: 2024-10-01)

Intermediate rate: 12%

Tax code (TaxCode)

In the case of field 2.5.1.1 - Tax type code (TaxType) = VAT, it must be filled in with:

• “RED” - Reduced rate;
• “INT” - Intermediate rate;
• “NOR” - Standard rate;
• “ISE” – Exempt; and
• “OUT” – Others, applicable to special VAT regimes.

In the case of field 2.5.1.1 - Tax Type Code (TaxType) = IS, it must be filled in with:

• The respective item code;
• “ISE” – Exempt.

In the case of non-liability, it must be filled in with “NS”.

On receipts issued without itemised tax, it must be filled in with “NA”.

generated according to vatIdentification

• Normal
• Reduzida
• Isenta
• Intermédia

Stamp duty currently not supported

Expiry date (TaxExpirationDate)

Last legal date of application of the tax rate, in the event of a change to it, during the tax period.

Tax rate percentage (TaxPercentage)

This field must be filled in if it is a tax percentage.

In the case of exemption or non-taxability, use this field with the value “0” (zero).

Tax amount (TaxAmount)

This field must be filled in if it is a fixed stamp duty amount.

DocumentType:

• 0 / [0] = Receipt
• 1 / [1] = Invoice

Unique sales document identification (InvoiceNo)

This identification is composed sequentially of the following elements: the internal code of the document type assigned by the application, a space, the document series identifier, a slash (/) and the sequential number of that document within that series.

There cannot be any records with the same identification.

The same internal document type code cannot be used in different document types.

FiscalResponse.AdditionalFields.AtCud

In case of SAF-T Export ONLY: 

Upstream system sends ATCUD in fiscalisationAdditionalFields.AtCudPortugal

Unique Document Code (ATCUD)

This field must contain the Unique Document Code. The field must be filled in with “0” (zero) until it is regulated.

ATCUD-code is mandatory since 2023.

"N" for all transactions (sales and returns) but not for voiding (cancellation)

"A" if 

• Document.DocumentReference.ReturnReasonType: userMistake

“S” - not supported

“R“ - not supported

“F” - not used in RF

Current status of the document (InvoiceStatus)

Must be filled in with:

• “N” – Normal;
• “S” – Self-invoicing;
• “A” – Document cancelled;
• “R” – Summary document of other documents created in other applications and generated in this application;
• “F” – Document invoiced.

Date and time of the current status of the document (InvoiceStatusDate)

Date of the last recording of the status of the document to the second. Date and time type: “YYYY-MM-DDThh:mm:ss”.

Reason for status change (Reason)

The reason for the change in the document's status must be indicated.

User code (SourceID)

User responsible for the current status of the document.

Document origin (SourceBilling)

Must be filled in with:

• “P” – Document produced in the application;
• “I” – Document integrated and produced in another application;
• “M” – Document originating from recovery or manual issuance;

fiscalResponse.signature

In case of SAF-T Export ONLY: 

Upstream system sends Hash in fiscalAdditionalFields.HashPortugal

Document key (Hash)

Signature in accordance with Ordinance No. 363/2010, of 23 June.

The field must be filled in with “0” (zero) if certification is not mandatory.

fiscalResponse.AdditionalFields.HashControlValue

In case of SAF-T Export ONLY: 

Upstream system sends HashControl in fiscalAdditionalFields.HashControlPortugal

Control key (HashControl)

Version of the private key used to create the signature in field 4.1.4.4. - Document key (Hash).

The field must be filled in with “0” (zero) if the document is generated by a non-certified programme.

Calculated from FiscalYearStartMonth

if value is e.g. 3 (=March) and export was made for April, value of <Period> is “2”.

Accounting period (Period)

The month of the tax period must be indicated from “1” to “12”, counting from the date of its commencement.

Sales document date (InvoiceDate)

Date of issue of the sales document.

Mapping:

FT: DocumentType": 1 / "[1] = Invoice

FS: DocumentType": 0 / "[0] = Receipt

FR: DocumentType: 0 / "[0] = Receipt if Document.Partner is set (contains data).

ND: not supported

NC: DocumentType": 0 / "[0] = Receipt" OR "DocumentType": 1 / "[1] = Invoice" if:

• CancellationDocument: true

VD, TV, TD, AA, DA obsolete

Inssurance sector (RP, RE, CS, LD, RA) not supported

Document type (InvoiceType)

Must be filled in with:

• “FT” – Invoice, issued under the terms of Article 36 of the VAT Code;
• “FS” – Simplified invoice, issued under the terms of Article 40 of the VAT Code;
• “FR” – Invoice-receipt;
• “ND” – Debit note;
• “NC” – Credit note;
• “VD” – Cash sale and invoice/receipt; (a)
• “TV” – Sales receipt; (a)
• “TD” – Return receipt; (a)
• “AA” – Disposal of assets; (a)
• “DA” – Return of assets. (a)

For the Insurance sector, when not included in table 4.3. - Documents for checking goods or services (Working Documents), it can also be filled in with:

• “RP” – Premium or premium receipt;
• “RE” – Reversal or reversal receipt;
• “CS” – Allocation to co-insurers;
• “LD” – Allocation to lead co-insurer;
• “RA” – Reinsurance accepted.

(a) For data up to 31 December 2012.

Self-billing indicator (SelfBillingIndicator)

Must be filled in with “1” if self-billing applies and with “0” (zero) if not.

Setting in configuration

• Standard Regime (Indicator = 0)
• Cash Regime (Indicator = 1)

Cash VAT Scheme Indicator (CashVATSchemeIndicator)

Indicator of adherence of the Cash VAT Scheme.

It should be filled in with “1” if there is adherence and with “0” (zero) if not.

Indicator of invoicing issued in the name and on behalf of third parties (ThirdPartiesBillingIndicator)

It must be filled in with “1” if it refers to invoicing issued in the name and on behalf of third parties and with “0” (zero) otherwise.

User code (SourceID)

User who generated the document.

CAE Code (EACCode)

The CAE code for the activity related to the issuance of this document must be indicated.

Document recording date (SystemEntryDate)

Date of record entry to the second, at the time of signature. Date and time format: “YYYY-MM-DDThh:mm:ss”.

Transaction identifier (TransactionID)

This field must be completed in the case of an integrated accounting and invoicing system, even though the file type (TaxAccountingBasis) should not contain the tables relating to accounting.

The unique key from table 3. Accounting movements (GeneralLedgerEntries) of the transaction where this document was posted must be indicated, in accordance with the rule defined there for field 3.4.3.1 - Unique key of the accounting movement (TransactionID).

Customer identifier (CustomerID)

Unique key for table 2.2. – Customer table (Customer), complying with the rule defined therein for field 2.2.1. – Unique customer identifier (CustomerID).

Local de descarga (ShipTo)

Informação do local e data de descarga onde os artigos vendidos são colocados à disposição do cliente, ou de quem este indicar no caso de operações triangulares.

Delivery identifier (DeliveryID)

In the case of triangular transactions, the place of delivery and the VAT number of the recipient must be indicated.

Delivery date (DeliveryDate)

In the insurance sector, this field must be filled in with the end date of the risk coverage period.

partner.street

+

partner.streetNumber

partner.countryCode

converted to ISO 3166 ALPHA-2

Place of loading (ShipFrom)

Information on the place and date of loading where the shipment of items sold to the customer begins.

Delivery identifier (DeliveryID)

The registration number of the transport vehicle or means of shipment used must be indicated, e.g. express courier, etc.

Date of receipt (DeliveryDate)

In the insurance sector, this field must be filled in with the start date of the risk coverage period.

storeAddress.street

+

storeAddress.streetNumber (from Configuration)

Date and time of end of transport (MovementEndTime)

Date and time type: ‘YYYY-MM-DDThh:mm:ss’ where “ss” can be ‘00’ in the absence of specific information.

Date and time for the start of transport (MovementStartTime)

Date and time type: ‘YYYY-MM-DDThh:mm:ss’ where “ss” can be ‘00’ in the absence of specific information.

This field must be completed if the document also serves as a transport document in accordance with the provisions of the Regime for Goods in Circulation, approved by Decree-Law No. 147/2003 of 11 July.

Line number (LineNumber)

Lines should be exported in the same order as they appear in the original document.

Reference to the source document (OrderReferences)

If more than one reference is required, this structure can be generated as many times as necessary.

Originating document number (OriginatingON)

The type, series and number of the document supporting the issue of this document must be indicated.

If the document is contained in SAF-T (PT), the numbering structure of the originating field must be used.

Product or service identifier (ProductCode)

Key to the record in table 2.4. – Table of products/services (Product), in field 2.4.2. – Product or service identifier (ProductCode).

Product or service description (ProductDescription)

Description of the invoice line, linked to table 2.4. – Product/service table (Product), in field 2.4.4. – Product or service description (ProductDescription).

Positions.QuanitityUnit.IsoCode

Use ISO/UCUM codes

Unit price (UnitPrice)

Unit price minus line and header discounts, excluding taxes.

Must be filled in with ‘0.00’ if field 4.1.4.19.8 must be filled in. - Taxable unit value (TaxBase).

Only used for free-of-charge items,

if grossValue: 0 and baseGrossValue> 0

Unit taxable value (TaxBase)

Unit taxable value that does not contribute to the Total of the document without taxes (NetTotal). This value is used as the basis for calculating the taxes for the line. The sign (debit or credit) with which the tax thus calculated contributes to TaxPayable results from the existence of DebitAmount or CreditAmount in the line.

for DocumentType": 0 / "[0] = Receipt

• = bookDate

for DocumentType": 1 / "[1] = Invoice

• = ServicePeriodEnd

Date of shipment of goods or provision of services (TaxPointDate)

Date of shipment of goods or provision of services.

Must be filled in with the date of the associated delivery note, if any.

If there is more than one delivery note, the date of the oldest one must be indicated.

References to invoices (References)

References to invoices in their corrective documents.

If more than one reference is required, this structure can be generated as many times as necessary.

Serial Number

Must include the serial number of the product listed in the document. E.g.: VIN, IMEI, ISSN, ISAN.

If more than one reference is required, this field can be generated as many times as necessary.

Debit Amount (DebitAmount)

Line amount, excluding tax, of documents to be posted to the sales account.

This amount is deducted from line and header discounts.

Credit Amount

Line amount, excluding tax, of documents to be posted as credit to the sales account.

This amount is deducted from line and header discounts.

Tax type code (TaxType)

The tax type must be indicated in this field.

It must be filled in with:

• “IVA” – Value added tax;
• “IS” – Stamp duty.
• “NS“ – Not subject to VAT or ST.

derived from FiscalRegions (of Store)

• Portugal
• Acores
• Madeira

Mapping:

• Portugal - 'PT'
• Acores - 'PT-AC'
• Madeira - 'PT-MA'

Tax country or region (TaxCountryRegion)

Must be completed in accordance with ISO 3166 - 1- alpha-2.

In the case of the autonomous regions of Madeira and the Azores, it must be filled in with:

• “PT-AC” - Tax area of the Autonomous Region of the Azores;
• “PT-MA” - Tax area of the Autonomous Region of Madeira.

vatIdentification

In Portugal the following vat rates apply:

Portugal:

Normal rate: 23%

Reduced rate: 6%

Intermediate rate: 13%

Acores:

Normal rate: 16%

Reduced rate: 4%

Intermediate rate: 9%

Madeira:

Normal rate: 22%

Reduced rate: 4% (valide from: 2024-10-01)

Intermediate rate: 12%

Tax code (TaxCode)

Tax code in the tax table.

In the case of field 4.1.4.19.15.1. - Tax type code (TaxType) = VAT, it must be filled in with:

• “RED” - Reduced rate;
• “INT” – Intermediate rate;
• “NOR” – Standard rate;
• “ISE” – Exempt;
• “OUT” – Others, applicable to special VAT regimes.

In the case of field 4.1.4.19.15.1 - Tax type code (TaxType) = IS, it must be filled in with:

• The respective budget code;
• “ISE” - Exempt.

In the case of non-liability, it must be filled in with ‘NS’.

Tax percentage (TaxPercentage)

This field must be completed if it is a tax percentage.

The tax percentage corresponds to the tax applicable to field 4.1.4.19.13. - Debit Amount (DebitAmount) or field 4.1.4.19.14. - Credit Amount (CreditAmount).

In the case of exemption or non-taxability, use this field with the value “0” (zero).

Tax amount (TaxAmount)

This field must be filled in if it is a fixed unit amount of stamp duty. This amount, multiplied by the quantity (Quantity), contributes to the tax payable (TaxPayable).

Exempt-Reason Codes M01-M99

fiscalResponse.printingFields

Reason for tax exemption (TaxExemptionReason)

This field must be completed when fields 4.1.4.19.15.4 - Tax percentage (TaxPercentage) or 4.1.4.19.15.5 -

Tax amount (TaxAmount) are equal to zero.

The applicable legal provision must be referenced.

This field must also be completed in cases of non-liability for the taxes referred to in Table 2.5. - Tax table (TaxTable).

Tax exemption reason code (TaxExemptionCode)

Must be filled in with the exemption or non-assessment reason code, which can be found in the Software Integration Manual – Communication of Invoices to the AT.

This field must be filled in when fields 4.1.4.19.15.4 - Tax percentage (TaxPercentage) or 4.1.4.19.15.5 - Tax amount (TaxAmount) are equal to zero.

This field must also be filled in cases of non-liability for the taxes referred to in table 2.5. – Tax Table (TaxTable).

Line settlement amount (SettlementAmount)

Must reflect all discounts granted (the proportion of global discounts for this line and those specific to the same line) that affect the value of field 4.1.4.20.3. – Document total with taxes (GrossTotal).

Administrative reference code (ARCNo)

Fill in with the code assigned after validation of the e-DA electronic administrative document.

If more than one reference is required, this field can be generated as many times as necessary.

Amount of excise duty for the line (IECAmount)

Amount of excise duty included in the taxable base for the document line if it is not itemised on a separate line in the document, with the “Product or service indicator (ProductType)” = E.

Total document amount excluding taxes (NetTotal)

This field should not include the amounts relating to the taxes listed in Table 2.5. – Tax Table (TaxTable).

Total document amount including taxes (GrossTotal)

This field should not reflect any withholding taxes included in structure 4.1.4.21. – Withholding Tax (WithholdingTax)

Currency code (CurrencyCode)

In the case of foreign currency, this must be filled in accordance with ISO 4217.

Total amount in foreign currency (CurrencyAmount)

Value of field 4.1.4.20. 3. – Document total including taxes (GrossTotal) in the original currency of the document.

Exchange rate (ExchangeRate)

The exchange rate used for conversion to EUR must be indicated.

Agreements or payment methods.

If more than one reference is required, this structure can be generated as many times as necessary.

Future discount agreements (SettlementDiscount)

Must be filled in with the discount agreements to be applied in the future on the present value.

Settlement amount (SettlementAmount)

Represents the agreed amount for future discount without affecting the present value of the document indicated in field 4.1.4.20.3. — Document total with taxes (GrossTotal).

Agreed settlement date (SettlementDate)

The information to be included is the agreed date for payment with discount

Payment terms

The information to be included is the terms agreed or the payment deadline.

In the case of mixed payments, the amounts must be indicated by type of means and date of payment.

If more than one reference is required, this structure can be generated as many times as necessary.

payments.paymentType

Mapping:

• CC - 2 / CreditCard
• CD - 1 / EcCard
• CH - 14 / Cheque
• CI - not mapped
• CO - 4 / MultiPurposeVoucher
• CS
  • 6 / Deposit
  • 15 / CreditNote
• DE
  • 12 / CustomerCard
  • 13 / Loyalty
• LC - not mapped
• MB - Mapping:
• CC - 2 / CreditCard
• CD - 1 / EcCard
• CH - 14 / Cheque
• CI - not mapped
• CO - 4 / MultiPurposeVoucher
• CS6 / Deposit
• 15 / CreditNote
• DE12 / CustomerCard
• 13 / Loyalty
• LC - not mapped
• MB - 5 / PaymentProvider 
• NU - 0 / Cash
• OU9 / Crypto
• 10 / MobilePhoneApps
• PR - not mapped
• TB - 11 / BankAccount
• TR - not mapped
• NU - 0 / Cash
• OU
  • 9 / Crypto
  • 10 / MobilePhoneApps
• PR - not mapped
• TB - 11 / BankAccount
• TR - not mapped

Means of payment (PaymentMechanism)

Must be filled in with:

• “CC” – Credit card;
• “CD” – Debit card;
• “CH” – Bank cheque;
• “CI” – International documentary credit;
• “CO” – Cheque or gift card;
• “CS” – Current account balance compensation;
• “DE” – Electronic money, e.g. stored on loyalty or points cards;
• “LC” – Commercial letter;
• “MB” – Payment references for Multibanco;
• “NU” – Cash;
• “OU” – Other means not listed here;
• “PR” – Exchange of goods;
• “TB” – Bank transfer or authorised direct debit;
• “TR” – Non-salary compensation vouchers regardless of their medium, e.g. meal vouchers, education vouchers, etc.

Payment amount (PaymentAmount)

The amount per payment method must be indicated.

Withholding Tax

If more than one reference is required, this structure can be generated as many times as necessary.

Withholding tax type code (WithholdingTaxType)

In this field, you must indicate the type of withholding tax by filling it in with:

• “IRS” – Personal income tax;
• “IRC” – Corporate income tax;
• “IS” – Stamp duty.

Reason for withholding tax (WithholdingTaxDescription)

The applicable legal provision must be indicated.

If the tax type code (WithholdingTaxType) = IS, the respective tax code must be entered.

Withholding tax amount (WithholdingTaxAmount)

The amount of tax withheld must be indicated.