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.

Esta página recorre la factura completa. Un cuerpo por cada tipo de factura (simplificada, exenta, intracomunitaria, con recargo, con retención, rectificativa) está en Ejemplos (TicketBAI).

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": "B00000000",
      "nombre": "Prueba 1 SL"
    },
    "destinatario": {
      "nif": "B11111119",
      "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": "B00000000",
        "nombre": "Prueba 1 SL",
    },
    "destinatario": {
        "nif": "B11111119",
        "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": "B00000000",
      "nombre": "Prueba 1 SL"
    },
    "destinatario": {
      "nif": "B11111119",
      "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, obligatorios en cada línea; `descuento` en euros, opcional). Obligatorio en Araba; opcional en el resto. Máximo 250 líneas por factura. Ver líneas de detalle.
`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": "B00000000",
  "idFactura": "…",
  "estado": "en_cola",
  "sistemaFiscal": "ticketbai",
  "provincia": "bizkaia",
  "numSerieFactura": "A12345",
  "serie": "A",
  "numero": "12345",
  "tipoFactura": "F1",
  "importeTotal": "121.00",
  "cuotaTotal": "21.00",
  "creadoEn": "2026-04-03T10:00:00Z",
  "idTbai": "TBAI-B00000000-…",
  "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.