Laravel Holded Laravel Package

Product Decisions This Supports

• Build vs. buy for Holded integrations — v3.0 turns this from a thin API wrapper into a production-grade integration layer: retries with backoff, typed exceptions, a DTO for contact payloads, and file/PDF handling mean the team can ship Holded-connected features without writing (or maintaining) custom HTTP plumbing.
• Feature delivery on document and contact workflows — File attachments and PDF retrieval unlock concrete customer-facing features: invoice/estimate PDF delivery, attaching signed contracts or supplier documents to Holded records, and automated document archival — all without leaving the Laravel app.
• Roadmap confidence for ERP-adjacent work — The explicit Laravel 11/12 and PHP 8.2 support matches modern framework upgrade plans, so Holded functionality won't block a Laravel upgrade. Factor this into the framework upgrade timeline rather than treating Holded as a legacy holdout.
• Reliability/SLO commitments — Automatic retry on 429 and 5xx plus isRateLimited()/isServerError() semantics let the team define failure behavior deliberately (retry, queue, surface to user) instead of guessing at Guzzle exception types. This directly supports decisions about whether Holded calls can run synchronously or must be queued.
• Reduced maintenance budget — The extracted BaseModule and the 49-test suite lower the ongoing cost of ownership; that's a budget line item to weigh against a paid integration platform or in-house code.
• Scope signal on what's still missing — No mention of webhooks, pagination helpers, or read-side query modules; plan features that depend on inbound Holded events or bulk sync accordingly, possibly as custom work on top.

When to Consider This Package

Adopt when:

• The product runs on Laravel 11 or 12 with PHP 8.2+, and Holded is a system the team will integrate with directly rather than through a middleware vendor.
• The required surface area is documents and contacts (create/update, upload attachments, download PDFs) — these are the mature, tested paths.
• Predictable failure handling matters: you want typed exceptions and configurable retries rather than raw Guzzle errors leaking into domain logic.
• You want a maintained dependency with an authored test suite instead of hand-rolled HTTP clients per feature.

Look elsewhere, or budget custom work, when:

• The runtime is PHP 8.1 or Laravel 10 or below — v3.0's raised floor and constructor changes make this a hard break.
• You need broad Holded coverage (invoicing ledgers, inventory, accounting reports, webhooks) — the release notes only evidence document and contact modules.
• Your architecture needs an event-driven or sync-oriented integration (webhooks, incremental sync, bulk backfill); nothing here indicates support for that.
• You require vendor SLA/support contracts or an abstraction layer that lets you swap ERP providers; this is Holded-specific and couples you to its API shape.
• You're already standardized on an iPaaS (Zapier/Make/n8n) for ERP connectivity and have no in-app need for typed Holded objects.

How to Pitch It (Stakeholders)

For executives: This release moves our Holded integration from a fragile prototype to something we can put in front of customers. It adds reliability (automatic retries when Holded is busy or erroring), clear error reporting instead of cryptic failures, and two new capabilities — attaching files to documents and pulling invoice/estimate PDFs — that map directly to features customers ask for. It is tested (49 automated tests) and explicitly supports the Laravel versions we're standardizing on, so it won't hold back our framework upgrades. Cost is low and contained: one dependency, no new infrastructure, no vendor contract. The caveats are honest ones — it requires PHP 8.2+ and Laravel 11+, so we should confirm our deployment baseline, and it covers documents and contacts rather than all of Holded, so anything beyond that is scoped separately.

For engineering: Adopt v3.0 and treat the upgrade as a small migration, not a rewrite. Three things to plan for: the PHP 8.2 floor, HoldedException replacing bubbled Guzzle exceptions (any existing catch (GuzzleException) or RequestException handlers need updating, and this is actually an improvement — use isRateLimited()/isServerError()/isClientError() for branching), and the new $retryConfig constructor parameter (update any manual module instantiation, or move to container resolution). Wire retry behavior through config/holded.php per environment — conservative in request-path code, more aggressive in queued jobs. Prefer the ContactData DTO over raw arrays for contacts to get validation and normalization for free, and keep arrays only at the boundaries. Route attach() and pdf() calls through queued jobs where file sizes or latency could affect response times, and note that pdf() returns base64 — decide deliberately on decode-and-store versus stream-through. Finally, log the response body from HoldedException on 4xx so we can distinguish our own malformed payloads from Holded-side issues; the exception gives us that detail, but it needs to reach our observability stack to be worth anything.