Invoicing Integration Laravel Package

Technical Evaluation

Scope of this release. v0.5.4 is a single-commit patch: fix: correct type casting in CegidVendus client find results (PR #55). No new endpoints, configuration keys, migrations, or deprecations are introduced. From a TPM standpoint this is a low-blast-radius bugfix release, and it is the first assessment for this package — there is no prior baseline to diff against.

Architecture fit. csarcrr/invoicing-integration is a Laravel package wrapping the Cegid Vendus invoicing API (Portuguese fiscal document issuance). It fits the "service client / anti-corruption layer" slot in a Laravel architecture: it should sit behind our own domain interface so that document issuance, series/ATCUD handling, and fiscal QR/PDF concerns do not leak into controllers or jobs. The release notes tell us the package owns response hydration and type mapping — a find method returning a typed result object or DTO. That is the right shape, but it also means the package is on the critical path for any data we persist from Vendus lookups.

Integration feasibility. High on mechanics, medium on correctness. Laravel package installation, config publishing, and service-container binding are routine. The real feasibility question is semantic: a type-casting defect in find results implies the upstream API returns loosely typed JSON (numeric strings, nulls, "0" vs 0, float-vs-string monetary fields) and the client previously passed those through untransformed. That class of bug rarely stays contained — it typically surfaces as strict-comparison failures, silent 0 vs null confusion, and downstream persistence of strings into integer/decimal columns. Any consumer that already worked around the defect locally (casting at the call site) is now double-casting and should be reviewed.

Technical risk.

• Pre-1.0 API churn (high). A 0.x version line reserves the right to make breaking changes in minor releases. Treat every 0.x bump as potentially breaking until pinned and tested.
• Fiscal correctness (high impact, low likelihood here). Invoicing integrations carry statutory weight; incorrect types on amounts, tax rates, or document identifiers are audit-relevant, not cosmetic.
• Thin release surface (medium). A one-line fix with no accompanying test changes cited in the notes gives limited assurance the casting rules are now exhaustively specified across all Vendus response shapes.
• Single-maintainer concentration (medium). Package authored and maintained by one contributor; bus factor and response time to upstream API changes are unverified.

Key questions.

1. Does the package declare a typed DTO/contract for find results, or return arrays whose element types are now implicitly guaranteed?
2. Which fields changed type — monetary amounts, tax percentages, document IDs, series numbers, or timestamps — and does the fix cover nullable and zero-value cases?
3. Are there tests pinning the casting behaviour against recorded Vendus response fixtures?
4. What is our current pinned version in composer.json, and are we on a ^0.5 constraint that will silently absorb future 0.x minor releases?
5. Does the package cover the full document lifecycle we need (create, find, void/annul, PDF/QR retrieval), or only issuance?

Integration Approach

Stack fit. Standard Laravel package: composer install, optional config publish, facade or container-resolved client. It should be wrapped in our own InvoiceGateway interface with the package bound as the implementation, so a future swap (or a fork if the maintainer goes quiet) is a single binding change. Keep the package's DTOs out of our public domain contracts.

Migration path. There is nothing to migrate from — this is a greenfield integration assessment. Greenfield is the favourable case: we can adopt the wrapper pattern from day one rather than retrofitting it. If a parallel invoicing provider already exists in the codebase, model the new gateway on the same interface to keep the domain layer provider-agnostic.

Compatibility. Verify PHP and Laravel version constraints against our runtime before adoption; the release notes do not state them. Confirm Guzzle/HTTP client version alignment with the rest of the application to avoid a duplicate HTTP stack. Confirm whether credentials are read from config/services.php or a package-specific config file so secrets land in our existing secret-management path rather than a committed config file.

Sequencing.

1. Pin 0.5.4 exactly (not ^0.5) in composer.json; establish an explicit upgrade ritual for 0.x bumps.
2. Stand up the gateway interface plus a fake implementation so application code can be built and tested without network calls to Vendus.
3. Integrate against the Vendus sandbox/certification environment; capture real response fixtures for each document type we will issue.
4. Assert round-trip types explicitly in our own integration tests — do not rely on the package's internal tests to prove the v0.5.4 casting fix holds for our payloads.
5. Audit any pre-existing local casting workarounds and remove them once the pinned version is verified.
6. Promote to production behind a feature flag, with a manual reconciliation check on the first N documents.

Operational Impact

Maintenance. Low surface area, but the burden is real: an unmaintained wrapper around a fiscal API is a compliance liability. Assign a named owner and a review cadence for upstream releases. Because the package is 0.x, budget for at least one breaking change per quarter and keep the gateway interface stable so those changes stay contained. Track the Cegid Vendus API changelog independently — the package will always lag the provider.

Support. Escalation is effectively to a single upstream maintainer via GitHub issues, with no commercial SLA. For a fiscal system that is an unacceptable sole path. Mitigations: pin versions so upstream breakage cannot reach us unreviewed, retain the ability to vendor/fork the package (small codebase, MIT-style licence assumed — verify), and keep a documented manual fallback for issuing documents through the Vendus UI during an outage.

Scaling. Client-side concerns are modest: the bottleneck will be Vendus API rate limits and latency, not the PHP package. Ensure the integration runs in queued jobs with exponential backoff rather than synchronously in a request cycle, and that retries are idempotent — duplicate invoice issuance is a fiscal incident, not a transient error. Use the package's find capability as the idempotency check before retrying a create. Watch for unbounded result sets if find is used for listing; pagination behaviour is unconfirmed.

Failure modes.

• Type regression. The v0.5.4 fix is itself evidence that response typing is fragile. Guard with assertions at the gateway boundary: reject non-numeric amounts and unexpected nulls loudly rather than coercing.
• Silent upstream schema drift. Vendus adds or renames a field; casting quietly yields null. Detect via required-field validation on hydration.
• Partial failure. Document created upstream but our persistence fails, or vice versa. Requires a reconciliation job keyed on the Vendus document ID.
• Credential/network failure. Surfaces as generic HTTP exceptions; map to domain exceptions so callers can distinguish retryable from terminal.
• Certification/environment confusion. Issuing test documents against production is a real hazard; make the environment explicit in config and fail closed if unset.

Ramp-up. A Laravel developer can integrate the happy path in under a day. The expensive knowledge is domain, not package: Portuguese fiscal rules (ATCUD, QR code payload, series management, document retention, void-vs-credit-note semantics) and the certification process. Plan for one engineer to own the fiscal domain end to end, and do not treat the package as abstracting that domain away — it abstracts the HTTP call, not the compliance obligation.