Skip to main content

​
Introduction

Invopop, as a certified provider in Portugal, allows you to issue fully-compliant tax documents and report them to the Autoridade Tributária e Aduaneira (AT). Using the AT Portugal app, you can generate PDFs with the correct signatures, ATCUD and QR codes for all your documents (invoices, transport documents, payments, etc.). Also, you can report them to the AT either in batch, via periodic SAF-T PT reports, or in real-time, using the AT web services. This guide will walk you through the process of issuing invoices, delivery documents, and payments in a supplier’s name, cancelling them if needed, and reporting them to the AT.

​
Prerequisites

To issue invoices and other documents in Portugal, you will need:
  • A registered supplier: follow the AT supplier registration guide to connect the AT Portugal app, register the supplier, and register their document series before issuing.
  • Document details:
    • Line items with quantity, price, description
    • Applicable VAT rates
    • Any other details required for the specific document type

​
Setup

Prepare the processing and cancel workflows for the document types you plan to issue: invoices, deliveries, and payments.
The AT Portugal app must already be connected and configured, and the supplier registered — this is covered in the supplier registration guide.
All of the following steps must be carried out from the Invopop Console.
1

Prepare the invoice processing workflow

You can skip this step if you don’t plan to issue invoices.

AT issue invoice workflow

This workflow will issue an invoice through the AT (Portugal).
2

Prepare the invoice cancel workflow

You can skip this step if you don’t plan to cancel invoices.

AT cancel invoice workflow

This workflow will cancel an invoice through the AT (Portugal).
3

Prepare the delivery processing workflow

You can skip this step if you don’t plan to issue delivery documents.

AT issue delivery workflow

This workflow will issue a delivery document through the AT (Portugal).
4

Prepare the delivery cancel workflow

You can skip this step if you don’t plan to cancel delivery documents.

AT cancel delivery workflow

This workflow will cancel a delivery document through the AT (Portugal).
5

Prepare the payment processing workflow

You can skip this step if you don’t plan to issue payments.

AT issue payment workflow

This workflow will issue a payment through the AT (Portugal).
6

Prepare the payment cancel workflow

You can skip this step if you don’t plan to cancel payments.

AT cancel payment workflow

This workflow will cancel a payment through the AT (Portugal).

​
Running

In this section, we’ll provide details on how to issue AT invoices and other documents on behalf of a registered supplier, cancel them, and report them to the AT.
The recommended approach for running jobs is to perform two steps: first upload the document to the silo, then create a job.

​
Send a document

The following examples show partial GOBL documents you can copy and paste directly into the Invopop Console or store via the API as silo entries. After uploading, you must run the corresponding processing workflow (invoice, delivery, or payment) created during setup.
GOBL Documents reported to the AT require the regime to be set to PT and addons to include pt-saft-v1. Invopop will try to assign these automatically, but we recommend defining them explicitly before uploading.
Documents are issued under one of the series registered during supplier onboarding, and their sequence number (the code property) is assigned automatically by the Record document for SAF-T step — do not add a sequence step. See Series management in the supplier registration guide for naming rules, sequence assignment, and series types.
In this example, we’re issuing a simple invoice from a Portuguese supplier to another Portuguese business.Notice:
  • the minimal version in the first tab contains only the essential fields required to create the invoice, without totals or calculations,
  • the pt-saft-v1 addon ensures the document will be validated and normalized using the SAF-T PT v1 rules built into the GOBL library,
  • the supplier and series fields are set to example values; you’ll need to replace them with the details of supplier and series registered as per the previous sections. The series must be registered in the Supplier Portal and follow Portuguese naming conventions (see Series management for details),
  • when running gobl build, or uploading the file, the system automatically calculates totals, assigns the pt-saft-invoice-type extension to FT (Fatura), sets the pt-saft-payment-means extension to CC for card payment, and applies the pt-saft-tax-rate extension to NOR for standard VAT,
  • the built version in the second tab shows the normalized document with calculated totals, line item sums (including advance payment deductions), tax breakdowns, and automatically generated fields, and,
  • the h item unit causes the pt-saft-product-type extension to be set to S (Serviço), and the pt-region extension is automatically set to PT.
In this example, a self-employed professional (trabalhador independente) invoices a Portuguese company for consulting services. On top of the standard VAT, the customer retains personal income tax (IRS) at source.Notice:
  • the minimal version in the first tab contains only the essential fields; the line carries a second tax on top of VAT: an IRS combo with percent set to 25% and no rate,
  • the document-level tax.notes entry with cat: "IRS" carries the legal basis for the withholding (here Art. 101.º CIRS); the SAF-T export surfaces it as the WithholdingTaxType (IRS) and WithholdingTaxDescription of the WithholdingTax block, and,
  • in the built version the IRS tax becomes its own retained category in totals.taxes, separate from VAT, with retained: "250.00" (25% of the 1000,00 base).
