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 registering a supplier, issuing invoices in their name, and generating a SAF-T PT report.

​
Prerequisites

To issue invoices and other documents in Portugal, you will need:
  • Supplier details, including:
    • Legal business name
    • Tax ID
    • Business address
  • An email address for the supplier to access the Supplier Portal
  • The supplier’s credentials to access the AT’s web services for registering series and report documents in real-time
  • Document details:
    • Line items with quantity, price, description
    • Applicable VAT rates
    • Any other details required for the specific document type

​
Setup

There are four key processes to prepare:
  • create a supplier post-registration workflow,
  • connect the AT Portugal app,
  • configure a supplier registration workflow, and,
  • prepare a document processing workflow.
All of the following steps must be carried out from the Invopop Console.
1

Connect the AT Portugal App

  1. Navigate to Configuration → Apps.
  2. Find AT Portugal in the app discovery list.
  3. Click Connect to activate.
2

Create Supplier post-registration workflow

AT supplier post-registration workflow

Marks Suppliers as “Registered”. You will select this workflow in the AT (Portugal) app configuration later.
3

Configure the AT Portugal App

  1. Navigate to Configuration → Apps.
  2. Find AT Portugal in the connected apps list.
  3. Click Configure and choose the “Post-registration workflow” we created in the previous step.
  4. Click the Save button.
4

Configure the supplier registration workflow

AT supplier registration workflow

Issues a registration request for a supplier to complete.
5

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).
6

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).
7

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).
8

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).
9

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).
10

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 first persist and register a supplier, followed by issuing AT invoices and other documents on their behalf.
The recommended approach for running jobs is to perform two steps: first upload the document to the silo, then create a job.

​
Register a Supplier

1

Submit the Supplier Information

This can be done either manually via the Invopop Console or programmatically via the API. The process is essentially the same; here we’ll do it manually.Find the Parties section of the sidebar and click Suppliers. Click the + New Supplier button to be presented with a new editor. You can use the following example as a template, and replace it with the details of your company. Note that you’ll need the details of a real company both in the sandbox and production environments:
Portugal AT supplier example
{
    "$schema": "https://gobl.org/draft-0/org/party",
    "name": "Innovatech Lda",
    "tax_id": {
        "country": "PT",
        "code": "504614240"
    },
    "addresses": [
        {
            "num": "156",
            "street": "Avenida da República",
            "locality": "Lisboa",
            "code": "1050-045",
            "country": "PT"
        }
    ],
    "emails": [
        {
            "addr": "maria@example.com"
        }
    ],
    "registration": {
        "capital": "150000.00",
        "office": "CRC Lisboa",
        "other": "sob NIF 770013813"
    }
}
Each supplier must have a unique email address. The email serves as the login for the Supplier Portal, so it can only be linked to one supplier. Attempting to register a different supplier with an already-used email will result in an error.
Click Build, ensure there are no errors, and click Save.We should now see the document. Find and click the Select Workflow button. Select the Register Supplier workflow created during setup, and click Run Workflow.The execution should be successful, and the silo entry will now be in the “Processing” state.
2

Obtain the Supplier's AT Credentials

To complete the registration process, the supplier will need to obtain the credentials of a user with the necessary permissions in the AT’s Portal das Finanças. To create a new user, the supplier can follow these steps:
  1. Go to the AT’s Portal das Finanças and click on the Iniciar Sessão button.
  2. Authenticate by any of the available methods.
  3. Go to Todos os Serviços > Autenticação de Contribuintes > Gestão de Utilizadores.
  4. Click on the Criar Novo Utilizador button.
  5. Fill in the form with the required information. We recommend setting a name that identifies the purpose of the user, for example “Invopop User”.
  6. Select the user permissions, depending on the supplier needs:
    • WSE – Always required. It allows to register series for any document type.
    • WSA – Required if the supplier wants to submit invoices to the AT in real-time, rather than using SAF-T.
    • WDT – Required if the supplier wants to submit transport documents (e.g. “Guia de Remessa”, “Guia de Transporte”, etc.) to the AT in real-time, rather than using SAF-T.
  7. Click on the Submeter button to create the user.
  8. Store the username and password in a secure location, as they will be needed in the next step.
3

Provide the Supplier's AT Credentials and Register Series

White-label integration: If you need to fully integrate this functionality into your own platform, the AT Portugal API provides programmatic access to manage credentials, register series, and generate SAF-T reports without requiring suppliers to use the Supplier Portal as described below.
Now, the supplier will need to complete the registration process in the Invopop’s Supplier Portal:
  1. Go to the Invopop AT Portugal Supplier Portal
  2. Enter the email address provided in the supplier’s information. The system will send to the provided address a code to complete the authentication process.
  3. Once logged in, go to Credentials, enter the AT credentials obtained in the previous step, and press Save.
  4. Go to the Series section, click + Register and register at least a series for each document type that the supplier will issue.
