AEATPHP 7.2 – 8.5ComposerMIT

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-php

Requisitos: 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étodoDevuelve
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 en getData('status').
  • Envío síncrono: añade 'sincrono' => true a 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. Sin sincrono, 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' => true

Anulació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 ClientEndpoint
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.

Crear cuenta de pruebas Guía rápida