Crear factura (TicketBAI)

Alta de una factura TicketBAI ante la hacienda foral que corresponda, con firma y encadenado inmediatos.

Da de alta una factura TicketBAI con una petición a:

POST /v1/ticketbai/crear

Tres diferencias respecto a VeriFactu:

Los campos serie, numero y fechaExpedicion viajan en el nivel superior del JSON, no dentro de cabecera.
El campo provincia es obligatorio y selecciona la hacienda foral, y con ella las reglas de validación y el destino del envío.
El desglose fiscal es la lista plana desglose (baseImponible, tipoImpositivo, cuota), y el total viaja como importeTotal en el nivel superior. No hay bloque totales.

Petición

POST/v1/ticketbai/crear

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": "Descripcion de la factura",
    "emisor": {
      "nif": "B76116342",
      "nombre": "Prueba 1 SL"
    },
    "destinatario": {
      "nif": "B17195595",
      "nombre": "Nombre cliente, SL"
    },
    "desglose": [
      {
        "baseImponible": "100.00",
        "tipoImpositivo": "21.00",
        "cuota": "21.00"
      }
    ],
    "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": "Descripcion de la factura",
    "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"),
        },
    ],
    "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": "Descripcion de la factura",
    "emisor": {
      "nif": "B76116342",
      "nombre": "Prueba 1 SL"
    },
    "destinatario": {
      "nif": "B17195595",
      "nombre": "Nombre cliente, SL"
    },
    "desglose": [
      {
        "baseImponible": "100.00",
        "tipoImpositivo": "21.00",
        "cuota": "21.00"
      }
    ],
    "importeTotal": "121.00"
  }),
});

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

Campos específicos de TicketBAI

Campo	Notas
`provincia`	Obligatorio: `araba`, `bizkaia` o `gipuzkoa`. Determina la hacienda foral de destino.
`desglose`	Obligatorio, mínimo una línea: `baseImponible`, `tipoImpositivo` y `cuota`. En Gipuzkoa, cada línea exige además `descripcion`.
`importeTotal`	Total de la factura, IVA incluido, en el nivel superior.
`lineas`	Líneas de detalle de la factura (`descripcion`, `importeUnitario` sin IVA, `importeTotal` con IVA). Obligatorio en Araba; opcional en el resto. Máximo 250 líneas por factura.
`idMaquina`	Opcional. Identificador del dispositivo o TPV emisor. Ver Alta capacidad si emites desde muchos dispositivos a la vez.

Los tipos de factura y las reglas de destinatario (obligatorio salvo en F2 y R5) siguen las de VeriFactu, y las reglas de fecha (formato, no-futuro, fecha de operación) están en Fechas de la factura. El contrato completo, campo a campo, está en la referencia TicketBAI.

Bizkaia y el LROE

Los envíos a la Hacienda Foral de Bizkaia se realizan dentro del envoltorio LROE del sistema Batuz. La API lo gestiona por completo: el contrato de la petición no cambia.

Respuesta

200 OK. En TicketBAI, la firma y el encadenado se completan en el momento del alta, por lo que la respuesta incluye el identificador TBAI:

{
  "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 de la factura, generado a partir de la firma.
estado: en_cola. El registro está firmado y encadenado; la remisión a la hacienda foral se completa en segundo plano.
qrBase64 y urlValidacion: el QR TicketBAI, verificable ante la hacienda foral correspondiente.