laravel-fatture-in-cloud-v2.md

meta	gitName
name content description A simple Laravel integration with Fatture in Cloud APIs v2.	laravel-fatture-in-cloud-v2

laravel-fatture-in-cloud-v2

A simple Laravel integration with Fatture in Cloud APIs v2.

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

Installation

Install the package through Composer.

Run the Composer require command from the Terminal:

composer require offline-agency/laravel-fatture-in-cloud-v2

You should publish config file with:

php artisan vendor:publish --provider="OfflineAgency\LaravelFattureInCloudV2\LaravelFattureInCloudV2ServiceProvider"

Configuration

Package provide multiple-companies handling. In your config you can provide more companies like that

... 

'companies' => [
    'default' => [
        'id' => env('FCV2_DEFAULT_ID', ''),
        'bearer' => env('FCV2_DEFAULT_BEARER', '')
    ],
    'first_company' => [
        'id' => env('FCV2_FIRST_COMPANY_ID', ''),
        'bearer' => env('FCV2_FIRST_COMPANY_BEARER', '')
    ],
    'second_company' => [
        'id' => env('FCV2_SECOND_COMPANY_ID', ''),
        'bearer' => env('FCV2_SECOND_COMPANY_BEARER', '')
    ]
]

Then you can specify (or not) a company on class initialization:

// take the default
$issued_documents = new \OfflineAgency\LaravelFattureInCloudV2\Api\IssuedDocument();

// specify company
$issued_documents = new \OfflineAgency\LaravelFattureInCloudV2\Api\IssuedDocument('first_company');

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

For the example described above the package also provide the binDetail() method. It allows you to get the invoice from the ID of a deleted proforma.

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

Usage instructions & examples

This package provides a class for each api group like clients, issued documents, products... After instantiate one of them you can access to all its endpoints. Here you can see an example of just how simple this package is to use.

$client = new \OfflineAgency\LaravelFattureInCloudV2\Api\Client();
$client_list = $client->list();

This snippet returns an instance of \OfflineAgency\LaravelFattureInCloudV2\Entities\Client\ClientList that provide 3 public methods:

• hasItems() that check if the list has at least one element
• getItems() that returns an array of \OfflineAgency\LaravelFattureInCloudV2\Entities\Client\Client from which you can access to all client's fields
• getPagination() that returns an instance of \OfflineAgency\LaravelFattureInCloudV2\Entities\Client\ClientPagination from which you can access to all pagination's fields and methods

You can also specify query parameters passing an array:

$client = new \OfflineAgency\LaravelFattureInCloudV2\Api\Client();
$client_list = $client->list([
    'per_page' => 50
]);

If the endpoint expect one or more required parameters and if it's a GET endpoint you can provide them as the follow:

$product = new \OfflineAgency\LaravelFattureInCloudV2\Api\Product();
$product_detail = $product->detail($product_id, [
    'fields' => 'id,name,code'
]);

If the endpoint is a POST/PUT one you only need to provide an array with all parameters (required and not):

$product = new \OfflineAgency\LaravelFattureInCloudV2\Api\Product();
$new_product = $product->create([
    'data' => [
        'name' => $product_name,
        'code' => $product_code
    ],
]);

The package validates body using Laravel Validators. If something goes wrong the method returns an instance of \Illuminate\Support\MessageBag that contains all errors.

Api coverage

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

✅ = implemented

🔜 = coming soon

❌ = not implemented

Each response entity has this prefix on the namespace: \OfflineAgency\LaravelFattureInCloudV2\Entities\

User

Done	Endpoint	Type	Response
✅	Get User Info		-
✅	List User Companies		-

Companies

Done	Endpoint	Type	Response
✅	Get Company Info		-

Clients

Done	Endpoint	Type	Response
✅	List clients		Client\ClientList
✅	Create client		Client\Client
✅	Get client		Client\Client
✅	Modify client		Client\Client
✅	Delete client		'Client deleted'

Suppliers

Done	Endpoint	Type	Response
✅	List Suppliers		Supplier\SupplierList
✅	Create Supplier		Supplier\Supplier
✅	Get Supplier		Supplier\Supplier
✅	Modify Supplier		Supplier\Supplier
✅	Delete Supplier		'Supplier deleted'

Products

Done	Endpoint	Type	Response
✅	List products		Product\ProductList
✅	Create product		Product\Product
✅	Get product		Product\Product
✅	Modify product		Product\Product
✅	Delete product		'Product deleted'

Issued Documents

