Spain - TicketBAI

Introduction

TicketBAI is a fiscal initiative developed collaboratively by the Basque Government and the provincial tax authorities of Álava, Gipuzkoa, and Bizkaia. Its primary objective is to combat tax fraud by ensuring that all invoices issued by individuals and entities conducting economic activities in the Basque Country are reported to the corresponding tax authorities.

Under this system, businesses are required to use certified invoicing software that generates a unique TicketBAI QR code for each invoice. These codes facilitate the traceability of transactions and prevent the manipulation or deletion of invoices. The invoicing software must also create an XML file for each transaction, which is electronically signed and sent to the relevant provincial tax authority.

The implementation timeline for TicketBAI varies across the three provinces:

Alava: Mandatory adoption began in phases starting in 2022, with full compliance required by December 1, 2022.
Gipuzkoa: A phased implementation commenced in 2022, with different sectors required to comply by specific dates, concluding on May 1, 2023.
Bizkaia: The province has integrated TicketBAI into a broader tax control system known as Batuz. Mandatory adoption for large companies began on January 1, 2024, with a staggered implementation for other entities extending until January 1, 2026.

Invopop will automatically convert GOBL Invoices into the TicketBAI format, including the required “chaining”, and will send them to the correct tax authority.

Prerequisites

In order to register a supplier and issue invoices, you will need:

Supplier details, including:
- company name,
- a tax ID (NIF) from a company in one of the three Tax Agencies, and,
- an address which includes the Region name; “Alaba”, “Bizkaia”, or “Gipuzkoa”.
Customer details for B2B sales, including the tax ID if selling to a Spanish or EU entity.
Quantity, name, price, and VAT rates of items being sold, including differenciating between physical goods and services.
An invoicing series.

If you do not already have a tax ID from a company in the Basque Country, you will need to use test data. In the examples, we use the name HFPn5yhXZ9tdD4pHRbvwymaVPrGZQr and tax ID code A99805194, which were issued by the TicketBAI tax authorities for testing.

Setup

To correctly issue TicketBAI invoices, you will need to prepare your Invopop Workspace by following these steps:

Create supplier registration workflow

Currently the Invopop TicketBAI integration does not require a registration workflow, but this may change in the future.

TicketBAI requires all suppliers to sign an agreement with their invoicing provider explicitly granting permission to represent them. This is currently a manual process performed outside of Invopop. For more details, contact support.

Connect the TicketBAI app

Head over to Configuration, Apps, and find TicketBAI from the list of apps to discover. Tap the Connect button to enable.

No further configuration is required.

Create invoice workflow

If you haven’t already, checkout the workflows guide and ensure you’re familiar with the process.

Create a new Invoices workflow with the following steps:

Add Sequential Code - chose the dynamic sequence option, set a name, and check the Sign document checkbox.
Generate TicketBAI (Spain) - this step generates the TicketBAI XML document.
Generate PDF - configure as required, the PDF will use the QR code generated in the previous step. After this step, you may want to add a webhook or similar.
Send TicketBAI (Spain) - will take the previously generate XML document, and send to the appropriate gateway.

Invoices must be signed before processing with TicketBAI. If you choose not to use the Add Sequential Code step, be sure to add the Sign Envelope step instead.

If in the unlikely scenario a document is rejected, you will need to try and correct the error inside a new document and resend. As documents are all chained together in the Generate TicketBAI step, modifications are not permitted.

You can copy and paste the following JSON while editing a Workflow in “developer” mode. This example adds support for setting states on silo entries which we strongly recomend.

Example TicketBAI Invoice Workflow with States
{
  "name": "TicketBAI Invoice",
  "steps": [
    {
      "id": "dd319d60-8bc1-11ef-96af-b55bf69bb0b8",
      "name": "Add Sequential Code",
      "next": [
        {
          "status": "KO",
          "step_id": "dd889490-7b3a-11ef-bffc-d9a10ebf9f89"
        }
      ],
      "config": {
        "name": "TicketBAI Invoice",
        "sign": true,
        "start": 1,
        "prefix": "F",
        "padding": 6
      },
      "summary": "Dynamic · TicketBAI Invoice · F000001",
      "provider": "sequence.enumerate"
    },
    {
      "id": "ba77d5b0-7b3a-11ef-bffc-d9a10ebf9f89",
      "name": "Set State",
      "config": {
        "state": "processing"
      },
      "summary": "Set state to `processing`{.state .processing}",
      "provider": "silo.state"
    },
    {
      "id": "fc618ea0-a757-11ef-8377-c15ac3014ffb",
      "name": "Generate TicketBAI (Spain)",
      "next": [
        {
          "status": "KO",
          "step_id": "dd889490-7b3a-11ef-bffc-d9a10ebf9f89"
        }
      ],
      "provider": "ticketbai.generate"
    },
    {
      "id": "0448df60-a758-11ef-8377-c15ac3014ffb",
      "name": "Send TicketBAI (Spain)",
      "next": [
        {
          "status": "KO",
          "step_id": "dd889490-7b3a-11ef-bffc-d9a10ebf9f89"
        }
      ],
      "provider": "ticketbai.send"
    },
    {
      "id": "c61adaa0-7b55-11ef-bffc-d9a10ebf9f89",
      "name": "Generate PDF",
      "next": [
        {
          "status": "KO",
          "step_id": "dd889490-7b3a-11ef-bffc-d9a10ebf9f89"
        }
      ],
      "config": {
        "locale": "es",
        "date_format": "%Y-%m-%d",
        "logo_height": 40
      },
      "summary": "Spanish",
      "provider": "pdf"
    },
    {
      "id": "d8693d70-7b3a-11ef-bffc-d9a10ebf9f89",
      "name": "Set State",
      "next": [
        {
          "stop": true,
          "status": "NA"
        }
      ],
      "config": {
        "state": "sent"
      },
      "summary": "Set state to `sent`{.state .sent}",
      "provider": "silo.state"
    },
    {
      "id": "dd889490-7b3a-11ef-bffc-d9a10ebf9f89",
      "name": "Set State",
      "config": {
        "state": "error"
      },
      "summary": "Set state to `error`{.state .error}",
      "provider": "silo.state"
    }
  ]
}

