API Verifactu para PHP
Envía tus facturas a la AEAT con Verifactu 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 registro de facturación, calcula la huella, lo encadena, lo remite a la Agencia Tributaria y te devuelve la huella, la URL de cotejo y el QR. No necesitas certificado digital en tu servidor ni implementar el servicio web de la AEAT.
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. ¿Tienes clientes en el País Vasco? Mira la API TicketBAI 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');
$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()):
{
"result": "PENDING",
"return": {
"huella": "C675BBEBE0194E42DB3337353B1D276014283164D4D9E9231DBDFC4C13B55123",
"qr": "iVBORw0KGgo… (PNG en base64)",
"url": "https://www2.agenciatributaria.gob.es/wlpl/TIKE-CONT/ValidarQR?nif=B89670855&numserie=T20261024&fecha=22-11-2026&importe=6.00"
},
"msg": null
}Imprime en la factura el QR y la leyenda «VERI*FACTU». El QR ya es válido aunque la respuesta sea PENDING: la factura está registrada y en cola de envío a la AEAT.
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, 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 AEAT 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;
}Particularidades de Verifactu
- Respuesta
PENDING. Sinsincrono, la API registra la factura, calcula la huella y la encadena al momento, y la envía a la AEAT en segundo plano. Para tu aplicación es un éxito (isSuccess()). - Identificador: el campo es
huella(en TicketBAI,huella_tbai). Si tu aplicación sirve para los dos sistemas, usa$r->getData('huella_tbai') ?: $r->getData('huella'). - Clientes personas físicas: la AEAT comprueba que el nombre y el NIF coincidan con su censo. Valídalos antes de emitir con
validarNif()(solo en producción). - Clientes de la UE: comprueba el NIF-IVA con
validarNifVies($nif, $pais).
$v = $tbai->validarNif('12345678Z', 'MARTINEZ RODRIGUEZ JUAN');
if ($v->getData('resultado') !== 'IDENTIFICADO') {
// Pide al cliente que revise su nombre y NIF antes de emitir la factura
}Factura completa
Factura con los datos del cliente, esperando la respuesta de la AEAT 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": "EFF303CD7F5695D6022B63DA12D650A7C31D3D20888B75B7B1E9CECFE3D1220B",
"qr": "iVBORw0KGgo… (PNG en base64)",
"url": "https://www2.agenciatributaria.gob.es/wlpl/TIKE-CONT/ValidarQR?nif=B89670855&numserie=A2026000153&fecha=22-11-2026&importe=308.55"
},
"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
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.
$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.
Autorización ante Hacienda
Para enviar en producción con el certificado de Ticketbai WS, cada empresa firma una vez un documento de representación. Puedes gestionarlo desde tu aplicación:
// 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' => 'Madrid',
'provincia' => 'Madrid',
'cp' => '28001',
'diputacion' => Diputacion::VERIFACTU, // 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
¿Por qué la respuesta es PENDING?
En Verifactu la API acepta la factura, calcula la huella y la deja en cola para enviarla a la AEAT. Puedes imprimir ya el QR. El resultado final te llega por webhook o con consultarFactura(); si quieres esperar a la AEAT en la misma llamada, añade sincrono: true.
¿El mismo código sirve para TicketBAI?
Sí. Si tienes clientes en Araba, Bizkaia o Gipuzkoa, la API envía sus facturas a la Hacienda foral que corresponde según el NIF emisor, sin cambios en tu código.
¿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.