In this example, we’re issuing a standard invoice from a Portuguese supplier that has adhered to the Cash VAT scheme (regime de IVA de Caixa), under which VAT becomes due only when the customer actually pays rather than when the invoice is issued.Notice:
  • the only difference from the standard AT B2B invoice above is the cash-vat tag ($tags: ["cash-vat"]), which flags the supplier’s membership in the scheme,
  • the pt-saft-v1 addon reacts to that tag by setting the pt-saft-cash-vat extension to 1 in the invoice’s tax section, and,
  • the document is otherwise a normal standard invoice: the pt-saft-invoice-type extension is still set to FT (Fatura) and the standard VAT rate still maps to the pt-saft-tax-rate extension NOR.
In this example, we’re issuing a simplified invoice (Fatura Simplificada) — the short-form invoice used for low-value retail sales where the customer doesn’t need to be identified.Notice:
  • the document carries the simplified tag ($tags: ["simplified"]) and omits the customer entirely,
  • the pt-saft-v1 addon reacts to the tag by setting the pt-saft-invoice-type extension to FS (Fatura Simplificada), and the series follows the matching FS prefix convention,
  • if the document also records full payment (for example, a 100% advance), the addon derives the type FR (Fatura-Recibo) instead, and the series must then use the FR prefix, and,
  • as with the other examples, totals and tax breakdowns are calculated automatically when running gobl build or uploading.
In this example, we’re issuing a delivery note from a Portuguese supplier to another Portuguese receiver.Notice:
  • the first tab shows the minimal version containing only the essential fields required to create the delivery document; there are no totals or calculations,
  • the pt-saft-v1 addon ensures the document will be validated and normalized using the SAF-T PT v1 rules built into the GOBL library,
  • the supplier and series fields are set to example values; you’ll need to replace them with the details of supplier and series registered as per the previous sections. The series must be registered in the Supplier Portal and follow Portuguese naming conventions (see Series management for details),
  • this is a note document type with the pt-saft-movement-type extension set to GR (Guia de Remessa),
  • when running gobl build, or uploading the document, the system automatically calculates totals, applies the standard VAT rate with the pt-saft-tax-rate extension set to NOR, and normalizes all fields,
  • the second tab shows the built version of the document with the calculated totals, line item sums, tax breakdowns, and automatically generated fields, and,
  • the pt-region extension is automatically set to PT.
A return guide (Guia de Devolução) records goods being returned to the supplier — for example, defective items, unsold stock, or any other scenario where previously delivered goods are sent back.Notice:
  • the document carries the return tag ($tags: ["return"]), which the pt-saft-v1 addon uses to automatically set the pt-saft-movement-type extension to GD (Guia de Devolução),
  • the series follows the GD prefix convention and must be registered through the Supplier Portal, and,
  • the flow of goods is reversed compared to a delivery note: the customer is the party returning the goods, and the supplier is the one receiving them back.
For shipments where the specific recipient is not known upfront — for example, multi-stop delivery runs — issuers can emit a global waybill (Guia de Transporte Global) to cover the goods in transport.Notice:
  • the document type is set to waybill, which the pt-saft-v1 addon normalizes to the pt-saft-movement-type extension GT (Guia de Transporte),
  • the series follows the GT prefix convention required by the AT and must be registered through the Supplier Portal, and,
  • the customer field is omitted: when no customer is provided on a GT, the SAF-T submission auto-fills the AT-prescribed generic entry Consumidor final with NIF 999999990 and address Desconhecido.
Once the recipient of part of the goods covered by a global waybill is known, a concrete document — typically a GR (Guia de Remessa) — must be issued with the full transaction details, including the customer and a cross-reference back to the originating GT so the AT can correlate both records.Notice:
  • the customer is now populated with the actual recipient of the goods, and,
  • the preceding array carries one entry with the series, code, and issue_date of the originating GT.
A return can also be linked back to a global waybill — for example, when surplus goods that were not delivered to any customer come back to the depot at the end of a delivery run.Notice:
  • as in the standalone return guide, the return tag drives the pt-saft-movement-type extension to GD,
  • the preceding array references the originating GT, and,
  • the customer is omitted, since the goods are returning to the issuer’s own depot rather than to a specific party.
