Laravel Fatture In Cloud Laravel Package

Technical Evaluation

datomatic/laravel-fatture-in-cloud is a community-built Laravel wrapper over the Fatture in Cloud (FIC) REST API v2. In practical terms it is an HTTP client abstraction with Laravel ergonomics — service provider, config file, facade, and resource-oriented methods — that saves the team from hand-rolling authentication, pagination, and endpoint plumbing. It is not an opinionated domain layer: it does not model invoicing workflows, SdI lifecycle, or compliance rules. Treat it as an accelerator for the transport tier, not as an integration strategy.

Architecture fit

• Good fit if our application is Laravel and FIC is a system-of-record for invoicing/accounting, with our app as the originating system (orders → invoices, customers → anagrafiche, and PDF/document retrieval).
• Poor fit if we need deep domain modelling of Italian e-invoicing (SdI states, VAT regimes, withholding, split payments, reverse charge). Those semantics live in FIC and in our business logic; the wrapper only moves payloads.
• The package boundary is thin enough that we can keep it behind our own InvoiceGateway interface. That is the single most valuable architectural decision here — it converts a 10-star dependency into a swappable adapter.
• Expect it to map roughly one method per FIC endpoint with typed-ish array payloads. Verify whether it returns typed DTOs or raw arrays; this determines how much defensive mapping we write.

Integration feasibility

• Low technical barrier: composer require, publish config, wire OAuth2 app credentials (client ID/secret) and per-tenant tokens. The real effort is OAuth consent flow, token storage, and refresh, which the package may or may not own end-to-end.
• FIC provides a sandbox/"companies" test environment; plan to validate against it before touching production data.
• Feasibility hinges on credentials management: multiple customers = multiple FIC accounts = multi-tenant token storage. Confirm the package supports resolving credentials per-tenant, not just a single global env config.
• Laravel's Http fake / Saloon-style mocking (whichever the package uses) makes contract tests cheap; confirm testability before committing.

Technical risk

• Bus factor and maturity: 10 stars, small maintainer org, MIT. This is the dominant risk — not functionality, but longevity. Assume we may need to fork within 12–18 months and budget accordingly.
• API surface drift: FIC API v2 evolves; a thin community wrapper lags. Any breaking change on FIC's side becomes our outage unless we can patch.
• Idempotency: document creation is a financial event. If the wrapper does not expose or implement idempotency keys/retry-safe creation, we must add it at our adapter layer or risk duplicate invoices — a compliance problem, not just a data-quality one.
• Error fidelity: confirm whether FIC validation errors and SdI rejection reasons are surfaced verbatim or flattened. Flattened errors make reconciliation and user remediation painful.
• Auth/token handling: verify refresh-and-retry on 401, concurrent-refresh safety, and where tokens are persisted (cache? DB? encrypted?).
• Version constraints: check composer.json for supported Laravel/PHP ranges against our baseline (Laravel 11/12, PHP 8.2+). A narrow range can force an upgrade we do not want.

Key questions

1. Does it manage the full OAuth2 lifecycle (authorize, refresh, revoke) or only bearer-token consumption?
2. Does it support per-tenant credential resolution for a multi-account SaaS deployment?
3. Are entity payloads typed DTOs, arrays, or a mix — and how stable is that contract across minor versions?
4. How are rate limits (429) and transient 5xx handled — retry with backoff built in, or left to us?
5. Is there first-class support for document upload/PDF retrieval and e-invoice XML, or only JSON invoice CRUD?
6. What is the test suite quality, and is there a published coverage or CI signal?
7. Who is the maintainer, what is their response history on issues, and is there a stated deprecation policy?

Integration Approach

Stack fit

• Requires Laravel with a modern HTTP client and service-container conventions. Sits cleanly alongside existing Http, Queue, and Cache primitives — no new infrastructure.
• Wrap it: define our own BillingGateway interface with a small set of domain methods (issueInvoice, registerCustomer, fetchDocument, voidDocument). The package becomes one implementation behind that interface. This is non-negotiable given the maturity profile.
• Keep FIC-specific payload shaping in an anti-corruption layer so FIC field names never leak into controllers or jobs.

Migration path

