PHPackages csarcrr/invoicing-integration - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. csarcrr/invoicing-integration ActiveLibrary csarcrr/invoicing-integration ============================= This package aims to help integrations with invoicing systems v0.5.4(1mo ago)562[1 PRs](https://github.com/csarcrr/invoicing-integration/pulls)MITPHPPHP ^8.2CI passing Since Nov 8Pushed 1mo agoCompare [ Source](https://github.com/csarcrr/invoicing-integration)[ Packagist](https://packagist.org/packages/csarcrr/invoicing-integration)[ Docs](https://github.com/csarcrr/invoicing-integration)[ GitHub Sponsors](https://github.com/:vendor_name)[ RSS](/packages/csarcrr-invoicing-integration/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (10)Dependencies (30)Versions (29)Used By (0) Invoicing Integration ===================== [](#invoicing-integration) [![Latest Version on Packagist](https://camo.githubusercontent.com/37ddf05d8b70549774c8e38a5bf1b4936fec7600597470c906321f0b68d2fa99/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f637361726372722f696e766f6963696e672d696e746567726174696f6e2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/csarcrr/invoicing-integration)[![GitHub Tests Action Status](https://camo.githubusercontent.com/27ff5f1869b0a6a2b634d3fd9d19f0b1850e1ebaccb2b838027ba9d7b6f89ce2/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f637361726372722f696e766f6963696e672d696e746567726174696f6e2f66756c6c2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/csarcrr/invoicing-integration/actions?query=workflow%3Arun-tests+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/f01ac1f574a767fd29f55ae5bb515ca738c47c62802bb7a6d149817bd2d7084d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f637361726372722f696e766f6963696e672d696e746567726174696f6e2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/csarcrr/invoicing-integration) **Invoicing Integration** is a Laravel package that aggregates invoicing software providers in Portugal. It offers a fluent, provider-agnostic API so you can issue compliant documents without re-learning each vendor's HTTP contract. > **Supported provider (today):** Cegid Vendus. The package architecture allows more providers to be added without changing your application code. Why Invoicing Integration? -------------------------- [](#why-invoicing-integration) Issuing fiscally compliant invoices in Portugal can be challenging. Each provider has its own API, authentication flow, and data formats. This package solves that by giving you: - **One API for all providers** - Switch providers without rewriting your integration - **Fluent builders** - Intuitive, chainable methods that read like natural language - **Built-in validation** - Catch errors before they reach the provider - **Type safety** - Strongly typed DTOs powered by `spatie/laravel-data` Highlights ---------- [](#highlights) - Fluent builders for all fiscal document types (FT, FR, FS, RG, NC, GT) - DTO-first workflows via `InvoiceData`, so requests/responses share the same typed object - First-class client management via the `Client` facade (create, get, find) - Strongly typed DTOs powered by `spatie/laravel-data` - Built-in PDF / ESC/POS outputs with secure file persistence helpers - Centralized HTTP error handling and provider configuration facades Table of Contents ----------------- [](#table-of-contents) - [Important Legal Disclaimer](#important-legal-disclaimer) - [Requirements](#requirements) - [Installation](#installation) - [Configuration](#configuration) - [Usage](#usage) - [Quick Start](#quick-start) - [Error Handling](#error-handling) - [Testing & Quality](#testing--quality) - [Documentation](#documentation) - [Contributing](#contributing) - [Security](#security) - [License](#license) Important Legal Disclaimer -------------------------- [](#important-legal-disclaimer) **This package facilitates invoicing provider API usage and is not intended to serve as legal guidance.** It is **your responsibility** to: - Comply with all invoicing laws and regulations in your jurisdiction - Understand each provider's specific requirements - Ensure proper invoicing practices according to your legal obligations - Validate that your usage complies with tax laws and accounting standards Always consult with legal and accounting professionals when implementing invoicing solutions. Requirements ------------ [](#requirements) - PHP 8.2+ - Laravel 11.x or 12.x (`illuminate/contracts: ^11.0 || ^12.0`) Installation ------------ [](#installation) ``` composer require csarcrr/invoicing-integration ``` Publish the configuration file once the package is installed: ``` php artisan vendor:publish --tag="invoicing-integration-config" ``` See the documentation section: Getting Started - 4. Configuration File for detailed configuration instructions. ### Runtime access to provider configuration [](#runtime-access-to-provider-configuration) Use the `ProviderConfiguration` facade when you need to inspect or cache the active provider during runtime: ``` use CsarCrr\InvoicingIntegration\Facades\ProviderConfiguration; $activeProvider = ProviderConfiguration::getProvider(); $config = ProviderConfiguration::getConfig(); ``` ### Environment reference [](#environment-reference) VariableDescription`INVOICING_INTEGRATION_PROVIDER`Provider key (`CegidVendus` for now)`CEGID_VENDUS_API_KEY`API token generated in Vendus`CEGID_VENDUS_MODE``tests` (sandbox/training) or `production` (fiscal)`CEGID_VENDUS_PAYMENT_*`Mapping between `PaymentMethod` enums and Vendus payment IDs> The package validates configuration lazily when you issue invoices or clients, so misconfigured payment IDs will raise descriptive exceptions before the HTTP call is sent. Usage ----- [](#usage) ### Creating an invoice [](#creating-an-invoice) Every invoice now starts with a populated `InvoiceData` DTO. Pass the DTO to the `Invoice` facade and the package handles provider translation for you. ``` use CsarCrr\InvoicingIntegration\Data\ClientData; use CsarCrr\InvoicingIntegration\Data\InvoiceData; use CsarCrr\InvoicingIntegration\Data\ItemData; use CsarCrr\InvoicingIntegration\Data\PaymentData; use CsarCrr\InvoicingIntegration\Enums\InvoiceType; use CsarCrr\InvoicingIntegration\Enums\PaymentMethod; use CsarCrr\InvoicingIntegration\Facades\Invoice; $invoiceData = InvoiceData::make([ 'type' => InvoiceType::InvoiceReceipt, 'client' => ClientData::make([ 'name' => 'Maria Silva', 'vat' => 'PT123456789', 'email' => 'maria.silva@email.pt', 'address' => 'Rua Augusta, 25', 'city' => 'Lisboa', 'postalCode' => '1100-053', 'country' => 'PT', ]), 'items' => [ ItemData::make([ 'reference' => 'HEADPHONES-PRO', 'note' => 'Wireless Noise-Cancelling Headphones', 'price' => 14999, // 149.99 in cents 'quantity' => 1, ]), ItemData::make([ 'reference' => 'SHIPPING-STD', 'note' => 'Standard Delivery (2-3 business days)', 'price' => 499, // 4.99 in cents ]), ], 'payments' => [ PaymentData::make([ 'method' => PaymentMethod::CREDIT_CARD, 'amount' => 15498, // Total: 154.98 ]), ], ]); $invoice = Invoice::create($invoiceData)->execute()->getInvoice(); if ($invoice->output) { $invoice->output->save('invoices/' . $invoice->output->fileName()); } ``` The result contains everything you need: ``` { "id": 4567, "sequence": "FR 01P2025/1", "total": 15498, "totalNet": 12600, "atcudHash": "FR 01P2025/1 ABC123" } ``` > `ClientData`, `ItemData`, `PaymentData`, and other value objects extend `spatie/laravel-data\Data`. Instantiate them with `::make([...])` (or via dependency injection) so validation and transformers run before each HTTP request. > Prefer the `Invoice` facade for day-to-day usage. If you need to resolve the underlying action for dependency injection (e.g., in jobs), bind `CsarCrr\InvoicingIntegration\InvoiceAction` from the container. **Key rules:** - At least one item is required for FT/FR/FS/NC documents - Payments are required for FR, FS, RG, and NC types - Tax exemptions require `ItemTax::EXEMPT` plus a valid `TaxExemptionReason` ### Manage clients via the facade [](#manage-clients-via-the-facade) You can register customers in the provider so they can be reused across orders: ``` use CsarCrr\InvoicingIntegration\Data\ClientData; use CsarCrr\InvoicingIntegration\Facades\Client; // Register a new customer $client = Client::create( ClientData::make([ 'name' => 'TechStore Portugal Lda', 'vat' => 'PT509876543', 'email' => 'invoices@techstore.pt', 'address' => 'Zona Industrial do Porto, Lote 15', 'city' => 'Porto', 'postalCode' => '4100-000', 'country' => 'PT', ]) )->execute()->getClient(); // Retrieve the customer later by their provider ID $fetched = Client::get(ClientData::make(['id' => $client->id]))->execute()->getClient(); // Search for customers by email domain $filters = ClientData::make(['email' => 'techstore.pt']); $results = Client::find($filters)->execute(); ``` See [docs/clients/README.md](docs/clients/README.md) for pagination and filtering options. > All DTOs expose public typed properties. Access values via `$client->name`, `$invoice->sequence`, etc. - legacy getter methods no longer exist. ### Common validation rules [](#common-validation-rules) - Receipts (RG) are the only document without items - Credit notes require related document references, payments, and a reason - Transport details require a client, origin date, and valid ISO 3166-1 codes - Output formats (`PDF_BASE64`, `ESCPOS`) can be persisted via the `Output` value object (`save()`, `getPath()`, etc.) Quick Start ----------- [](#quick-start) For detailed workflows per document type, visit: - [Creating an Invoice](docs/invoices/creating-an-invoice.md) - [Creating a Receipt (RG)](docs/invoices/creating-a-RG-for-an-invoice.md) - [Credit Notes (NC)](docs/invoices/creating-a-nc-invoice.md) - [Outputting documents (PDF/ESC-POS)](docs/invoices/outputting-invoice.md) Error Handling -------------- [](#error-handling) The `Http::handleUnwantedFailures()` macro maps HTTP status codes to package-specific exceptions: - `UnauthorizedException` - invalid or missing credentials (401) - `FailedReachingProviderException` - provider error/unreachable (500) - `RequestFailedException` - provider returned structured errors Refer to [docs/handling-errors.md](docs/handling-errors.md) for the full exception matrix and troubleshooting steps. Testing & Quality --------------------- [](#testing--quality) ``` composer test # Pest (parallel) test suite composer analyse # PHPStan (Larastan) analysis composer format # Laravel Pint code style composer complete # Format + analyse + test ``` Documentation ------------- [](#documentation) Browse the full documentation at [csarcrr.github.io/invoicing-integration](https://csarcrr.github.io/invoicing-integration/#/). - [Features Matrix](docs/features.md) - [API Reference](docs/api-reference.md) - [Clients](docs/clients/README.md) - [Provider Guides](docs/providers/README.md) Contributing ------------ [](#contributing) Please see [CONTRIBUTING.md](CONTRIBUTING.md) for coding standards, branching strategy, and release process. Security -------- [](#security) Please review [the security policy](https://github.com/csarcrr/invoicing-integration/security/advisories) to learn how to report vulnerabilities. License ------- [](#license) The MIT License (MIT). See [LICENSE.md](LICENSE.md) for the full text. --- *Last updated: February 2026* ### Health Score 44 — FairBetter than 91% of packages Maintenance96 Actively maintained with recent releases Popularity15 Limited adoption so far Community9 Small or concentrated contributor base Maturity48 Maturing project, gaining track record Bus Factor1 Top contributor holds 98.2% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~8 days Recently: every ~3 days Total 17 Last Release 50d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/cf46d1c4226cb0f4f1d55f3e9cb356b0f96347bc7a21a2f063cb275ea997b0c4?d=identicon)[cesardcorreia](/maintainers/cesardcorreia) --- Top Contributors [![csarcrr](https://avatars.githubusercontent.com/u/8506726?v=4)](https://github.com/csarcrr "csarcrr (163 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (2 commits)")[![Copilot](https://avatars.githubusercontent.com/in/1143301?v=4)](https://github.com/Copilot "Copilot (1 commits)") --- Tags invoicing-toollaravellaravel-packagelegaltoolsportugalportuguese-invoicingsaft-ptlaravelcsarcrrinvoicing-integration ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/csarcrr-invoicing-integration/health.svg) ``` [![Health](https://phpackages.com/badges/csarcrr-invoicing-integration/health.svg)](https://phpackages.com/packages/csarcrr-invoicing-integration) ``` ### Alternatives [vormkracht10/laravel-mails Laravel Mails can collect everything you might want to track about the mails that has been sent by your Laravel app. 24149.7k](/packages/vormkracht10-laravel-mails)[danestves/laravel-polar A package to easily integrate your Laravel application with Polar.sh 7812.3k](/packages/danestves-laravel-polar)[tarfin-labs/event-machine Event-driven state machines for Laravel with event sourcing, type-safe context, and full audit trail. 188.5k](/packages/tarfin-labs-event-machine)[basillangevin/laravel-data-json-schemas Transforms Spatie Data objects into JSON Schemas with built-in validation 1312.2k1](/packages/basillangevin-laravel-data-json-schemas)[a2insights/filament-saas Filament Saas for A2Insights 161.1k](/packages/a2insights-filament-saas) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)