How to Create an Invoice Series in InvoiceXpress

InvoiceXpress is the certified package most used by Portuguese online shops, partly because its API is the easiest to automate. But before any automation issues its first invoice, there has to be a series filed with the tax authority with an ATCUD assigned.

This guide covers creating the series in InvoiceXpress, filing it, and confirming it is ready to issue. At the end is the trap that breaks more automations than anything else: in InvoiceXpress a series is not a sequence, it is a family of sequences.

Before you start

You need two things:

• Administrator access to the InvoiceXpress account. Only an administrator sees the series tab.
• An AT sub-user with the Comunicação e Gestão de Séries por webservice (WSE) operation. If you have not created one, start with ATCUD: creating the user at the tax authority.

If the concept of a series is not yet settled, read Invoice series: what they are and how to file them first.

Step 1: open series management

1. Sign in to your account at https://<your-account>.app.invoicexpress.com.
2. Top right menu (the account name) → Definições.
3. The Séries de Faturação tab.

The list shows the existing series, their filing status with the tax authority, and which one is marked as the default. A new account usually ships with an automatic series for the current year.

The account address is <account>.app.invoicexpress.com. The older subdomain without .app still answers on some screens but not all. If a link errors, add the .app.

Step 2: create the series

Click Nova Série and fill in:

| Field | What to put | Example | |---|---|---| | Series name | Capitals and digits, no spaces, no accents | 2026A | | Starting number | 1 for a new series. Migrating from other software, the number after the last one issued | 1 | | Default | Tick it if this is the series new documents should use | ✓ |

Unlike Moloni, you do not choose the document type here. In InvoiceXpress the series serves every type (invoice, invoice-receipt, simplified invoice, credit note, debit note, receipt) and the system keeps separate numbering per type inside it. That is why you will see the same name 2026A on documents with different sequences.

The name has to match exactly the identifier you file with the tax authority. One letter off and the SAF-T file is rejected months later, when it is expensive to fix.

Step 3: file the series with the tax authority

Route A: by webservice, from InvoiceXpress (recommended)

1. In Definições → Comunicação AT (some accounts call it Configurações AT or Webservice AT), enter the AT sub-user credentials in NIF/N form and its password. These are the same credentials as the sub-user you created on the Portal das Finanças: the webservice is authorised when that user is created, there is no separate key to request.
2. Go back to Definições → Séries de Faturação, open the series and click Comunicar à AT.
3. Within seconds the tax authority returns the 8-character validation code, which is stored on the series. The status becomes Comunicada.

Route B: by hand on the Portal das Finanças

1. Portal das Finanças → Todos os Serviços → Faturas e Outros Documentos Fiscais → Comunicar Séries Documentais → Registar Série.
2. Fill in, once per document type you will issue in that series (FT, FR, FS, NC, ND and so on):
   • Document type.
   • Series identifier: the exact name (2026A).
   • Starting sequence number: 1.
   • Processing method: Programa informático de faturação.
   • Software certification number: 192, InvoiceXpress's number with the tax authority. Always confirm it in the footer of an issued document, which prints Processado por programa certificado n.º 192/AT.
3. Submit and keep each validation code returned.
4. Back in InvoiceXpress, edit the series and paste the code into the ATCUD field.

Route A avoids all of this: InvoiceXpress files each document type for you as it becomes needed.

Step 4: confirm the series issues certified documents

Issue a test document, preferably an invoice-receipt, which is the type automations use most, and confirm that:

• The identifier reads FR 2026A/1.
• The PDF carries a QR Code.
• It carries the ATCUD: <code>-<number> line, for example CSDF7T5H-00001.
• The footer mentions the certified software.

Where the series and the ATCUD appear on a certified document.

If the document comes out without an ATCUD, the series is not filed for that type, even if it is filed for others.

The trap: one series is several sequences

This is the part the documentation does not spell out, and the one that breaks automations silently.

In InvoiceXpress a series holds one id per document type. The top-level id is the invoice's.

When you ask for the series through the API (GET /sequences.json), each series answers with a top-level id and a separate id per document type:

{
  "id": 47734,
  "serie": "2026A",
  "current_invoice_sequence_id": 47734,
  "current_invoice_receipt_sequence_id": 47736,
  "current_credit_note_sequence_id": 47739
}

The top-level id is the invoice's. Use it to create an invoice-receipt and InvoiceXpress answers:

HTTP 400 — A série não corresponde ao tipo de documento

The document is not created and the sale goes uninvoiced, with no visible error on the shop side. The rule is: always use the id specific to the type you are issuing, and fall back to the top-level id only when the specific one is absent.

There is a second detail: while only drafts exist in a series, that type's specific id may not be filled in yet. It appears once the first document of that type is finalised.

Common mistakes in InvoiceXpress

• A series that is not the default. Documents created without an explicit series fall into whichever is marked default. If that is still last year's, January starts numbering in the wrong place.
• Status "Por comunicar" on a single document type. You filed FT but not NC, and the year's first refund fails.
• A name with a space or an accent. Accepted by InvoiceXpress, rejected in the SAF-T file.
• Changing the starting number after the first document. Not possible. Create a new series and deactivate the old one.
• The turn of the year. A new yearly series has to be created and filed before January's first sale, not after.

How Rioko helps

Rioko reads the series from your InvoiceXpress account through the API and shows them by name in the dashboard. You pick the series and Rioko handles the rest, including choosing the right id for the document type it is about to issue on each sale: invoice, invoice-receipt or credit note. If you configure a series the account does not have, or one that has not been filed, the connection refuses to issue rather than letting an invoice go out without an ATCUD.

At the turn of the year, the dashboard tells you to point the connection at the new series, so no January sale comes out numbered in the previous financial year.

Set up your InvoiceXpress connection →