Laravel Zatca Laravel Package

Product Decisions This Supports

Saudi market entry / expansion gating. ZATCA Phase 2 (Integration Phase) is a legal prerequisite to invoice Saudi customers at all. This package is a candidate to satisfy that gate for a Laravel backend, and its presence or absence directly affects whether a KSA launch date is credible. v1.2.0 does not change this gate — it remains the same legal dependency — but it does confirm the package is still moving.

Build vs. buy vs. borrow for the compliance layer. The realistic options are: (a) build UBL 2.1 XML generation, canonicalization, secp256k1 signing, TLV QR encoding, and the Fatoora clearance/reporting APIs in-house; (b) license a ZATCA-accredited vendor with a support contract; (c) adopt an OSS package like this and own the residual risk. This package is the cheapest path (MIT, no per-invoice fees), so the decision becomes "is the savings worth the maintenance and audit burden?" v1.2.0 adds a presentation-layer capability (PNG/SVG QR rendering) on top of the compliance core — convenient, but it does not shift the build-vs-buy economics, which are driven by signing, clearance/reporting, and certificate lifecycle.

Scope decisions on invoice flows. Force the team to specify which flows ship in v1: standard tax invoices (B2B, clearance API, requires buyer VAT and acceptance/rejection handling) vs. simplified tax invoices (B2C, reporting API, QR mandatory at issuance), plus credit/debit notes. Whether the package cleanly abstracts both flows determines whether B2B is a v1 or v2 item. New in v1.2.0: the package now emits QR as PNG/SVG, which directly reduces scope on the B2C side — simplified-invoice QR must be visible on the issued receipt/PDF/email, and that rendering work no longer has to be built. Treat this as a small scope credit for B2C v1, not as evidence the QR TLV encoding itself is correct (those are separate concerns; the TLV payload still needs sandbox validation).

Roadmap sequencing around Phase 2 waves. ZATCA onboarding is wave-based by revenue threshold; if we onboard mid-wave, we inherit an integration deadline, not a self-chosen one. That makes this a fixed-date dependency to slot ahead of feature work, and it justifies carving out a dedicated "compliance" epic rather than folding it into billing. The v1.1.0 → v1.2.0 cadence is a positive signal that the dependency is being actively worked, which slightly de-risks the fixed-date bet — but it does not change the deadline's immovability.

Multi-tenant / marketplace product design. If we sell to Saudi merchants (SaaS invoicing, marketplace seller tools), per-tenant CSID management, certificate rotation, and environment separation (sandbox / simulation / production) become product requirements — not implementation details. The package's support for per-tenant credentials is a feature-level input here. Nothing in v1.2.0 addresses this; it stays an open diligence item.

Customer-facing document design. Because the package now returns QR images directly, the question of where the QR appears (invoice PDF, email body, POS receipt, customer portal) becomes a product/design decision we can make without an engineering dependency. Prior releases forced that work into the build; now it's a template choice. Worth noting for any B2C receipt redesign already on the roadmap.

Procurement and lock-in posture. MIT + self-hosted means no vendor dependency for the core, but it also means no vendor accountability to ZATCA. This informs whether we budget an internal owner (a named engineer accountable for ZATCA spec changes) as part of the resourcing ask. v1.2.0 introduces a new transitive dependency (simplesoftwareio/simple-qrcode) — trivial in risk, but it must enter our dependency-review and license-scan process, and it means the QR-image feature is optional rather than core.

Diligence checklist this assessment should trigger before commit:

• Does it cover both clearance (B2B) and reporting (B2C) endpoints, or only one?
• Does it handle CSID onboarding, renewal, and compliance-vs-production certificate switching? (README now clarifies production CSID does not require OTP — useful, but confirm the lifecycle code matches the docs.)
• Does it produce spec-compliant UBL 2.1 including invoice hashing, previous-invoice-hash chaining, and TLV QR? (Distinguish TLV payload generation from the new image rendering — v1.2.0 only evidences the latter.)
• Does it expose the raw TLV/base64 QR string, or only rendered images? Non-web consumers (mobile app, POS terminal, partner integrations) need the string.
• Test coverage, static analysis, and whether there's a sandbox integration test suite. The README rewrite corrected a VAT-number format and clarified OTP behaviour — ask what else in the prior docs was wrong, and whether tests cover those corrections.
• Laravel/PHP version support against our current stack; release cadence and maintainer responsiveness. (Two releases with a docs overhaul is encouraging; still one maintainer.)

When to Consider This Package

Adopt (with caveats) if:

