Download the PHP package aichadigital/lara-verifactu without Composer

Lara Verifactu

Development happens on gitlab.castris.com. The GitHub repository is a read-only distribution mirror: issues and pull requests opened there are not seen.

Laravel package for *VERIFACTU (AEAT) compliance** — Spain's invoicing records regulation (Real Decreto 1007/2023). It generates AEAT-conformant chained fingerprints (huella), validation QR codes and registration XML, and submits registration and cancellation records to the AEAT web service.

Status: v1.0.0 — stable.

The public API (including src/Contracts/*) and the published database schema are frozen under SemVer; breaking changes require a MAJOR bump (see VERSIONING.md). Every artifact this package produces has been validated against the official AEAT specifications, and the full submission flow has been accepted live by the AEAT external testing environment (Pruebas Externas): real registration and cancellation records submitted with a representative certificate, answered Correcto with CSV, including AEAT-side validation of the chained fingerprint. "Stable" means the API and schema are locked for the declared scope, not full Spanish-law coverage — see the honest-core support matrix below. The post-1.0 coverage roadmap is tracked in AID-209.

Conformance

• Fingerprint (huella) per the official hash spec v0.1.2 — the three official AEAT test vectors are part of the test suite.
• QR per the official QR spec v0.4.7: cotejo URL with exactly nif, numserie, fecha, importe; error correction level M.
• XML validated against the official SuministroLR.xsd in CI; the official schemas and WSDL are bundled with the package (offline SOAP client, endpoint forced per environment and certificate type).
• Endpoints from the official WSDL port bindings: sello certificates use the www10/prewww10 hosts; ciudadano/representante use www1/prewww1.

Regulatory deadlines

The adaptation deadline for obligated taxpayers was extended to 2027 by Real Decreto-ley 15/2025 (2 December 2025), which amended the final provision of RD 1007/2023:

• July 29, 2025: invoicing software / SIF must already meet the requirements.
• January 1, 2027: mandatory for Corporate Income Tax payers (was 2026).
• July 1, 2027: mandatory for the remaining obligated parties, including freelancers (was 2026).

Support matrix (v1.0 honest core)

The package implements an honest core: it emits only what it can produce correctly and rejects fail-loud (a ValidationException) anything it cannot, rather than sending XSD-valid XML the AEAT would reject — or accept con errores (subsanable).

Core — supported and emitted

Rejected fail-loud (post-1.0)

• TipoFactura R2 / R3 / R4 (Art. 80.3 / 80.4 / Resto)
• Impuesto 05 (Otros)
• ClaveRegimen ≠ 01 (special regimes)
• CalificacionOperacion S2 / N1 (inversión del sujeto pasivo / no sujeta art. 7, 14)
• OperacionExenta E2 / E3 with IVA or IGIC, and E5 (intra-community supply of goods)
• Generador identified by IDOtro in the anulación block (the recipient IDOtro is now core)
• Recipient IDType 07 (No Censado — Spanish non-censused, a domestic edge)
• Date-windowed surcharge rates (5 %, 0 %, 2 %, 7,5 % — rules 1165-1170 / 1277)

Out of scope

• TicketBAI (Basque Country) — a different system.
• SII del IGIC (Canary libros registro, remitted to the ATC) — see the note.

Notes

• IGIC: VeriFactu (RD 1007/2023) applies to Canary issuers, with references to IVA read as IGIC; IGIC (Impuesto=03) is emitted in the VeriFactu flow to the AEAT like any other tax. The separate SII del IGIC — the Canary libros-registro reporting to the Agencia Tributaria Canaria (ATC) — is a different obligation and is out of scope here. (AEAT ámbitos de aplicación, BOE RD 1007/2023, SII del IGIC — ATC)
• XSD vs official lists: the XSD OperacionExentaType accepts E7/E8, but AEAT list L10 documents only E1-E6 (the enum models E1-E6). The XSD admits ClaveRegimen 21 (IGIC simplified), absent from list L8A. Neither is emitted by the core.

Requirements

• PHP 8.3+ (CI-tested on 8.3, 8.4 and 8.5)
• Laravel 12.x or 13.x
• Extensions: soap, openssl, dom, libxml
• A digital certificate (PKCS#12) for AEAT submission: representante, sello or ciudadano

Installation

Configure your environment:

Note: macOS Keychain exports .p12 files with legacy RC2-40 encryption that OpenSSL 3.x rejects (misleadingly reported as a wrong password). Re-package with modern encryption:

Verify your setup against AEAT:

Usage

Facade

Testing your integration

Artisan commands

Custom invoice models

Any model implementing AichaDigital\LaraVerifactu\Contracts\InvoiceContract can be registered — the bundled Invoice model (native mode) is optional. See config/verifactu.php for the model bindings.

Now supported (AID-344): Registry::invoice() resolves the model class from config('verifactu.models.invoice') and the hardcoded FK to verifactu_invoices was dropped, so any Eloquent model — any table, integer primary key — implementing InvoiceContract can be registered, cancelled and queried through the facade (register/cancel/status).

Still native-only: the verifactu:register artisan command (single-ID and --all), ProcessInvoiceRegistrationJob and verifactu:status resolve/query the native Invoice Eloquent model directly and don't go through the config binding — use the facade programmatically for a custom model instead of those entry points. A non-integer/string invoice primary key is also not supported (InvoiceContract::getId(): ?int and invoice_id are int-only).

Already model-agnostic: verifactu:retry-failed never touches the Invoice model — it retries pending Registry submissions directly, so it works the same way regardless of which invoice model registered them.

Architecture notes

• *VERIFACTU mode does not sign records**: the chained fingerprint replaces the signature. XAdES signing is available behind verifactu.signing.enabled (default false) for the non-Verifactu modality.

• Filed records are sealed. Once the agency has ruled on a registry (SENT, ACCEPTED or REJECTED), its fiscal artefact — xml, signed_xml, hash, previous_hash, hash_generated_at — and the identity it was filed under — invoice_id, registry_number, registry_date, registry_type, subsanacion, rechazo_previo, amends_registry_id — can no longer be changed, and the record can no longer be deleted. Corrections are made by a subsequent record: cancel() for a RegistroAnulacion, amendRejected() for a subsanación (RD 1007/2023 arts. 8 & 16). Deleting an invoice still soft-deletes its unfiled registries, but leaves the filed ones intact — the invoice may go, the record the agency holds may not.

  The columns that record what the agency answered (status, submitted_at, aeat_csv, aeat_response, aeat_error, submission_attempts) stay writable: they are the conversation, not the artefact.

  Declared limit. The seal is enforced through Eloquent model events, and Eloquent fires none for query-builder writes. Registry::query()->delete() and DB::table('verifactu_registries')->update(...) therefore bypass it by construction. What is closed is the consumer's ordinary path — $registry->delete(), $registry->forceDelete(), $registry->save(). This limit is stated rather than papered over, and pinned by a test so the statement cannot drift away from the code.

• Cancellations are links of the fingerprint chain in their own right (registry_type), keeping the chain verifiable end to end.
• Submissions are sequential by design (dedicated fiscal_verification queue with a unique lock) to preserve chain ordering.

• The overlap locks require a shared cache store. Two guarantees ride on Cache::lock(): submissions stay sequential, and two verifactu:retry-failed passes never race over one record. Both are only as good as the store behind them, so the package refuses to run on one that cannot carry a lock across processes:

  Store	Overlap lock
  null	none	hands out a NoLock whose acquire() returns true unconditionally — every check passes
  array	none across processes	a real lock, but in the memory of one process
  file	per host	fine for several processes on one machine
  database, redis, memcached	across hosts	what a multi-node deployment needs

  Set CACHE_STORE accordingly. On null or array the package throws a ConfigurationException naming the store and the setting, rather than letting a scheduled command report a success it never serialised.

• AceptadoConErrores responses map to success: AEAT registered the record, so it must not be resubmitted; the error details are persisted.
• Rectifications: TipoRectificativa derives from getRectificationType() (S substitution / I incremental). A substitution (S) requires the substituted amounts via getRectificationAmounts() (native mode reads metadata['rectification_amounts']), emitted as ImporteRectificacion; a missing block raises ValidationException.
• Substitution of simplified invoices (F3): invoice type InvoiceTypeEnum::SUBSTITUTE emits FacturasSustituidas (the substituted simplified invoices via getSubstitutedInvoices(); native mode reads metadata['substituted_invoices']). An F3 requires a recipient (AEAT rule 1189) and at least one substituted invoice, otherwise it raises ValidationException.

Sandbox validation

The suite includes tests/Feature/RealSandboxSubmissionTest.php, which performs a real registration and cancellation against AEAT Pruebas Externas. It is skipped automatically unless a real certificate is configured through the VERIFACTU_* environment variables — CI never contacts AEAT.

Testing & quality

Running the suite (MariaDB / MySQL)

The suite runs against MariaDB/MySQL (the deployment engines), not SQLite, so it surfaces schema and engine behavior SQLite silently masks. One-time local setup (this repo's dev box runs MariaDB on port 3307):

Point the suite at it (CI uses the same values but DB_PORT=3306):

CI runs the full suite against both MariaDB 12.3 and MySQL 8.4. composer test is serial (parallel testing is intentionally disabled, see AID-259).

Security

If you discover a security vulnerability, please email [email protected] instead of using the issue tracker. Never commit certificates or credentials; keep your .p12 outside the project tree with restrictive permissions.

Logging & privacy

Third-party fiscal PII never reaches the logs unredacted. The SOAP request/response payload (NIF, names, amounts, dates, signature) is not logged by default; enable it with VERIFACTU_LOG_SOAP_PAYLOAD=true and even then it is always passed through a redactor — there is no raw-payload mode. Full stack traces and AEAT error text are gated behind VERIFACTU_LOG_DEBUG and a redactor respectively.

What the logs do carry are the issuer's own operational identifiers — invoice_number, invoice_serie, registry_number, invoice_id and the AEAT csv (cotejo) code. These are the issuer's references to its own operations, not third-party personal data, and they are kept on purpose for support and operational audit ("what happened to invoice FA-2026-001 / CSV A-xxx?"). They are controlled by the log level (VERIFACTU_LOG_LEVEL, default info):

• Intermediate steps and idempotency skips are logged at debug (off by default); real transitions (submitted to AEAT, registered) at info; failures at warning/error/critical.
• For restricted environments (a shared SIEM, external support without strict access/retention controls) set VERIFACTU_LOG_LEVEL=warning so only failures are persisted. Field-level redaction of these operational ids is intentionally not done in v1.0; it would only be warranted if your logs leave to an uncontrolled third party.

Changelog

See CHANGELOG.md.

License

The MIT License (MIT). See LICENSE.md.

Credits

• Aicha Digital
• Built against the official AEAT VERI*FACTU specifications
• Package skeleton by Spatie

Made with ❤️ by Aicha Digital