API TicketBAI para las tres haciendas forales
Araba, Bizkaia y Gipuzkoa con una sola integración. La API firma, encadena y remite el registro, y devuelve el identificador TBAI y el código QR en la misma respuesta.
- Validación previa al envío
- QR y URL de verificación
- Firma (XAdES, SHA) y encadenado
- Envío a AEAT o Haciendas Forales
- Notificación por Webhook
- Factura Registrada
Empresas que ya emiten con VeriBai
Tres administraciones, un campo en la petición.
Cada hacienda foral tiene sus reglas de validación y su destino de envío. En tu integración la diferencia es el valor de provincia: el resto de la petición es idéntico.
Araba · Álava
"provincia": "araba"
El registro llega a la Hacienda Foral de Araba directamente, firmado y encadenado. Es la única de las tres que exige las líneas de detalle de la factura.
Bizkaia
"provincia": "bizkaia"
El envío viaja dentro del envoltorio LROE del sistema Batuz. La API lo construye por completo y el contrato de tu petición no cambia.
Gipuzkoa
"provincia": "gipuzkoa"
El registro llega a la Hacienda Foral de Gipuzkoa directamente, y su acuse devuelve el identificador TBAI de la factura.
TicketBAI ya es obligatorio en las tres provincias. Fuera de ellas se aplica VeriFactu ante la AEAT, y un software con clientes a un lado y otro necesita los dos sistemas: en VeriBai, la misma cuenta y la misma clave.
El contrato, en una llamada.
El identificador TBAI y el código QR vuelven en la respuesta del alta, porque la firma ya está hecha. Sin SDK obligatorio y sin certificados propios. Los ejemplos van recortados; el contrato campo a campo vive en la documentación.
Petición
POST /v1/ticketbai/crear
x-api-key: …
{
"version": "1.0",
"provincia": "gipuzkoa",
"serie": "A", "numero": "882",
"fechaExpedicion": "03-04-2026",
"tipoFactura": "F1",
"emisor": { "nif": "B76116342", … },
"lineas": [
{ "descripcion": "Consultoría",
"cantidad": "1",
"importeUnitario": "100.00",
"importeTotal": "121.00" }
],
"desglose": [
{ "baseImponible": "100.00",
"tipoImpositivo": "21.00", … }
],
"importeTotal": "121.00"
}Respuesta
// 200 OK
{
"idFactura": "…",
"estado": "en_cola",
"sistemaFiscal": "ticketbai",
"provincia": "gipuzkoa",
"idTbai": "TBAI-B76116342-0304…",
"urlValidacion": "https://…",
"qrBase64": "…"
}Webhook
// factura.registrada
{
"evento": "factura.registrada",
"datos": {
"estadoFactura": "registrada",
"provincia": "gipuzkoa",
"idRegistroTbai": "TBAI-B761…"
}
}Lo que ocurre en cada llamada.
Validación por provincia
El campo provincia selecciona la hacienda foral y con ella sus reglas. Los errores se detectan antes del envío, no en la remisión.
Firma XAdES con el certificado de VeriBai
Cada registro se firma y queda enlazado con el anterior del mismo emisor. Ni tú ni tus clientes gestionáis certificados.
Identificador TBAI y código QR
Ambos se derivan de la firma, así que llegan en la misma respuesta del alta, listos para la factura.
Envío a la hacienda foral
Por HTTPS a la administración que corresponda, con colas de reintento. En Bizkaia, dentro del envoltorio LROE.
Confirmación por webhook
Cuando la hacienda foral confirma el registro, tu sistema recibe un POST firmado con HMAC.
Qué incluye la integración.
Las tres provincias, un registro
Araba, Bizkaia y Gipuzkoa con la misma integración y la misma clave. La provincia es un campo de la petición.
Batuz y el envoltorio LROE
El libro registro de Bizkaia lo construye la API. Tu petición es idéntica a la de las otras dos provincias.
Subsanación y anulación
Endpoints propios para corregir un registro ya remitido o para retirar el que no debió existir.
La misma cuenta que VeriFactu
Clientes en territorio común y en el foral conviven en una cuenta. El sistema lo decide el endpoint al que llamas.
Alta de emisores por API
Cada NIF con su propia cadena de registros, con numeración y encadenado independientes de los demás.
Evidencia durante siete años
El XML firmado y el código QR de cada registro, archivados y disponibles por API o desde el panel.
Sin certificados que gestionar.
VeriBai está registrado como Software Garante ante las haciendas forales de Araba, Bizkaia y Gipuzkoa, con un registro único válido en las tres. Nuestro certificado firma cada registro y lo remite a la hacienda que corresponda, así que ni tú ni tus clientes tenéis que solicitar, instalar ni renovar certificados digitales.
Tu única tarea es una firma. Cada hacienda foral exige su propio documento: el mandato de representación en Araba, el Anexo II en Gipuzkoa y el modelo R32 en Bizkaia. La API genera el que corresponde, listo para firmar, y cada emisor lo firma una vez.
Cómo funciona la representaciónLa acreditación de VeriBai como software garante ante las tres haciendas forales y una única firma tuya, el modelo de representación, convergen en el certificado de VeriBai, que firma y remite cada registro: el resultado es cada factura firmada y remitida.
VeriBai · Registrado
Software Garante
Registro único ante Araba, Bizkaia y Gipuzkoa
Tú · una vez
Modelo de Representación
Mandato TicketBAI, Anexo II (DFG) o modelo R32 (DFB)
Certificado de VeriBai
Emitido, custodiado y renovado por nosotros.
Factura A-882
Tu cliente, S.L.
firmada y remitida
Una acreditación nuestra y una firma tuya: todo lo que hace falta para que cada registro salga firmado y remitido a su hacienda foral.
Lo que cuesta.
TicketBAI y VeriFactu están en todos los planes de pago, al mismo precio y con la misma clave. El entorno Sandbox es gratuito, sin límite de tiempo y sin tarjeta. En producción el precio va por NIF activo: desde 16 € al mes por NIF en el plan Esencial. Sin coste de alta ni permanencia.
Lo que dicen los equipos que ya están en producción.
Vending«Hemos integrado las más de 5.000 máquinas de nuestros clientes en menos de dos semanas. La documentación y el soporte han sido extraordinarios.»
B2B Ecommerce«Queríamos llegar a 2027 con VeriFactu resuelto y capaz de gestionar los miles de facturas que emitimos cada mes. La integración fue cuestión de días.»
«Hemos integrado las más de 5.000 máquinas de nuestros clientes en menos de dos semanas. La documentación y el soporte han sido extraordinarios.»
«Queríamos llegar a 2027 con VeriFactu resuelto y capaz de gestionar los miles de facturas que emitimos cada mes. La integración fue cuestión de días.»
Preguntas sobre la API TicketBAI.
Para tu integración, un campo. La petición lleva provincia con valor araba, bizkaia o gipuzkoa, y eso determina la hacienda foral de destino y sus reglas de validación. Araba y Gipuzkoa reciben el registro directamente. Bizkaia lo recibe dentro del envoltorio LROE del sistema Batuz, que gestiona la API sin cambios en tu petición.
Un 200 con el identificador TBAI de la factura, el código QR en base64, su URL de verificación ante la hacienda foral y el estado en_cola. El identificador y el QR se derivan de la firma, que ya está hecha cuando responde la API. El contrato completo está en Crear factura (TicketBAI).
VeriBai está registrado como software garante ante las haciendas forales de Araba, Bizkaia y Gipuzkoa, con un registro único válido en las tres. Los registros TicketBAI salen firmados con el certificado de VeriBai. Tu software envía los datos de la factura por la API y recibe el QR y el identificador TBAI.
No. Es la misma cuenta, la misma clave API y el mismo flujo. El sistema lo decide el endpoint al que llamas: POST /v1/ticketbai/crear o POST /v1/verifactu/crear. Un mismo software puede tener clientes en territorio común y en el foral sin mantener dos integraciones. Ver ¿VeriFactu o TicketBAI?.
XAdES, con el certificado de VeriBai, y cada registro queda encadenado con el anterior del mismo emisor. La firma se hace antes de responder a tu petición, de ahí que el identificador TBAI y el QR lleguen en la misma respuesta. Ver El registro de facturación.
Batuz es el sistema de la Hacienda Foral de Bizkaia, y TicketBAI es una de sus piezas: allí el registro viaja dentro del envoltorio LROE, el libro registro de Batuz. La API lo construye por completo, así que tu petición es la misma que en Araba o en Gipuzkoa. Lo que sí cambia está en el alta del emisor: un autónomo con hacienda tbai-bizkaia necesita su epígrafe IAE del Modelo 140, validado contra el catálogo oficial. Bizkaia admite además solo ejercicios desde 2024. Ver Clientes (emisores).
Tú construyes el producto.
Del cumplimiento nos ocupamos nosotros. Cuenta gratuita, entorno de pruebas completo, producción cuando tú decidas.