Skip to main content

PHP SDK

The Fatture in Cloud PHP SDK is a PHP library that offers models and methods to interact with the Fatture in Cloud v2 REST API.

Do you need a generic intro?

If you want to know more generic information about our SDKs, please check the SDK Overview page.

☑️  Requirements and Dependencies​

This SDK supports PHP 7.1 and later. It is mainly based on the Guzzle HTTP Client.

⬇️  Download and Installation​

The SDK code and detailed documentation can be found in the GitHub repository.

🎻  Installation with Composer​

The SDK is published into Packagist and it can be installed using Composer:

composer require fattureincloud/fattureincloud-php-sdk
Important!

Make sure you always import the newest version of our SDK, you can check which version is the latest on Packagist

🔧  Installation without Composer​

If you can't install our library using composer there are three routes you can take:

  • the first and recommended one is to download the latest release of the sdk Phar Archive, then you can simply include it in your project.
require_once('./fattureincloud-php-sdk.phar');
  • the second route is to download our sdk using php-download and include it in your project
  • the third route is to create your own custom autoloader and download all the dependencies (transitive included) as explained here.

👷  SDK Structure​

Our SDK is mainly split into two different packages:

  • Api: Here you can find the classes that implement our API methods, you will need an instance of one of those classes to actually call our APIs.
  • Model: This package contains all the classes that represent our API requests and responses; when using one of the methods above, you'll have to manage some of those classes.

There are some special classes in the Model package:

  • The classes with a name ending for Request can be used as request body for one of our methods.
  • The classes with a name ending for Response will be returned after the execution of one of the methods. Instances of all the other classes will be used to compose the requests or responses for our methods.

You can think about Request and Response classes as wrappers: each one of them are dedicated to a single method of the API, and they will most of the time contain a single attribute called data, that contains the real body of the request or the response represented through a composition of the other classes. Each method will accept at most one instance of the Request classes and will return at most one instance of the Response classes.

Let's take for example the Modify Supplier method.

It is included in the SuppliersApi class, it accepts one instance of the ModifySupplierRequest class and it returns an instance of the ModifySupplierResponse class. In both cases, the data parameter will contain an instance of the Supplier class, that represents the modifies to apply to the supplier (for the request) and the final status of the supplier (for the response).

In contrast, the List Suppliers method is still contained in the SuppliersApi class, but it doesn't need any request body and returns a single instance of the ListSuppliersResponse class, where the data parameter will contain an array of instances of the Supplier class.

📢  API calls​

The API methods can be categorized as follows:

Category (prefix)Request BodyResponse BodyNotes
List (list)❌✅🎩  + 🔃  + 📃 + 🏷
Create (create)✅✅
Get (get)❌✅🎩
Modify (modify)✅✅
Delete (delete)❌❌

In addition to the Request, every method could require some additional parameters like the IDs of the company and of the resource.
Retrieve your Company ID!

In this example, we'll suppose you have to manage just one Company, so we simply inserted its ID directly in the code. If instead, you need to be able to manage multiple companies, you'll need to retrieve the ID of the current company in some way. Check the Company-scoped Methods page for more info. Additionally, the PHP Quickstart contains an example of Company ID retrieval using the SDK.

🎩  Response customization​

The List and Post methods include some parameters dedicated to the response customization. These parameters are passed as method arguments.

🔃  Sorting​

The List methods are a particular case because they are related to a set of resources instead of a single one; this means that the API will need to assign an order to the resources that will be returned. If needed, you can explicitly define a sorting rule by passing the scope parameter.

📃  Pagination​

Strictly related to the Sorting functionality is the Pagination. The List methods return a potentially huge set of resources, making it necessary to paginate the results to make the responses manageable; each method will then accept an additional set of pagination parameters, and the Response classes will contain some pagination details along with the data parameter.

🏷  Filtering​

By default, the List methods will return the whole set of available resources for a certain method. If you instead want to focus on a particular subset of resources, you can apply specific filters to reduce the size of the result and retrieve only what you need.

🔑  Authentication & Authorization​