Running

Invopop uses the GOBL framework for sending and storing invoices to be sent to TicketBAI. In this section we provide example GOBL documents that you can copy and customize.

We also recommend using the GOBL Builder to test building invoices and generating PDFs in real-time to see what the framework is capable of.

All of the following examples assume you will be performing two key steps:

Upload the example either via the Invopop Console or using the Invopop Silo Create an Entry API endpoint.
Create a job to process the Silo Entry with your TicketBAI workflow either manually via the console, or using the Invopop Transform Create a Job endpoint.

The Invopop API will automatically prepare the uploaded documents from the minimal data provided, this allows us to keep the examples short and concise.

GOBL Invoices sent to TicketBAI require the following properties in order to perform the correct normalization and validation steps:

$region to be set to ES
$addons to include es-tbai-v1

Invopop will try to assign these automatically if not explicitly provided.

Scenario details:

The supplier is based out of Bilbao in Bizkaia, using the sandbox data provided by TicketBAI.
The customer is in Madrid.
They’re selling software development services with standard VAT.
The series for the invoice is “F1”.

{
  "$schema": "https://gobl.org/draft-0/bill/invoice",
  "$addons": ["es-tbai-v1"],
  "series": "F1",
  "supplier": {
    "name": "HFPn5yhXZ9tdD4pHRbvwymaVPrGZQr",
    "tax_id": {
      "country": "ES",
      "code": "A99805194"
    },
    "addresses": [
      {
        "num": "42",
        "street": "San Frantzisko",
        "locality": "Bilbo",
        "region": "Bizkaia",
        "code": "48003",
        "country": "ES"
      }
    ],
    "emails": [
      {
        "addr": "billing@example.com"
      }
    ]
  },
  "customer": {
    "name": "Receive One S.L.",
    "tax_id": {
      "country": "ES",
      "code": "B98602642"
    },
    "emails": [
      {
        "addr": "billing@example.com"
      }
    ],
    "addresses": [
      {
        "num": "42",
        "street": "Calle Pradillo",
        "locality": "Madrid",
        "region": "Madrid",
        "code": "28002",
        "country": "ES"
      }
    ]
  },
  "lines": [
    {
      "quantity": "20",
      "item": {
        "name": "Development services",
        "price": "90.00",
        "unit": "h"
      },
      "taxes": [
        {
          "cat": "VAT",
          "rate": "standard"
        }
      ]
    }
  ],
  "notes": [
    {
      "key": "general",
      "text": "Invoice for development services"
    }
  ]
}

Key details to take away from this example:

We’re applying the es-tbai-v1 addon to ensure GOBL’s TicketBAI validation checks are applied.
There is no currency nor issue_date, as these will be assigned automatically.
There is no invoice code as this will be assigned by the workflow.
TicketBAI requires a general note, so we’ve added one at the bottom.

In this example:

The supplier is based out of Bilbao in Bizkaia, using the sandbox data provided by TicketBAI.
There is no cusomter
Physical goods are being sold with a standard VAT rate.
The series for the invoice is “FS1”.

{
  "$schema": "https://gobl.org/draft-0/bill/invoice",
  "$addons": ["es-tbai-v1"],
  "series": "FS1",
  "tax": {
    "prices_include": "VAT"
  },
  "supplier": {
    "name": "HFPn5yhXZ9tdD4pHRbvwymaVPrGZQr",
    "tax_id": {
      "country": "ES",
      "code": "A99805194"
    },
    "addresses": [
      {
        "num": "42",
        "street": "San Frantzisko",
        "locality": "Bilbo",
        "region": "Bizkaia",
        "code": "48003",
        "country": "ES"
      }
    ],
    "emails": [
      {
        "addr": "billing@example.com"
      }
    ]
  },
  "lines": [
    {
      "quantity": "1",
      "item": {
        "name": "Advanced screwdriver set",
        "price": "25.10",
        "ext": {
          "es-tbai-product": "goods"
        }
      },
      "taxes": [
        {
          "cat": "VAT",
          "rate": "standard"
        }
      ]
    }
  ],
  "notes": [
    {
      "key": "general",
      "text": "In person sale"
    }
  ]
}

Observations:

There is no customer object.
The tax object contains the prices_include value set to VAT, which will ensure all totals will be calculated assuming that prices include VAT.
The line item includes a es-tbai-product extension with the value goods.
TicketBAI requires a general note, in this case we’ve added a generic message.

Introduction

API

Guides

Spain - TicketBAI

Introduction

Prerequisites

Setup

Running

FAQ

Introduction

API

Guides

​Introduction

​Prerequisites

​Setup

​Running

​FAQ

Introduction

Prerequisites

Setup

Running

FAQ