README

🔙 This is the documentation for the API v2. You can find the package for the API v1 here.

Warning for integrators

• Keep your copy up to date: Check the official laravel-fatture-in-cloud-v2 package and update your local dependency (e.g. run composer update offline-agency/laravel-fatture-in-cloud-v2 or pull the latest from the repository).
• Response variables are camelCase: Entity properties use camelCase (e.g. amountGross, amountNet, amountVat), not snake_case (amount_gross, amount_net, amount_vat). If you have existing code that reads response data, update it to use the new property names. Use the entity classes in this package as the reference—for example, IssuedDocument for issued documents. Examples: amount_gross → amountGross, amount_net → amountNet, created_at → createdAt.
• Config: Check the package config config/fatture-in-cloud-v2.php and update your project’s config to match, especially baseUrl. Use the root API URL only (no extra path segments).

Requirements

• PHP ^8.4 (includes 8.5)
• Laravel ^11.0|^12.0|^13.0

API Granularization (Breaking Changes)

The monolithic Settings and Setting classes have been split into granular resources to improve maintainability and strictly follow the Single Responsibility Principle:

• Settings -> Split into VatType, PaymentAccount, and PaymentMethod.
• ArchiveDocument -> Renamed to Archive.
• Cashbooks -> Renamed to Cashbook.
• New classes added: Email, Situation, PriceList, and Webhook.

Strictly Typed & Readonly Entities

All entities (e.g., Client, IssuedDocument, PriceList) have been refactored to be readonly classes with strict types.

• Properties are now immutable.
• Usage of mixed types has been minimized in favor of strict string, int, float, bool, etc.
• Constructors ensure safe data mapping from API responses.

Modern testing suite

• Switched from PHPUnit to Pest PHP for a more expressive and modern testing experience.
• Automated code styling with Laravel Pint.

Architecture

• The package now utilizes a central FattureInCloud connector for better state management.
• API interactions are handled via the native Laravel Http client.

Documentation, Installation, and Usage Instructions

This package provides a simple Laravel integration with Fatture in Cloud APIs v2.

See the documentation for detailed installation and usage instructions.

$issued_documents = new \OfflineAgency\LaravelFattureInCloudV2\Api\IssuedDocument();
$issued_document_list = $issued_document->list('invoice', [
    'per_page' => 50
]);  

// return an array of invoices 
$issued_document_list->getItems();

// return pagination fields like page, per_page...
$issued_document_list->getPagination();

// return single product's fields
$product = new \OfflineAgency\LaravelFattureInCloudV2\Api\Product();
$product_detail = $product->detail($product_id);

Features

All

This package provide all() method that allow you to get an array of all results without pagination. It's implemented for all endpoint that provide a list method with pagination. Let's see an example:

$issued_documents = new \OfflineAgency\LaravelFattureInCloudV2\Api\IssuedDocument();
$issued_document_list = $issued_documents->all('invoice');

Pagination

This package provides a pagination system that allow you to move between pages using simple methods:

$issued_documents = new \OfflineAgency\LaravelFattureInCloudV2\Api\IssuedDocument();
$issued_document_list = $issued_documents->list('invoice');

// check if the response has more than one page
$issued_document_list->getPagination()->isSinglePage();

// check if the document has a next page
$issued_document_list->getPagination()->hasNextPage();

// check if the document has a previous page
$issued_document_list->getPagination()->hasPrevPage();

// return documents of the next page
$issued_document_list->getPagination()->goToNextPage();

// return documents of the previous page
$issued_document_list->getPagination()->goToPrevPage();

// return documents of the first page
$issued_document_list->getPagination()->goToFirstPage();

// return documents of the last page
$issued_document_list->getPagination()->goToLastPage();

Bin

This package provides bin() method for deleted issued documents that allow you to get its detail. This is very useful, for example, when you convert a proforma into an invoice (deleting the proforma) and you need old document's detail. Let's see an example:

$issued_documents = new \OfflineAgency\LaravelFattureInCloudV2\Api\IssuedDocument();
$response = $issued_documents->bin($document_id);

Rate limit

This package provides a method to intercept throttle errors (403, 429) and automatically retry. You can specify limits on your config, remember to use milliseconds to indicate time:

'limits' => [
    'default' => 300000,
    '403' => 300000,
    '429' => 3600000,
],

API coverage

We are currently work on this package to implement all endpoints. Enable notifications to be notified when new API are released.

✅ User

✅ Companies

✅ Clients

✅ Suppliers

✅ Products

✅ Issued Documents

✅ Issued e-invoices

✅ Received Documents

✅ Receipts

✅ Taxes

✅ Archive

✅ Cashbook

✅ Info

✅ Price Lists

✅ Webhooks

✅ Situation

✅ Emails

✅ Stock

✅ Payment Accounts

✅ Payment Methods

✅ VAT Types

Testing

composer test

Unit and Feature tests use mocked HTTP. To run integration tests (real HTTP calls to Fatture in Cloud), set in .env:

• FCV2_DEFAULT_ID – company ID
• FCV2_DEFAULT_BEARER – API bearer token

Then run:

php vendor/bin/pest tests/Integration

If these env vars are not set, integration tests are skipped.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security-related issues, please email support@offlineagency.com instead of using the issue tracker.

Credits

• Offline Agency
• Giacomo Fabbian
• Nicolas Sanavia
• All Contributors

About us

Offline Agency is a web design agency based in Padua, Italy. You'll find an overview of our projects on our website.

License

The MIT License (MIT). Please see License File for more information.