Facturax Contracts Laravel Package

Product Decisions This Supports

• Contract-first API design for a regional e-invoicing product. This package is a set of versioned DTOs (namespace Api\V1\Dto\...) for the Facturax API plus a shared validator/normalizer. It lets both sides of the API — Facturax itself and any client system — speak the same JSON shape for the document families that matter in Peruvian e-invoicing: comprobantes, notas de crédito/débito, resúmenes diarios, comunicaciones de baja, reversiones, guías de remisión, percepciones y retenciones. That covers the mainstream Greenter/SUNAT document set.
• Client-side validation before submission. The bundled ContractValidator and ContractNormalizer mean downstream apps can catch malformed payloads before they hit the API. As a PM this translates into fewer 4xx round-trips, cleaner error surfaces for end users, and less support load around "why did my document fail?"
• Decoupling from the invoicing engine. The DTOs are deliberately kept separate from Greenter\Model\* while preserving enough semantics to map internally. This is a genuine architectural decision worth endorsing: it means the public contract can evolve independently of the underlying SUNAT/Greenter implementation. If you are building a product on top of Facturax, you are not signing up to be coupled to Greenter's internals.
• A versioning discipline you can copy. The Api\V1\Dto namespace convention is the template you want for any future API surface — including non-Peruvian expansion. Adopting it now makes the "how do we do v2?" conversation a formality rather than a re-architecture.
• Build vs buy for DTO/validation layers. The honest framing: what you buy here is alignment with Facturax, not raw technical capability. Anyone can write a DTO. What you cannot easily write is a DTO set that is guaranteed to stay in sync with the server's expectations and that another team maintains.
• Use cases in scope: a SaaS invoicing/ERP product integrating with Facturax as a client; an internal system that issues or receives electronic documents in Peru; the Facturax team itself, using the bundle to keep server-side validation consistent with the published contract.

When to Consider This Package

Adopt if:

• You are integrating with the Facturax API (or building it). This is the strongest and most honest reason. If Facturax is in your architecture, using its published contracts is close to a no-op decision — it saves you re-deriving payload shapes and keeps you aligned as the API evolves.
• You need to construct and validate Peruvian SUNAT-related documents (facturas, boletas, notas, resúmenes, bajas, guías, retenciones, percepciones) and would otherwise be hand-rolling DTOs against Greenter.
• Your stack is on the bleeding edge this package targets: PHP 8.5+ and Symfony 8.x (with the optional bundle). If you are a Laravel app already running a current Symfony component set, this is plausible; if you are on PHP 8.1/8.2 or Symfony 6, it is not.
• You value explicit API versioning and want a concrete reference pattern for how to do it.

Look elsewhere if:

• You are not using Facturax. The value proposition collapses entirely. The DTOs are a contract for a specific API; they are not a general-purpose e-invoicing library. Do not mistake this for a Greenter replacement or a SUNAT/OSE client.
• You need the actual submission machinery. Emisor credentials, SOL certificates, endpoints, and SUNAT/OSE transmission are explicitly out of scope per the README. This package validates and shapes payloads; it does not file them.
• You are on mainstream, non-8.5 PHP. PHP 8.5+ / Symfony 8.x is a very aggressive floor. For most teams in 2025–2026 this is a blocker, not a rounding error.
• You need production-grade assurance. The signal here is stark: 1 GitHub star, 0 dependents, version 0.0.2, a single maintainer, and a last release dated in the future (2026-07-22), which suggests metadata you should not treat as a maturity indicator. This is pre-1.0, pre-community, pre-track-record. There is no ecosystem to fall back on if the maintainer steps away.
• You need non-Peruvian tax regimes — Mexico CFDI, Colombia DIAN, EU VAT, etc. This is Peru/SUNAT shaped and nothing else. (Note: some existing third-party write-ups conflate this package with Spanish "Facturae" and with CFDI/DIOT schemas. That is incorrect. Evaluate against Peru only.)
• You are on a non-PHP stack. These are PHP DTOs; the shape is reusable as documentation, but the validation tooling is not.

Adoption posture I would recommend: treat this as a contract reference and integration convenience, not a dependency to build a product strategy around. If you are inside the Facturax ecosystem, consume it and pin the version tightly. If you are outside, use docs/examples/v1/ as the specification and implement your own DTOs — you get the same clarity with none of the single-maintainer risk.

How to Pitch It (Stakeholders)

For executives: "This is a small, focused package that defines the shared vocabulary for electronic invoicing through Facturax — the exact data shapes for invoices, credit notes, daily summaries, cancellations, shipping guides, withholdings and perceptions under Peruvian SUNAT rules. Adopting it is cheap when we are already a Facturax client, and it removes a class of integration bugs: our systems and the API agree on what a valid document looks like before anything is sent. Two caveats I want on record. First, it is very early — version 0.0.2, essentially one maintainer, no adoption yet — so it is a convenience, not a platform bet. Second, it requires PHP 8.5 and Symfony 8, which is ahead of where most of our stack sits. My recommendation is to adopt it only if Facturax is already load-bearing for us, and otherwise to treat its published examples as a specification we implement ourselves."

For engineering: "This is a set of namespaced DTOs (Api\V1\Dto\...) for the Facturax API plus an optional Symfony bundle exposing ContractValidator and ContractNormalizer. The design intent is good: the contracts are intentionally decoupled from Greenter\Model\* while remaining mappable, so the public API surface can change independently of the SUNAT submission layer. Hard requirements are PHP 8.5+ and Symfony 8.x. Credentials, certificates, and SUNAT/OSE endpoints are explicitly not in scope — this validates and normalizes payloads, it does not transmit anything. For integration, the bundle gives you a service container hook if you are on Symfony; on Laravel you would bind the validator/normalizer yourself or, more likely, just use the DTOs and the example JSON in docs/examples/v1/ as your wire format. The real risk is dependency and maintenance: it is a v0.0.2 with one maintainer and no downstream users, so pin the exact version, wrap it behind our own interface, and assume we may have to fork or reimplement. Do not let it leak into domain code directly."

For legal / compliance: "This package describes document structure, not legal validity. It encodes the field shapes for Peruvian SUNAT document families and normalizes payloads so malformed ones fail early. It does not handle certification, digital signatures, SUNAT submission, or OSE transmission — those remain with the invoicing engine and our operational process. Two things to verify with us: that the versioned contract we pin actually reflects the current SUNAT schema requirements for each document family, and that we have an internal owner for tracking SUNAT regulatory changes rather than relying on a single external maintainer's release cadence. The package being pre-1.0 does not itself create compliance exposure, but treating it as a compliance guarantee would."