API TicketBAI para PHP
Emite facturas TicketBAI en Araba, Bizkaia (Batuz) y Gipuzkoa desde tu aplicación PHP con una librería de código abierto. Tú envías los datos de la factura y Ticketbai WS genera el XML, lo firma, lo encadena, lo envía a la Hacienda foral y te devuelve el identificador TBAI, la URL de cotejo y el QR. No necesitas certificado digital en tu servidor ni conocer el XSD de TicketBAI.
Ver en GitHub Packagist Crear cuenta de pruebas
La misma librería sirve para TicketBAI y Verifactu: la API decide a qué Hacienda enviar según cómo esté dada de alta la empresa emisora. ¿Facturas en territorio común? Mira la API Verifactu para PHP.
Instalación
composer require ticketbaiws/ticketbaiws-phpRequisitos: PHP 7.2 o superior con las extensiones curl y json. No tiene más dependencias.
Necesitas una cuenta de Ticketbai WS. En el área privada, cada empresa tiene un token de test (para https://api-test.ticketbaiws.eus, sin validez fiscal) y un token real (para https://api.ticketbaiws.eus). Empieza siempre en pruebas.
<?php
require 'vendor/autoload.php';
use TicketbaiWS\Client;
$tbai = new Client(
getenv('TBAIWS_TOKEN'), // token de test o real de la empresa
'B89670855', // NIF de la empresa emisora
['entorno' => 'test'] // 'test' o 'real'
);Primera factura
Una factura simplificada (un ticket) es lo más sencillo: no lleva datos del cliente. Los importes de las líneas van sin IVA y total_factura es el total con IVA.
$r = $tbai->crearFactura([
'fecha' => '22/11/2026',
'hora' => '10:30:00',
'serie' => 'T2026',
'numero' => '1024',
'simplificada' => true,
'lineas' => [
['descripcion' => 'Café con leche', 'cantidad' => 2, 'importe_unitario' => 1.3636, 'tipo_iva' => 10, 'tipo_req' => 0],
['descripcion' => 'Pintxo de tortilla', 'cantidad' => 1, 'importe_unitario' => 2.7273, 'tipo_iva' => 10, 'tipo_req' => 0],
],
'total_factura' => 6.0,
]);
if ($r->isSuccess()) {
$identificador = $r->getData('huella_tbai');
$urlCotejo = $r->getData('url');
file_put_contents('qr.png', base64_decode($r->getData('qr')));
} else {
echo $r->getMessageText(); // motivos del error
}Respuesta de la API ($r->toArray()) para una empresa de Gipuzkoa:
{
"result": "OK",
"return": {
"huella_tbai": "TBAI-B89670855-221126-xnW76+AZTkLbM-137",
"qr": "iVBORw0KGgo… (PNG en base64)",
"url": "https://tbai.egoitza.gipuzkoa.eus/qr/?id=TBAI-B89670855-221126-xnW76%2BAZTkLbM-137&s=T2026&nf=1024&i=6&cr=022"
},
"msg": null
}Imprime en la factura el QR y el identificador TBAI. Es obligatorio. Guarda también la URL y el identificador en tu base de datos para poder reimprimirla.
Puedes probar este mismo JSON sin cuenta en el terminal de pruebas. Tienes más casos (intracomunitarias, exportaciones, exentas, recargo de equivalencia…) en los ejemplos de la API: el array PHP es el mismo que el JSON.
Respuestas y errores
Todos los métodos devuelven un objeto TicketbaiWS\Response con el resultado de la API:
| Método | Devuelve |
|---|---|
getResult() | OK, PENDING (aceptada y en cola de envío) o ERROR |
isSuccess() | true con OK o PENDING |
isOk(), isPending(), isError() | — |
getData('campo') | Un campo del resultado (huella_tbai, qr, url…) o todo si no indicas campo |
getMessageText() | Los mensajes de error o avisos en un solo texto, listos para mostrar o guardar |
getMessages() | Los mensajes como lista |
Un rechazo de Hacienda no es una excepción: llega como respuesta con ERROR y los motivos en el mensaje. La librería solo lanza excepciones cuando no hay respuesta que procesar: sin conexión, límite de peticiones superado tras los reintentos automáticos, o textos que no están en UTF-8.
use TicketbaiWS\Exception\TicketbaiWSException;
try {
$r = $tbai->crearFactura($factura);
if ($r->isError()) {
// Error de validación o rechazo de Hacienda: corrige los datos y reenvía
guardarError($factura['serie'], $factura['numero'], $r->getMessageText(' | '));
}
} catch (TicketbaiWSException $e) {
// Sin respuesta de la API: deja la factura en cola y reintenta más tarde
}Si superas el límite de peticiones (HTTP 429), la librería reintenta sola con espera creciente y respeta la cabecera Retry-After.
Estado en Hacienda
La API responde al momento y envía la factura a la Hacienda foral en segundo plano, con reintentos si no responde. Para conocer el resultado final:
- Webhook (recomendado): te avisamos cuando la factura pasa a OK o a ERROR. Mira Webhooks.
- Consulta:
$tbai->consultarFactura($serie, $numero)devuelve el estado engetData('status'). - Envío síncrono: añade
'sincrono' => truea la factura para esperar la respuesta de Hacienda en la misma llamada.
$estado = $tbai->consultarFactura('T2026', '1024');
switch ($estado->getData('status')) {
case 'OK': /* aceptada */ break;
case 'PENDING': /* en cola: vuelve a consultar */ break;
case 'ERROR': echo $estado->getMessageText(); break;
}Los tres territorios
El código es el mismo para Araba, Bizkaia y Gipuzkoa. La API elige la Hacienda por el NIF de la empresa emisora y aplica las diferencias de cada una:
| Araba | Bizkaia (Batuz) | Gipuzkoa | |
|---|---|---|---|
| Dirección y CP del cliente | Obligatorios | Recomendados | Obligatorios |
| Plazo de envío | 24 horas | Hasta el día 25 del mes siguiente al trimestre (31 de enero para el cuarto) | 7 días |
| Autorización a Ticketbai WS | Registro del certificado de dispositivo | Documento de representación | Documento de representación |
| Libro de compras y gastos | — | LROE (lroeRecibidas(), lroeGastosSinFactura()…) | — |
En Bizkaia, las personas físicas con actividad (modelo 140) pueden indicar el epígrafe del IAE en cada factura (epigrafe) o en cada línea. El catálogo de epígrafes está en $tbai->epigrafes().
Factura completa
Factura con los datos del cliente, esperando la respuesta de Hacienda con sincrono:
$r = $tbai->crearFactura([
'fecha' => '22/11/2026',
'hora' => '10:30:00',
'fecha_operacion' => '21/11/2026',
'nif' => 'B12345674',
'nombre' => 'Cliente Ejemplo S.L.',
'direccion' => 'Calle Mayor 1',
'cp' => '01001',
'pais_cliente' => 'ES',
'serie' => 'A2026',
'numero' => '000153',
'simplificada' => false,
'rectificativa' => false,
'tipo_operacion' => 'servicios',
'retencion' => 0,
'lineas' => [
['descripcion' => 'Mantenimiento web — octubre', 'cantidad' => 1, 'importe_unitario' => 120, 'tipo_iva' => 21, 'tipo_req' => 0],
['descripcion' => 'Horas de soporte', 'cantidad' => 3, 'importe_unitario' => 45, 'tipo_iva' => 21, 'tipo_req' => 0],
],
'total_factura' => 308.55,
'sincrono' => true,
]);{
"result": "OK",
"return": {
"huella_tbai": "TBAI-B89670855-221126-7/MDzX9WldYCK-181",
"qr": "iVBORw0KGgo… (PNG en base64)",
"url": "https://tbai.egoitza.gipuzkoa.eus/qr/?id=TBAI-B89670855-221126-7%2FMDzX9WldYCK-181&s=A2026&nf=000153&i=308.55&cr=175"
},
"msg": null
}Rectificativas, subsanación y anulación
Rectificativa
Una rectificativa por diferencias lleva los importes en negativo e indica las facturas que rectifica. Si la factura original no se emitió con Ticketbai WS, añade sus importes (base, cuota, recargo) en cada elemento de rectificadas.
$r = $tbai->crearFactura([
// ...mismos datos de cliente que la factura original
'serie' => 'R2026',
'numero' => '000012',
'rectificativa' => true,
'clave_rectificativa' => 'R1', // R1 a R4; R5 en simplificadas
'tipo_rectificativa' => 'I', // I: por diferencias; S: sustitutiva
'rectificadas' => [
['serie' => 'A2026', 'numero' => '000153', 'fecha' => '03/11/2026'],
],
'lineas' => [
['descripcion' => 'Devolución horas de soporte', 'cantidad' => -1, 'importe_unitario' => 45, 'tipo_iva' => 21, 'tipo_req' => 0],
],
'total_factura' => -54.45,
]);Subsanación (zuzendu)
Si Hacienda devuelve errores o avisos, reenvía la factura con los datos corregidos. La serie, el número y el total deben ser los de la original. En Bizkaia se aplica a las facturas rechazadas por Batuz y conserva la huella y el QR; para cambiar una factura ya aceptada, emite una rectificativa.
$r = $tbai->subsanarFactura($facturaCorregida); // añade 'zuzendu' => trueAnulación
Anula una factura enviada por error. El número no se puede volver a usar.
$r = $tbai->anularFactura('A2026', '000153');
// Con varias facturas de igual serie y número, indica la fecha: anularFactura('A2026', '000153', '03/11/2026')PDF, XML y QR
// PDF de la factura (base64)
file_put_contents('factura.pdf', base64_decode($tbai->pdfFactura('A2026', '000153')->getData()));
// XML enviado y respuesta de Hacienda
$xml = $tbai->xmlFactura('A2026', '000153');
$xml->getData('xml_request');
$xml->getData('xml_response');
// FacturaE 3.2 (base64), con los códigos DIR3 si va a FACe. Solo en producción.
$fe = $tbai->facturae('A2026', '000153', [
'cod_organo_gestor' => 'CODIGO_DIR3_ORGANO',
'cod_unidad_tramitadora' => 'CODIGO_DIR3_UNIDAD',
'cod_oficina_contable' => 'CODIGO_DIR3_OFICINA',
]);El QR de cada factura llega en la respuesta de crearFactura() y de consultarFactura() como PNG en base64, junto con la URL de cotejo que contiene.
Factura electrónica B2B (SPFE)
La Ley Crea y Crece (RD 238/2026 y Orden HAC/1028/2026) obliga a expedir las facturas entre empresas y profesionales en formato electrónico y a informar de su estado: pago, cobro, rechazo o impago. Ticketbai WS envía automáticamente a la SPFE de la AEAT, en UBL, las facturas completas a clientes españoles con NIF que emites con crearFactura(), y descarga cada hora las que recibes de tus proveedores. No tienes que generar el UBL ni conectarte a la AEAT.
Se activa por empresa en el área privada (Factura electrónica B2B) o por API con $cuenta->activarSpfe($nif). Al activarla se envían las facturas desde ese día. Más sobre la factura electrónica B2B.
use TicketbaiWS\Resource\Spfe;
$spfe = $tbai->spfe();
// Facturas recibidas nuevas desde la última sincronización
$r = $spfe->recibidasDesde($ultimoId);
foreach ($r->getData() as $recibida) {
// factura, fecha_factura, nif_emisor, nombre_emisor, base, cuota, total, vencimiento, estado...
$ultimoId = $recibida['id'];
}
// Pago o rechazo de una recibida: se le pasa la fila tal cual
$spfe->pago($recibida, '10/11/2026', $recibida['vencimiento']);
$spfe->rechazo($recibida, Spfe::RECHAZO_COMERCIAL);
// Cobro o impago de una factura que has emitido
$spfe->cobro('A2026', '000153', '10/11/2026');
$spfe->impago('A2026', '000153', '03/12/2026');
// Resultado de cada estado: PENDING (en cola), OK o ERROR
$spfe->estados(['serie' => 'A2026']);Los estados se envían a la AEAT en cola; añade 'sincrono' => true en las opciones para esperar su respuesta. Si la AEAT no permite consultar las recibidas (falta el certificado de la empresa o el apoderamiento), getMessageText() lo avisa.
LROE de Batuz (Bizkaia)
Las facturas emitidas van al LROE automáticamente. Para el resto de libros, cada uno tiene alta(), modificar(), consultar() y anular():
| Libro | Método |
|---|---|
| Facturas recibidas (compras) | $tbai->lroeRecibidas() |
| Gastos sin factura (modelo 140, apartado 2.2) | $tbai->lroeGastosSinFactura() |
| Criterio de caja: cobros | $tbai->lroeCriterioCajaCobros() |
| Criterio de caja: pagos | $tbai->lroeCriterioCajaPagos() |
// Cuota de autónomos y comisión bancaria de septiembre
$r = $tbai->lroeGastosSinFactura()->alta([
'ejercicio' => 2026,
'gastos' => [
['fecha_operacion' => '30/09/2026', 'concepto' => '64201', 'epigrafe' => '165140', 'linea' => 1, 'importe' => 294.00],
['fecha_operacion' => '30/09/2026', 'concepto' => '626', 'epigrafe' => '165140', 'linea' => 1, 'importe' => 12.50],
],
]);
// Compras de un proveedor en el ejercicio
$compras = $tbai->lroeRecibidas()->consultar(['ejercicio' => 2026, 'nif' => 'B01000012']);Autorización ante Hacienda
Para enviar en producción con el certificado de Ticketbai WS, cada empresa nos autoriza una vez. En Bizkaia y Gipuzkoa se firma un documento de representación, que puedes gestionar desde tu aplicación. En Araba se registra el certificado de dispositivo en la sede de la Diputación (guía de registro).
// 1. Modelo en PDF (para personas jurídicas, con los datos del representante legal)
$modelo = $tbai->modeloDocRepresentante([
'nombre_representante' => 'Ane Etxeberria Goikoetxea',
'nif_representante' => '12345678Z',
'poblacion_representante' => 'Bilbao',
'direccion_representante' => 'Calle Mayor 1',
]);
file_put_contents('representacion.pdf', base64_decode($modelo->getData()));
// 2. Firmado con certificado reconocido (FNMT, Izenpe...), se sube
$tbai->enviarDocRepresentante('representacion-firmada.pdf');También se puede firmar y subir desde el área privada. Si la empresa prefiere usar su propio certificado, lo carga allí y no necesita el documento.
Webhooks
Recibe un aviso cada vez que cambia el estado de una factura (cambio_estado) y, si usas la factura electrónica B2B, del envío a la SPFE (spfe_envio), de cada pago o cobro comunicado (spfe_estado) y de cada factura recibida (spfe_recibida). Los webhooks de pruebas y de producción son independientes: crea uno en cada entorno.
$w = $tbai->crearWebhook('https://tu-web.com/tbaiws-aviso.php', 'un-secret-largo-y-aleatorio', false, true, \TicketbaiWS\Webhook::EVENTOS);
$codigo = $w->getData('codigo');
// Solo avisos de errores
$tbai->modificarWebhook($codigo, ['solo_errores' => true]);En el receptor, la librería comprueba la firma HMAC-SHA256 (cabecera X-Tbaiws-Hmac-Sha256) antes de que proceses nada:
<?php // tbaiws-aviso.php
require 'vendor/autoload.php';
use TicketbaiWS\Webhook;
use TicketbaiWS\Exception\WebhookException;
try {
$aviso = Webhook::recibir('un-secret-largo-y-aleatorio');
} catch (WebhookException $e) {
http_response_code(401); // firma no válida
exit;
}
$aviso['evento']; // cambio_estado, spfe_envio, spfe_estado o spfe_recibida
$aviso['entorno']; // 'test' o 'real'
$aviso['datos']; // contenido del aviso
http_response_code(200);Con Laravel o Symfony, pasa el cuerpo y las cabeceras de la petición: Webhook::recibir($secret, $request->getContent(), $request->headers->all()).
Integradores: empresas por API
Si tu software factura para muchas empresas (ERP, TPV, gestorías), puedes darlas de alta y gestionar sus licencias desde tu código con TicketbaiWS\Cuenta. Usa el token de desarrollador y el NIF de tu cuenta del área privada, no los de una empresa. Estos métodos solo existen en producción.
use TicketbaiWS\Cuenta;
use TicketbaiWS\Diputacion;
$cuenta = new Cuenta(getenv('TBAIWS_TOKEN_DESARROLLADOR'), getenv('TBAIWS_NIF_CUENTA'));
$r = $cuenta->crearEmpresa([
'nombre_social' => 'Mi Cliente S.L.',
'nif' => 'B89670855',
'direccion' => 'Calle Mayor 1',
'poblacion' => 'Donostia',
'provincia' => 'Gipuzkoa',
'cp' => '20001',
'diputacion' => Diputacion::GIPUZKOA, // ARABA, BIZKAIA, GIPUZKOA o VERIFACTU
]);
// $r->getData() incluye los tokens de test y real de la nueva empresa
$cuenta->editarEmpresa('B89670855', ['email' => 'facturas@micliente.com']);
$cuenta->listarEmpresas();¿Integras a muchos clientes? Escríbenos para condiciones de partner.
Referencia de métodos
Método de Client | Endpoint |
|---|---|
crearFactura(array $factura) | POST /tbai/ |
subsanarFactura(array $factura) | POST /tbai/ con zuzendu |
consultarFactura($serie, $numero) | GET /tbai/ |
anularFactura($serie, $numero, $fecha = null) | DELETE /tbai/ |
listarFacturas(array $filtros) | GET /tbai-list/ |
completarFactura(array $datos) | POST /tbai-completar/ |
pdfFactura(), xmlFactura(), facturae() | GET /tbai-pdf/, /tbai-xml/, /facturae/ (FacturaE solo en producción) |
reenviarFactura($serie, $numero) | PUT /reset-tbai/ |
estado(), estaOperativo() | GET /status/ |
validarNif(), validarNifVies() | POST /validar-nif/, /validar-nif-vies/ |
modeloDocRepresentante(), enviarDocRepresentante(), descargarDocRepresentante(), revocarDocRepresentante() | /doc-representante/ |
lroeRecibidas(), lroeGastosSinFactura(), lroeCriterioCajaCobros(), lroeCriterioCajaPagos(), epigrafes() | LROE de Batuz (solo Bizkaia) |
spfe()->pago(), rechazo(), cobro(), impago(), comunicarEstado(), anularEstado(), estados() | /spfe-estados/ (factura electrónica B2B) |
spfe()->recibidas(), recibidasDesde() | GET /spfe-recibidas/ |
crearWebhook(), modificarWebhook(), listarWebhooks() | /webhooks/ |
peticion($metodo, $ruta, array $datos) | Cualquier otro método del API |
Opciones del constructor: entorno (test, real o una URL), timeout (60 s), verificar_ssl (true), reintentos_429 (3) y transport (tu propio cliente HTTP, por ejemplo para tests). Todos los campos de cada método están en la documentación del API y en la especificación OpenAPI.
Clase de un solo fichero
¿Tu proyecto no usa Composer o ya usas la clase class_ticketbaiwsclient? Sigue incluida en el paquete, actualizada, en legacy/class_ticketbaiwsclient.php. Basta con un require:
require 'class_ticketbaiwsclient.php';
$tbai = new class_ticketbaiwsclient(class_ticketbaiwsclient::URL_PRUEBAS, $token, 'B89670855');
$return = $tbai->nuevo_tbai($factura);
if ($tbai->get_last_result() === 'ERROR') {
echo is_array($return) ? implode("\n", $return) : $return;
}Con Composer, la clase antigua se carga sola junto a la nueva, así que puedes migrar poco a poco. La tabla de equivalencias está en el README.
Preguntas frecuentes
¿El mismo código sirve para Araba, Bizkaia y Gipuzkoa?
Sí. La API sabe a qué Hacienda foral enviar por el NIF de la empresa emisora. Solo cambian algunos requisitos, como la dirección y el código postal del cliente, obligatorios en Araba y Gipuzkoa.
¿Y si mañana tengo clientes en territorio común (Verifactu)?
El código es el mismo: la empresa se da de alta como Verifactu y la librería envía las facturas a la AEAT sin cambios en tu aplicación.
¿Necesito un certificado digital en mi servidor?
No. Ticketbai WS firma las facturas con su certificado (con tu autorización de representación) o con el tuyo si lo subes al área privada. Tu servidor solo hace peticiones HTTPS.
¿Qué versiones de PHP admite la librería?
De PHP 7.2 a 8.5. Solo necesita las extensiones curl y json, sin otras dependencias.
¿Funciona con Laravel, Symfony, WordPress o PrestaShop?
Sí. Es una librería PHP sin dependencias que se instala con Composer. Si tu proyecto no usa Composer, puedes incluir el fichero único legacy/class_ticketbaiwsclient.php.
¿Puedo usar la librería en software comercial?
Sí. Tiene licencia MIT: puedes usarla, modificarla y distribuirla en proyectos propietarios.