In this example, we’re issuing a payment receipt from a Portuguese supplier to another Portuguese business.Notice:
  • the minimal version in the first tab contains only the essential fields required to create the payment document,
  • the pt-saft-v1 addon ensures the document will be validated and normalized using the SAF-T PT v1 rules built into the GOBL library,
  • the supplier and series fields are set to example values; you’ll need to replace them with the details of supplier and series registered as per the previous sections. The series must be registered in the Supplier Portal and follow Portuguese naming conventions (see Series management for details),
  • this is a single receipt payment that bundles multiple payment methods: 30,00 EUR in cash plus 31,50 EUR by card, summing to the document total of 61,50 EUR. Each method gets its own pt-saft-payment-means extension auto-assigned (NU for cash, CC for card),
  • when running gobl build, the system automatically assigns the pt-saft-payment-type extension to RG and the pt-saft-source extension to P,
  • the built version in the second tab shows the normalized document with all automatically generated fields and extensions properly set,
  • the payment lines reference the original invoice being paid, though a single receipt can reference multiple invoices if needed,
  • this receipt could represent either a full or partial payment of the referenced invoice; it simply records the amounts and taxes being paid, so the total may or may not cover the full invoice amount, and,
  • there are no calculations in the minimal version; all normalizations will be made automatically when uploading.
In this example, we’re issuing a payment receipt for a supplier under the Cash VAT scheme (regime de IVA de Caixa). For these suppliers, the receipt is the document that actually triggers the VAT becoming due, so the AT distinguishes it from an ordinary receipt.Notice:
  • the document carries the cash-vat tag ($tags: ["cash-vat"]), exactly as the Cash VAT invoice does,
  • on a receipt, that tag drives the pt-saft-payment-type extension to RC (Recibo no âmbito do regime de IVA de Caixa) instead of the default RG (Outro Recibo) you’d get on the ordinary AT payment receipt above,
  • the series follows the RC prefix convention and must be registered through the Supplier Portal,
  • the payment line references the original invoice being settled, carrying its VAT breakdown so the AT can match the now-due tax to the issued invoice, and,
  • as with any receipt, the pt-saft-payment-means extension is auto-assigned per method (TB for the bank transfer) and the pt-saft-source extension is set to P.

​
Cancel a document

If you need to cancel a document that has already been issued and reported to the AT, you can use the cancel workflows created during setup. The cancellation process follows the same pattern as sending a document: create a job for the silo entry you want to cancel using the cancel workflow appropriate for the document type.

​
Recovering documents issued offline

If you lose the connection to Invopop and cannot issue documents through your regular workflow, Portuguese law defines exactly what to do. Despacho n.º 8632/2014, section 2.4, regulates the issuance of documents during a period of software unavailability (inoperacionalidade do programa) and their later integration into the certified invoicing system.

​
While offline: issue on paper

During the outage, documents must be issued manually on pre-printed paper forms acquired from an AT-authorized typography (tipografia autorizada). These paper documents:
  • Carry their own series and sequential numbering, pre-printed by the typography.
  • Include a pre-printed ATCUD: the typography registers the series with the AT and obtains the validation code on your behalf.
  • Do not require a QR code: the QR code obligation only applies to documents issued by certified software.
We recommend keeping a pad of these forms on hand as your offline contingency.

​
Once back online: recover the documents

Immediately after the connection is restored, each paper document must be re-entered (“recovered”) through Invopop so it becomes part of the certified record and gets reported to the AT:
  1. Register a recovery series (type R), either through the Supplier Portal or the series registration endpoint. You can do this ahead of time as part of your contingency setup. Documents recovered from paper can only be issued under a recovery series.
  2. Create a GOBL document replicating the paper document exactly — same line items, taxes, and totals — with these specifics:
    • The issue_date must be the date of the original paper document.
    • The $tags array must include bypass, so the totals are taken verbatim from the paper document instead of being recalculated.
    • The pt-saft-source extension must be set to M (manual).
    • The pt-saft-source-ref extension must reference the paper document using the format defined in section 2.4.5 of the despacho: the document type code followed by the letter M, a space, and the paper document’s series and number separated by a slash.
    This partial example shows only the recovery-specific fields. Complete the document with the supplier, customer, lines, and totals copied from the paper document.
  3. Run your regular invoice workflow on the document. The recovered document is sealed like any other software-issued document — it receives a hash, an ATCUD from the recovery series, and a QR code — and is reported to the AT through the usual channels (real-time webservice and/or SAF-T PT). The reference to the paper document is included in the SAF-T HashControl field, as required by the despacho.
Keep in mind:
  • Each paper document can be recovered only once. Attempting to recover the same source reference twice is rejected.
  • Any later document referencing a recovered one (e.g., a credit note rectifying it) must reference the original paper document’s series and number, not the number assigned to the recovered document.