Done	Endpoint	Type	Response
✅	List Issued Documents		IssuedDocument\IssuedDocumentList
✅	Create Issued Documents		IssuedDocument\IssuedDocument
✅	Get Issued Document		IssuedDocument\IssuedDocument
✅	Get Deleted Document		IssuedDocument\IssuedDocument
✅	Modify Issued Document		IssuedDocument\IssuedDocument
✅	Delete Issued Document		'Document deleted'
✅	Get New Issued Document Totals		IssuedDocument\IssuedDocumentTotals
✅	Get Existing Issued Document Totals		IssuedDocument\IssuedDocumentTotals
✅	Upload Issued Document Attachment		IssuedDocument\IssuedDocumentAttachment
✅	Delete Issued Document Attachment		'Attachment deleted'
✅	Get Issued Document Pre-create info		IssuedDocument\IssuedDocumentPreCreateInfo
✅	Get Email Data		IssuedDocument\IssuedDocumentEmail
✅	Schedule Email		IssuedDocument\IssuedDocumentScheduleEmail

Issued e-invoice

Done	Endpoint	Type	Response
🔜	Send the e-invoice		-
🔜	Verify e-invoice XML		-
🔜	Get e-invoice XML		-
🔜	Get e-invoice rejection reason		-

Received Documents

Done	Endpoint	Type	Response
❌	List Received Documents		-
❌	Create Received Document		-
❌	Get Received Document		-
❌	Modify Received Document		-
❌	Delete Received Document		-
❌	Get New Received Document Totals		-
❌	Get Existing Received Document Totals		-
❌	Upload Received Document Attachment		-
❌	Delete Received Document Attachment		-
❌	Get Received Document Pre-create info		-

Receipts

Done	Endpoint	Type	Response
✅	List Receipts		-
✅	Create Receipts		-
✅	Get Receipts		-
✅	Modify Receipts		-
✅	Delete Receipts		-
✅	Get Receipts Pre-Create Info		-
✅	Get Receipts Monthly Totals		-

Taxes

Done	Endpoint	Type	Response
❌	List F24		-
❌	Create F24		-
❌	Get RF24		-
❌	Modify F24		-
❌	Delete F24		-
❌	Upload F24 Attachment		-
❌	Delete F24 Attachment		-

Archive

Done	Endpoint	Type	Response
✅	List Archive Documents		ArchiveDocuments\ArchiveDocuments
✅	Create Archive Documents		ArchiveDocuments\ArchiveDocuments
✅	Get Archive Documents		ArchiveDocuments\ArchiveDocuments
✅	Modify Archive Documents		ArchiveDocuments\ArchiveDocuments
✅	Delete Archive Documents		'Archive deleted'
✅	Upload Archive Documents Attachment		'Archive uploaded'

Cashbook

Done	Endpoint	Type	Response
✅	List Cashbook Entries		CashBook\CashBookEntries
✅	Create Cashbook Entries		CashBook\CashBookEntries
✅	Get Cashbook Entries		CashBook\CashBookEntries
✅	Modify Cashbook Entries		CashBook\CashBookEntries
✅	Delete Cashbook Entries		'CashBook deleted'

Info

Done	Endpoint	Type	Response
🔜	List Countries		-
🔜	List Detailed Countries		-
🔜	List Cities		-
🔜	List Languages		-
🔜	List Templates		-
🔜	List Currencies		-
🔜	List Units of Measure		-
🔜	List Delivery Notes Default Casuals		-
✅	List Vat Types		-
🔜	List Payment Methods		-
🔜	List Payment Accounts		-
🔜	List Revenue Centers		-
🔜	List Cost Centers		-
🔜	List Product Categories		-
🔜	List Received Document Categories		-
🔜	List Archive Categories		-

Settings

Done	Endpoint	Type	Response
✅	Create Payment Method		Settings\PaymentMethods
✅	Get Payment Method		Settings\PaymentMethods
✅	Modify Payment Method		Settings\PaymentMethods
✅	Delete Payment Method		'Method deleted'
✅	Create Payment Account		Settings\PaymentAccount
✅	Get Payment Account		Settings\PaymentAccount
✅	Modify Payment Account		Settings\PaymentAccount
✅	Delete Payment Account		'Account deleted'
✅	Create Vat Type		Settings\VatType
✅	Get Vat Type		Settings\VatType
✅	Modify Vat Type		Settings\VatType
✅	Delete Vat Type		'VatType deleted'

Testing

composer test

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security-related issues, please email [email protected] 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.