Invoicing Integration Laravel Package

Product Decisions This Supports

• Build vs. buy for fiscalization/invoicing: csarcrr/invoicing-integration wraps the Cegid Vendus API behind a Laravel-native client. It converts a "we must issue legally-compliant invoices" requirement into a vendor-integration task rather than a ground-up fiscal engine — the single biggest scope reduction available in this domain.
• Vendor strategy and portability: A thin, provider-specific client lets you defer the "which invoicing provider" decision longer, and keeps the door open to swap in another certified provider (or a second one for multi-market) behind your own interface, provided you wrap it rather than call it directly.
• Roadmap sequencing for billing/revenue features: Lets you ship invoice creation and lookup earlier in the roadmap, ahead of things like dunning, revenue reporting, or multi-currency support.
• Compliance-risk positioning: Because the hard part (certified document series, ATCUD/QR, SAF-T obligations) is delegated to Vendus, this is a risk-transfer decision, not just a code decision. That belongs in the risk register, not the backlog.
• Data-integrity decisions in downstream features: The v0.5.4 fix — correcting type casting in find results — tells you raw Vendus payloads are not type-consistent (e.g. IDs/amounts arriving as strings vs. numeric types). Any product surface that keys off invoice IDs, matches records, or does arithmetic on returned values needs normalization at the boundary; budget for a defensive mapping layer rather than trusting pass-through types.

When to Consider This Package

Consider it when:

• You are building on Laravel/PHP and need programmatic invoicing against Cegid Vendus specifically — not "invoicing in general."
• Your market/regulatory context is Portugal (or wherever Vendus is certified), and you have confirmed with finance/legal that Vendus certification satisfies your obligations.
• You want integration speed over integration depth: create/find invoice operations inside your app, with the provider owning the fiscal-legal layer.
• You can accept pre-1.0 versioning (v0.5.x). Pin the version, read the changelog on every bump, and do not assume API stability. Patch releases like v0.5.4 are bug fixes, but minor-version bumps in a 0.x line can and do break.
• You are willing to wrap it: put your own repository/adapter interface in front of it so the provider and package version are both replaceable.

Look elsewhere (or build) when:

• You need multiple invoicing providers or multi-country fiscalization — this is a single-provider client; the abstraction is yours to build.
• You need 1.0-level stability guarantees, published support windows, or a large maintainer bench — this is a narrow-scope package with a small contributor base.
• Your volume or latency profile requires async/queued fiscalization with reconciliation, which a client wrapper does not provide on its own.
• Regulatory scope is non-Portuguese/unsupported jurisdictions, or your finance team has already standardized on a different certified provider.
• The invoice is not the regulated artifact in your flow (e.g. you only need PDFs or internal records) — you would be paying integration cost for compliance you do not need.

How to Pitch It (Stakeholders)

For executives: This package is a shortcut to issuing legally valid invoices from our Laravel application without building a fiscal engine. It connects us to Cegid Vendus, a certified provider, so the compliance burden — document series, certification, tax-authority formats — sits with them and their contract, not our engineering team. The trade-off is dependency: we are betting on one provider in one regulatory market, and the package is pre-1.0, meaning we pin versions and accept ongoing maintenance overhead. Net position: materially lower time-to-market and lower compliance risk, in exchange for vendor concentration and a small, single-maintainer dependency we should wrap in our own interface.

For engineering: Treat this as an adapter, not a foundation. Put our own interface in front of it so the Vendus client is swappable and testable with fakes. Pin the version exactly and review each release — v0.5.4 is a patch fixing type casting in find results, which is a useful signal that provider responses are not reliably typed; normalize and validate at the boundary rather than propagating raw values into our domain. Assume 0.x means breaking changes are permitted on minor bumps. Keep integration tests against a Vendus sandbox and treat their API as we would any third-party SLA we do not control.