Skip to main content

TicketBAI

TicketBAI is the standardized digital format for submitting all invoices issued in the Basque Country, Spain.

Quaderno is officially recognized as "guaranteeing software" for TicketBAI by the local tax authorities.

Thanks to our API, complying is as easy as sending your sales and refund data to Quaderno in a single API call. You will receive a JSON response with the signed PDF of the document, which contains a QR code to ease later verification.

tip

You can test the TicketBAI integration in our Sandbox environment, which simulates the production environment without sending real data to the AEAT.

Connecting TicketBAI​

To start using TicketBAI in Quaderno, you need to upload your electronic certificate and then activate the integration. You can do both from the dashboard or through the API.

From the dashboard​

  1. Upload your electronic certificate on the Certificates page.
  2. Connect the TicketBAI integration from the Integrations page.

Using the API​

Before activating TicketBAI, make sure that:

  • Your account has a valid NIF set as registration_number.
  • Your account business_name matches the name registered with the tax authority for that NIF.
  • Your account has no other e-invoicing integration (Verifactu or TicketBAI) connected. Only one is allowed per account.
note

Only admin or developer API keys can manage certificates.

1. Upload your certificate​

Send your PKCS#12 file to the Certificates API. The file content must be encoded in base64, and the country must be ES:

curl https://ACCOUNT_NAME.quadernoapp.com/api/certificates \
  -u YOUR_API_KEY:x \
  -H "Content-Type: application/json" \
  -H "Accept: application/json; api_version=20260309" \
  -d '{
    "country": "ES",
    "password": "secret",
    "file": {
      "filename": "certificate.p12",
      "data": "BASE64_ENCODED_CERTIFICATE"
    }
  }'

The response includes the certificate id, which you'll need in the next step. Quaderno extracts the subject_name and valid_until from the file, and only one active certificate per country is allowed.

warning

PKCS#12 files contain a private key. Only send them over HTTPS, and never log or store the base64 payload on the client side.

2. Activate TicketBAI​

Call the TicketBAI API with the certificate_id and the Basque tax agency your business reports to (araba, bizkaia or gipuzkoa):

curl https://ACCOUNT_NAME.quadernoapp.com/api/einvoicing/ticketbai \
  -u YOUR_API_KEY:x \
  -H "Content-Type: application/json" \
  -H "Accept: application/json; api_version=20260309" \
  -d '{
    "certificate_id": 42,
    "agency": "bizkaia",
    "epigraph": 722,
    "lroe_model": "240"
  }'

For bizkaia, epigraph (activity code) is required. lroe_model is optional: use 140 for physical persons and 240 for legal entities. If omitted, it's derived from the NIF type.

The API returns 201 with the integration, or 422 if a parameter is invalid or a prerequisite isn't met.

Checking and updating the integration​

  • Use GET /einvoicing/ticketbai to retrieve the integration. It returns 404 if TicketBAI hasn't been activated yet.
  • Use PUT /einvoicing/ticketbai to change the epigraph or lroe_model, or to rotate the certificate by passing a new certificate_id.
  • To renew an expiring certificate, replace its file with PUT /certificates/{id}. Since only one active certificate per country is allowed, the integration keeps using the same certificate ID. A certificate linked to an active integration cannot be deleted.

Sending sales and refunds data​

Send your sales and refunds data to Quaderno as usual, using our Transactions API.

These guides will walk you through the process:

When the TicketBAI integration is enabled, Quaderno will automatically send all invoices and credit notes to the corresponding tax administration.

TicketBAI's verification_code and verification_url will be available from the API responses, and generated invoices will display their verification ID and a QR code, allowing your customers to confirm the status of the invoice with the respective tax administration.

Delivery events​

When an invoice or credit note is sent to the Basque Country tax authorities via TicketBAI, Quaderno will generate a delivery event to notify you of the result. You can subscribe to these events using webhooks to receive real-time notifications in your application.

The available delivery events are:

  • delivery.succeeded – The document was successfully delivered to the tax authorities.
  • delivery.failed – The delivery failed due to a technical error (e.g., network issues, service unavailable).
  • delivery.rejected – The tax authorities rejected the document due to validation errors in the data.

These events allow you to automate your workflow and take appropriate action based on the delivery status, such as notifying customers, retrying failed deliveries, or correcting rejected documents.

Limitations​

Once you enable the TicketBAI integration, keep these limitations in mind:

  • You won't be able to assign a custom number or issue_date to invoices or receipts. They will be assigned automatically.
  • The TicketBAI integration cannot be disabled. If you need to stop sending invoices, you must contact our support team.