Portugal · InvoiceXpress Guide

🇵🇹 Issue invoices in Portugal using the InvoiceXpress provider.

Introduction

Invopop partners with the local invoicing provider InvoiceXpress to issue invoices, invoice-receipts, and credit notes in Portugal and allow users to submit their tax reports (SAF-T) to the Portuguese tax authority (AT).

This guide explains how to integrate with InvoiceXpress, a Portuguese invoicing provider that enables you to:

• Issue compliant invoices, invoice-receipts, and credit notes in Portugal.
• Submit tax reports (SAF-T) to the Portuguese tax authority (AT).
• Enable real-time tax reporting.

For technical details and examples of Portuguese GOBL documents, see the GOBL Portugal Tax Regime documentation.

Prerequisites

To issue invoices through InvoiceXpress, you’ll need the following information:

• Supplier Details, including:

  • legal business name,
  • tax ID (Número de Identificação Fiscal),
  • complete business address,
  • contact email address.

• Invoice details, including:

  • line item descriptions,
  • quantities and unit prices,
  • applicable Portuguese VAT rates.

Setup

The integration requires three main components:

1. InvoiceXpress app connection
2. Supplier registration workflow
3. Invoice processing workflow

All of the following steps must be carried out from the Invopop Console.

1. Connect InvoiceXpress App

   1. Navigate to Configuration → Apps.
   2. Find InvoiceXpress 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.

2. Configure the supplier registration workflow

   Template

   Register Supplier workflow

   Issues a registration request for a supplier to complete.

   Select a workspace to use this template

   Register Supplier workflow

   Issues a registration request for a supplier to complete.

   Select a workspace to use this template

   Copy and paste into a new Empty Party workflow code view.

   {
     "name": "Register in InvoiceXpress",
     "description": " ",
     "steps": [
       {
         "id": "e78ab920-b8be-11ef-9825-f56714a03659",
         "name": "Sign Envelope",
         "provider": "silo.close"
       },
       {
         "id": "01d3e8a0-499e-11ef-b4fe-47a6daefa429",
         "name": "Set State",
         "config": {
           "state": "processing"
         },
         "summary": "Set state to `processing`{.state .processing}",
         "provider": "silo.state"
       },
       {
         "id": "dbac1680-b8be-11ef-9825-f56714a03659",
         "name": "Register InvoiceXpress issuer",
         "provider": "invoicexpress.register"
       },
       {
         "id": "0eb04c30-499e-11ef-b4fe-47a6daefa429",
         "name": "Set State",
         "config": {
           "state": "registered"
         },
         "summary": "Set state to `registered`{.state .registered}",
         "provider": "silo.state"
       }
     ],
     "rescue": [
       {
         "id": "12ad6a70-499e-11ef-b4fe-47a6daefa429",
         "name": "Set State",
         "config": {
           "state": "error"
         },
         "summary": "Set state to `error`{.state .error}",
         "provider": "silo.state"
       }
     ]
   }
   

   Before starting, review the workflows guide to understand the general setup process.

   In Console, create a new workflow and choose Empty Party workflow as the base. Then name the workflow with a descriptive label such as “InvoiceXpress Register Supplier”.

   The new workflow will need to perform three steps:

   • Sign the Envelope - Validates the document
   • Register InvoiceXpress issuer - Creates supplier account
   • Set State - Marks progress as processing

   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.

