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.
The Verifactu PHP library must be configured once before any operation. Configuration tells the library which digital certificate to use, whether you are targeting the AEAT production system or the homologation (sandbox) environment, and how to reach the correct SOAP endpoint.
The Verifactu::config() Method
The primary entry point for configuration is the static Verifactu::config() facade method. Call it at application bootstrap — before any invoice registration, cancellation, or query.
use eseperio\verifactu\Verifactu;
Verifactu::config(
string $certPath, // Absolute path to your PFX/P12 certificate file
string $certPassword, // Password protecting the certificate file
string $certType, // Verifactu::TYPE_CERTIFICATE or Verifactu::TYPE_SEAL
string $environment // Verifactu::ENVIRONMENT_PRODUCTION or Verifactu::ENVIRONMENT_SANDBOX
);
Verifactu::config() resolves the correct SOAP endpoint URL and QR verification URL based on the $certType and $environment arguments, then delegates to VerifactuService::config().
Constants Reference
Certificate Type Constants
| Constant | Value | When to Use |
|---|
Verifactu::TYPE_CERTIFICATE | 'certificate' | Personal or company X.509 certificate |
Verifactu::TYPE_SEAL | 'seal' | Sello electrónico (seal certificate) issued to a legal entity |
Environment Constants
| Constant | Value | When to Use |
|---|
Verifactu::ENVIRONMENT_PRODUCTION | 'production' | Live submissions to AEAT — real fiscal obligations |
Verifactu::ENVIRONMENT_SANDBOX | 'sandbox' | AEAT homologation environment — safe for testing |
SOAP Endpoint URLs
The library automatically selects one of the four official AEAT endpoints based on your certificate type and environment. The raw URL constants are available on the Verifactu class if you ever need to reference them directly:
// Production — standard certificate
Verifactu::URL_PRODUCTION
// => 'https://www1.agenciatributaria.gob.es/wlpl/TIKE-CONT/ws/SistemaFacturacion/VerifactuSOAP'
// Production — seal certificate
Verifactu::URL_PRODUCTION_SEAL
// => 'https://www10.agenciatributaria.gob.es/wlpl/TIKE-CONT/ws/SistemaFacturacion/VerifactuSOAP'
// Sandbox (homologation) — standard certificate
Verifactu::URL_TEST
// => 'https://prewww1.aeat.es/wlpl/TIKE-CONT/ws/SistemaFacturacion/VerifactuSOAP'
// Sandbox (homologation) — seal certificate
Verifactu::URL_TEST_SEAL
// => 'https://prewww10.aeat.es/wlpl/TIKE-CONT/ws/SistemaFacturacion/VerifactuSOAP'
QR Verification URLs
QR codes embedded in invoices point to one of these AEAT validation portals. The library sets the correct base URL automatically when you call Verifactu::config():
// Production QR verification
Verifactu::QR_VERIFICATION_URL_PRODUCTION
// => 'https://www2.agenciatributaria.gob.es/wlpl/TIKE-CONT/ValidarQR'
// Sandbox QR verification
Verifactu::QR_VERIFICATION_URL_TEST
// => 'https://prewww2.aeat.es/wlpl/TIKE-CONT/ValidarQR'
Configuration Examples
The recommended approach for most applications — let the facade pick the right URLs automatically.use eseperio\verifactu\Verifactu;
// Production with a standard certificate
Verifactu::config(
'/var/secrets/company-certificate.p12',
env('VERIFACTU_CERT_PASSWORD'),
Verifactu::TYPE_CERTIFICATE,
Verifactu::ENVIRONMENT_PRODUCTION
);
// --- or --- Sandbox with a seal certificate (e.g. during development)
Verifactu::config(
'/var/secrets/test-seal.p12',
env('VERIFACTU_CERT_PASSWORD'),
Verifactu::TYPE_SEAL,
Verifactu::ENVIRONMENT_SANDBOX
);
Verifactu::registerInvoice(),
Verifactu::cancelInvoice(), Verifactu::queryInvoices(), and
Verifactu::generateInvoiceQr() will use this configuration automatically. When you need granular control — custom SOAP endpoints, a custom WSDL path,
or an alternative QR verification URL — call VerifactuService::config()
directly with an associative array keyed by the service’s own constants.use eseperio\verifactu\services\VerifactuService;
VerifactuService::config([
VerifactuService::CERT_PATH_KEY => '/var/secrets/company-certificate.p12',
VerifactuService::CERT_PASSWORD_KEY => env('VERIFACTU_CERT_PASSWORD'),
VerifactuService::SOAP_ENDPOINT => 'https://www1.agenciatributaria.gob.es/wlpl/TIKE-CONT/ws/SistemaFacturacion/VerifactuSOAP',
VerifactuService::QR_VERIFICATION_URL => 'https://www2.agenciatributaria.gob.es/wlpl/TIKE-CONT/ValidarQR',
// Optional: override the bundled WSDL with your own copy
VerifactuService::WSDL_ENDPOINT => '/var/app/schemas/SistemaFacturacion.wsdl',
]);
Available Configuration Keys
| Constant | Key String | Description |
|---|
VerifactuService::CERT_PATH_KEY | 'certPath' | Absolute path to the PFX/P12 certificate file |
VerifactuService::CERT_PASSWORD_KEY | 'certPassword' | Password for the certificate file |
VerifactuService::SOAP_ENDPOINT | 'soapEndpoint' | Full SOAP service URL to override the default |
VerifactuService::QR_VERIFICATION_URL | 'qrValidationUrl' | Base URL used when building invoice QR codes |
VerifactuService::WSDL_ENDPOINT | 'wsdl' | Path or URL to the WSDL file (defaults to the bundled SistemaFacturacion.wsdl) |
WSDL_ENDPOINT is not provided, the library automatically uses the official AEAT WSDL bundled at src/schemes/SistemaFacturacion.wsdl.
Using a .env File for Credentials
Store sensitive certificate details in an environment file rather than in source code. The library ships with a .env.example template:
Then populate .env:
#############################################
# PRODUCTION CONFIG (AEAT) #
#############################################
# Path to your certificate (P12/PFX)
VERIFACTU_CERT_PATH=/path/to/your/certificate.p12
# Certificate password
VERIFACTU_CERT_PASSWORD=your_certificate_password
# Certificate type: 'certificate' or 'seal'
VERIFACTU_CERT_TYPE=certificate
# Environment: 'production' or 'sandbox'
VERIFACTU_ENVIRONMENT=production
Verifactu::config():
use eseperio\verifactu\Verifactu;
use Dotenv\Dotenv;
$dotenv = Dotenv::createImmutable(__DIR__);
$dotenv->load();
Verifactu::config(
$_ENV['VERIFACTU_CERT_PATH'],
$_ENV['VERIFACTU_CERT_PASSWORD'],
$_ENV['VERIFACTU_CERT_TYPE'], // 'certificate' or 'seal'
$_ENV['VERIFACTU_ENVIRONMENT'] // 'production' or 'sandbox'
);
Never hardcode certificate paths or passwords directly in PHP source files or commit them to version control. Use environment variables, a secrets manager, or a .env file that is excluded from Git via .gitignore.
Production vs Sandbox
| Sandbox (ENVIRONMENT_SANDBOX) | Production (ENVIRONMENT_PRODUCTION) |
|---|
| Purpose | AEAT homologation — validate integration | Submit real invoices with fiscal effect |
| Certificate | Test or real certificate accepted | Only valid AEAT-issued certificates |
| Data persisted? | No — test data is discarded | Yes — permanent fiscal record |
| QR URL | prewww2.aeat.es/…/ValidarQR | www2.agenciatributaria.gob.es/…/ValidarQR |
| SOAP host | prewww1.aeat.es / prewww10.aeat.es | www1.agenciatributaria.gob.es / www10.agenciatributaria.gob.es |
ENVIRONMENT_PRODUCTION only once your integration is fully validated and you are ready to submit live invoices.
Invoices submitted to ENVIRONMENT_PRODUCTION create real, legally binding fiscal records with the AEAT. There is no undo — cancellations must be submitted as separate InvoiceCancellation records.