> ## Documentation Index
> Fetch the complete documentation index at: https://docs.invopop.com/llms.txt
> Use this file to discover all available pages before exploring further.

# TicketBAI Invoicing Guide

> Issue invoices in the Basque Country with 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](https://docs.gobl.org/draft-0/bill/invoice) into the TicketBAI format, including the required "chaining", and will send them to the correct tax authority.

| -                         | Sandbox                                                                     | Live                                                                                |
| ------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| **Supplier**              | Can use test name `HFPn5yhXZ9tdD4pHRbvwymaVPrGZQr` and test NIF `A99805194` | Real company in Basque Country required                                             |
| **Supplier registration** | Required (automated acceptance/rejection)                                   | Required (signed agreement with invoicing provider, manual process outside Invopop) |
| **Environment**           | TicketBAI - Pruebas                                                         | TicketBAI - 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.

<Info>
  TicketBAI requires all suppliers to sign an agreement with their invoicing
  provider explicitly granting permission to represent them. See the
  [TicketBAI Supplier Onboarding Guide](/guides/es-ticketbai-supplier) for
  detailed instructions on how to register suppliers.
</Info>

## Setup

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="Create invoice workflow">
    <Tabs>
      <Tab title="Template">
        <Card iconType="duotone" title="TicketBAI issue invoice workflow" icon="code-branch" href="https://console.invopop.com/redirect/workflows/new?template=es-ticketbai-invoice" cta="Add to my workspace">
          This workflow will issue an invoice through TicketBAI.
        </Card>
      </Tab>

      <Tab title="Code">
        Copy and paste into a new [Empty Invoice workflow](https://console.invopop.com/redirect/workflows/new?template=empty-invoice) code view. This example adds support for setting states on silo entries which we strongly recommend.

        ```json Example TicketBAI invoice workflow theme={"system"}
        {
          "name": "TicketBAI issue invoice",
          "description": "Issue a TicketBAI invoice and generate PDF with QR",
          "schema": "bill/invoice",
          "steps": [
            {
              "id": "dd319d60-8bc1-11ef-96af-b55bf69bb0b8",
              "name": "Add sequential code",
              "config": {
                "name": "TicketBAI Invoice",
                "start": 1,
                "prefix": "F",
                "padding": 6
              },
              "summary": "Dynamic · TicketBAI · 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": "fc75e4f0-8721-11ef-a962-73e3f2037a52",
              "name": "Sign envelope",
              "provider": "silo.close"
            },
            {
              "id": "fc618ea0-a757-11ef-8377-c15ac3014ffb",
              "name": "Generate TicketBAI XML",
              "provider": "gov-es.ticketbai.generate"
            },
            {
              "id": "0448df60-a758-11ef-8377-c15ac3014ffb",
              "name": "Send invoice to TicketBAI",
              "provider": "gov-es.ticketbai.send"
            },
            {
              "id": "c61adaa0-7b55-11ef-bffc-d9a10ebf9f89",
              "name": "Generate PDF",
              "config": {
                "locale": "es",
                "date_format": "%Y-%m-%d",
                "logo_height": 40
              },
              "summary": "Spanish · A4",
              "provider": "pdf"
            },
            {
              "id": "d8693d70-7b3a-11ef-bffc-d9a10ebf9f89",
              "name": "Set state",
              "config": {
                "state": "sent"
              },
              "summary": "Set state to `sent`{.state .sent}",
              "provider": "silo.state"
            }
          ],
          "rescue": [
            {
              "id": "dd889490-7b3a-11ef-bffc-d9a10ebf9f89",
              "name": "Set state",
              "config": {
                "state": "error"
              },
              "summary": "Set state to `error`{.state .error}",
              "provider": "silo.state"
            }
          ]
        }
        ```
      </Tab>

      <Tab title="Build from scratch">
        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 "TicketBAI issue invoice".

        The new workflow will need to perform these steps:

        * **Add sequential code** - choose the "dynamic" sequence option and set a name.
        * **Set state** - to "Processing".
        * **Sign envelope** - this step signs the TicketBAI document, preventing further modifications.
        * **Generate TicketBAI XML** - this step generates the TicketBAI XML document.
        * **Send invoice to TicketBAI** - will take the previously generated XML document, and send to the appropriate gateway.
        * **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.
        * **Set state** - 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.

        <Tip>
          Invoices must be signed before processing with TicketBAI, be sure to add the *Sign envelope* step.
        </Tip>
      </Tab>
    </Tabs>

    <Warning>
      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 XML* step, modifications are not
      permitted.
    </Warning>
  </Step>
</Steps>

## 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`](https://docs.gobl.org/addons/es-tbai-v1#activity-code-bizkaia) extension on the supplier with the appropriate code from the [Batuz LROE list of activity codes](https://www.batuz.eus/fitxategiak/batuz/lroe/batuz_lroe_lista_epigrafes_v1_0_4.xlsx).

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

```json Supplier with Bizkaia activity code theme={"system"}
"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"
  }
}
```

## VAT regime key

TicketBAI requires every invoice line to report a `ClaveRegimenIvaOpTrascendencia` code that classifies the VAT regime or operation type. Set the [`es-tbai-regime`](https://docs.gobl.org/addons/es-tbai-v1#ticketbai-vat-regime-key) extension on a tax combo to control this value explicitly. The most common codes are:

| Code | Description                                                     |
| ---- | --------------------------------------------------------------- |
| `01` | General regime operation                                        |
| `02` | Export                                                          |
| `03` | Used goods, art, antiques and collectibles                      |
| `05` | Travel agencies                                                 |
| `07` | Cash accounting                                                 |
| `17` | OSS or IOSS                                                     |
| `51` | Equivalence surcharge                                           |
| `52` | Simplified VAT regime                                           |
| `53` | Operations by or for entities without a permanent establishment |

If you do not set the extension, GOBL assigns a default based on the line context:

| Combo context                           | Regime code |
| --------------------------------------- | ----------- |
| Tax key is `export`                     | `02`        |
| Combo carries an equivalence surcharge  | `51`        |
| Invoice has the `simplified-scheme` tag | `52`        |
| Otherwise                               | `01`        |

```json Tax combo with explicit regime theme={"system"}
"taxes": [
  {
    "cat": "VAT",
    "rate": "standard",
    "ext": {
      "es-tbai-regime": "17"
    }
  }
]
```

See the [TicketBAI extension reference](https://docs.gobl.org/addons/es-tbai-v1#ticketbai-vat-regime-key) for the complete list of values.

## Customer identity type

When a customer has no tax identifier (for example, a foreign individual paying with a passport), TicketBAI expects the document type to be reported under the `IDOtro` element with an `IDType` code from the L7 list. The [`es-tbai-identity-type`](https://docs.gobl.org/addons/es-tbai-v1#identity-type-code) extension on a party identity carries that code.

Prefer the customer's tax ID where possible — GOBL maps it automatically:

* Spanish tax IDs map to the `NIF` field.
* EU tax IDs map to `IDOtro` with code `02` (NIF-VAT / VIES).
* Non-EU tax IDs map to `IDOtro` with code `04` (foreign identity document).

For other identity documents, set the identity `key` and GOBL fills in the extension:

| Identity key | Extension code | Document                                 |
| ------------ | -------------- | ---------------------------------------- |
| `passport`   | `03`           | Passport                                 |
| `foreign`    | `04`           | Foreign identity document                |
| `resident`   | `05`           | Spanish resident foreigner identity card |
| `other`      | `06`           | Other identity document                  |

```json Customer with a passport theme={"system"}
"customer": {
  "name": "Jane Smith",
  "identities": [
    {
      "key": "passport",
      "country": "GB",
      "code": "123456789"
    }
  ]
}
```

After normalization the identity carries `"ext": { "es-tbai-identity-type": "03" }`.

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

<Steps>
  <Step title="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.

    <Tabs>
      <Tab title="Template">
        <Card title="VERI*FACTU cancel invoice workflow" icon="code-branch" iconType="duotone" href="https://console.invopop.com/redirect/workflows/new?template=es-ticketbai-cancel" cta="Add to my workspace">
          This workflow will cancel a TicketBAI document.
        </Card>
      </Tab>

      <Tab title="Code">
        Copy and paste into a new [Empty Party workflow](https://console.invopop.com/redirect/workflows/new?template=empty-party) code view.

        ```json Example TicketBAI cancel invoice workflow theme={"system"}
        {
            "name": "TicketBAI cancel invoice",
            "description": "Cancel an invoice via TicketBAI",
            "schema": "bill/invoice",
            "steps": [
                {
                    "id": "2f897e30-3c9c-11f0-8690-a921c0418914",
                    "name": "Cancel invoice in TicketBAI",
                    "provider": "gov-es.ticketbai.cancel"
                },
                {
                    "id": "334ffc10-3c9c-11f0-8690-a921c0418914",
                    "name": "Set state",
                    "provider": "silo.state",
                    "summary": "Set state to `void`{.state .void}",
                    "config": {
                        "state": "void"
                    }
                }
            ],
            "rescue": [
                {
                    "id": "384cfe20-3c9c-11f0-8690-a921c0418914",
                    "name": "Set state",
                    "provider": "silo.state",
                    "summary": "Set state to `error`{.state .error}",
                    "config": {
                        "state": "error"
                    }
                }
            ]
        }

        ```
      </Tab>

      <Tab title="Build from scratch">
        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 "VERI\*FACTU Cancel Invoice".

        We recommend adding the following steps:

        1. **Cancel invoice** - Cancels the TicketBAI document.
        2. **Set state** - select *Void* in the step configuration. This will set the state of the invoice to `Void`.
        3. In the Error Handling area, **Set state** - select `Error` in the step configuration.

        Add any additional steps you may need, and save the new workflow.
      </Tab>
    </Tabs>
  </Step>

  <Step title="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](/api-ref/transform/jobs/create-a-job-post) endpoint.

    The invoice's status will change to `Void` when the workflow completes successfully.
  </Step>
</Steps>

## Running

Invopop uses the [GOBL](https://docs.gobl.org) 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](https://build.gobl.org) 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](https://console.invopop.com) or using the Invopop Silo [Create an Entry](/api-ref/silo/entries/create-an-entry-put) 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](/api-ref/transform/jobs/create-a-job-put) 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](https://docs.gobl.org/draft-0/bill/invoice) sent to TicketBAI require the following properties in order to perform the correct normalization and validation steps:

* `$region` to be set to [`ES`](https://docs.gobl.org/regimes/es)
* `$addons` to include [`es-tbai-v1`](https://docs.gobl.org/addons/es-tbai-v1)

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

<Tip>
  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.
</Tip>

<AccordionGroup>
  <Accordion title="B2B Invoice">
    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`](https://docs.gobl.org/addons/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`](https://docs.gobl.org/addons/es-tbai-v1#region-code) extension to `BI` (Bizkaia) based on the supplier's address, applies the standard VAT rate (21%), and assigns the [`es-tbai-product`](https://docs.gobl.org/addons/es-tbai-v1#ticketbai-product-key) 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.

    <CodeGroup>
      ```json TicketBAI B2B Invoice theme={"system"}
      {
        "$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"
          }
        ]
      }
      ```

      ```json Built version theme={"system"}
      {
      	"$schema": "https://gobl.org/draft-0/bill/invoice",
      	"$regime": "ES",
      	"$addons": [
      		"es-tbai-v1"
      	],
      	"type": "standard",
      	"series": "F1",
      	"issue_date": "2026-04-20",
      	"currency": "EUR",
      	"tax": {
      		"ext": {
      			"es-tbai-region": "BI"
      		}
      	},
      	"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"
      		},
      		"addresses": [
      			{
      				"num": "42",
      				"street": "Calle Pradillo",
      				"locality": "Madrid",
      				"region": "Madrid",
      				"code": "28002",
      				"country": "ES"
      			}
      		],
      		"emails": [
      			{
      				"addr": "billing@example.com"
      			}
      		]
      	},
      	"lines": [
      		{
      			"i": 1,
      			"quantity": "20",
      			"item": {
      				"name": "Development services",
      				"price": "90.00",
      				"unit": "h"
      			},
      			"sum": "1800.00",
      			"taxes": [
      				{
      					"cat": "VAT",
      					"key": "standard",
      					"rate": "general",
      					"percent": "21.0%",
      					"ext": {
      						"es-tbai-product": "services"
      					}
      				}
      			],
      			"total": "1800.00"
      		}
      	],
      	"totals": {
      		"sum": "1800.00",
      		"total": "1800.00",
      		"taxes": {
      			"categories": [
      				{
      					"code": "VAT",
      					"rates": [
      						{
      							"key": "standard",
      							"ext": {
      								"es-tbai-product": "services"
      							},
      							"base": "1800.00",
      							"percent": "21.0%",
      							"amount": "378.00"
      						}
      					],
      					"amount": "378.00"
      				}
      			],
      			"sum": "378.00"
      		},
      		"tax": "378.00",
      		"total_with_tax": "2178.00",
      		"payable": "2178.00"
      	},
      	"notes": [
      		{
      			"key": "general",
      			"text": "Invoice for development services"
      		}
      	]
      }
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="B2C Simplified Invoice">
    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`](https://docs.gobl.org/addons/es-tbai-v1#ticketbai-product-key) 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`](https://docs.gobl.org/addons/es-tbai-v1#region-code) 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.

    <CodeGroup>
      ```json TicketBAI B2C Invoice theme={"system"}
      {
        "$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"
          }
        ]
      }
      ```

      ```json Built version theme={"system"}
      {
      	"$schema": "https://gobl.org/draft-0/bill/invoice",
      	"$regime": "ES",
      	"$addons": [
      		"es-tbai-v1"
      	],
      	"type": "standard",
      	"series": "FS1",
      	"issue_date": "2026-04-20",
      	"currency": "EUR",
      	"tax": {
      		"prices_include": "VAT",
      		"ext": {
      			"es-tbai-region": "BI"
      		}
      	},
      	"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": [
      		{
      			"i": 1,
      			"quantity": "1",
      			"item": {
      				"name": "Advanced screwdriver set",
      				"price": "25.10",
      				"ext": {
      					"es-tbai-product": "goods"
      				}
      			},
      			"sum": "25.10",
      			"taxes": [
      				{
      					"cat": "VAT",
      					"key": "standard",
      					"rate": "general",
      					"percent": "21.0%",
      					"ext": {
      						"es-tbai-product": "services"
      					}
      				}
      			],
      			"total": "25.10"
      		}
      	],
      	"totals": {
      		"sum": "25.10",
      		"tax_included": "4.36",
      		"total": "20.74",
      		"taxes": {
      			"categories": [
      				{
      					"code": "VAT",
      					"rates": [
      						{
      							"key": "standard",
      							"ext": {
      								"es-tbai-product": "services"
      							},
      							"base": "20.74",
      							"percent": "21.0%",
      							"amount": "4.36"
      						}
      					],
      					"amount": "4.36"
      				}
      			],
      			"sum": "4.36"
      		},
      		"tax": "4.36",
      		"total_with_tax": "25.10",
      		"payable": "25.10"
      	},
      	"notes": [
      		{
      			"key": "general",
      			"text": "In person sale"
      		}
      	]
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Should I send credit notes with positive or negative values?">
    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](https://docs.gobl.org/draft-0/bill/invoice) documentation with `type` set to `credit-note`.
  </Accordion>

  <Accordion title="Where do I find Spain-specific GOBL documentation?">
    See the [Spain tax regime in GOBL](https://docs.gobl.org/regimes/es) for tax categories, NIF rules, and Spanish-specific extensions. Subsystem-specific addons live alongside: [`es-verifactu-v1`](https://docs.gobl.org/addons/es-verifactu-v1), [`es-tbai-v1`](https://docs.gobl.org/addons/es-tbai-v1), [`es-facturae-v3`](https://docs.gobl.org/addons/es-facturae-v3).
  </Accordion>

  <Accordion title="What's the workflow for issuing TicketBAI invoices?">
    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).
  </Accordion>

  <Accordion title="Why don't TicketBAI QR codes work in the sandbox environment?">
    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](https://pruebatuz.bizkaia.eus/B4PEQR0C/testQr.xhtml?idioma=es).
  </Accordion>
</AccordionGroup>

More available in our [Spain FAQ](/faq/spain) section

***

<AccordionGroup>
  <Accordion title="🇪🇸 Invopop resources for Spain">
    |            |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
    | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Compliance | <Icon icon="https://assets.invopop.com/flags/es.svg" /> [Invoicing compliance in Spain](/compliance/spain)<br /> <Icon icon="timeline" /> [Compliance timeline](/timelines/spain)                                                                                                                                                                                                                                                                                                                   |
    | Apps       | <Icon icon="https://assets.invopop.com/apps/gov-es/icon.svg" /> [Spain](/apps/spain)<br /> <Icon icon="https://assets.invopop.com/apps/verifactu/icon.svg" /> [VERI\*FACTU Spain](/apps/verifactu-spain)<br /><Icon icon="https://assets.invopop.com/apps/ticketbai/icon.svg" /> [TicketBAI Spain](/apps/ticketbai-spain)                                                                                                                                                                           |
    | Guides     | <Icon icon="book" /> [Facturae Guide](/guides/es-facturae)<br /><Icon icon="book" /> [VERI\*FACTU Invoicing Guide](/guides/es-verifactu)<br /><Icon icon="book" /> [VERI\*FACTU Supplier Onboarding](/guides/es-verifactu-supplier)<br /><Icon icon="book" /> [SII Invoicing Guide](/guides/es-sii)<br /><Icon icon="book" /> [SII Supplier Onboarding](/guides/es-sii-supplier)<br /><Icon icon="book" /> [TicketBAI Guide](/guides/es-ticketbai)                                                  |
    | FAQ        | <Icon icon="square-question" /> [Spain FAQ](/faq/spain)                                                                                                                                                                                                                                                                                                                                                                                                                                             |
    | GOBL       | <Icon icon="https://assets.invopop.com/icons/gobl.svg" />  [Spain Tax Regime](https://docs.gobl.org/regimes/es)<br /> <Icon icon="https://assets.invopop.com/icons/gobl.svg" /> [VERI\*FACTU Addon](https://docs.gobl.org/addons/es-verifactu-v1)<br /> <Icon icon="https://assets.invopop.com/icons/gobl.svg" /> [Facturae Addon](https://docs.gobl.org/addons/es-facturae-v3)<br /> <Icon icon="https://assets.invopop.com/icons/gobl.svg" /> [SII Addon](https://docs.gobl.org/addons/es-sii-v1) |
    | GitHub     | <Icon icon="github" /> [gobl.facturae](https://github.com/invopop/gobl.facturae)<br /><Icon icon="github" /> [gobl.verifactu](https://github.com/invopop/gobl.verifactu)<br /> <Icon icon="github" /> [gobl.ticketbai](https://github.com/invopop/gobl.ticketbai)                                                                                                                                                                                                                                   |
  </Accordion>
</AccordionGroup>

<Card title="Participate in our community" icon="forumbee" href="https://community.invopop.com" arrow="true" horizontal>
  Ask and answer questions about TicketBAI invoicing in Spain →
</Card>
