Verifactu en Magento: cómo conectar Magento 2 con la API Verifactu
Verifacti no tiene extensión oficial para Magento: Magento 2 se conecta con la API Verifactu con un módulo propio cuyo observer, al pagarse una factura, la envía en JSON 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. En Álava, Bizkaia y Gipuzkoa, el mismo patrón sirve con la API TicketBAI.
Qué APIs necesitas para Magento
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 Magento con la API
Flujo: factura pagada en Magento 2 (evento sales_order_invoice_save_commit_after) → tu módulo → 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 módulo con un observer para
sales_order_invoice_save_commit_afterenetc/events.xml: llega cuando la factura ya está guardada y tiene número. - Construye la factura desde la
Invoicey llama aPOST /verifactu/create. - Guarda
uuid,qryhuellay añade el QR al PDF de la factura.
¿Fabricas software y quieres ofrecer Verifactu a tus clientes? Lo tienes en software de facturación.
Ejemplo: de la factura pagada al registro
El observer solo actúa sobre facturas pagadas, usa el número de la factura de Magento (increment_id) y agrupa las líneas y el envío (con su descuento) por tipo de IVA. El tipo del envío se ajusta al tipo válido más cercano, porque Magento solo guarda la cuota redondeada.
<?php
// app/code/Verifacti/Verifactu/Observer/InvoicePaid.php · Magento 2.4.4+ (PHP 8).
// Registrado en etc/events.xml para el evento sales_order_invoice_save_commit_after, que llega cuando
// la factura ya está guardada y tiene número (sales_order_invoice_pay llega antes de que lo tenga):
// <event name="sales_order_invoice_save_commit_after"><observer name="verifacti_invoice_paid" instance="Verifacti\Verifactu\Observer\InvoicePaid"/></event>
// La API key va en app/etc/env.php como 'verifacti' => ['api_key' => 'vf_test_...'].
namespace Verifacti\Verifactu\Observer;
use Magento\Framework\App\DeploymentConfig;
use Magento\Framework\Event\Observer;
use Magento\Framework\Event\ObserverInterface;
use Magento\Framework\HTTP\Client\Curl;
use Magento\Sales\Model\Order\Invoice;
use Psr\Log\LoggerInterface;
class InvoicePaid implements ObserverInterface
{
private const TIPOS = [0, 4, 10, 21];
public function __construct(
private Curl $curl,
private DeploymentConfig $config,
private LoggerInterface $logger
) {
}
public function execute(Observer $observer): void
{
/** @var Invoice $invoice */
$invoice = $observer->getEvent()->getInvoice();
if ($invoice->getState() != Invoice::STATE_PAID) {
return;
}
$cuerpo = json_encode($this->factura($invoice));
$this->curl->setHeaders([
'Authorization' => 'Bearer ' . $this->config->get('verifacti/api_key'),
'Content-Type' => 'application/json',
'Idempotency-Key' => 'magento-' . $invoice->getIncrementId() . '-' . substr(hash('sha256', $cuerpo), 0, 12),
]);
$this->curl->setTimeout(30);
$this->curl->post('https://api.verifacti.com/verifactu/create', $cuerpo);
$registro = json_decode($this->curl->getBody(), true);
if ($this->curl->getStatus() !== 200) {
$this->logger->error('Verifactu ' . $invoice->getIncrementId(), $registro ?? []);
return;
}
$this->logger->info('Verifactu ' . $invoice->getIncrementId() . ': registro ' . $registro['uuid']);
// Guarda $registro['uuid'], $registro['qr'] y $registro['huella'] en tu tabla para el PDF de la factura
// (no vuelvas a guardar la factura aquí: dispararía este mismo evento)
}
private function factura(Invoice $invoice): array
{
$porTipo = [];
foreach ($invoice->getAllItems() as $item) {
if ($item->getOrderItem()->getParentItem()) {
continue;
}
// Si aplicas el descuento sobre precios con IVA, resta también getDiscountTaxCompensationAmount()
$tipo = (string) (float) $item->getOrderItem()->getTaxPercent();
$porTipo[$tipo]['base'] = ($porTipo[$tipo]['base'] ?? 0) + $item->getRowTotal() - $item->getDiscountAmount();
$porTipo[$tipo]['cuota'] = ($porTipo[$tipo]['cuota'] ?? 0) + $item->getTaxAmount();
}
$envio = $invoice->getShippingAmount() - (float) $invoice->getOrder()->getShippingDiscountAmount();
if ($envio > 0) {
$tipo = (string) $this->tipoValido($invoice->getShippingTaxAmount() / $envio * 100);
$porTipo[$tipo]['base'] = ($porTipo[$tipo]['base'] ?? 0) + $envio;
$porTipo[$tipo]['cuota'] = ($porTipo[$tipo]['cuota'] ?? 0) + $invoice->getShippingTaxAmount();
}
$direccion = $invoice->getBillingAddress();
$nif = $direccion->getVatId();
$factura = [
'serie' => 'MAG-',
'numero' => $invoice->getIncrementId(),
'fecha_expedicion' => date('d-m-Y'),
'tipo_factura' => $nif ? 'F1' : 'F2',
'descripcion' => 'Pedido ' . $invoice->getOrder()->getIncrementId(),
'lineas' => [],
'importe_total' => number_format((float) $invoice->getGrandTotal(), 2, '.', ''),
];
if ($nif) {
$factura['nif'] = preg_replace('/^ES/', '', $nif);
$factura['nombre'] = $direccion->getCompany() ?: $direccion->getName();
}
foreach ($porTipo as $tipo => $l) {
$factura['lineas'][] = [
'base_imponible' => number_format($l['base'], 2, '.', ''),
'tipo_impositivo' => $tipo,
'cuota_repercutida' => number_format($l['cuota'], 2, '.', ''),
];
}
return $factura;
}
// El tipo del envío se deduce de la cuota redondeada (4,95 € → 21,01 %): se ajusta al tipo válido más cercano
private function tipoValido(float $tipo): float
{
$mejor = self::TIPOS[0];
foreach (self::TIPOS as $t) {
if (abs($t - $tipo) < abs($mejor - $tipo)) {
$mejor = $t;
}
}
return $mejor;
}
}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 Magento
| 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 |
| 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 Magento
Más preguntas sobre Verifactu¿Hay una extensión de Verifacti para Magento?
¿Basta con Magento 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 Magento en el entorno de test
Crea tu cuenta gratuita y prueba la API con un NIF de prueba antes de pasar a producción.