Recovery series also cover a second scenario regulated by section 2.5 of the same despacho: re-entering documents lost to a system failure from their printed duplicates. In that case, the pt-saft-source-ref extension uses the letter D instead of M (e.g., FTD FT SERIES/123), and the original series is automatically decommissioned once the first document is recovered, as the law requires it to be closed.

​
Reporting documents to the AT

The AT Portugal app supports two methods for reporting documents to the Autoridade Tributária e Aduaneira:
  1. Real-time reporting - Documents are submitted individually to the AT immediately upon issuance via webservice
  2. SAF-T PT reporting - Documents are reported in batch format through periodic SAF-T PT reports
The workflow templates provided in this guide enable both reporting mechanisms.

​
Real-time reporting

The Send document to AT step uses the AT’s webservice to submit each document to the tax authority immediately after it is recorded. This step is optional. If you prefer to report documents only via SAF-T PT reports, you can remove it from your workflows.
The Send document to AT step requires the supplier to have the appropriate AT user permissions (WFA for invoices, WDT for transport documents) as described in the supplier registration guide.

​
SAF-T PT reporting

SAF-T PT reports allow you to submit documents to the AT in batch format. The Record document for SAF-T step takes care of recording the documents for this purpose.
The Record document for SAF-T step is required in all workflows, regardless of whether you also use real-time reporting. The AT may request SAF-T PT reports for audit purposes at any time, so all documents must be properly recorded.
To generate a SAF-T PT report, a supplier can follow these steps:
  1. Go to the Invopop AT Portugal Supplier Portal
  2. Log in using the email address provided with the supplier’s information
  3. Go to the SAF-T PT section, enter a date range and click Generate
The system will generate a SAF-T PT file containing all documents issued within the specified date range that have been recorded for SAF-T reporting. This file can then be submitted to the AT through their portal or via command line.

​
FAQ

In Portugal, fiscally relevant documents issued through invoicing software must be reported to the Tax Authority (AT). There are two possible reporting models:
  1. SAF-T monthly export – a single XML file including all documents for the month. This file is generated by the invoicing software and then uploaded manually to the AT portal, as there is no API available for submitting it automatically.
  2. Real-time transmission – instead of a monthly file, each invoice is sent individually to the AT at the time of issuance, using the authority’s API.
Whether one model or the other is used usually depends on the issuer’s accountant’s preference (who typically uploads the SAF-T monthly report should they choose that model). Invopop’s AT Portugal app supports both reporting methods, so each supplier can pick the one that best fits their needs.
Install the AT Portugal app, register the supplier with their NIF, and pick a reporting model (monthly SAF-T or real-time submission). Run invoices through the AT Issue Invoice workflow — Invopop generates the ATCUD, QR, and signature automatically.
When issuing in Portugal you may see an error similar to:
recording envelope: totals: (payable: too high according to Artigo 40.º do CIVA.)
What it means: Article 40 of the Portuguese VAT Code (Código do IVA) sets limits and rules for simplified invoices (faturas simplificadas). If the payable amount exceeds what is allowed for a simplified invoice in your situation, the rules effectively require a full invoice (fatura completa) with proper buyer identification—not an anonymous or minimal customer.What to do:
  • Treat the document as a full invoice and supply real customer tax data when you have it.
  • If you do not have the buyer’s tax information, Portuguese practice allows the generic retail customer: set the customer name to Consumidor final and the tax ID to 999999990.
  • For transactions above €1,000, the law also expects name and address on the document. The AT may not always reject submissions that omit some of that detail, but you should follow the rule for full compliance.
Adjust your GOBL customer block (or equivalent) accordingly and re-run the workflow.
This error means your workflow includes the Send to the AT step for a payment receipt. Payment receipts are not supported for real-time reporting — the AT does not accept them via the real-time webservice.The fix: remove the Send to the AT step from your payment workflow. RG receipts are only reportable through the monthly SAF-T file. The Record for SAF-T reporting step alone is all you need for full compliance.
Portugal defines two payment receipt types:
  • RG — Outros Recibos: Standard payment receipts, reported through the monthly SAF-T file only. Real-time reporting is not available for this type.
  • RC — Recibo no âmbito do regime de IVA de Caixa: Receipts specific to the VAT Cash accounting regime. RC payments are not currently supported by the AT Portugal app.
See the Portugal tax regime in GOBL for tax categories, NIF rules, and AT-specific extensions. The pt-saft-v1 addon documents fields required by the SAF-T schema.
More available in our Portugal FAQ section

Participate in our community

Ask and answer questions about Portugal’s regulation →