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.

Important Legal Disclaimer
Requirements
Installation
Configuration
Quick Start
Common Workflows
Architecture Overview
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)
Composer 2.x
An active Cegid Vendus account with API access (for credentials and payment method IDs)

Installation

composer require csarcrr/invoicing-integration

Publish the configuration file once the package is installed:

php artisan vendor:publish --tag="invoicing-integration-config"

Configuration

Set your provider and credentials in .env:

INVOICING_INTEGRATION_PROVIDER=CegidVendus

# Cegid Vendus credentials
CEGID_VENDUS_API_KEY=your-api-key
CEGID_VENDUS_MODE=tests   # "tests" issues training documents, "normal" issues fiscal documents

# Payment method IDs (from Cegid Vendus UI)
CEGID_VENDUS_PAYMENT_MB_ID=123456
CEGID_VENDUS_PAYMENT_CREDIT_CARD_ID=123457
CEGID_VENDUS_PAYMENT_CURRENT_ACCOUNT_ID=123458
CEGID_VENDUS_PAYMENT_MONEY_ID=123459
CEGID_VENDUS_PAYMENT_MONEY_TRANSFER_ID=123460

config/invoicing-integration.php mirrors those values:

<?php

use CsarCrr\InvoicingIntegration\Enums\PaymentMethod;

return [
    'provider' => env('INVOICING_INTEGRATION_PROVIDER'),
    'providers' => [
        'CegidVendus' => [
            'key' => env('CEGID_VENDUS_API_KEY'),
            'mode' => env('CEGID_VENDUS_MODE'),
            'payments' => [
                PaymentMethod::MB->value => env('CEGID_VENDUS_PAYMENT_MB_ID'),
                PaymentMethod::CREDIT_CARD->value => env('CEGID_VENDUS_PAYMENT_CREDIT_CARD_ID'),
                PaymentMethod::CURRENT_ACCOUNT->value => env('CEGID_VENDUS_PAYMENT_CURRENT_ACCOUNT_ID'),
                PaymentMethod::MONEY->value => env('CEGID_VENDUS_PAYMENT_MONEY_ID'),
                PaymentMethod::MONEY_TRANSFER->value => env('CEGID_VENDUS_PAYMENT_MONEY_TRANSFER_ID'),
            ],
        ],
    ],
];

mode accepts normal (fiscal documents) or tests (training mode)
Payment IDs must match the numeric identifiers you copy from the Cegid Vendus UI (guide)

Quick Start

Issue an FT invoice with one item and a cash payment:

use CsarCrr\InvoicingIntegration\Enums\InvoiceType;
use CsarCrr\InvoicingIntegration\Enums\PaymentMethod;
use CsarCrr\InvoicingIntegration\Invoice;
use CsarCrr\InvoicingIntegration\Facades\ClientData;
use CsarCrr\InvoicingIntegration\ValueObjects\Item;
use CsarCrr\InvoicingIntegration\ValueObjects\Payment;

$invoice = Invoice::create()
    ->type(InvoiceType::Invoice);

$item = (new Item())
    ->reference('SKU-001')
    ->note('Consulting hours')
    ->price(10000)      // cents (100.00 €)
    ->quantity(1);

$payment = (new Payment())
    ->method(PaymentMethod::MONEY)
    ->amount(10000);

$client = ClientData::name('John Doe')
    ->vat('PT123456789')
    ->email('john@example.com');

$result = $invoice
    ->client($client)
    ->item($item)
    ->payment($payment)
    ->execute();

$sequence = $result->getSequence();
$result->getOutput()->save('invoices/' . $result->getOutput()->fileName());

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

Common Workflows

Architecture Overview

Invoice::create() (see src/Invoice.php) resolves the configured provider via the IntegrationProvider enum and returns a CreateInvoice builder.
Each provider implements the fluent builder contract. Currently, CsarCrr\InvoicingIntegration\IntegrationProvider\CegidVendus\Invoice\Create handles payload assembly, validation, and HTTP calls.
Traits under src/Traits/Invoice/ encapsulate builder capabilities such as clients, payments, transport, and notes.
Responses are normalized into value objects (src/ValueObjects/*) so your application code can remain provider-agnostic.

This separation keeps provider logic isolated while allowing the package to expose a consistent API.

Testing & Quality

composer test        # Pest test suite
composer analyse     # PHPStan (Larastan) analysis
composer format      # Laravel Pint code style
composer complete    # Format + analyse + test (helper script)

Documentation

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

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: January 2026

csarcrr / invoicing-integration

Maintainers

Details