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.

​
System requirements

Before installing, confirm your environment meets these requirements:
RequirementMinimum version
PHP8.1 or higher
Composer2.x recommended
ext-soapany (bundled with PHP)
ext-libxmlany (bundled with PHP)
ext-opensslany (bundled with PHP)
ext-domany (bundled with PHP)
Check your PHP version and loaded extensions: 
php -v
php -m | grep -E "soap|libxml|openssl|dom"
You should see soap, libxml, openssl, and dom listed. If any are missing, enable them in your php.ini or install the corresponding system package.
On Debian/Ubuntu systems you can install missing extensions with: sudo apt-get install php8.1-soap php8.1-xml. The dom and libxml extensions are usually bundled with php-xml. On macOS with Homebrew, use brew install php — all four extensions are enabled by default.

​
Installation steps

1
Require the package with Composer
2
Run the following in your project root:
3
composer require eseperio/verifactu-php
4
This installs the library and all required dependencies in one step:
5
  • bacon/bacon-qr-code ^3 — QR code generation
  • robrichards/xmlseclibs ^3.0 — XAdES XML digital signature
  • vlucas/phpdotenv ^5.5 — .env file support for certificate configuration
    • 6
    Verify autoloading
    7
    Ensure Composer’s autoloader is included in your application’s entry point:
    8
    <?php

require_once __DIR__ . '/vendor/autoload.php';
    9
    The library registers the PSR-4 namespace eseperio\verifactu\ mapped to the src/ directory:
    10
    {
  "autoload": {
    "psr-4": {
      "eseperio\\verifactu\\": "src/"
    }
  }
}
    11
    All classes are available immediately after including the autoloader — no service container or manual registration needed.
    12
    Prepare your digital certificate
    13
    AEAT requires a valid PKCS#12 digital certificate (.pfx or .p12) to sign and submit invoices. Place it in a secure location outside your web root:
    14
    /var/certs/aeat-certificate.p12   ← recommended
/var/www/html/certs/              ← NOT recommended (publicly accessible)
    15
    The library accepts:
    16
  • Verifactu::TYPE_CERTIFICATE — personal or company certificate
  • Verifactu::TYPE_SEAL — AEAT seal certificate (sello)
    • 17
    (Optional) Set up .env for certificate configuration
    18
    For development and CI environments, the library supports loading certificate paths from a .env file using vlucas/phpdotenv. Copy the example:
    19
    cp vendor/eseperio/verifactu-php/.env.example .env
    20
    Then edit .env:
    21
    # Path to your certificate file
VERIFACTU_CERT_PATH=/path/to/your/certificate.p12

# Password for your certificate
VERIFACTU_CERT_PASSWORD=your_certificate_password

# Certificate type: 'certificate' or 'seal'
VERIFACTU_CERT_TYPE=certificate

# Environment: 'production' or 'sandbox'
VERIFACTU_ENVIRONMENT=sandbox
    22
    Always add .env to your .gitignore. Never commit certificate paths or passwords to version control.
    23
    Verify your installation
    24
    Run this snippet to confirm the library loads and the main facade is reachable:
    25
    <?php

require_once __DIR__ . '/vendor/autoload.php';

use eseperio\verifactu\Verifactu;
use eseperio\verifactu\models\InvoiceSubmission;
use eseperio\verifactu\models\enums\InvoiceType;

// Confirm the facade constant is accessible
echo Verifactu::ENVIRONMENT_SANDBOX . PHP_EOL;  // "sandbox"
echo Verifactu::ENVIRONMENT_PRODUCTION . PHP_EOL; // "production"

// Confirm enums are available
echo InvoiceType::STANDARD->value . PHP_EOL; // "F1"

// Confirm model instantiation works
$invoice = new InvoiceSubmission();
echo get_class($invoice) . PHP_EOL; // "eseperio\verifactu\models\InvoiceSubmission"

echo "Installation OK" . PHP_EOL;
    26
    If you see Installation OK without any errors, you are ready to go.

    ​
    Docker setup

    A Dockerfile is included in the repository for containerised environments. To use it: 
    # Clone the repo (or copy the Dockerfile into your project)
git clone https://github.com/Eseperio/verifactu-php.git

# Build the image
docker build -t verifactu-php .

# Or use docker-compose (docker-compose.yml is also included)
docker-compose up --build
    The included docker-compose.yml sets up a complete development environment with all required PHP extensions pre-installed.

    ​
    Running the test suite

    The library ships with a comprehensive test suite using PHPUnit 10: 
    composer test
    Integration tests (composer test-sandbox) connect to AEAT’s homologation environment and require a valid certificate configured in .env. If .env is absent, Composer will create one from .env.example and tests that need a certificate will be skipped automatically.

    ​
    Installed directory structure

    After installation, the library is at vendor/eseperio/verifactu-php/src/: 
    src/
├── Verifactu.php                   ← Main facade
├── models/
│   ├── InvoiceSubmission.php       ← Alta (registration)
│   ├── InvoiceCancellation.php     ← Anulación (cancellation)
│   ├── InvoiceQuery.php            ← Query
│   ├── InvoiceResponse.php         ← Submission/cancellation response
│   ├── QueryResponse.php           ← Query response
│   ├── InvoiceId.php               ← Invoice identification
│   ├── Breakdown.php               ← Tax breakdown container
│   ├── BreakdownDetail.php         ← Individual tax rate line
│   ├── Chaining.php                ← Hash chaining
│   ├── ComputerSystem.php          ← System metadata
│   ├── LegalPerson.php             ← Person/company entity
│   └── enums/                      ← PHP 8.1 backed enums
│       ├── InvoiceType.php         ← F1, F2, F3, R1–R5
│       ├── TaxType.php             ← IVA, IGIC, IPSI, OTHER
│       ├── RegimeType.php          ← VAT regime keys
│       ├── YesNoType.php           ← YES / NO
│       └── ...
├── services/
│   ├── VerifactuService.php        ← Orchestration workflow
│   ├── HashGeneratorService.php    ← SHA-256 hash calculation
│   ├── XmlSignerService.php        ← XAdES XML signing
│   ├── QrGeneratorService.php      ← QR code generation
│   ├── ResponseParserService.php   ← SOAP response parsing
│   └── ...
└── dictionaries/
    └── ErrorRegistry.php           ← Official AEAT error code map

    ​
    Next steps

    Quickstart

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

    Introduction

    Learn what Verifactu is and what this library covers

    Build docs developers (and LLMs) love

    Get started for freeTalk to us