Invoicing Integration Laravel Package

Getting Started

• Install via Composer: composer require csarcrr/invoicing-integration. Laravel auto-discovers the service provider.
• Publish config: php artisan vendor:publish --tag=invoicing-integration-config. Review config/invoicing-integration.php for driver selection and credentials.
• Set required environment variables for your provider (e.g. CEGID_VENDUS_API_KEY, CEGID_VENDUS_BASE_URL, CEGID_VENDUS_CLIENT_ID). Check the package README for the exact keys per driver.
• Look first at the InvoicingIntegration facade (or InvoicingIntegrationManager class) to see available methods: driver(), invoices(), clients(), find(), etc.
• First use case: retrieve a known invoice by ID to confirm connectivity and result casting:

  use Csarcrr\InvoicingIntegration\Facades\InvoicingIntegration;
  $invoice = InvoicingIntegration::driver('cegid_vendus')->invoices()->find('INV-123');
  dump($invoice->total, $invoice->status); // verify types are correct after v0.5.4
  

• For creating a simple invoice, refer to the README's "Quick Start" example. Start with a sandbox/test environment if the driver supports it.

Implementation Patterns

• Driver-based usage: The package likely exposes a manager that resolves drivers (e.g. Cegid Vendus, maybe others). Always call InvoicingIntegration::driver('cegid_vendus') explicitly in production to avoid config drift.
• Service layer / actions: Wrap package calls in your own action classes (e.g. CreateInvoiceAction, FindInvoiceAction) to isolate your domain from the package API. This makes it easier to swap drivers later.
• DTO / result objects: The package returns result objects (the v0.5.4 fix concerns type casting in find results). Use these directly or map them to your own DTOs. Check the package's CegidVendus client classes for the exact return types.
• Testing: Use Laravel's Http::fake() to mock API responses. The package likely uses Laravel's HTTP client. Write feature tests that fake responses for find, create, and list methods.
• Queues / retries: For invoice creation, dispatch a queued job. The package may throw exceptions on API errors; wrap in try/catch and use $job->release() or retry logic. Check for rate-limiting headers in the driver.
• Multi-tenant: If integrating for multiple clients, resolve credentials dynamically per tenant. The config may support per-driver credentials; consider binding a configured driver instance per tenant via a service container.
• Events / webhooks: If the package supports webhooks (check README), register routes and validate signatures. Otherwise, poll for status changes.

Gotchas and Tips

• Type casting in find results (fixed in v0.5.4): Before this patch, CegidVendus client find results may have returned numeric fields as strings. Upgrade to v0.5.4+ if you rely on $invoice->total being a float/int. After upgrading, re-test any strict comparisons.
• Driver name casing: Config keys and driver names are usually snake_case. Check config/invoicing-integration.php for the exact driver key (e.g. cegid_vendus not CegidVendus).
• API version pinning: Some drivers require a specific API version header. The package config may expose it. Verify against provider docs; do not assume defaults.
• Error handling: The package may throw provider-specific exceptions. Catch \Csarcrr\InvoicingIntegration\Exceptions\InvoicingIntegrationException (or similar) and map to your domain errors. Log the raw response for debugging.
• Result objects are not arrays: Use ->toArray() if available, or access properties. Do not cast to array blindly; nested objects may not serialize as expected.
• Testing HTTP fakes: If using Http::fake(), ensure you fake the correct URL pattern. The driver may append paths like /api/v1/invoices. Check the client's base URL and endpoints.
• Extension points: If you need a custom driver, implement the driver contract (likely Csarcrr\InvoicingIntegration\Contracts\Driver) and register it in the config or via the manager's extend() method if available.
• Debugging: Enable Laravel's HTTP client logging (Http::withOptions(['debug' => true]) or use Log::debug()) in a local environment. The package may not log requests by default.
• Update strategy: This is a pre-1.0 package (v0.5.x). Pin to a minor version in composer.json (^0.5.4) and review changelogs for breaking changes between minor releases. v0.5.4 is a patch fix; safe to upgrade from v0.5.3.