This SDK allows you to retrieve and refresh the access token with the integrated OAuth Helper, you can find a complete guide about it here, in case you are using the manual auth you can always set the token manually.

🐤  Getting started​

After you followed the installation procedure and retrieved a valid Access Token (see above), you can start using our APIs.

First, you need to create a new instance of the Configuration class:

$config = FattureInCloud\Configuration::getDefaultConfiguration()->setAccessToken('YOUR_ACCESS_TOKEN');

The configuration, along with the HTTP client instance, can be used to instantiate one or more of the Api classes, for example:

$supplierApi = new FattureInCloud\Api\SuppliersApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);

Once you obtained the needed Api instance, you can start using the methods it provides.

Select the correct APIs!

If you want to use a method declared in two different API classes, you'll not be able to use the same instance. Instead, you'll need two different instances, one for each of the needed APIs.

Let's implement the listSuppliers and modifySupplier methods explained above:

$company_id = 12345; // int | The ID of the company.
$fields = 'fields_example'; // string | List of comma-separated fields.
$fieldset = 'fieldset_example'; // string | Name of the fieldset.
$sort = 'sort_example'; // string | List of comma-separated fields for result sorting (minus for desc sorting).
$page = 1; // int | The page to retrieve.
$per_page = 5; // int | The size of the page.

try {
    $result = $suppliersApi->listSuppliers($company_id, $fields, $fieldset, $sort, $page, $per_page);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling SuppliersApi->listSuppliers: ', $e->getMessage(), PHP_EOL;
}

$supplier_id = 56; // int | The ID of the supplier.

$supplier = new FattureInCloud\Model\Supplier;
$supplier->setName("nuovo nome");
$supplier->setPhone("03561234312");

$modify_supplier_request = new FattureInCloud\Model\ModifySupplierRequest;
$modify_supplier_request->setData($supplier);

try {
    $result = $suppliersApi->modifySupplier($company_id, $supplier_id, $modify_supplier_request);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling SuppliersApi->modifySupplier: ', $e->getMessage(), PHP_EOL;
}
We're done!

You can finally start interacting with the Fatture in Cloud API!

🗒  Retrieve the JSON request body​

If you are experiencing some kind of issue and you want to check the raw JSON sent as the body for your request (and maybe send it to our customer support) you can do it as follows:

echo(json_encode($modify_supplier_request));

🥥  Use raw JSON as request body​

If you already have a complete json that you want to use to call our APIs with the SDK without having to build the request object you can do it as follows:

$modify_supplier_request = json_decode("{\"data\":{\"name\":\"nuovo nome\", \"phone\":\"03561234312\"}}");

❌  Improve error handling​

If you have ever run into a Guzzle exception, you probably know that the error message gets truncated like this one:

Exception when calling IssuedDocumentsApi - > createIssuedDocument: [422]
Client error: `POST http://api-v2.local.fattureincloud.it//c/2/issued_documents`
resulted in a `422 Unprocessable Entity`
response: {
		"error": {
			"message": "Invalid request.",
			"validation_result": {
				"data": ["The data field is required."],
				"data.entity": ["The d (truncated...)

With an incomplete error like this most of the times it's difficult to understand where the actual problem is to proceed to fix it, luckily our SDK error handling can be improved like this:

// set your access token
$config = FattureInCloud\Configuration::getDefaultConfiguration()->setAccessToken('YUOR_ACCESS_TOKEN');

$stack = new HandlerStack(Utils::chooseHandler());
// define a custom error size
$stack->push(Middleware::httpErrors(new BodySummarizer(2048)), 'http_errors');
$stack->push(Middleware::redirect(), 'allow_redirects');
$stack->push(Middleware::cookies(), 'cookies');
$stack->push(Middleware::prepareBody(), 'prepare_body');

// create a custom client
$client = new Client(['handler' => $stack /* other options here */ ]);

$apiInstance = new FattureInCloud\Api\IssuedDocumentsApi(
    new Client(),
    $config
);

❓  What now?​

If you need a more detailed example, you can check our PHP SDK Quickstart.

Here you can find the full documentation of the available methods and models:

📚 Additional resources​