Once the series are registered, the supplier will be able to issue documents using them. When this happens, the system will automatically execute the “Post-registration workflow” if one was configured.
For detailed information about series management in Portugal, including naming conventions and automatic sequence assignment, see the Series Management section below.

​
Updating Supplier Data

After a supplier has been registered, you may need to update their information over time — for example, a change of address. Keep in mind that supplier data is used in two different contexts:
  • SAF-T reports use the data stored in the Supplier Record. To have updated information appear in SAF-T reports, update the Supplier Record directly via the API or the Console. Re-running the registration workflow is not necessary for data-only changes.
  • Printed PDFs use the supplier details included in each individual invoice, not from the Supplier Record. Make sure the invoice data is correct at the time of issuance.
If you need to change the supplier’s login email for the Supplier Portal, update the email in the Supplier Record and re-run the registration workflow so the portal access is updated accordingly.

​
Series Management

Series management in Portugal has specific requirements that differ from other countries. Understanding these particularities is essential for proper document issuance.

​
Naming

All series names in Portugal must follow a specific format:
  • Document type prefix: The name must start with a code indicating the document type (e.g., FT, FS, FR, NC…), followed by a space.
  • Base name: After the space, you can add any custom name you prefer. The custom name can contain letters, numbers, and most special characters, but not spaces, forward slashes (/), or carets (^).
Examples: FT A001, NC 2024-01, FR INV-2024 When you register series through the Supplier Portal, you’re asked to provide a base name (without the document prefix) and select the document types you plan to issue. The portal combines each selected prefix with the base name, registers every resulting series with the AT, and retrieves the corresponding validation code required for generating ATCUD codes.

​
Sequence Assignment

Unlike other countries, Portugal regulations do not allow pre-assigning sequence numbers to documents. The sequence number (i.e., the document’s code property) is automatically assigned during the Record for SAF-T reporting (Portugal) step in your workflow, following AT regulations. This is why you’ll find no sequence step in Portugal workflow templates and you should not add one.

