TicketBAI

Alta, subsanación y anulación de facturas TicketBAI ante las haciendas forales.

Los endpoints TicketBAI remiten facturas a la hacienda foral que indique provincia. Base URL: https://sandbox.veribai.com (TEST) o https://api.veribai.com (LIVE), con autenticación x-api-key.

A diferencia de VeriFactu, la firma y el encadenado TicketBAI se completan en el momento del alta: la respuesta ya incluye el identificador TBAI y el QR. La remisión a la hacienda foral se completa en segundo plano.

En LIVE, todas las operaciones exigen que el emisor tenga su representación firmada; en caso contrario devuelven 403 REPRESENTATION_PENDING. En TEST no se exige.

POST /v1/ticketbai/crear

En TicketBAI los datos de identificación viajan en el nivel superior del JSON (no hay bloque cabecera) y el desglose fiscal es la lista plana desglose:

curl -X POST https://sandbox.veribai.com/v1/ticketbai/crear \
  -H "x-api-key: TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.0",
    "provincia": "bizkaia",
    "serie": "A",
    "numero": "12345",
    "fechaExpedicion": "03-04-2026",
    "tipoFactura": "F1",
    "descripcion": "Servicios de consultoría",
    "emisor": {
      "nif": "B76116342",
      "nombre": "Prueba 1 SL"
    },
    "destinatario": {
      "nif": "B17195595",
      "nombre": "Nombre cliente, SL"
    },
    "desglose": [
      {
        "baseImponible": "100.00",
        "tipoImpositivo": "21.00",
        "cuota": "21.00",
        "descripcion": "Consultoría"
      }
    ],
    "importeTotal": "121.00"
  }'

from datetime import date
from decimal import Decimal

import veribai

client = veribai.Client(api_key="TU_CLAVE", environment="test")

respuesta = client.ticketbai.crear({
    "version": "1.0",
    "provincia": "bizkaia",
    "serie": "A",
    "numero": "12345",
    "fechaExpedicion": date(2026, 4, 3),
    "tipoFactura": "F1",
    "descripcion": "Servicios de consultoría",
    "emisor": {
        "nif": "B76116342",
        "nombre": "Prueba 1 SL",
    },
    "destinatario": {
        "nif": "B17195595",
        "nombre": "Nombre cliente, SL",
    },
    "desglose": [
        {
            "baseImponible": Decimal("100.00"),
            "tipoImpositivo": Decimal("21.00"),
            "cuota": Decimal("21.00"),
            "descripcion": "Consultoría",
        },
    ],
    "importeTotal": Decimal("121.00"),
})
print(respuesta["idTbai"], respuesta["urlValidacion"])

const respuesta = await fetch("https://sandbox.veribai.com/v1/ticketbai/crear", {
  method: "POST",
  headers: {
    "x-api-key": "TU_CLAVE",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "version": "1.0",
    "provincia": "bizkaia",
    "serie": "A",
    "numero": "12345",
    "fechaExpedicion": "03-04-2026",
    "tipoFactura": "F1",
    "descripcion": "Servicios de consultoría",
    "emisor": {
      "nif": "B76116342",
      "nombre": "Prueba 1 SL"
    },
    "destinatario": {
      "nif": "B17195595",
      "nombre": "Nombre cliente, SL"
    },
    "desglose": [
      {
        "baseImponible": "100.00",
        "tipoImpositivo": "21.00",
        "cuota": "21.00",
        "descripcion": "Consultoría"
      }
    ],
    "importeTotal": "121.00"
  }),
});

if (!respuesta.ok) throw new Error(`VeriBai ${respuesta.status}`);
const datos = await respuesta.json();

Campos

Tipos y formato del cuerpo

TicketBAI valida el tipo de cada campo antes de construir el XML, para que un dato mal tipado sea un 400 inmediato y no un fallo aguas abajo:

• provincia, serie, numero, fechaExpedicion, tipoFactura, emisor.nif y emisor.nombre deben ser cadenas JSON. Un número, null, un array o un objeto devuelve 400 VALIDATION_ERROR nombrando el campo (o 400 INVALID_FIELD_TYPE en anular).
• Las longitudes se comprueban en la entrada, con los máximos del propio XSD de TicketBAI 1.2.2: serie y numero, 20 caracteres cada uno (TextMax20Type); descripcion y lineas[].descripcion, 250; emisor.nombre y destinatario.nombre, 120; destinatario.direccion, 250; destinatario.codigoPostal, 20. Pasarse devuelve 400 VALIDATION_ERROR nombrando el campo y su máximo, sin llegar a firmar.
• Los caracteres #, & y ' se rechazan en serie y numero: Araba los rechaza con el código 004, y lo hace con el documento ya firmado. /, el espacio, Ñ, -, _, ., <, > y " sí se admiten.
• Los campos de texto no pueden contener caracteres de control ilegales en XML. El tabulador y los saltos de línea sí se admiten, y se eliminan al serializar.
• Los campos de texto tampoco admiten entidades XML o HTML ya codificadas (<, �, &…). El escapado del XML lo hace la API, así que ese texto es una doble codificación y devuelve 400 nombrando el campo. Un & suelto dentro de un nombre (Tom & Jerry) es correcto.
• El cuerpo debe ser un objeto JSON. Un array, una cadena, un número o null devuelven 400 BAD_REQUEST.

