> ## Documentation Index
> Fetch the complete documentation index at: https://docs.invopop.com/llms.txt
> Use this file to discover all available pages before exploring further.
# AT Portugal Guide
> Issue documents in Portugal using Invopop's certified implementation.
## 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.
| - | Sandbox | Live |
| --------------- | ----------------------------- | ----------------------------- |
| **Supplier** | Real company details required | Real company details required |
| **Series type** | `F` (Training) | `N` (Normal) |
## 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](https://console.invopop.com).
1. Navigate to **Configuration** → **Apps**.
2. Find **AT Portugal** in the app discovery list.
3. Click **Connect** to activate.
Marks Suppliers as "Registered". You will select this workflow in the AT (Portugal) app configuration later.
Copy and paste into a new [Empty Party workflow](https://console.invopop.com/redirect/workflows/new?template=empty-party) code view.
```json Example AT supplier post-registration workflow theme={"system"}
{
"name": "AT supplier post-registration",
"description": "Mark an AT supplier as registered",
"schema": "org/party",
"steps": [
{
"id": "7e8d8070-3870-11ef-af29-4533d56cea03",
"name": "Set state",
"config": {
"state": "registered"
},
"summary": "Set state to `registered`{.state .registered}",
"provider": "silo.state"
}
],
"rescue": []
}
```
Before starting, review the [workflows guide](/guides/features/workflows) to understand the general setup process.
In [Console](https://console.invopop.com), create a new workflow and choose [Empty Party workflow](https://console.invopop.com/redirect/workflows/new?template=empty-party) as the base. Then name the workflow with a descriptive label such as "PT-AT Post-registration workflow".
This workflow is composed by a single step:
1. **Set state** - To `Registered`.
Though you can customize it to suit your needs (adding a webhook, or an email notification after a supplier has been registered.)
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.
Issues a registration request for a supplier to complete.
Copy and paste into a new [Empty Party workflow](https://console.invopop.com/redirect/workflows/new?template=empty-party) code view.
```json Example AT register supplier workflow theme={"system"}
{
"name": "AT register supplier",
"description": "Register a supplier with AT",
"schema": "org/party",
"steps": [
{
"id": "6f9282a0-3870-11ef-af29-4533d56cea03",
"name": "Set state",
"config": {
"state": "processing"
},
"summary": "Set state to `processing`{.state .processing}",
"provider": "silo.state"
},
{
"id": "1a9bcde0-a816-11ef-87b2-fd751e6d3b88",
"name": "Sign envelope",
"provider": "silo.close"
},
{
"id": "5b6ca7e0-ad93-11ef-a7da-83137f995008",
"name": "Register supplier with AT",
"provider": "at-pt.register"
}
],
"rescue": []
}
```
Before starting, review the [workflows guide](/guides/features/workflows) to understand the general setup process.
In [Console](https://console.invopop.com), create a new workflow and choose [Empty Party workflow](https://console.invopop.com/redirect/workflows/new?template=empty-party) as the base. Then name the workflow with a descriptive label such as "AT supplier registration".
The new workflow will need to perform three steps:
* **Set state** - with configuration set to `Processing`.
* **Sign envelope**
* **Register supplier with AT**
Finally, in the Error Handling area, add the **Set state** action and select `Error`.
Add any additional steps you may need, and save the new workflow.
You can skip this step if you don't plan to issue invoices.
This workflow will issue an invoice through the AT (Portugal).
Copy and paste into a new [Empty Invoice workflow](https://console.invopop.com/redirect/workflows/new?template=empty-invoice) code view.
```json Example AT issue invoice workflow theme={"system"}
{
"name": "AT issue invoice",
"description": "Issue an invoice through AT and generate PDF",
"schema": "bill/invoice",
"steps": [
{
"id": "6f884d90-f2b9-11ef-acb2-cd64e858247e",
"name": "Set state",
"provider": "silo.state",
"config": {
"state": "processing"
}
},
{
"id": "76f194b0-f2b9-11ef-acb2-cd64e858247e",
"name": "Record document for SAF-T",
"provider": "at-pt.record"
},
{
"id": "59174840-c09a-11f0-b8a2-b531dbe0da3c",
"name": "Send document to AT",
"provider": "at-pt.send"
},
{
"id": "93795a50-f2b9-11ef-acb2-cd64e858247e",
"name": "Generate PDF",
"provider": "pdf",
"summary": "Portuguese · A4 · Original",
"config": {
"date_format": "%Y-%m-%d",
"hide_promo": true,
"label": "Original",
"layout": "A4",
"locale": "pt",
"logo_height": 40,
"watermark": ""
}
},
{
"id": "ce7c50c0-9d55-11f0-b3a4-87562f21f508",
"name": "Generate PDF",
"provider": "pdf",
"summary": "Portuguese · A4 · Duplicado",
"config": {
"date_format": "%Y-%m-%d",
"label": "Duplicado",
"layout": "A4",
"locale": "pt",
"logo_height": 40,
"watermark": "",
"duplicate": true
}
},
{
"id": "7a708240-f2b9-11ef-acb2-cd64e858247e",
"name": "Set state",
"provider": "silo.state",
"config": {
"state": "sent"
}
}
],
"rescue": [
{
"id": "805bdbf0-f2b9-11ef-acb2-cd64e858247e",
"name": "Set state",
"provider": "silo.state",
"config": {
"state": "error"
}
}
]
}
```
Before starting, review the [workflows guide](/guides/features/workflows) to understand the general setup process.
In [Console](https://console.invopop.com), create a new workflow and choose [Empty Invoice workflow](https://console.invopop.com/redirect/workflows/new?template=empty-invoice) as the base. Then name the workflow with a descriptive label such as "AT issue invoice".
The new workflow will need to perform these steps:
1. **Set state** - to `Processing`.
2. **Record document for SAF-T** - No configuration required.
3. **Send document to AT** - No configuration required.
4. **Generate PDF (Original)** - Portuguese - A4 - Title badge: "Original".
5. **Generate PDF (Duplicate)** - Portuguese - A4 - Title badge: "Duplicado" - Flag as duplicate
6. **Set state** to `Sent`.
Finally, in the Error Handling area, add the **Set state** action and select `Error`.
Add any additional steps you may need, and save the new workflow.
You can skip this step if you don't plan to cancel invoices.
This workflow will cancel an invoice through the AT (Portugal).
Copy and paste into a new [Empty Invoice workflow](https://console.invopop.com/redirect/workflows/new?template=empty-invoice) code view.
```json Example AT cancel invoice workflow theme={"system"}
{
"name": "AT cancel invoice",
"description": "Cancel an invoice through AT and generate PDF",
"schema": "bill/invoice",
"steps": [
{
"id": "6f884d90-f2b9-11ef-acb2-cd64e858247e",
"name": "Set state",
"provider": "silo.state",
"config": {
"state": "processing"
}
},
{
"id": "cc0002a0-927f-11f0-8cd1-bd9f2c371090",
"name": "Cancel SAF-T record",
"provider": "at-pt.cancel"
},
{
"id": "59174840-c09a-11f0-b8a2-b531dbe0da3c",
"name": "Send document to AT",
"provider": "at-pt.send"
},
{
"id": "7a708240-f2b9-11ef-acb2-cd64e858247e",
"name": "Set state",
"provider": "silo.state",
"config": {
"state": "void"
}
},
{
"id": "93795a50-f2b9-11ef-acb2-cd64e858247e",
"name": "Generate PDF",
"provider": "pdf",
"summary": "Portuguese · A4 · Original",
"config": {
"date_format": "%Y-%m-%d",
"hide_promo": true,
"label": "Original",
"layout": "A4",
"locale": "pt",
"logo_height": 40,
"watermark": ""
}
},
{
"id": "ce7c50c0-9d55-11f0-b3a4-87562f21f508",
"name": "Generate PDF",
"provider": "pdf",
"summary": "Portuguese · A4 · Duplicado",
"config": {
"date_format": "%Y-%m-%d",
"label": "Duplicado",
"layout": "A4",
"locale": "pt",
"logo_height": 40,
"watermark": "",
"duplicate": true
}
}
],
"rescue": [
{
"id": "805bdbf0-f2b9-11ef-acb2-cd64e858247e",
"name": "Set state",
"provider": "silo.state",
"config": {
"state": "error"
}
}
]
}
```
Before starting, review the [workflows guide](/guides/features/workflows) to understand the general setup process.
In [Console](https://console.invopop.com), create a new workflow and choose [Empty Invoice workflow](https://console.invopop.com/redirect/workflows/new?template=empty-invoice) as the base. Then name the workflow with a descriptive label such as "AT cancel invoice".
The new workflow will need to perform these steps:
1. **Set state** - to `Processing`.
2. **Cancel SAF-T record** - No configuration required.
3. **Send document to AT** - No configuration required.
4. **Set state** to `Void`.
5. **Generate PDF (Original)** - Portuguese - A4 - Title badge: "Original".
6. **Generate PDF (Duplicate)** - Portuguese - A4 - Title badge: "Duplicado" - Flag as duplicate
Finally, in the Error Handling area, add the **Set state** action and select `Error`.
Add any additional steps you may need, and save the new workflow.
You can skip this step if you don't plan to issue delivery documents.
This workflow will issue a delivery document through the AT (Portugal).
Copy and paste into a new [Empty Delivery workflow](https://console.invopop.com/redirect/workflows/new?template=empty-delivery) code view.
```json Example AT issue delivery workflow theme={"system"}
{
"name": "AT issue delivery",
"description": "Issue a delivery document through AT and generate PDF",
"schema": "bill/delivery",
"steps": [
{
"id": "6f884d90-f2b9-11ef-acb2-cd64e858247e",
"name": "Set state",
"provider": "silo.state",
"config": {
"state": "processing"
}
},
{
"id": "76f194b0-f2b9-11ef-acb2-cd64e858247e",
"name": "Record document for SAF-T",
"provider": "at-pt.record"
},
{
"id": "59174840-c09a-11f0-b8a2-b531dbe0da3c",
"name": "Send document to AT",
"provider": "at-pt.send"
},
{
"id": "93795a50-f2b9-11ef-acb2-cd64e858247e",
"name": "Generate PDF",
"provider": "pdf",
"summary": "Portuguese · A4 · Original",
"config": {
"date_format": "%Y-%m-%d",
"hide_promo": true,
"label": "Original",
"layout": "A4",
"locale": "pt",
"logo_height": 40,
"watermark": ""
}
},
{
"id": "ce7c50c0-9d55-11f0-b3a4-87562f21f508",
"name": "Generate PDF",
"provider": "pdf",
"summary": "Portuguese · A4 · Duplicado",
"config": {
"date_format": "%Y-%m-%d",
"label": "Duplicado",
"layout": "A4",
"locale": "pt",
"logo_height": 40,
"watermark": "",
"duplicate": true
}
},
{
"id": "7a708240-f2b9-11ef-acb2-cd64e858247e",
"name": "Set state",
"provider": "silo.state",
"config": {
"state": "sent"
}
}
],
"rescue": [
{
"id": "805bdbf0-f2b9-11ef-acb2-cd64e858247e",
"name": "Set state",
"provider": "silo.state",
"config": {
"state": "error"
}
}
]
}
```
Before starting, review the [workflows guide](/guides/features/workflows) to understand the general setup process.
In [Console](https://console.invopop.com), create a new workflow and choose [Empty Delivery workflow](https://console.invopop.com/redirect/workflows/new?template=empty-delivery) as the base. Then name the workflow with a descriptive label such as "AT issue delivery".
The new workflow will need to perform these steps:
1. **Set state** - to `Processing`.
2. **Record document for SAF-T** - No configuration required.
3. **Send document to AT** - No configuration required.
4. **Generate PDF (Original)** - Portuguese - A4 - Title badge: "Original".
5. **Generate PDF (Duplicate)** - Portuguese - A4 - Title badge: "Duplicado" - Flag as duplicate.
6. **Generate PDF (Triplicate)** - Portuguese - A4 - Title badge: "Triplicado" - Flag as duplicate. Only required if you plan to issue Global Transport Guides (GT).
7. **Set state** to `Sent`.
Finally, in the Error Handling area, add the **Set state** action and select `Error`.
Add any additional steps you may need, and save the new workflow.
If you plan to issue Global Transport Guides (GT), Portuguese law requires three printed copies of the document to accompany the goods during transport. To produce the third copy, add another **Generate PDF** step alongside the Original and Duplicate ones, with the title badge set to "Triplicado" and the duplicate flag enabled.
You can skip this step if you don't plan to cancel delivery documents.
This workflow will cancel a delivery document through the AT (Portugal).
Copy and paste into a new [Empty Delivery workflow](https://console.invopop.com/redirect/workflows/new?template=empty-delivery) code view.
```json Example AT cancel delivery workflow theme={"system"}
{
"name": "AT cancel delivery",
"description": "Cancel a delivery document through AT and generate PDF",
"schema": "bill/delivery",
"steps": [
{
"id": "6f884d90-f2b9-11ef-acb2-cd64e858247e",
"name": "Set state",
"provider": "silo.state",
"config": {
"state": "processing"
}
},
{
"id": "cc0002a0-927f-11f0-8cd1-bd9f2c371090",
"name": "Cancel SAF-T record",
"provider": "at-pt.cancel"
},
{
"id": "59174840-c09a-11f0-b8a2-b531dbe0da3c",
"name": "Send document to AT",
"provider": "at-pt.send"
},
{
"id": "7a708240-f2b9-11ef-acb2-cd64e858247e",
"name": "Set state",
"provider": "silo.state",
"config": {
"state": "void"
}
},
{
"id": "93795a50-f2b9-11ef-acb2-cd64e858247e",
"name": "Generate PDF",
"provider": "pdf",
"summary": "Portuguese · A4 · Original",
"config": {
"date_format": "%Y-%m-%d",
"hide_promo": true,
"label": "Original",
"layout": "A4",
"locale": "pt",
"logo_height": 40,
"watermark": ""
}
},
{
"id": "ce7c50c0-9d55-11f0-b3a4-87562f21f508",
"name": "Generate PDF",
"provider": "pdf",
"summary": "Portuguese · A4 · Duplicado",
"config": {
"date_format": "%Y-%m-%d",
"label": "Duplicado",
"layout": "A4",
"locale": "pt",
"logo_height": 40,
"watermark": "",
"duplicate": true
}
}
],
"rescue": [
{
"id": "805bdbf0-f2b9-11ef-acb2-cd64e858247e",
"name": "Set state",
"provider": "silo.state",
"config": {
"state": "error"
}
}
]
}
```
Before starting, review the [workflows guide](/guides/features/workflows) to understand the general setup process.
In [Console](https://console.invopop.com), create a new workflow and choose [Empty Delivery workflow](https://console.invopop.com/redirect/workflows/new?template=empty-delivery) as the base. Then name the workflow with a descriptive label such as "AT cancel delivery".
The new workflow will need to perform these steps:
1. **Set state** - to `Processing`.
2. **Cancel SAF-T record** - No configuration required.
3. **Send document to AT** - No configuration required.
4. **Set state** to `Void`.
5. **Generate PDF (Original)** - Portuguese - A4 - Title badge: "Original".
6. **Generate PDF (Duplicate)** - Portuguese - A4 - Title badge: "Duplicado" - Flag as duplicate
Finally, in the Error Handling area, add the **Set state** action and select `Error`.
Add any additional steps you may need, and save the new workflow.
You can skip this step if you don't plan to issue payments.
This workflow will issue a payment through the AT (Portugal).
Copy and paste into a new [Empty Payment workflow](https://console.invopop.com/redirect/workflows/new?template=empty-payment) code view.
```json Example AT issue payment workflow theme={"system"}
{
"name": "AT issue payment",
"description": "Issue a payment through AT and generate PDF",
"schema": "bill/payment",
"steps": [
{
"id": "6f884d90-f2b9-11ef-acb2-cd64e858247e",
"name": "Set state",
"provider": "silo.state",
"config": {
"state": "processing"
}
},
{
"id": "76f194b0-f2b9-11ef-acb2-cd64e858247e",
"name": "Record document for SAF-T",
"provider": "at-pt.record"
},
{
"id": "93795a50-f2b9-11ef-acb2-cd64e858247e",
"name": "Generate PDF",
"provider": "pdf",
"summary": "Portuguese · A4 · Original",
"config": {
"date_format": "%Y-%m-%d",
"hide_promo": true,
"label": "Original",
"layout": "A4",
"locale": "pt",
"logo_height": 40,
"watermark": ""
}
},
{
"id": "ce7c50c0-9d55-11f0-b3a4-87562f21f508",
"name": "Generate PDF",
"provider": "pdf",
"summary": "Portuguese · A4 · Duplicado",
"config": {
"date_format": "%Y-%m-%d",
"label": "Duplicado",
"layout": "A4",
"locale": "pt",
"logo_height": 40,
"watermark": "",
"duplicate": true
}
},
{
"id": "7a708240-f2b9-11ef-acb2-cd64e858247e",
"name": "Set state",
"provider": "silo.state",
"config": {
"state": "sent"
}
}
],
"rescue": [
{
"id": "805bdbf0-f2b9-11ef-acb2-cd64e858247e",
"name": "Set state",
"provider": "silo.state",
"config": {
"state": "error"
}
}
]
}
```
Before starting, review the [workflows guide](/guides/features/workflows) to understand the general setup process.
In [Console](https://console.invopop.com), create a new workflow and choose [Empty Payment workflow](https://console.invopop.com/redirect/workflows/new?template=empty-payment) as the base. Then name the workflow with a descriptive label such as "AT issue payment".
The new workflow will need to perform these steps:
1. **Set state** - to `Processing`.
2. **Record document for SAF-T** - No configuration required.
3. **Generate PDF (Original)** - Portuguese - A4 - Title badge: "Original".
4. **Generate PDF (Duplicate)** - Portuguese - A4 - Title badge: "Duplicado" - Flag as duplicate
5. **Set state** to `Sent`.
Finally, in the Error Handling area, add the **Set state** action and select `Error`.
Add any additional steps you may need, and save the new workflow.
You can skip this step if you don't plan to cancel payments.
This workflow will cancel a payment through the AT (Portugal).
Copy and paste into a new [Empty Payment workflow](https://console.invopop.com/redirect/workflows/new?template=empty-payment) code view.
```json Example AT cancel payment workflow theme={"system"}
{
"name": "AT cancel payment",
"description": "Cancel a payment through AT and generate PDF",
"schema": "bill/payment",
"steps": [
{
"id": "6f884d90-f2b9-11ef-acb2-cd64e858247e",
"name": "Set state",
"provider": "silo.state",
"config": {
"state": "processing"
}
},
{
"id": "cc0002a0-927f-11f0-8cd1-bd9f2c371090",
"name": "Cancel SAF-T record",
"provider": "at-pt.cancel"
},
{
"id": "7a708240-f2b9-11ef-acb2-cd64e858247e",
"name": "Set state",
"provider": "silo.state",
"config": {
"state": "void"
}
},
{
"id": "93795a50-f2b9-11ef-acb2-cd64e858247e",
"name": "Generate PDF",
"provider": "pdf",
"summary": "Portuguese · A4 · Original",
"config": {
"date_format": "%Y-%m-%d",
"hide_promo": true,
"label": "Original",
"layout": "A4",
"locale": "pt",
"logo_height": 40,
"watermark": ""
}
},
{
"id": "ce7c50c0-9d55-11f0-b3a4-87562f21f508",
"name": "Generate PDF",
"provider": "pdf",
"summary": "Portuguese · A4 · Duplicado",
"config": {
"date_format": "%Y-%m-%d",
"label": "Duplicado",
"layout": "A4",
"locale": "pt",
"logo_height": 40,
"watermark": "",
"duplicate": true
}
}
],
"rescue": [
{
"id": "805bdbf0-f2b9-11ef-acb2-cd64e858247e",
"name": "Set state",
"provider": "silo.state",
"config": {
"state": "error"
}
}
]
}
```
Before starting, review the [workflows guide](/guides/features/workflows) to understand the general setup process.
In [Console](https://console.invopop.com), create a new workflow and choose [Empty Payment workflow](https://console.invopop.com/redirect/workflows/new?template=empty-payment) as the base. Then name the workflow with a descriptive label such as "AT cancel payment".
The new workflow will need to perform these steps:
1. **Set state** - to `Processing`.
2. **Cancel SAF-T record** - No configuration required.
3. **Set state** to `Void`.
4. **Generate PDF (Original)** - Portuguese - A4 - Title badge: "Original".
5. **Generate PDF (Duplicate)** - Portuguese - A4 - Title badge: "Duplicado" - Flag as duplicate
Finally, in the Error Handling area, add the **Set state** action and select `Error`.
Add any additional steps you may need, and save the new workflow.
## 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](/api-ref/silo/entries/create-an-entry-put), then [create a job](/api-ref/transform/jobs/create-a-job-put).
### Register a Supplier
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:
```json Portugal AT supplier example theme={"system"}
{
"$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](https://at-pt.invopop.com/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.
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](https://www.portaldasfinancas.gov.pt) 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.
* `WFA` – 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.
**White-label integration:** If you need to fully integrate this functionality into your own platform, the [AT Portugal API](/api-ref/apps/at-pt) 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](https://at-pt.invopop.com/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](#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](https://at-pt.invopop.com/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 document for SAF-T** 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.
#### Series type
Every series registered with the AT has a type that determines its purpose. You must choose one of three types when [registering a series](/api-ref/apps/at-pt/series-register), whether through the Supplier Portal or the API:
| Type | Code | Description |
| --------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Normal** | `N` | The standard type for series used in production. Use this type for all real documents with fiscal effect in live workspaces. |
| **Training**
*(Formação)* | `F` | For testing and training purposes only. Documents issued under a training series are fictitious and carry no fiscal effect. Use this type in sandbox workspaces when validating your integration before going live. |
| **Recovery**
*(Recuperação)* | `R` | A special type for registering documents that were issued manually on paper during a system outage. Portuguese law requires that when the invoicing system is unavailable, issuers continue on paper and then re-enter those documents once the system is restored. See [Recovering documents issued offline](#recovering-documents-issued-offline) for the full process. |
The series type is set at registration time and cannot be changed afterward. Make sure to choose the correct type for your use case.
### Send a document
The following examples show partial [GOBL](https://docs.gobl.org) documents you can copy and paste directly into the [Invopop Console](https://console.invopop.com) 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 in the first tab contains only the essential fields required to create the invoice, without totals or calculations,
* the [`pt-saft-v1`](https://docs.gobl.org/addons/pt-saft-v1) addon ensures the document will be validated and normalized using the SAF-T PT v1 rules built into the [GOBL](https://docs.gobl.org) 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](/guides/pt-at#series-management) for details),
* when running `gobl build`, or uploading the file, the system automatically calculates totals, assigns the [`pt-saft-invoice-type`](https://docs.gobl.org/addons/pt-saft-v1#invoice-type) extension to `FT` (Fatura), sets the [`pt-saft-payment-means`](https://docs.gobl.org/addons/pt-saft-v1#payment-means) extension to `CC` for card payment, and applies the [`pt-saft-tax-rate`](https://docs.gobl.org/addons/pt-saft-v1#tax-rate-code) 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`](https://docs.gobl.org/addons/pt-saft-v1#product-type) extension to be set to `S` (Serviço), and the [`pt-region`](https://docs.gobl.org/regimes/pt#region-code) extension is automatically set to `PT`.
```json AT B2B Invoice (minimal) theme={"system"}
{
"$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"
}
]
}
}
```
```json Built version theme={"system"}
{
"$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",
"value_date": "2024-12-23",
"currency": "EUR",
"tax": {
"ext": {
"pt-saft-invoice-type": "FT",
"pt-saft-source": "P"
}
},
"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": [
{
"i": 1,
"quantity": "20.0",
"item": {
"name": "Development services",
"price": "50.00",
"unit": "h",
"ext": {
"pt-saft-product-type": "S"
}
},
"sum": "1000.00",
"taxes": [
{
"cat": "VAT",
"key": "standard",
"rate": "general",
"percent": "23.0%",
"ext": {
"pt-region": "PT",
"pt-saft-tax-rate": "NOR"
}
}
],
"total": "1000.00"
}
],
"payment": {
"advances": [
{
"date": "2024-12-23",
"key": "card",
"description": "Advance payment",
"amount": "12.34",
"ext": {
"pt-saft-payment-means": "CC"
}
}
]
},
"totals": {
"sum": "1000.00",
"total": "1000.00",
"taxes": {
"categories": [
{
"code": "VAT",
"rates": [
{
"key": "standard",
"ext": {
"pt-region": "PT",
"pt-saft-tax-rate": "NOR"
},
"base": "1000.00",
"percent": "23.0%",
"amount": "230.00"
}
],
"amount": "230.00"
}
],
"sum": "230.00"
},
"tax": "230.00",
"total_with_tax": "1230.00",
"payable": "1230.00",
"advance": "12.34",
"due": "1217.66"
}
}
```
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`](https://docs.gobl.org/addons/pt-saft-v1) addon ensures the document will be validated and normalized using the SAF-T PT v1 rules built into the [GOBL](https://docs.gobl.org) 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](/guides/pt-at#series-management) for details),
* this is an `note` document type with the [`pt-saft-movement-type`](https://docs.gobl.org/addons/pt-saft-v1#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`](https://docs.gobl.org/addons/pt-saft-v1#tax-rate-code) 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,delivery
* the [`pt-region`](https://docs.gobl.org/regimes/pt#region-code) extension is automatically set to `PT`.
```json AT Delivery (minimal) theme={"system"}
{
"$schema": "https://gobl.org/draft-0/bill/delivery",
"$regime": "PT",
"$addons": [
"pt-saft-v1"
],
"type": "note",
"series": "GR SERIES-A",
"issue_date": "2026-04-01",
"currency": "EUR",
"despatch_date": "2026-04-02",
"receive_date": "2026-04-03",
"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"
}
]
},
"despatcher": {
"name": "Innovatech Logistics",
"addresses": [
{
"street": "Rua da Indústria 45",
"locality": "Porto",
"code": "4050-300",
"country": "PT"
}
]
},
"receiver": {
"name": "Gusto Armazém",
"addresses": [
{
"street": "Zona Industrial, Lote 23",
"locality": "Lisboa",
"code": "1300-300",
"country": "PT"
}
]
},
"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"
}
]
}
```
```json Built version theme={"system"}
{
"$schema": "https://gobl.org/draft-0/bill/delivery",
"$regime": "PT",
"$addons": [
"pt-saft-v1"
],
"type": "note",
"series": "GR SERIES-A",
"issue_date": "2026-04-01",
"currency": "EUR",
"despatch_date": "2026-04-02",
"receive_date": "2026-04-03",
"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"
}
},
"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"
}
]
},
"despatcher": {
"name": "Innovatech Logistics",
"addresses": [
{
"street": "Rua da Indústria 45",
"locality": "Porto",
"code": "4050-300",
"country": "PT"
}
]
},
"receiver": {
"name": "Gusto Armazém",
"addresses": [
{
"street": "Zona Industrial, Lote 23",
"locality": "Lisboa",
"code": "1300-300",
"country": "PT"
}
]
},
"lines": [
{
"i": 1,
"quantity": "10",
"item": {
"name": "Product A",
"price": "5.00",
"unit": "unit",
"ext": {
"pt-saft-product-type": "P"
}
},
"sum": "50.00",
"taxes": [
{
"cat": "VAT",
"key": "standard",
"rate": "general",
"percent": "23.0%",
"ext": {
"pt-region": "PT",
"pt-saft-tax-rate": "NOR"
}
}
],
"total": "50.00"
}
],
"totals": {
"sum": "50.00",
"total": "50.00",
"taxes": {
"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"
},
"tax": "11.50",
"total_with_tax": "61.50",
"payable": "61.50"
},
"notes": [
{
"text": "Delivery note for products"
}
]
}
```
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`](https://docs.gobl.org/addons/pt-saft-v1) addon uses to automatically set the [`pt-saft-movement-type`](https://docs.gobl.org/addons/pt-saft-v1#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.
```json AT Return guide (minimal) theme={"system"}
{
"$schema": "https://gobl.org/draft-0/bill/delivery",
"$regime": "PT",
"$addons": [
"pt-saft-v1"
],
"$tags": ["return"],
"type": "note",
"series": "GD SERIES-A",
"issue_date": "2026-04-03",
"currency": "EUR",
"despatch_date": "2026-04-03",
"receive_date": "2026-04-03",
"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"
}
]
},
"despatcher": {
"name": "Gusto Armazém",
"addresses": [
{
"street": "Zona Industrial, Lote 23",
"locality": "Lisboa",
"code": "1300-300",
"country": "PT"
}
]
},
"receiver": {
"name": "Innovatech Logistics",
"addresses": [
{
"street": "Rua da Indústria 45",
"locality": "Porto",
"code": "4050-300",
"country": "PT"
}
]
},
"lines": [
{
"quantity": "3",
"item": {
"name": "Product A",
"price": "5.00",
"unit": "unit",
"ext": {
"pt-saft-product-type": "P"
}
},
"taxes": [
{
"cat": "VAT",
"rate": "standard"
}
]
}
],
"notes": [
{
"text": "Goods returned by the customer."
}
]
}
```
```json Built version theme={"system"}
{
"$schema": "https://gobl.org/draft-0/bill/delivery",
"$regime": "PT",
"$addons": [
"pt-saft-v1"
],
"$tags": [
"return"
],
"type": "note",
"series": "GD SERIES-A",
"issue_date": "2026-04-03",
"currency": "EUR",
"despatch_date": "2026-04-03",
"receive_date": "2026-04-03",
"tax": {
"ext": {
"pt-saft-movement-type": "GD"
}
},
"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"
}
]
},
"despatcher": {
"name": "Gusto Armazém",
"addresses": [
{
"street": "Zona Industrial, Lote 23",
"locality": "Lisboa",
"code": "1300-300",
"country": "PT"
}
]
},
"receiver": {
"name": "Innovatech Logistics",
"addresses": [
{
"street": "Rua da Indústria 45",
"locality": "Porto",
"code": "4050-300",
"country": "PT"
}
]
},
"lines": [
{
"i": 1,
"quantity": "3",
"item": {
"name": "Product A",
"price": "5.00",
"unit": "unit",
"ext": {
"pt-saft-product-type": "P"
}
},
"sum": "15.00",
"taxes": [
{
"cat": "VAT",
"key": "standard",
"rate": "general",
"percent": "23.0%",
"ext": {
"pt-region": "PT",
"pt-saft-tax-rate": "NOR"
}
}
],
"total": "15.00"
}
],
"totals": {
"sum": "15.00",
"total": "15.00",
"taxes": {
"categories": [
{
"code": "VAT",
"rates": [
{
"key": "standard",
"ext": {
"pt-region": "PT",
"pt-saft-tax-rate": "NOR"
},
"base": "15.00",
"percent": "23.0%",
"amount": "3.45"
}
],
"amount": "3.45"
}
],
"sum": "3.45"
},
"tax": "3.45",
"total_with_tax": "18.45",
"payable": "18.45"
},
"notes": [
{
"text": "Goods returned by the customer."
}
]
}
```
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`](https://docs.gobl.org/addons/pt-saft-v1) addon normalizes to the [`pt-saft-movement-type`](https://docs.gobl.org/addons/pt-saft-v1#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*.
```json AT Global waybill (minimal) theme={"system"}
{
"$schema": "https://gobl.org/draft-0/bill/delivery",
"$regime": "PT",
"$addons": [
"pt-saft-v1"
],
"type": "waybill",
"series": "GT SERIES-A",
"issue_date": "2026-04-01",
"currency": "EUR",
"despatch_date": "2026-04-02",
"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"
}
},
"despatcher": {
"name": "Innovatech Logistics",
"addresses": [
{
"street": "Rua da Indústria 45",
"locality": "Porto",
"code": "4050-300",
"country": "PT"
}
]
},
"lines": [
{
"quantity": "100",
"item": {
"name": "Product A",
"price": "5.00",
"unit": "unit",
"ext": {
"pt-saft-product-type": "P"
}
},
"taxes": [
{
"cat": "VAT",
"rate": "standard"
}
]
}
],
"notes": [
{
"text": "Global waybill for multi-stop delivery"
}
]
}
```
```json Built version theme={"system"}
{
"$schema": "https://gobl.org/draft-0/bill/delivery",
"$regime": "PT",
"$addons": [
"pt-saft-v1"
],
"type": "waybill",
"series": "GT SERIES-A",
"issue_date": "2026-04-01",
"currency": "EUR",
"despatch_date": "2026-04-02",
"tax": {
"ext": {
"pt-saft-movement-type": "GT"
}
},
"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"
}
},
"despatcher": {
"name": "Innovatech Logistics",
"addresses": [
{
"street": "Rua da Indústria 45",
"locality": "Porto",
"code": "4050-300",
"country": "PT"
}
]
},
"lines": [
{
"i": 1,
"quantity": "100",
"item": {
"name": "Product A",
"price": "5.00",
"unit": "unit",
"ext": {
"pt-saft-product-type": "P"
}
},
"sum": "500.00",
"taxes": [
{
"cat": "VAT",
"key": "standard",
"rate": "general",
"percent": "23.0%",
"ext": {
"pt-region": "PT",
"pt-saft-tax-rate": "NOR"
}
}
],
"total": "500.00"
}
],
"totals": {
"sum": "500.00",
"total": "500.00",
"taxes": {
"categories": [
{
"code": "VAT",
"rates": [
{
"key": "standard",
"ext": {
"pt-region": "PT",
"pt-saft-tax-rate": "NOR"
},
"base": "500.00",
"percent": "23.0%",
"amount": "115.00"
}
],
"amount": "115.00"
}
],
"sum": "115.00"
},
"tax": "115.00",
"total_with_tax": "615.00",
"payable": "615.00"
},
"notes": [
{
"text": "Global waybill for multi-stop delivery"
}
]
}
```
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`.
```json AT Delivery note from global waybill (minimal) theme={"system"}
{
"$schema": "https://gobl.org/draft-0/bill/delivery",
"$regime": "PT",
"$addons": [
"pt-saft-v1"
],
"type": "note",
"series": "GR SERIES-A",
"issue_date": "2026-04-02",
"currency": "EUR",
"despatch_date": "2026-04-02",
"receive_date": "2026-04-02",
"preceding": [
{
"series": "GT SERIES-A",
"code": "1",
"issue_date": "2026-04-01"
}
],
"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"
}
]
},
"despatcher": {
"name": "Innovatech Logistics",
"addresses": [
{
"street": "Rua da Indústria 45",
"locality": "Porto",
"code": "4050-300",
"country": "PT"
}
]
},
"receiver": {
"name": "Gusto Armazém",
"addresses": [
{
"street": "Zona Industrial, Lote 23",
"locality": "Lisboa",
"code": "1300-300",
"country": "PT"
}
]
},
"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": "Stop delivery from global waybill GT SERIES-A/1"
}
]
}
```
```json Built version theme={"system"}
{
"$schema": "https://gobl.org/draft-0/bill/delivery",
"$regime": "PT",
"$addons": [
"pt-saft-v1"
],
"type": "note",
"series": "GR SERIES-A",
"issue_date": "2026-04-02",
"currency": "EUR",
"preceding": [
{
"issue_date": "2026-04-01",
"series": "GT SERIES-A",
"code": "1"
}
],
"despatch_date": "2026-04-02",
"receive_date": "2026-04-02",
"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"
}
},
"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"
}
]
},
"despatcher": {
"name": "Innovatech Logistics",
"addresses": [
{
"street": "Rua da Indústria 45",
"locality": "Porto",
"code": "4050-300",
"country": "PT"
}
]
},
"receiver": {
"name": "Gusto Armazém",
"addresses": [
{
"street": "Zona Industrial, Lote 23",
"locality": "Lisboa",
"code": "1300-300",
"country": "PT"
}
]
},
"lines": [
{
"i": 1,
"quantity": "10",
"item": {
"name": "Product A",
"price": "5.00",
"unit": "unit",
"ext": {
"pt-saft-product-type": "P"
}
},
"sum": "50.00",
"taxes": [
{
"cat": "VAT",
"key": "standard",
"rate": "general",
"percent": "23.0%",
"ext": {
"pt-region": "PT",
"pt-saft-tax-rate": "NOR"
}
}
],
"total": "50.00"
}
],
"totals": {
"sum": "50.00",
"total": "50.00",
"taxes": {
"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"
},
"tax": "11.50",
"total_with_tax": "61.50",
"payable": "61.50"
},
"notes": [
{
"text": "Stop delivery from global waybill GT SERIES-A/1"
}
]
}
```
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`](https://docs.gobl.org/addons/pt-saft-v1#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.
```json AT Return from global waybill (minimal) theme={"system"}
{
"$schema": "https://gobl.org/draft-0/bill/delivery",
"$regime": "PT",
"$addons": [
"pt-saft-v1"
],
"$tags": ["return"],
"type": "note",
"series": "GD SERIES-A",
"issue_date": "2026-04-03",
"currency": "EUR",
"preceding": [
{
"issue_date": "2026-04-01",
"series": "GT SERIES-A",
"code": "1"
}
],
"despatch_date": "2026-04-03",
"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"
}
},
"despatcher": {
"name": "Innovatech Logistics",
"addresses": [
{
"street": "Rua da Indústria 45",
"locality": "Porto",
"code": "4050-300",
"country": "PT"
}
]
},
"receiver": {
"name": "Innovatech Depot",
"addresses": [
{
"street": "Rua da Indústria 45",
"locality": "Porto",
"code": "4050-300",
"country": "PT"
}
]
},
"lines": [
{
"quantity": "2",
"item": {
"name": "Product A",
"price": "5.00",
"unit": "unit",
"ext": {
"pt-saft-product-type": "P"
}
},
"taxes": [
{
"cat": "VAT",
"rate": "standard"
}
]
}
],
"notes": [
{
"text": "Surplus from global waybill GT SERIES-A/1 returned to depot."
}
]
}
```
```json Built version theme={"system"}
{
"$schema": "https://gobl.org/draft-0/bill/delivery",
"$regime": "PT",
"$addons": [
"pt-saft-v1"
],
"$tags": [
"return"
],
"type": "note",
"series": "GD SERIES-A",
"issue_date": "2026-04-03",
"currency": "EUR",
"preceding": [
{
"issue_date": "2026-04-01",
"series": "GT SERIES-A",
"code": "1"
}
],
"despatch_date": "2026-04-03",
"tax": {
"ext": {
"pt-saft-movement-type": "GD"
}
},
"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"
}
},
"despatcher": {
"name": "Innovatech Logistics",
"addresses": [
{
"street": "Rua da Indústria 45",
"locality": "Porto",
"code": "4050-300",
"country": "PT"
}
]
},
"receiver": {
"name": "Innovatech Depot",
"addresses": [
{
"street": "Rua da Indústria 45",
"locality": "Porto",
"code": "4050-300",
"country": "PT"
}
]
},
"lines": [
{
"i": 1,
"quantity": "2",
"item": {
"name": "Product A",
"price": "5.00",
"unit": "unit",
"ext": {
"pt-saft-product-type": "P"
}
},
"sum": "10.00",
"taxes": [
{
"cat": "VAT",
"key": "standard",
"rate": "general",
"percent": "23.0%",
"ext": {
"pt-region": "PT",
"pt-saft-tax-rate": "NOR"
}
}
],
"total": "10.00"
}
],
"totals": {
"sum": "10.00",
"total": "10.00",
"taxes": {
"categories": [
{
"code": "VAT",
"rates": [
{
"key": "standard",
"ext": {
"pt-region": "PT",
"pt-saft-tax-rate": "NOR"
},
"base": "10.00",
"percent": "23.0%",
"amount": "2.30"
}
],
"amount": "2.30"
}
],
"sum": "2.30"
},
"tax": "2.30",
"total_with_tax": "12.30",
"payable": "12.30"
},
"notes": [
{
"text": "Surplus from global waybill GT SERIES-A/1 returned to depot."
}
]
}
```
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`](https://docs.gobl.org/addons/pt-saft-v1) addon ensures the document will be validated and normalized using the SAF-T PT v1 rules built into the [GOBL](https://docs.gobl.org) 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](/guides/pt-at#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`](https://docs.gobl.org/addons/pt-saft-v1#payment-means) extension auto-assigned (`NU` for cash, `CC` for card),
* when running `gobl build`, the system automatically assigns the [`pt-saft-payment-type`](https://docs.gobl.org/addons/pt-saft-v1#payment-type) extension to `RG` and the [`pt-saft-source`](https://docs.gobl.org/addons/pt-saft-v1#document-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 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.
```json AT Payment (minimal) theme={"system"}
{
"$schema": "https://gobl.org/draft-0/bill/payment",
"$regime": "PT",
"$addons": [
"pt-saft-v1"
],
"type": "receipt",
"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"
}
}
],
"methods": [
{
"key": "cash",
"description": "Cash portion",
"amount": "30.00"
},
{
"key": "card",
"description": "Card portion",
"amount": "31.50"
}
]
}
```
```json Built version theme={"system"}
{
"$schema": "https://gobl.org/draft-0/bill/payment",
"$regime": "PT",
"$addons": [
"pt-saft-v1"
],
"type": "receipt",
"series": "RG SERIES-A",
"issue_date": "2024-12-23",
"currency": "EUR",
"ext": {
"pt-saft-payment-type": "RG",
"pt-saft-source": "P"
},
"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": [
{
"i": 1,
"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"
}
}
],
"methods": [
{
"key": "cash",
"description": "Cash portion",
"amount": "30.00",
"ext": {
"pt-saft-payment-means": "NU"
}
},
{
"key": "card",
"description": "Card portion",
"amount": "31.50",
"ext": {
"pt-saft-payment-means": "CC"
}
}
],
"total": "61.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.
### 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](https://info.portaldasfinancas.gov.pt/pt/informacao_fiscal/legislacao/diplomas_legislativos/Documents/Despacho_n%C2%BA_8632_2014_03_07.pdf), 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](/api-ref/apps/at-pt/series-register). 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`](https://docs.gobl.org/addons/pt-saft-v1#document-source) extension must be set to `M` (manual).
* The [`pt-saft-source-ref`](https://docs.gobl.org/addons/pt-saft-v1#source-document-reference) 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.
```json theme={"system"}
{
"$schema": "https://gobl.org/draft-0/bill/invoice",
"$regime": "PT",
"$addons": ["pt-saft-v1"],
"$tags": ["bypass"],
"series": "FT RECOVERY",
"issue_date": "2026-05-28",
"tax": {
"ext": {
"pt-saft-source": "M",
"pt-saft-source-ref": "FTM ABC123/00042"
}
}
}
```
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 "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 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](https://at-pt.invopop.com/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](https://faturas.portaldasfinancas.gov.pt/faturas/comerciante/enviar-saft.action) or via [command line](https://faturas.portaldasfinancas.gov.pt/envioBatchInfoNovo.action).
## 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](/apps/at-portugal) 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 AT does not accept them via the real-time webservice. 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](https://docs.gobl.org/regimes/pt) for tax categories, NIF rules, and AT-specific extensions. The [`pt-saft-v1`](https://docs.gobl.org/addons/pt-saft-v1) addon documents fields required by the SAF-T schema.
More available in our [Portugal FAQ](/faq/portugal) section
***
| | |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Compliance | [Invoicing compliance in Portugal](/compliance/portugal)
[Compliance timeline](/timelines/portugal) |
| Apps | [AT Portugal](/apps/at-portugal) |
| Guides | [AT Portugal Guide](/guides/pt-at) |
| FAQ | [Portugal FAQ](/faq/portugal) |
| GOBL | [Portugal Tax Regime](https://docs.gobl.org/regimes/pt)
[Portugal SAF-T Addon ](https://docs.gobl.org/addons/pt-saft-v1) |
Ask and answer questions about Portugal's regulation →