Skip to main content

Documentation Index

Fetch the complete documentation index at: https://invopop-mintlify-changelog-week-1778411791.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

​
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.
-SandboxLive
SupplierCan use test name HFPn5yhXZ9tdD4pHRbvwymaVPrGZQr and test NIF A99805194Real company in Basque Country required
Supplier registrationRequired (automated acceptance/rejection)Required (signed agreement with invoicing provider, manual process outside Invopop)
EnvironmentTicketBAI - PruebasTicketBAI - Producción

​
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.
TicketBAI requires all suppliers to sign an agreement with their invoicing provider explicitly granting permission to represent them. See the TicketBAI Supplier Onboarding Guide for detailed instructions on how to register suppliers.

​
Setup

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

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.
2

Create invoice workflow

TicketBAI issue invoice workflow

This workflow will issue an invoice through TicketBAI.
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.

​
Bizkaia activity code for individuals

Individual suppliers (autónomos) issuing invoices in Bizkaia must report through the LROE Modelo 140 register, which requires an economic activity code (epígrafe). Set the es-tbai-bi-activity extension on the supplier with the appropriate code from the Batuz LROE list of activity codes. The code is a numeric value of up to seven digits. It is required for individual issuers in Bizkaia and is not used by organisations (which file through Modelo 240).
Supplier with Bizkaia activity code
"supplier": {
  "name": "Maria Garcia",
  "tax_id": {
    "country": "ES",
    "code": "12345678Z"
  },
  "addresses": [
    {
      "street": "San Frantzisko",
      "locality": "Bilbo",
      "region": "Bizkaia",
      "code": "48003",
      "country": "ES"
    }
  ],
  "ext": {
    "es-tbai-bi-activity": "6201"
  }
}

​
Cancel an Invoice

TicketBAI also allows you to cancel an invoice. In general, you should only cancel an invoice if it hasn’t been handed to the customer nor accepted by the tax authority. Different from a credit note or a corrective, canceling an invoice doesn’t produce a second document, which means you don’t have a paper to hand to your customer to show the cancellation. That’s why, if the invoice has been handed to the customer, we recommend issuing a credit note instead.
1

Add a cancel invoice workflow (only once)

To cancel an invoice, you need a workflow with the Cancel invoice step. You can start with the template below.

VERI*FACTU cancel invoice workflow

This workflow will cancel a TicketBAI document.
2

Send to cancellation workflow

To cancel an invoice, simply send it to the VERI*FACTU cancel invoice workflow created earlier using the Create a job endpoint.The invoice’s status will change to Void when the workflow completes successfully.

​
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:
  1. Upload the example either via the Invopop Console or using the Invopop Silo Create an Entry API endpoint.
  2. 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: Invopop will try to assign these automatically if not explicitly provided.
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.
In this example, we’re issuing a standard B2B invoice from a Basque supplier to a customer in Madrid.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”.
Notice:
  • the minimal version (ticketbai-b2b.min.mdx) contains only the essential fields required to create the invoice,
  • 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,
  • when running gobl build, the system automatically calculates totals, assigns the $regime to ES, sets the es-tbai-region extension to BI (Bizkaia) based on the supplier’s address, applies the standard VAT rate (21%), and assigns the es-tbai-product extension to services based on the item unit,
  • the built version (ticketbai-b2b.mdx) shows the normalized document with calculated totals, line item sums, tax breakdowns, and automatically generated fields, and,
  • there are no totals or calculations in the minimal version; all these will be made automatically when uploading.
{
  "$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"
    }
  ]
}
In this example, we’re issuing a simplified B2C invoice from a Basque supplier for an in-person sale.Scenario details:
  • The supplier is based out of Bilbao in Bizkaia, using the sandbox data provided by TicketBAI.
  • There is no customer.
  • Physical goods are being sold with a standard VAT rate.
  • The series for the invoice is “FS1”.
Notice:
  • the minimal version (ticketbai-b2c.min.mdx) contains only the essential fields required to create the simplified invoice,
  • 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,
  • when running gobl build, the system automatically calculates the tax-included totals (splitting the €25.10 price into €20.74 base + €4.36 VAT), assigns the $regime to ES, sets the es-tbai-region extension to BI (Bizkaia), applies the standard VAT rate (21%), and normalizes all fields,
  • the built version (ticketbai-b2c.mdx) shows the normalized document with calculated totals including tax-included calculations, line item sums, tax breakdowns, and automatically generated fields, and,
  • there are no totals or calculations in the minimal version; all these will be made automatically when uploading.
{
  "$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"
    }
  ]
}

​
FAQ

You should send the credit note with the same sign as the original invoice.In Spain, unlike other countries, credit notes must be submitted to Hacienda with inverse values. Invopop handles this conversion automatically before transforming the credit note into a “factura rectificativa” (corrective invoice).This means you only need to send the credit note following international standards (with same sign as the invoice). Invopop will automatically adapt it when submitting to Hacienda.For reference, see the GOBL Invoice documentation with type set to credit-note.
See the Spain tax regime in GOBL for tax categories, NIF rules, and Spanish-specific extensions. Subsystem-specific addons live alongside: es-verifactu-v1, es-tbai-v1, es-facturae-v3.
Build a GOBL invoice with the es-tbai-v1 addon, send it through the TicketBAI Issue Invoice workflow. Invopop signs with its sello de empresa certificate, generates the chained XML, and submits to the relevant Diputación Foral (Bizkaia, Gipuzkoa, or Álava).
This is expected. QR codes generated in the TicketBAI sandbox environment are intentionally non-functional to prevent sandbox invoices from being mistaken for real ones.To verify that a sandbox QR code is correct, upload the PDF or a QR image to the foral tax authority’s test verification page: pruebatuz.bizkaia.eus.
More available in our Spain FAQ section

Participate in our community

Ask and answer questions about TicketBAI invoicing in Spain →