​
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.
In this example, we’re issuing a simple invoice from a Portuguese supplier to another Portuguese business.Notice:
  • the minimal version (at-b2b.min.mdx) contains only the essential fields required to create the invoice,
  • 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, 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 (at-b2b.mdx) shows the normalized document with calculated totals, line item sums (including advance payment deductions), tax breakdowns, and automatically generated fields,
  • 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, and,
  • there are no totals or calculations in the minimal version; all these will be made automatically when uploading.
{
    "$schema": "https://gobl.org/draft-0/bill/invoice",
    "$regime": "PT",
    "$addons": [
      "pt-saft-v1"
    ],
    "type": "standard",
    "series": "FT SERIES-A",
    "issue_date": "2024-12-23",
    "currency": "EUR",
    "supplier": {
      "name": "Innovatech Lda",
      "tax_id": {
        "country": "PT",
        "code": "504614240"
      },
      "addresses": [
        {
          "num": "156",
          "street": "Avenida da República",
          "locality": "Lisboa",
          "code": "1050-045",
          "country": "PT"
        }
      ],
      "emails": [
        {
          "addr": "maria@example.com"
        }
      ],
      "registration": {
        "capital": "150000.00",
        "office": "CRC Lisboa",
        "other": "sob NIF 770013813"
      }
    },
    "customer": {
      "name": "Gusto Unipessoal Lda",
      "tax_id": {
        "country": "PT",
        "code": "514329874"
      },
      "addresses": [
        {
          "street": "Avenida da Liberdade 152 2º Direito",
          "locality": "Lisboa",
          "code": "1250-146",
          "country": "PT"
        }
      ],
      "emails": [
        {
          "addr": "gusto@example.com"
        }
      ],
      "websites": [
        {
          "url": "https://gusto.example.com"
        }
      ],
      "telephones": [
        {
          "num": "+351912345678"
        }
      ]
    },
    "lines": [
      {
        "quantity": "20.0",
        "item": {
          "name": "Development services",
          "price": "50.00",
          "unit": "h"
        },
        "taxes": [
          {
            "cat": "VAT",
            "rate": "standard"
          }
        ]
      }
    ],
    "payment": {
      "advances": [
        {
          "date": "2024-12-23",
          "key": "card",
          "description": "Advance payment",
          "amount": "12.34"
        }
      ]
    }
}
In this example, we’re issuing a delivery note from a Portuguese supplier to another Portuguese receiver.Notice:
  • the minimal version (delivery.min.mdx) contains only the essential fields required to create the delivery 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 an advice document type with the pt-saft-movement-type extension set to GR (Guia de Remessa),
  • when running gobl build, 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 built version (delivery.mdx) shows the normalized document with calculated totals, line item sums, tax breakdowns, and automatically generated fields,
  • the pt-region extension is automatically set to PT, and,
  • there are no totals or calculations in the minimal version; all these will be made automatically when uploading.
{
  "$schema": "https://gobl.org/draft-0/bill/delivery",
  "$regime": "PT",
  "$addons": [
    "pt-saft-v1"
  ],
  "type": "advice",
  "series": "GR SERIES-A",
  "issue_date": "2024-12-23",
  "currency": "EUR",
  "despatch_date": "2024-12-23",
  "receive_date": "2024-12-24",
  "tax": {
    "ext": {
      "pt-saft-movement-type": "GR"
    }
  },
  "supplier": {
    "name": "Innovatech Lda",
    "tax_id": {
      "country": "PT",
      "code": "770013813"
    },
    "addresses": [
      {
        "street": "Rua das Flores 200 3º Esquerdo",
        "locality": "Porto",
        "code": "4050-265",
        "country": "PT"
      }
    ],
    "registration": {
      "capital": "100000.00",
      "office": "Porto"
    }
  },
  "receiver": {
    "name": "Gusto Unipessoal Lda",
    "tax_id": {
      "country": "PT",
      "code": "514329874"
    },
    "addresses": [
      {
        "street": "Avenida da Liberdade 152 2º Direito",
        "locality": "Lisboa",
        "code": "1250-146",
        "country": "PT"
      }
    ],
    "telephones": [
      {
        "num": "+351912345678"
      }
    ]
  },
  "lines": [
    {
      "quantity": "10",
      "item": {
        "name": "Product A",
        "price": "5.00",
        "unit": "unit",
        "ext": {
          "pt-saft-product-type": "P"
        }
      },
      "taxes": [
        {
          "cat": "VAT",
          "rate": "standard"
        }
      ]
    }
  ],
  "notes": [
    {
      "text": "Delivery note for products"
    }
  ]
}
In this example, we’re issuing a payment receipt from a Portuguese supplier to another Portuguese business.Notice:
  • the minimal version (payment.min.mdx) 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 receipt payment with the method set to cash, which causes GOBL to automatically assign the pt-saft-payment-means extension to NU (Numerário),
  • 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 (payment.mdx) shows the normalized document with all automatically generated fields and extensions properly set,
  • the payment lines reference the original invoice document being paid, and,
  • there are no calculations in the minimal version; all normalizations will be made automatically when uploading.
{
  "$schema": "https://gobl.org/draft-0/bill/payment",
  "$regime": "PT",
  "$addons": [
    "pt-saft-v1"
  ],
  "type": "receipt",
  "method": {
    "key": "cash",
    "detail": "Full settlement made in cash"
  },
  "series": "RG SERIES-A",
  "issue_date": "2024-12-23",
  "currency": "EUR",
  "supplier": {
    "name": "Innovatech Lda",
    "tax_id": {
      "country": "PT",
      "code": "770013813"
    },
    "addresses": [
      {
        "street": "Rua das Flores 200 3º Esquerdo",
        "locality": "Porto",
        "code": "4050-265",
        "country": "PT"
      }
    ],
    "registration": {
      "capital": "100000.00",
      "office": "Porto"
    }
  },
  "customer": {
    "name": "Gusto Unipessoal Lda",
    "tax_id": {
      "country": "PT",
      "code": "514329874"
    },
    "addresses": [
      {
        "street": "Avenida da Liberdade 152 2º Direito",
        "locality": "Lisboa",
        "code": "1250-146",
        "country": "PT"
      }
    ],
    "emails": [
      {
        "addr": "gusto@example.com"
      }
    ],
    "websites": [
      {
        "url": "https://gusto.example.com"
      }
    ],
    "telephones": [
      {
        "num": "+351912345678"
      }
    ]
  },
  "lines": [
    {
      "document": {
        "issue_date": "2024-12-23",
        "series": "FT SERIES-A",
        "code": "1",
        "description": "Invoice 1"
      },
      "amount": "61.50",
      "tax": {
        "categories": [
          {
            "code": "VAT",
            "rates": [
              {
                "key": "standard",
                "ext": {
                  "pt-region": "PT",
                  "pt-saft-tax-rate": "NOR"
                },
                "base": "50.00",
                "percent": "23.0%",
                "amount": "11.50"
              }
            ],
            "amount": "11.50"
          }
        ],
        "sum": "11.50"
      }
    }
  ]
}

​
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.

​
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 to the AT (Portugal) 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 to the AT (Portugal) step requires the supplier to have the appropriate AT user permissions (WSA for invoices, WDT for transport documents) as described in the “Obtain the Supplier’s AT Credentials” section above.

​
SAF-T PT Reporting

SAF-T PT reports allow you to submit documents to the AT in batch format. The Record for SAF-T reporting (Portugal) step takes care of recording the documents for this purpose.
The Record for SAF-T reporting (Portugal) 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.

Portugal FAQ

Find answers to frequently asked questions about invoicing in Portugal →

Participate in our community

Ask and answer questions about Portugal’s regulation →