• If replacing manual Guzzle calls or an older SDK, extract the call sites behind the new interface first, then swap the implementation. Behaviour parity is easier to assert than a big-bang switch.
• Start read-only: list companies, fetch customers, list invoices. Prove auth, pagination, and error mapping before enabling writes.
• Then enable low-risk writes (create customer), then document creation, then document state transitions.
• Backfill strategy: import or sync existing records via the sandbox first, then a controlled production run against a test company.

Compatibility

• Pin the package version explicitly and commit the lockfile. With a small maintainer base, allow minor-version drift only through a reviewed PR.
• Validate Laravel/PHP constraints against our matrix; if incompatible, fork and relax constraints rather than downgrading the framework.
• Confirm API version pinning: the wrapper should target FIC v2 explicitly; watch for v2.1-style additive changes that alter response shapes.
• Test against FIC sandbox in CI nightly (a smoke test), so upstream drift is detected by us before customers.

Sequencing

1. Spike (1–2 days): auth flow, one read, one write, one error case in sandbox. Decide build-vs-adopt.
2. Define BillingGateway interface and error taxonomy.
3. Implement adapter over the package; add idempotency keys and retry policy at this layer.
4. Multi-tenant credential storage + rotation.
5. Queue-backed write path with dead-letter handling and reconciliation job.
6. Observability: structured logs per FIC request, correlation IDs, alerting on 4xx validation spikes.
7. Production rollout behind a feature flag, per-tenant.

Operational Impact

Maintenance

• Budget a standing allowance (roughly 0.1–0.2 FTE) for dependency upkeep and FIC API drift. Small, but it must be named and owned.
• Vendor-risk mitigation: keep the fork path exercised — confirm we can build from a fork and release internally within a day.
• Track upstream releases and FIC changelog in the same review cadence; do not let either drift unobserved.

Support

• First-line support will field "invoice didn't appear" tickets. That requires runbook-level visibility into FIC request/response pairs and document IDs. Instrument the adapter from day one.
• Error taxonomy must be human-actionable: auth failure (our config), validation failure (bad data, user-fixable), SdI rejection (compliance, needs finance), platform outage (retry). Support routing depends on this distinction.
• Publish an internal doc mapping our domain errors to FIC errors so support does not read raw API payloads.

Scaling

• Throughput will be bounded by FIC rate limits, not by us. Design for it: queue writes, batch where the API allows, and apply token-bucket throttling per tenant.
• Read-heavy paths (invoice listing, PDF fetch) should be cached where legal/commercially sensible; PDFs are immutable once issued, making them good cache candidates.
• Multi-tenant scaling means many credential sets and many rate-limit buckets — track per-tenant quota consumption, not just global.
• Horizontal scaling of our app is unaffected; the package is stateless apart from token storage, which must be shared (cache/DB), not in-process.

Failure modes

• Token expiry / refresh race: concurrent workers refreshing simultaneously can invalidate each other. Mitigate with a lock around refresh and a shared token store.
• Duplicate document creation: biggest blast radius. Enforce idempotency at the adapter and a reconciliation job that compares our records to FIC's by external reference.
• Partial failure: customer created, invoice failed — leaves inconsistent state. Use a saga/compensation pattern with explicit states, not fire-and-forget.
• SdI rejection after acceptance: FIC may accept a document that SdI later rejects. Our system must model that asynchronous state, not treat 201 as final.
• Upstream API change: nightly sandbox smoke tests plus contract tests are the only realistic early warning.
• Silent data loss on pagination: verify the wrapper iterates all pages; a truncated customer list corrupts downstream matching.

Ramp-up

• A Laravel developer unfamiliar with FIC needs roughly 3–5 days to be productive: 1 day on the package and auth, 2–3 days on FIC domain concepts (companies, issued vs received docs, SdI states, VAT regimes), 1 day on our adapter and runbooks.
• Finance/ops stakeholders need a separate, non-technical walkthrough of document states and rejection handling — this is where most production surprises originate.
• Produce a one-page "FIC integration" runbook covering credential rotation, replay of failed jobs, and duplicate remediation before go-live.
• Given the maturity signal, make sure at least two engineers understand the adapter — not one. The dependency's bus factor should not become ours.