3. Prepare Invoice Workflow

   Template

   Issue Invoice through InvoiceXpress

   This workflow will issue an invoice through InvoiceXpress.

   Select a workspace to use this template

   Issue Invoice through InvoiceXpress

   This workflow will issue an invoice through InvoiceXpress.

   Select a workspace to use this template

   Copy and paste into a new Empty Invoice workflow code view.

   {
       "name": "Send invoice to InvoiceXpress",
       "description": null,
       "steps": [
           {
               "id": "61b16e10-b8c9-11ef-b752-d31a7493e92d",
               "name": "Send to InvoiceXpress",
               "provider": "invoicexpress",
               "config": {
                   "skip_pdf": true
               }
           },
           {
               "id": "2b65e8e0-2f21-11ef-803c-8d182b3d70cd",
               "name": "Generate PDF",
               "config": {
                   "logo_height": 40,
                   "locale": "pt",
                   "date_format": "%Y-%m-%d"
               },
               "summary": "Portuguese",
               "provider": "pdf"
           },
           {
               "id": "6a8f6740-49a1-11ef-8c8c-7bca04ed2465",
               "name": "Set State",
               "config": {
                   "state": "sent"
               },
               "summary": "Set state to `sent`{.state .sent}",
               "provider": "silo.state"
           }
       ],
       "rescue": [
           {
               "id": "6e7ea2d0-49a1-11ef-8c8c-7bca04ed2465",
               "name": "Set State",
               "config": {
                   "state": "error"
               },
               "summary": "Set state to `error`{.state .error}",
               "provider": "silo.state"
           }
       ]
   }
   

   Before starting, review the workflows guide to understand the general setup process.

   In Console, create a new workflow and choose Empty Invoice workflow as the base. Then name the workflow with a descriptive label such as “Send invoice to InvoiceXpress”.

   The new workflow will need to perform these steps:

   • Send to InvoiceXpress - Transmits invoice data
   • Generate PDF - Creates document (configure for your environment)
   • Set State - Updates status 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.

Running

Sandbox Environment

InvoiceXpress provides a way to configure their accounts to use the AT’s sandbox environment so that you can test the issuance of invoices and credit notes end-to-end without fiscal or legal consequences. If you wish to use this environment, please contact us via Slack or [e-mail] and we will walk you through the setup process.

Supplier Onboarding

InvoiceXpress supports multiple suppliers under one integration. Each supplier receives their own account for document issuance and tax reporting.

Follow these steps to onboard a supplier:

1. Submit Supplier Information

   Send a GOBL Party document to your supplier registration workflow. The system will automatically:

   • Create an InvoiceXpress account
   • Send login credentials to the supplier’s email (first email in the emails list)

   Example GOBL Party document:

   Example supplier

   InvoiceXpress supplier example

     {
       "$schema": "https://gobl.org/draft-0/org/party",
       "uuid": "9de7584f-ea5c-42a7-b159-5e4c6a280a5c",
       "tax_id": {
         "country": "PT",
         "code": "545259045"
       },
       "name": "Hotelzinho",
       "emails": [
         {
           "addr": "[e-mail]"
         }
       ],
       "addresses": [
         {
           "street": "Rua do Hotelzinho",
           "code": "1000-000",
           "locality": "Lisboa"
         }
       ]
     }
   

2. Configure InvoiceXpress account

   The user invited to the new account will now have to log in to InvoiceXpress and complete the account’s configuration.

   An account will be ready to issue invoices once a default sequence is registered in the AT. This guide from InvoiceXpress’ documentation explains how to do it:

   • Sequence Registration Guide (English)
   • Guia de Registro de Séries (Portuguese)

   Important Notes:

   • You’ll find a pre-created sequence in the account pending to be registered. You can register and use that one, or create a different one, as you prefer.
   • In any case, you must ensure the sequence you want to use is the default one in the account. Currently, only the default series can be used to issue documents.

Send an invoice

Once configured, you can begin issuing documents:

1. Create GOBL Invoice documents following PT regime specifications
2. Send to your invoice processing workflow
3. Ensure the supplier UUID and Tax ID match the registered supplier details

Additional Features

Suppliers can:

• Export SAF-T reports through InvoiceXpress UI
• Configure real-time tax reporting using this guide: Portal das Finanças Integration Guide

Troubleshooting

Error: “An account for the provided tax ID code and name already exists…”

When you run the supplier registration workflow for a new supplier, you may get the following KO error:

An account for the provided tax ID code and name already exists under a different supplier UUID. The same tax code ID can be used with multiple suppliers as long as they have different names.

What does this mean?

InvoiceXpress allows you to register the same tax ID (Número de Identificação Fiscal) for multiple suppliers. This is useful if, for example, a single invoice issuer wants to segregate invoices by branch or location. In these cases, you can create multiple suppliers with the same tax ID but different names.

However, there is a limitation in InvoiceXpress: you must provide a unique name for each supplier when registering a new account with the same tax ID. If InvoiceXpress detects that both the tax ID and the name match an existing account, it assumes you want to use the existing account instead of creating a new one. To prevent confusion, our system checks for this scenario and displays the error above if it occurs.

How to resolve this issue:

• Make sure the name you provide for the new supplier is different from any existing supplier with the same tax ID in InvoiceXpress.
• The supplier UUID must also be unique for each supplier you register.