Verifactu en FacturaScripts: cómo conectar FacturaScripts con la API Verifactu
Verifacti no tiene plugin oficial para FacturaScripts: FacturaScripts se conecta con la API Verifactu con un plugin propio que extiende el modelo de factura de cliente, la envía en JSON al emitirla y recibe el QR. Sin generar el XML, sin calcular la huella y sin certificado digital: Verifacti envía el registro de facturación a la AEAT como colaborador social. El mismo patrón sirve para TicketBAI con la API TicketBAI.
Qué APIs necesitas para FacturaScripts
Tu conector usa dos piezas: la API de envío que corresponde al NIF (API Verifactu en territorio común; API TicketBAI en Álava, Bizkaia y Gipuzkoa) y la API de gestión de NIFs, que integras una vez para dar de alta el NIF, gestionar el modelo de representación y recibir los webhooks. Cada NIF usa una u otra API según dónde tribute.
Cómo conectar FacturaScripts con la API
Flujo: factura de cliente que pasa a un estado no editable en FacturaScripts (extensión del modelo FacturaCliente) → tu plugin → API Verifactu o API TicketBAI → AEAT o hacienda foral.
- Da de alta el NIF con la API de gestión de NIFs y firma el modelo de representación. Cada NIF tiene su API key.
- Crea un plugin con una extensión del modelo
FacturaClientey regístrala enInit.php. - En
saveBefore, cuando la factura pasa a un estado no editable (por ejemplo, Emitida), construye la factura desde sus líneas y llama aPOST /verifactu/create. Si la API responde con un error, el cambio de estado no se guarda. - Guarda
uuidyqry añade el QR al formato de impresión.
¿Fabricas software y quieres ofrecer Verifactu a tus clientes? Lo tienes en fabricantes de ERP.
Ejemplo: de la factura emitida al registro
La extensión envía la factura cuando deja de ser editable: entonces ya tiene sus líneas y sus totales, y no se puede cambiar después. Usa la serie, el ejercicio y el número de FacturaScripts, que ya son correlativos, aplica los descuentos globales a las bases y calcula el total como base + IVA (sin recargo, suplidos ni retención). Los abonos se saltan: necesitan su propio mapeo como rectificativa.
<?php
// Plugins/Verifacti/Extension/Model/FacturaCliente.php · FacturaScripts 2024+.
// Se registra en Plugins/Verifacti/Init.php con $this->loadExtension(new Extension\Model\FacturaCliente());
// La API key va en la configuración del plugin (Tools::settings('verifacti', 'apikey')).
// Envía la factura cuando pasa a un estado no editable (por ejemplo, «Emitida»): entonces ya tiene
// sus líneas y sus totales, y no se puede cambiar después. Si la API responde con un error, el
// cambio de estado no se guarda.
namespace FacturaScripts\Plugins\Verifacti\Extension\Model;
use Closure;
use FacturaScripts\Core\Model\FacturaCliente as Factura;
use FacturaScripts\Core\Tools;
class FacturaCliente
{
public function saveBefore(): Closure
{
return function () {
if (!$this->exists() || $this->editable || $this->idfacturarect) {
return true; // nueva, todavía editable o abono (rectificativa: mapeo propio)
}
$antes = new Factura();
if (!$antes->loadFromCode($this->idfactura) || !$antes->editable) {
return true; // ya estaba cerrada: ya se envió
}
$descuento = (1 - $this->dtopor1 / 100) * (1 - $this->dtopor2 / 100); // descuentos globales
$porTipo = [];
foreach ($this->getLines() as $linea) {
$tipo = (string) (float) $linea->iva;
$base = $linea->pvptotal * $descuento;
$porTipo[$tipo]['base'] = ($porTipo[$tipo]['base'] ?? 0) + $base;
$porTipo[$tipo]['cuota'] = ($porTipo[$tipo]['cuota'] ?? 0) + $base * $linea->iva / 100;
}
$factura = [
'serie' => $this->codserie . $this->codejercicio . '-',
'numero' => (string) $this->numero,
'fecha_expedicion' => $this->fecha,
'tipo_factura' => $this->cifnif ? 'F1' : 'F2',
'descripcion' => $this->observaciones ?: 'Factura ' . $this->codigo,
'lineas' => [],
// total incluye recargo y suplidos y resta la retención de IRPF: el registro lleva base + IVA
'importe_total' => number_format($this->neto + $this->totaliva, 2, '.', ''),
];
if ($this->cifnif) {
$factura['nif'] = $this->cifnif;
$factura['nombre'] = $this->nombrecliente;
}
foreach ($porTipo as $tipo => $l) {
$factura['lineas'][] = [
'base_imponible' => number_format($l['base'], 2, '.', ''),
'tipo_impositivo' => $tipo,
'cuota_repercutida' => number_format($l['cuota'], 2, '.', ''),
];
}
$cuerpo = json_encode($factura);
$ch = curl_init('https://api.verifacti.com/verifactu/create');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . Tools::settings('verifacti', 'apikey'),
'Content-Type: application/json',
'Idempotency-Key: facturascripts-' . $this->idfactura . '-' . substr(hash('sha256', $cuerpo), 0, 12),
],
CURLOPT_POSTFIELDS => $cuerpo,
]);
$registro = json_decode((string) curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) !== 200) {
Tools::log()->error('Verifactu: ' . ($registro['error'] ?? 'sin respuesta'));
return false; // el cambio de estado no se guarda
}
Tools::log()->notice('Verifactu: registro ' . $registro['uuid']);
// Guarda $registro['uuid'] y $registro['qr'] en tu tabla para imprimir el QR
return true;
};
}
}El código agrupa las líneas por tipo de IVA y usa F1 si el cliente tiene NIF y F2 si no. Envía la cabecera Idempotency-Key con el identificador de la factura y un resumen del cuerpo: un reintento igual no duplica la factura y, si corriges los datos tras un error, la clave cambia. La respuesta trae el uuid, el estado (Pendiente: el envío a la AEAT queda en cola), la URL de verificación, el QR en Base64 y la huella: guárdalos con la factura.
Más código en el tutorial de Verifactu en PHP. Para TicketBAI, la llamada es a POST /ticketbai/create con la API key del NIF foral: los campos, en la documentación de la API TicketBAI.
Casos particulares en FacturaScripts
| Caso | Qué hacer | Dónde ampliar |
|---|---|---|
| Numeración | Cada factura necesita una serie con numeración correlativa. Si los números de factura pueden tener huecos, asigna a la factura un número propio | Requisitos de Verifactu |
| Cliente sin NIF | Factura simplificada (F2), sin nif ni nombre. La API rechaza una F2 de más de 3.000 € (vf-verifactu-f2_limite_3000) | Factura simplificada |
| Devolución o abono | Factura rectificativa: R5 si la original era simplificada; R1–R4 si era completa | Rectificativas |
| Cliente que pide factura completa después | Factura de canje (F3) que sustituye a la simplificada | Factura de canje |
| Canarias, Ceuta y Melilla | IGIC o IPSI en las líneas (campo impuesto), no IVA | IGIC · IPSI |
| Productos sin IVA | Revisa si son exentos (operacion_exenta) o no sujetos (calificacion_operacion): no se envían como tipo 0 | Factura exenta |
| Anulación | Solo para facturas que no debieron emitirse: POST /verifactu/cancel | Anulación |
| Venta a otro país de la UE | Depende de si el cliente es empresa y del umbral de ventas a distancia | Ejemplos intracomunitarios |
| Recargo de equivalencia | tipo_recargo_equivalencia y cuota_recargo_equivalencia en la línea de IVA, no como otra línea | Recargo de equivalencia |
| Retención de IRPF | No se envía: importe_total es base + cuota (+ recargo), sin restar la retención | Suplidos y retención |
| Varias sociedades o tiendas | Un NIF por sociedad, cada uno con su API key | API de gestión de NIFs |
Fechas
La primera fila solo aplica si construyes el conector para venderlo a otros: entonces vendes software de facturación. Para quien factura, las fechas de Verifactu están publicadas en el BOE y el aplazamiento a octubre de 2028 está anunciado sin norma publicada. En Álava, Bizkaia y Gipuzkoa, TicketBAI está en vigor.
| Quién | Fecha | Estado | Norma |
|---|---|---|---|
| Productores y comercializadores de software de facturación El RDL 15/2025 no modificó esta fecha. | Desde 29 jul 2025 | En vigor | RD 1007/2023 · Orden HAC/1177/2024 |
| Contribuyentes del Impuesto sobre Sociedades | 1 ene 2027 | Publicada en el BOE con fecha futura | RDL 15/2025 |
| Resto de obligados, autónomos incluidos | 1 jul 2027 | Publicada en el BOE con fecha futura | RDL 15/2025 |
| Aplazamiento de las obligaciones pendientes La nota no precisa el alcance para quien factura más de 8 M€. | oct 2028 | Anunciada sin norma publicada | Nota de Hacienda, 5 oct 2026 |
| TicketBAI en Álava: obligados forales Escalonado desde el 1 de abril de 2022; el resto de contribuyentes, desde el 1 de diciembre de 2022. | Desde 1 dic 2022 | En vigor | NF 13/2021 y DF 48/2021 · FAQ 1.9 · calendario |
| Batuz en Bizkaia (TicketBAI y LROE): todos los obligados Sociedades que no son pymes, desde el 1 de enero de 2024; el resto, en ventanas el 1 de julio de 2024, el 1 de enero de 2025, el 1 de julio de 2025 y el 1 de enero de 2026. | Desde 1 ene 2026 | En vigor | NF 8/2023 · Batuz |
| TicketBAI en Gipuzkoa: obligados forales Escalonado por actividad desde el 1 de julio de 2022. | Desde 1 jun 2023 | En vigor | NF 3/2020 · DF 32/2020 |
Esta información no es asesoramiento: cada contribuyente determina lo que le aplica con su asesor.
Más detalle en plazos de Verifactu y TicketBAI.
Precio
Tarifa pública de la API Verifactu y la API TicketBAI: pagas por cada NIF activo en producción, sin IVA. Para volumen hay precio a medida por NIF.
Desde
14,99 €
al mes el primer NIF activo en producción, sin IVA
Ver todos los precios- El precio por NIF baja con cada tramo de NIFs.
- Entorno de test y NIF de prueba gratuitos.
- Plan anual con un 10 % de descuento, sin costes de instalación.
- Hasta 3.000 registros de facturación al mes por NIF.
- Plan Startup para empresas de menos de 12 meses, con menos de 100.000 € de facturación y menos de 200.000 € de financiación.
- Mismo precio con la API Verifactu y la API TicketBAI: cada NIF usa una u otra según dónde tribute.
- Firma online del modelo de representación: 2,90 € + IVA por firma.
Recursos para desarrolladores
Para tu IA: llms.txt y la especificación OpenAPI.
Preguntas sobre Verifactu y FacturaScripts
Más preguntas sobre Verifactu¿Hay un plugin de Verifacti para FacturaScripts?
¿Basta con FacturaScripts para cumplir Verifactu?
¿Sirve también para TicketBAI?
/ticketbai/create), los campos de la factura y la API key.¿Necesito certificado digital?
¿Cuánto cuesta?
Otras integraciones
Conecta FacturaScripts en el entorno de test
Crea tu cuenta gratuita y prueba la API con un NIF de prueba antes de pasar a producción.