> ## Documentation Index
> Fetch the complete documentation index at: https://invopop-singapore.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# AT Guide
> Issue documents in Portugal using Invopop's certified implementation.
We are currently in the process of certifying our direct integration with the Portuguese Tax Authority (AT). As a result, the AT implementation —described in this guide— is not yet available for use.
In the meantime, if you need to issue documents in Portugal, you can use our fully functional integration via [InvoiceXpress](/guides/countries/pt-invoicexpress).
## 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](https://console.invopop.com).
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 with states theme={"system"}
{
"name": "AT supplier post-registration",
"description": "Workflow to set suppliers 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"
}
]
}
```
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 worfkow 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 app discovery list.
3. Click **Connect** to activate.
Click the **Configure** button on the app, and choose the "Post-registration workflow" we created in the previous step.
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 with states theme={"system"}
{
"name": "AT register supplier",
"description": "Register a supplier in Portugal",
"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 AT issuer (Portugal)",
"provider": "at-pt.register"
}
]
}
```
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 the Envelope**
* **Register AT Issuer (Portugal)**
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.
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 with states theme={"system"}
{
"name": "Issue AT invoice",
"description": "Issue an invoice in Portugal and generate PDF",
"schema": "bill/invoice",
"steps": [
{
"id": "6f884d90-f2b9-11ef-acb2-cd64e858247e",
"name": "Set State",
"provider": "silo.state",
"summary": "Set state to `processing`{.state .processing}",
"config": {
"state": "processing"
}
},
{
"id": "78055c60-f2be-11ef-b357-abb0f65e5f45",
"name": "Add Sequential Code",
"provider": "sequence.enumerate",
"summary": "Dynamic · AT documents · 1",
"config": {
"name": "AT documents",
"padding": 1,
"start": 1
}
},
{
"id": "fc75e4f0-8721-11ef-a962-73e3f2037a52",
"name": "Sign Envelope",
"provider": "silo.close"
},
{
"id": "750b2170-f2b9-11ef-acb2-cd64e858247e",
"name": "Seal for the AT (Portugal)",
"provider": "at-pt.seal"
},
{
"id": "76f194b0-f2b9-11ef-acb2-cd64e858247e",
"name": "Record for SAF-T reporting (Portugal)",
"provider": "at-pt.record"
},
{
"id": "93795a50-f2b9-11ef-acb2-cd64e858247e",
"name": "Generate PDF",
"provider": "pdf",
"summary": "Portuguese - A4",
"config": {
"date_format": "%Y-%m-%d",
"layout": "A4",
"locale": "pt",
"logo_height": 40
}
},
{
"id": "7a708240-f2b9-11ef-acb2-cd64e858247e",
"name": "Set State",
"provider": "silo.state",
"summary": "Set state to `sent`{.state .sent}",
"next": [
{
"status": "NA",
"stop": true
}
],
"config": {
"state": "sent"
}
}
],
"rescue": [
{
"id": "805bdbf0-f2b9-11ef-acb2-cd64e858247e",
"name": "Set State",
"provider": "silo.state",
"summary": "Set state to `error`{.state .error}",
"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:
* **Set State** - to "processing".
* **Add Sequential Code** - with dynamic sequences, and name like "AT Documents".
* **Seal for the AT (Portugal)**.
* **Record for SAF-T reporting (Portugal)**.
* **Generate PDF** - configured for your environment.
* **Set State** - to "sent".
Optionally, if you want to submit each document individually to the AT in real-time, you can add a "Send to the AT (Portugal)" step right after recording the document for SAF-T.
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 **Contacts** 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"
},
"emails": [
{
"addr": "maria@example.com"
}
]
}
```
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.
* `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.
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.
### Send an invoice
The following examples show partial GOBL 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 "Issue AT document" workflow created during setup.
GOBL Invoices reported to the AT require the following properties to perform the correct normalization and validation steps. Invopop will try to assign these automatically, but we recommend defining them explicitly before uploading:
* `$region` to be set to [`PT`](https://docs.gobl.org/regimes/pt)
* `$addons` to include [`pt-saft-v1`](https://docs.gobl.org/addons/pt-saft-v1)
In this example, we're issuing a simple invoice from a Portuguese supplier to another Portuguese business.
Notice:
* we've added the `pt-saft-v1` addon; this 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,
* this is a `standard` invoice and the advance payments don't cover the total amount of the invoice; so, GOBL will automatically assign the `pt-saft-invoice-type` extension to `FT` (Fatura),
* the `card` payment method will cause the addon to set the `pt-saft-payment-means` extension to `CC` (Cartão crédito),
* the `h` item unit will cause the `pt-saft-product-type` extension to be set to `S` (Serviço),
* the `standard` VAT rate will cause the `pt-saft-tax-rate` extension to be set to `NOR` (Normal),
* the `pt-region` extension will automatically be set to the default value of `PT`, and
* there are no totals or calculations; all these will be made automatically when uploading.
```json AT B2B Invoice theme={"system"}
{
"$schema": "https://gobl.org/draft-0/bill/invoice",
"$regime": "PT",
"$addons": [
"pt-saft-v1"
],
"uuid": "0193f36f-9fda-7000-9aff-4f4e28043a66",
"type": "standard",
"series": "FT 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"
}
]
},
"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"
},
"taxes": [
{
"cat": "VAT",
"rate": "standard"
}
]
}
],
"payment": {
"advances": [
{
"date": "2024-12-23",
"key": "card",
"description": "Advance payment",
"amount": "12.34"
}
]
}
}
```
### Generate a SAF-T report
Once documents have been issued, Suppliers can generate SAF-T PT reports via the Supplier Portal:
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**