Sandbox sobre la preproducción de la AEAT · sin tarjeta · Primera factura en 5 minutos
verifactu.co

Integración · PHP

VeriFactu en PHP

El ejemplo completo de registrar una factura y reaccionar al resultado, con cURL nativo, sin Composer.

¿Cómo se integra VeriFactu en PHP?

Con una petición HTTP POST a /v1/registros enviando los datos de la factura en JSON y la clave de API en la cabecera Authorization. La respuesta trae la huella y la URL del QR para imprimir.

Lo único que hay que cuidar en cualquier lenguaje es usar tipos decimales exactos para los importes, enviar una cabecera Idempotency-Key y no bloquear la impresión de la factura esperando la respuesta de la AEAT.

01 Registrar una factura cURL nativo, sin Composer

PHP es donde vive la mayor parte del software de facturación español, y muy a menudo en versiones que no admiten dependencias modernas. El ejemplo usa solo cURL: funciona en un PHP 7.4 de un hosting compartido.

PHP
<?php
// Sin dependencias: cURL de PHP y nada más.

function vf_registrar(array $factura, string $clave): array
{
    $ch = curl_init('https://api.verifactu.co/v1/registros');
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 15,
        CURLOPT_HTTPHEADER     => [
            'Authorization: Bearer ' . $clave,
            'Content-Type: application/json',
            // El número de factura como clave de idempotencia:
            // un reintento tuyo NO crea un segundo registro.
            'Idempotency-Key: ' . $factura['numero'],
        ],
        CURLOPT_POSTFIELDS     => json_encode($factura),
    ]);

    $cuerpo = curl_exec($ch);
    $codigo = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);

    $datos = json_decode($cuerpo, true);

    if ($codigo >= 400) {
        // El error trae el campo que falla y quién lo corrige.
        throw new RuntimeException($datos['error']['titulo']);
    }

    return $datos;
}

$reg = vf_registrar([
    'emisor'   => ['nif' => 'B12345678'],
    'numero'   => 'F2026/0184',
    'fecha'    => '2026-08-26',
    'tipo'     => 'F1',
    'base'     => 100.00,
    'cuota'    =>   7.00,
    'total'    => 107.00,
    'impuesto' => 'IGIC',
], getenv('VERIFACTU_KEY'));

// Ya puedes imprimir: huella y QR no cambian con la respuesta de la AEAT.
echo $reg['huella'], "\n", $reg['qr'], "\n";
02 Lo que hay que respetar En cualquier lenguaje
01

Idempotency-Key siempre

Usa el número de factura. Un reintento tuyo sin esa cabecera crea un segundo registro con su propia huella, y en una cadena encadenada eso no se deshace.

02

Decimales exactos, no coma flotante

decimal, BigDecimal o enteros de céntimos. Un double produce importes que no cuadran con la huella y el registro queda «aceptado con errores».

03

Timeout en la petición

Una llamada sin timeout dentro del flujo de emisión puede colgar la factura del usuario. Quince segundos sobran.

04

Imprime con el 201, no esperes a la AEAT

La huella y el QR ya vienen en la respuesta y no cambian con el resultado de la remisión. Bloquear la impresión es un error de diseño.

Última revisión normativa: Especificaciones de huella AEAT v0.1.2 Revisado por el equipo técnico de verifactu.co