Retención de IRPF (autónomos)

Una factura corriente de un autónomo con retención lleva tres importes: base 550,00, IVA 115,50 y retención de IRPF 82,50. El campo importeTotal es el importe con IVA, antes de la retención: aquí "665.50", no "583.00". La retención viaja aparte, en retencionSoportada.

Restar el IRPF de importeTotal es el error habitual, y no pasa silenciosamente: el total deja de cuadrar con el desglose y la petición responde 400, indicando que la retención se declara en su propio campo.

Reglas por provincia

Cada hacienda foral valida cosas distintas. La API las comprueba en el alta, para que el error llegue como un 400 inmediato y no como un rechazo foral diferido:

• Araba exige las líneas de detalle: lineas es obligatorio.
• Gipuzkoa exige descripcion en cada línea de desglose.
• Bizkaia opera dentro de Batuz/LROE (el envoltorio lo gestiona la API sin cambios en tu petición) y solo admite ejercicios desde 2024.

desglose y lineas son cosas distintas: el desglose es el resumen fiscal por tipo impositivo; las líneas son los conceptos de la factura. Ninguno se deriva del otro.

Respuesta

200 OK. La factura queda firmada y encadenada en el momento:

{
  "nifEmisor": "B76116342",
  "idFactura": "…",
  "estado": "en_cola",
  "sistemaFiscal": "ticketbai",
  "provincia": "bizkaia",
  "serieNumero": "A12345",
  "tipoFactura": "F1",
  "importeTotal": "121.00",
  "cuotaTotal": "21.00",
  "creadoEn": "2026-04-03T10:00:00Z",
  "idTbai": "TBAI-B76116342-…",
  "urlValidacion": "https://…",
  "qrBase64": "…"
}

• idTbai: el identificador TBAI, generado a partir de la firma.
• estado vale en_cola: firmada y encadenada, pendiente de remisión foral. Estado final en /estado.
• qrBase64 y urlValidacion: el QR TicketBAI, verificable ante la hacienda foral.

Los duplicados son idempotentes: reenviar un alta con la misma identidad devuelve 200 con el registro ya existente, no un error. En la repetición, estado trae el valor de ciclo de vida (registrada, anulada o rectificada) y no se incluyen los campos del QR.

La repetición funciona también con la remisión en curso: si el original ya está firmado pero aún no registrado (o fue rechazado), la respuesta trae la identidad almacenada (idTbai, urlValidacion, el estado de la remisión, p. ej. en_cola o rechazada) más "yaExistente": true. La factura nunca se vuelve a firmar, así que el identificador TBAI es estable entre reintentos. En la ventana breve en que una petición idéntica anterior sigue firmando, la respuesta es 409 INVOICE_SIGNING_IN_FLIGHT: reintenta en unos segundos.

PUT /v1/ticketbai/subsanar

Corrige un registro ya remitido. El cuerpo es el mismo que el de crear con los datos corregidos; la API marca la subsanación automáticamente. Acepta rechazoPrevio (booleano) para declarar un rechazo foral previo.

POST /v1/ticketbai/anular

El cuerpo es plano e incluye provincia, como el alta:

curl -X POST https://sandbox.veribai.com/v1/ticketbai/anular \
  -H "x-api-key: TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "provincia": "bizkaia",
    "nifEmisor": "B76116342",
    "serie": "A",
    "numero": "12345",
    "fechaExpedicion": "03-04-2026"
  }'

from datetime import date

import veribai

client = veribai.Client(api_key="TU_CLAVE", environment="test")

respuesta = client.ticketbai.anular({
    "provincia": "bizkaia",
    "nifEmisor": "B76116342",
    "serie": "A",
    "numero": "12345",
    "fechaExpedicion": date(2026, 4, 3),
})

const respuesta = await fetch("https://sandbox.veribai.com/v1/ticketbai/anular", {
  method: "POST",
  headers: {
    "x-api-key": "TU_CLAVE",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "provincia": "bizkaia",
    "nifEmisor": "B76116342",
    "serie": "A",
    "numero": "12345",
    "fechaExpedicion": "03-04-2026"
  }),
});

if (!respuesta.ok) throw new Error(`VeriBai ${respuesta.status}`);
const datos = await respuesta.json();

Respuesta

{
  "nifEmisor": "B76116342",
  "idFactura": "…",
  "idAnulacion": "…",
  "estado": "en_cola",
  "sistemaFiscal": "ticketbai",
  "provincia": "bizkaia",
  "serie": "A",
  "numero": "12345",
  "fechaExpedicion": "03-04-2026",
  "creadoEn": "2026-04-03T11:00:00Z"
}

La anulación se firma y encadena en el momento, como el alta. No genera QR: es un registro de baja, no una factura.

Repetición idempotente: si la factura ya tiene una anulación registrada o en curso, la respuesta es un 200 con la misma forma (sin creadoEn) más "yaAnulada": true; estado refleja el envío de la anulación previa (registrada o en_cola). Una anulación previamente rechazada no bloquea el reintento.

Errores

Los códigos comunes están en Errores. Específicos de estos endpoints: