Laravel Verifactu Laravel Package

Technical Evaluation

Architecture fit. squareetlabs/laravel-verifactu is a natural architectural fit for a Laravel-based billing monolith: it is likely packaged as a service provider with publishable config/migrations, Eloquent models, events/listeners, and queueable submission jobs. The correct placement is a compliance subsystem around the invoice lifecycle, not the system of record for pricing, billing, or invoicing. VeriFactu imposes record chaining, hash integrity, QR generation, and AEAT submission/status handling; the package should be treated as an adapter for those concerns unless code review proves broader scope. The main architecture risk is coupling: if the package expects to own invoice tables or numbering, it can conflict with existing billing models. Prefer an anti-corruption layer that maps internal invoices to VeriFactu records and keeps the package swappable.

Integration feasibility. Technically feasible for a Laravel 10–12 application with standard MySQL/PostgreSQL, Redis queues, and scheduler. Installation is likely straightforward; production integration is not, because regulatory correctness, certificate handling, multi-tenant sequencing, and audit evidence must be validated. The package has only 23 stars and zero dependents, so there is effectively no public production evidence. Feasibility should be proven through a sandbox spike, not assumed from the README. A reasonable estimate is 2–4 weeks for a technical/regulatory spike and 6–10 weeks to production for a single-entity Laravel app, longer for multi-tenant, legacy, or high-volume invoicing.

Technical risk. The highest risk is regulatory, not code: AEAT schema versions, hash-chain rules, QR content, record immutability, and submission semantics must be correct. Other risks include concurrency around invoice numbering and hash chaining, certificate storage/rotation, idempotency and duplicate submission, time synchronization, queue reliability, and upgrade handling when AEAT specifications change. The MIT license limits lock-in, but low adoption implies a high bus factor and likely internal ownership of fixes. Security review should cover certificate secrets, signed payloads, PII, and retention.

Key questions.

• Does the package generate records only, or also submit to AEAT and reconcile status?
• Is it VeriFactu-only, or does it also address SII/FacturaE requirements?
• What evidence exists of AEAT sandbox/production validation and test coverage?
• Which Laravel, PHP, database, queue, and multi-tenant configurations are supported?
• How does it integrate with existing invoice models: contracts, events, or its own tables?
• How are per-company sequences, certificates, and hash chains isolated?
• Does it provide idempotency, retry, dead-letter, and chain-repair tooling?
• What is the release/upgrade policy for AEAT schema changes, and who maintains it?
• What are the data retention, immutability, and audit-export guarantees?

Integration Approach

Stack fit. Best fit is a Laravel 10–12 application using Eloquent, MySQL/PostgreSQL, Redis queues, and the scheduler, with invoices already modeled in the app. The package should sit behind an internal VerifactuGateway interface so controllers, jobs, and billing services never call package classes directly. For non-Laravel or event-driven estates, wrap it as a sidecar compliance service rather than forcing it into the core billing path.

Migration path. Start with legal/accounting review and a sandbox spike. Install in an isolated environment, inspect migrations/config, and submit a test invoice to the AEAT test endpoint. Then map the existing invoice aggregate to a compliance ledger without backfilling history unless legally required. Establish a cutover date and run a shadow mode that generates records and QR codes for comparison before enabling real submission. Roll out by entity/tenant behind a feature flag, then certify and decommission shadow mode.

Compatibility. Verify PHP version, Laravel 10/11/12 support, database driver, UUID vs auto-increment keys, timezone (Europe/Madrid), currency, VAT regimes, and multi-company support. Check for conflicts with existing invoice number generators and PDF/QR pipelines. Pin the package version, publish and review migrations, and confirm the upgrade path for AEAT schema changes. Test certificate storage against the organization’s secrets manager.

Sequencing.

1. Confirm regulatory scope and AEAT obligations with a Spanish tax advisor.
2. Run a technical spike in sandbox; validate hash, QR, submission, and status retrieval.
3. Define the internal invoice-to-compliance contract and tenant/company isolation model.
4. Build an outbox/idempotent submission flow with monitoring and reconciliation.
5. Pilot one entity in production; verify chain integrity and AEAT acceptance.
6. Roll out per tenant; document runbooks and certificate rotation.
7. Schedule post-launch audit and AEAT regression tests.

Operational Impact

Maintenance. Expect to own maintenance despite the MIT license. Budget for Laravel/PHP upgrades, AEAT schema changes, dependency patching, and test maintenance. Keep a fork or vendor-patch path ready. Low adoption means fewer community bug reports and no broad compatibility signal; treat every release as requiring regression testing.

Support. Support is likely GitHub issues on a best-effort basis, with no commercial SLA. Name an internal owner and backup, and define escalation for regulatory interpretation as well as code defects. If the package is critical, consider paid maintainer engagement or a support contract.

Scaling. Invoice volumes are usually modest, so database and queue capacity are unlikely to be the first constraint. The real constraint is per-company serialization of invoice numbering and hash chaining. Do not parallelize submissions per tenant without database locks or idempotency keys. Plan for AEAT rate limits, timeouts, immutable record growth, and archival.

Failure modes. Watch for AEAT outages/timeouts, expired certificates, duplicate submissions, validation rejects, hash-chain breaks from failed transactions or edited invoices, sequence gaps, queue backlog, clock drift, QR mismatches, migration failures, cross-tenant data leakage, and package abandonment. Mitigate with an outbox pattern, idempotency keys, dead-letter queues, chain-verification jobs, certificate-expiry alerts, append-only storage, backups, and a sandbox regression suite.

Ramp-up. A Laravel developer can install and generate a record in 1–2 days; understanding VeriFactu/AEAT flows and failure handling takes 1–2 weeks. Finance/legal users need 3–5 days of orientation. Plan runbooks for daily submission monitoring, monthly chain audits, and annual certificate rotation. Track submission success rate, latency, chain-verification pass rate, unresolved rejects, and certificate days-to-expiry.