# laravel-fatture-in-cloud-v2

A simple Laravel integration with Fatture in Cloud APIs v2 (opens new window).

Github (opens new window) Latest Stable Version (opens new window) Total Downloads (opens new window) MIT Licensed StyleCI (opens new window)

This is the documentation for the API v2. You can find the package for the API v1 here (opens new window)

# Installation

Install the package through Composer (opens new window).

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 HOT

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 HOT

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 HOT

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 (opens new window). 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 (opens new window) 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 GET method -
List User Companies GET method -

# Companies

Done Endpoint Type Response
Get Company Info GET method -

# Clients

Done Endpoint Type Response
List clients GET method Client\ClientList
Create client POST method Client\Client
Get client GET method Client\Client
Modify client PUT method Client\Client
Delete client DELETE method 'Client deleted'

# Suppliers

Done Endpoint Type Response
List Suppliers GET method Supplier\SupplierList
Create Supplier POST method Supplier\Supplier
Get Supplier GET method Supplier\Supplier
Modify Supplier PUT method Supplier\Supplier
Delete Supplier DELETE method 'Supplier deleted'

# Products

Done Endpoint Type Response
List products GET method Product\ProductList
Create product POST method Product\Product
Get product GET method Product\Product
Modify product PUT method Product\Product
Delete product DELETE method 'Product deleted'

# Issued Documents

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

# Issued e-invoice

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

# Received Documents

Done Endpoint Type Response
List Received Documents GET method -
Create Received Document POST method -
Get Received Document GET method -
Modify Received Document PUT method -
Delete Received Document DELETE method -
Get New Received Document Totals POST method -
Get Existing Received Document Totals POST method -
Upload Received Document Attachment POST method -
Delete Received Document Attachment DELETE method -
Get Received Document Pre-create info GET method -

# Receipts

Done Endpoint Type Response
List Receipts GET method -
Create Receipts POST method -
Get Receipts GET method -
Modify Receipts PUT method -
Delete Receipts DELETE method -
Get Receipts Pre-Create Info GET method -
Get Receipts Monthly Totals GET method -

# Taxes

Done Endpoint Type Response
List F24 GET method -
Create F24 POST method -
Get RF24 GET method -
Modify F24 PUT method -
Delete F24 DELETE method -
Upload F24 Attachment POST method -
Delete F24 Attachment DELETE method -

# Archive

Done Endpoint Type Response
List Archive Documents GET method -
Create Archive Documents POST method -
Get Archive Documents GET method -
Modify Archive Documents PUT method -
Delete Archive Documents DELETE method -
Upload Archive Documents Attachment POST method -

# Cashbook

Done Endpoint Type Response
List Cashbook Entries GET method -
Create Cashbook Entries POST method -
Get Cashbook Entries GET method -
Modify Cashbook Entries PUT method -
Delete Cashbook Entries DELETE method -

# Info

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

# Settings

Done Endpoint Type Response
Create Payment Method POST method -
Get Payment Method GET method -
Modify Payment Method PUT method -
Delete Payment Method DELETE method -
Create Payment Account POST method -
Get Payment Account GET method -
Modify Payment Account PUT method -
Delete Payment Account DELETE method -
Create Vat Type POST method -
Get Vat Type GET method -
Modify Vat Type PUT method -
Delete Vat Type DELETE method -

# 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

# About us

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

# License

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

Last Updated: 10/26/2022, 10:18:05 AM