TicketBAI en País Vasco: Bizkaia, Gipuzkoa y Álava/Araba
TicketBAI es el sistema de facturación electrónica obligatorio en los tres territorios forales del País Vasco. Cada Diputación Foral tiene su propia plataforma de recepción, sus propios endpoints y sus propias fechas de entrada en vigor. Frihet soporta los tres territorios con detección automática por código postal.
Por qué hay tres sistemas distintos
Los territorios forales vascos tienen autonomía fiscal plena. Bizkaia, Gipuzkoa y Álava/Araba diseñaron sistemas técnicamente compatibles (mismo estándar XAdES, mismo encadenamiento SHA-256, mismo QR) pero con infraestructura de recepción separada. Que tu empresa esté en Bilbao o en Vitoria-Gasteiz determina a qué Hacienda Foral debes reportar y qué endpoint usa Frihet para el envío.
Detección automática por código postal
Frihet identifica el territorio foral a partir del código postal de tu perfil fiscal:
| Prefijo | Territorio | Sistema | Hacienda Foral |
|---|---|---|---|
48xxx | Bizkaia | BATUZ | Hacienda Foral de Bizkaia |
20xxx | Gipuzkoa | TicketBAI Gipuzkoa | Hacienda Foral de Gipuzkoa |
01xxx | Álava/Araba | TicketBAI Álava | Hacienda Foral de Álava |
Si tu código postal no comienza con ninguno de estos prefijos, la sección TicketBAI no aparece en Configuración. Navarra (31xxx) tiene su propio sistema con normativa de la Hacienda Foral de Navarra y no está incluida en esta versión.
Estructura de cada factura TicketBAI
Independientemente del territorio, cada factura TicketBAI contiene los mismos elementos obligatorios:
- XML firmado con XAdES-BES usando el certificado digital del contribuyente
- Hash SHA-256 encadenado con la factura inmediatamente anterior (
emisor|serie|numero|fecha|importe|hashAnterior) - Identificador TBAI asignado por la Hacienda Foral tras validar el envío
- Código QR generado a partir del TBAI real (nunca fabricado internamente)
El encadenamiento es inviolable: si un registro se altera, toda la cadena posterior queda invalidada.
Bizkaia — BATUZ
BATUZ es el sistema de Hacienda Foral de Bizkaia. A diferencia de Gipuzkoa y Álava, usa SOAP con cabeceras HTTP personalizadas en lugar de REST.
Endpoints
| Entorno | URL |
|---|---|
| Sandbox | https://pruebasarqueo.bizkaia.eus/N3B4000M/aurkezpena |
| Producción | https://sarrerak.bizkaia.eus/N3B4000M/aurkezpena |
Cabeceras específicas de BATUZ
El servicio SOAP de Bizkaia exige cabeceras HTTP propias que otros sistemas no usan:
eus-bizkaia-n3-version: 1.0
eus-bizkaia-n3-idoperacion: {UUID único por envío}
eus-bizkaia-n3-nif: {NIF del emisor}
eus-bizkaia-n3-tipoComunicacion: A00
Content-Type: application/octet-stream; charset=UTF-8
Frihet gestiona estas cabeceras de forma automática en su Cloud Function de envío BATUZ. No es necesaria ninguna configuración adicional.
Respuesta esperada
BATUZ devuelve un resultado SOAP con:
CSV— Código Seguro de Verificación para el contribuyenteIdentificadorTBAI— identificador único de la factura en BizkaiaEstado—Correcto,AceptadoConErroresoIncorrecto
Frihet almacena el CSV e IdentificadorTBAI en Firestore bajo invoices/{id}/tbai/submission y genera el QR a partir del IdentificadorTBAI real. Si BATUZ devuelve un estado de error, la factura queda marcada como pendiente de corrección.
Fechas de obligatoriedad en Bizkaia
| Colectivo | Desde |
|---|---|
| Grandes contribuyentes (> €6M cifra negocio) | 1 enero 2022 |
| Resto de empresas y autónomos | 1 enero 2023 |
| Software de facturación (cumplimiento técnico) | 1 enero 2022 |
Gipuzkoa — TicketBAI REST
La Hacienda Foral de Gipuzkoa usa una API REST en lugar de SOAP, lo que simplifica la integración técnica.
Endpoints
| Entorno | URL |
|---|---|
| Sandbox | https://tbai-z.prep.gipuzkoa.eus/sarrerak/alta |
| Producción | https://tbai-z.egoitza.gipuzkoa.eus/sarrerak/alta |
Método de envío
POST /sarrerak/alta
Content-Type: application/xml; charset=UTF-8
Authorization: {certificado de cliente en mTLS}
El cuerpo es el XML TicketBAI firmado con XAdES-BES. La respuesta devuelve el IdentificadorTBAI y el estado de validación en JSON.
Fechas de obligatoriedad en Gipuzkoa
| Colectivo | Desde |
|---|---|
| Contribuyentes en módulos | 1 enero 2022 |
| Autónomos en estimación directa simplificada | 1 octubre 2022 |
| Sociedades y autónomos restantes | 1 julio 2023 |
Álava/Araba — TicketBAI REST
La Hacienda Foral de Álava también usa REST, con estructura similar a Gipuzkoa pero dominio propio.
Endpoints
| Entorno | URL |
|---|---|
| Sandbox | https://pruebas-ticketbai.araba.eus/TicketBAI/v1/facturas/ |
| Producción | https://ticketbai.araba.eus/TicketBAI/v1/facturas/ |
Método de envío
POST /TicketBAI/v1/facturas/
Content-Type: application/xml; charset=UTF-8
La respuesta incluye el estado de validación y el IdentificadorTBAI para las facturas aceptadas.
Fechas de obligatoriedad en Álava
| Colectivo | Desde |
|---|---|
| Grandes empresas (> €6M) | 1 enero 2022 |
| Resto de contribuyentes con actividad económica | 1 enero 2023 |
Certificado digital BYOC
TicketBAI exige firma con el certificado del contribuyente, no con un certificado de servicio. Frihet implementa un modelo Bring Your Own Certificate (BYOC):
- Ve a Configuración → TicketBAI → Certificado digital.
- Sube el archivo
.p12o.pfxcon la contraseña del certificado. - Frihet cifra el certificado con AES-256-GCM y lo almacena en Firestore. La clave de cifrado no sale del entorno de Cloud Functions.
- En cada envío, Frihet descifra el certificado en memoria, firma el XML y lo descarta sin persistir la forma descifrada.
El certificado válido para TicketBAI puede ser:
- FNMT — Fábrica Nacional de Moneda y Timbre (personas físicas y jurídicas)
- Izenpe — Autoridad de certificación vasca (recomendado para contribuyentes forales)
- Otros certificados reconocidos por las Haciendas Forales (ACCV, ANF, Camerfirma)
Los certificados para personas jurídicas caducan. Frihet muestra un aviso 30 días antes. Una firma con certificado caducado es rechazada por la Hacienda Foral con error irrecuperable. Renueva el certificado antes de la caducidad y actualízalo en Configuración.
Probar en sandbox
El sandbox permite verificar la integración sin efectos fiscales:
- Ve a Configuración → TicketBAI.
- La sección solo aparece si tu código postal es de un territorio foral (48xxx, 20xxx, 01xxx).
- Haz clic en Probar sandbox para enviar una factura de prueba al entorno de test de tu Hacienda Foral.
- El resultado muestra el CSV de verificación y el IdentificadorTBAI si la prueba es exitosa.
En sandbox puedes enviar sin certificado real para verificar el formato XML y la conectividad. Para producción, el certificado es obligatorio.
Pipeline técnico en Frihet
Frihet ejecuta el pipeline TicketBAI en Cloud Functions (europe-west1):
- Construcción del XML — TicketBAI v1.2 conforme al esquema XSD de la Hacienda Foral correspondiente
- Firma XAdES-BES — con el certificado BYOC descifrado en memoria
- Encadenamiento SHA-256 — calcula
hashAnteriordel último registro de la misma serie - Detección de territorio — enruta al endpoint correcto (BATUZ SOAP, Gipuzkoa REST, Álava REST)
- Envío y validación — recibe CSV + IdentificadorTBAI
- Generación del QR — a partir del IdentificadorTBAI real devuelto por la Hacienda
- Persistencia — CSV, QR, hash y estado guardados en Firestore
Si el envío falla, la factura queda en estado pendiente_tbai y Frihet reintenta automáticamente con backoff exponencial.
Verificación del estado vía MCP
Si usas el servidor MCP de Frihet, la herramienta ticketbai_status devuelve el estado actual de cualquier factura:
ticketbai_status(invoiceId: string)
→ { invoiceId, status, csv, qrUrl, province, tbaiIdentifier, submittedAt }
status puede ser: submitted, accepted, rejected, pending, no_submission_yet.
Preguntas frecuentes
¿Es lo mismo TicketBAI que VeriFactu? No. VeriFactu es el sistema de la AEAT para el resto de España. TicketBAI es el sistema de las Haciendas Forales vascas. Si tu empresa está en el País Vasco, usas TicketBAI. Ambos sistemas coexisten pero son independientes y no intercambian datos entre sí.
¿Qué pasa si mi empresa tiene sedes en Bizkaia y en Madrid? Las facturas emitidas desde el establecimiento permanente en Bizkaia van a BATUZ. Las emitidas desde Madrid van a VeriFactu (AEAT). Frihet gestiona ambos sistemas en función del perfil fiscal activo en cada factura.
¿Funciona TicketBAI para autónomos? Sí. El sistema es obligatorio para cualquier contribuyente con actividad económica en territorio foral, ya sea persona física (autónomo) o jurídica (empresa). Los tipos de documento y las series de numeración aplicables son los mismos.
¿El sandbox usa datos reales? No. El sandbox de cada Hacienda Foral es un entorno de pruebas aislado. Los identificadores TBAI generados en sandbox no tienen validez fiscal y no aparecen en los registros de la Hacienda.
¿Cuándo estará disponible el modo producción? El botón de activación en producción requiere que hayas subido un certificado digital válido en Configuración. Una vez subido, el sistema activa automáticamente el envío real a la Hacienda Foral correspondiente.
Referencias oficiales
- BATUZ (Bizkaia): https://www.batuz.eus
- Hacienda Foral de Gipuzkoa: https://www.gipuzkoa.eus/es/hacienda/ticketbai
- Hacienda Foral de Álava: https://www.araba.eus/es/hacienda/ticketbai
- Especificación TicketBAI: https://www.ticketbai.eus
- Izenpe (certificación vasca): https://www.izenpe.eus