README

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?

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

• 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

• Important Legal Disclaimer
• Requirements
• Installation
• Configuration
• Usage
• Quick Start
• Error Handling
• Testing & Quality
• Documentation
• Contributing
• Security
• License

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

• PHP 8.2+
• Laravel 11.x or 12.x (illuminate/contracts: ^11.0 || ^12.0)

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

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

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

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

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 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

• 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

For detailed workflows per document type, visit:

• Creating an Invoice
• Creating a Receipt (RG)
• Credit Notes (NC)
• Outputting documents (PDF/ESC-POS)

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 for the full exception matrix and troubleshooting steps.

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

Browse the full documentation at csarcrr.github.io/invoicing-integration.

• Features Matrix
• API Reference
• Clients
• Provider Guides

Contributing

Please see CONTRIBUTING.md for coding standards, branching strategy, and release process.

Security

Please review the security policy to learn how to report vulnerabilities.

License

The MIT License (MIT). See LICENSE.md for the full text.

Last updated: February 2026