Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Eseperio/verifactu-php/llms.txt

Use this file to discover all available pages before exploring further.

​
What is Verifactu?

Verifactu (VERI*FACTU) is Spain’s mandatory digital invoice control system operated by the Agencia Estatal de Administración Tributaria (AEAT). It requires businesses using invoicing software to submit every invoice record to AEAT in near-real time, producing an auditable, tamper-evident chain of electronic invoices. Each invoice submitted to AEAT receives a CSV (Código Seguro de Verificación) — a unique reference code that proves the invoice was registered with the Spanish tax authority. Invoices must also display a QR code linking to AEAT’s verification portal so recipients can confirm authenticity. The system enforces:
  • Cryptographic chaining — every invoice hash references the previous record’s hash, creating an immutable sequence
  • XML digital signatures — documents are signed with an accredited certificate (XAdES Enveloped)
  • SOAP communication — submissions use AEAT’s official SOAP/WSDL endpoints
  • Strict schema validation — all fields are validated against AEAT’s published XSD schemas
VERI*FACTU obligation has been delayed to 2027. Companies must comply from 2027, and self-employed workers (autónomos) from 1 July 2027. You can start integrating now in AEAT’s sandbox environment to be ready well in advance.

​
What this library does

eseperio/verifactu-php is a complete, object-oriented PHP 8.1+ integration layer for the VERI*FACTU system. It handles the entire technical workflow described in AEAT’s regulatory specification:
  1. Build strongly-typed invoice models that map directly to AEAT’s XSD schema
  2. Auto-generate the SHA-256 hash (“huella”) for each invoice record
  3. Serialize models to AEAT-compliant XML
  4. Digitally sign the XML block (XAdES Enveloped) using your PKCS#12 certificate
  5. Transmit the signed XML to AEAT’s SOAP endpoint (production or sandbox)
  6. Parse the SOAP response into typed PHP objects with human-readable error messages
  7. Generate AEAT-compliant QR codes for printing on invoices

​
What this library does NOT do

This is not an invoicing or accounting system. It does not create, store, or manage invoices. It is purely an integration layer — you bring your own invoice data and this library handles the AEAT communication protocol.
The library does not:
  • Render PDF invoices or generate invoice documents
  • Store invoice data in a database
  • Manage invoice numbering or series
  • Handle VAT calculations — you compute amounts and pass them in
  • Replace your existing ERP or billing system

​
Key features

Invoice Registration (Alta)

Submit new invoices to AEAT with full hash chaining. Supports all invoice types: standard (F1), simplified (F2), replacement (F3), and rectification (R1–R5).

Invoice Cancellation (Anulación)

Cancel previously submitted invoices via the AEAT SOAP endpoint, with full chaining support for cancellations linked to the previous record hash.

Invoice Querying

Query previously submitted invoices by period, series, date, or counterparty, with paginated results parsed into typed QueryResponse objects.

Auto Hash Generation

SHA-256 hash (“huella”) is automatically computed from the required AEAT field ordering — you never need to implement this yourself.

XML Digital Signing

Built-in XAdES Enveloped XML signature using robrichards/xmlseclibs. Supports both personal/company certificates (TYPE_CERTIFICATE) and seal certificates (TYPE_SEAL).

QR Code Generation

Generate AEAT-compliant QR codes in PNG (via GD or Imagick) or SVG format at any resolution. Output as raw string, base64, or file, using bacon/bacon-qr-code.

Strongly Typed Models

All AEAT schema entities are modelled as PHP classes with full PHPDoc, PHP 8.1 enums for type-safe constants, and a built-in validate() method with detailed error messages.

Dual Environment Support

Toggle between ENVIRONMENT_PRODUCTION and ENVIRONMENT_SANDBOX with a single config parameter. The library automatically selects the correct SOAP endpoint and QR verification URL.

Official Error Translation

All AEAT error codes are mapped to human-readable descriptions using the official AEAT code dictionary bundled in src/dictionaries/ErrorRegistry.php.

Event Notifications

Submit system-level events (EventRecord) to AEAT as required by the regulation, via the dedicated EventDispatcherService.

​
Requirements

​
PHP version

This library requires PHP 8.1 or higher. It makes use of PHP 8.1 features including backed enums, readonly properties, and never return types.

​
Required PHP extensions

The following PHP extensions must be enabled:
ExtensionPurpose
ext-soapSOAP client for communicating with AEAT endpoints
ext-libxmlXML document parsing and generation
ext-opensslCertificate loading and cryptographic operations
ext-domDOM manipulation for XML signing

​
Composer dependencies

These packages are automatically installed when you run composer require eseperio/verifactu-php:
PackageVersionPurpose
bacon/bacon-qr-code^3QR code generation (PNG, SVG, Imagick)
robrichards/xmlseclibs^3.0XAdES XML digital signature
vlucas/phpdotenv^5.5.env file loading for certificate config

​
Dev dependencies

PackagePurpose
phpunit/phpunit ^10.0Unit and integration test suite
phpstan/phpstan 2.1.x-devStatic analysis

​
What you need from AEAT

To submit invoices to production you need:
  • A valid digital certificate (.pfx / .p12) issued by an accredited Spanish certification authority, or an AEAT seal certificate
  • Your company’s NIF registered in AEAT’s census (Mis datos censales) — the issuer NIF and name must match exactly
For sandbox testing no production certificate is required — AEAT provides a test environment at prewww1.aeat.es / prewww10.aeat.es.

​
PSR-4 namespace

All classes live under the eseperio\verifactu\ namespace: 
eseperio\verifactu\Verifactu                         — Main facade
eseperio\verifactu\models\InvoiceSubmission          — Invoice registration model
eseperio\verifactu\models\InvoiceCancellation        — Invoice cancellation model
eseperio\verifactu\models\InvoiceQuery               — Query model
eseperio\verifactu\models\InvoiceResponse            — Submission/cancellation response
eseperio\verifactu\models\QueryResponse              — Query response
eseperio\verifactu\models\enums\InvoiceType          — Invoice type enum (F1, F2, R1…)
eseperio\verifactu\models\enums\TaxType              — Tax type enum (IVA, IGIC, IPSI…)
eseperio\verifactu\models\enums\RegimeType           — VAT regime enum
eseperio\verifactu\models\enums\YesNoType            — Boolean enum (YES/NO)
eseperio\verifactu\services\QrGeneratorService       — QR code generation
eseperio\verifactu\services\HashGeneratorService     — SHA-256 hash generation

​
Next steps

Installation

Install via Composer, enable PHP extensions, and verify your setup

Quickstart

Submit your first invoice to the AEAT sandbox in under 10 minutes

​
Disclaimer

This is an open-source library provided without any warranties. It is the sole responsibility of the integrator to verify correct operation and compliance with all applicable legal and technical requirements. The library includes automated tests to help verify functionality, but use in production is entirely at your own risk. Always validate against AEAT’s official technical specification before deploying.

Build docs developers (and LLMs) love

Get started for freeTalk to us