• The product stack is Laravel/PHP and invoicing lives in-process — no separate billing microservice or third-party billing platform in between.
• KSA invoicing volume is moderate (thousands to low millions of invoices/month) and per-invoice vendor fees are a meaningful line item.
• Engineering has capacity to own a fork: budget ~1–2 engineer-weeks for a hardening pass plus an ongoing owner for spec changes and certificate lifecycle. v1.2.0 does not reduce that estimate — image rendering is a convenience, not hardening.
• We can build our own test harness against the ZATCA sandbox and treat the package as plumbing, not as a compliance guarantee.
• Time-to-market matters more than vendor indemnity — e.g., we need to invoice Saudi customers inside one quarter.
• We need customer-facing QR rendering (PDF/email/receipt) inside a PHP stack — v1.2.0 now covers this, removing a small custom-build item from the B2C path.

Look elsewhere if:

• We need an accredited/supported ZATCA solution with SLAs, indemnification, and audit documentation — OSS with 7 stars and 0 dependents has no community validation, no security review, and a single maintainer. That is a bus-factor of one on a legally mandated, penalty-bearing function. A v1.2.0 feature release is not a substitute for that; it does not add reviewers, adopters, or a support contract.
• Invoicing is not Laravel-native (Node/Go/JVM services, or a third-party billing platform like Stripe Tax / an ERP) — the integration cost advantage disappears, and the QR-image helper is of no use outside PHP.
• We need capabilities beyond the Phase 2 core: archiving/retention with legal hold, ERP-grade credit note workflows, multi-country e-invoicing (Peppol, Italy SdI, India IRP) under one abstraction.
• Compliance failure is existential (large enterprise, regulated finance) — then the correct answer is a supported vendor, and this package is a prototyping tool to de-risk the spec before signing.
• The package turns out to cover only one flow, or lacks certificate lifecycle handling — the hidden work would exceed a thin build. Still the single most likely disqualifier and untouched by this release.
• Our QR consumption is non-PHP (native mobile app, hardware POS) — you'd be pulling images over the wire when you want the TLV string. Confirm the raw payload is accessible before adopting for that architecture.

Middle path worth recommending: use it in the sandbox to build institutional knowledge of the ZATCA spec quickly, then decide between forking it as the production path and using that knowledge to negotiate/scope a vendor. The faster release cadence and corrected documentation make this path marginally more attractive than at v1.1.0.

How to Pitch It (Stakeholders)

To executives: ZATCA Phase 2 is a hard legal requirement for invoicing in Saudi Arabia — no workaround, no postponement by us. This package is an MIT-licensed Laravel component that implements most of the technical integration, which lets us reach compliance in weeks rather than a quarter, at zero license cost and no per-invoice fees. The tradeoff is maturity: it's a small, single-maintainer project with essentially no adoption, so we would be taking ownership of its correctness. The latest release (v1.2.0) is a good sign — the maintainer is active, shipped customer-facing QR rendering for invoices and receipts, and rewrote documentation that was previously inaccurate — but it doesn't change the underlying risk profile: no second maintainer, no security review, no vendor to hold accountable. I'm recommending we use it as the starting point, fund a short hardening and sandbox-validation phase, and hold a supported vendor as the fallback if validation fails. Either way, we need a named internal owner for this — the ZATCA spec changes and certificates expire, and compliance is ongoing, not a one-time ship. Net: low cash cost, real engineering ownership, a slightly smaller B2C build than last month, and the fastest credible path to a defensible KSA launch date.

To engineering: Treat the package as a spec-accurate starting point, not a drop-in. It should absorb the low-value, high-friction work — UBL 2.1 XML, canonicalization, secp256k1 signing, TLV QR, hash chaining, and the Fatoora API calls — but we must validate every one of those against the ZATCA sandbox before production, and we must own CSID onboarding, renewal, and environment switching regardless of what the package gives us. Plan for: a fork under our org, a conformance test suite against sandbox fixtures, structured logging of every submission with the ZATCA response retained for audit, and idempotent retry around the clearance endpoint. Flag any gap in B2B clearance vs. B2C reporting early — that's the most likely scope surprise and it changes the v1 surface.

v1.2.0 specifics for the build plan: the new qr_code_image / qr_code_svg accessors require simplesoftwareio/simple-qrcode — add it to the dependency review and licence scan, and pin it. Verify the accessors derive from the package's own TLV payload rather than re-encoding from raw fields (a second encoding path is a correctness risk, not a convenience). Expose or preserve the raw TLV base64 string for mobile/POS consumers instead of routing them through image generation. And treat the README corrections (VAT number format, production CSID requiring no OTP) as a prompt to diff docs against code — documentation that was wrong at v1.1.0 may still be wrong somewhere the rewrite didn't touch.