Skip to main content

JavaScript SDK

The Fatture in Cloud JavaScript SDK is a JavaScript 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 can be used in Node.js applications and in-browser (using Browserify). It is mainly based on the Superagent HTTP Client.

⬇️  Download and Installation

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

Important!

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

The SDK can be installed using NPM and Yarn:

npm install @fattureincloud/fattureincloud-js-sdk

👷‍♂️  SDK Structure

Our SDK is mainly split into two different packages:

  • api: Here you can find the implementation of our API methods, you will need to initialize one of those APIs to start.
  • model: This package contains all the representations of our API requests and responses; when using one of the methods above, you'll have to manage some of those models.

There are some models with a special role:

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

You can think about Request and Response as wrappers: each one of them is 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 models. Each method will accept at most one Request model and will return at most one Response model.

Let's take for example the Modify Supplier method.

It is included in the SuppliersApi, it accepts one ModifySupplierRequest and it returns a ModifySupplierResponse. In both cases, the data parameter will contain a Supplier, 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, but it doesn't need any request body and returns a single ListSuppliersResponse, where the data parameter will contain an array of Suppliers.

📢  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 the resource.

🎩  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 adding 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 retrieve a valid Access Token (see above), you can start using our APIs.

First, you need to import the SDK and initialize the authentication using the token:

var fattureInCloudSdk = require('@fattureincloud/fattureincloud-js-sdk');

var defaultClient = fattureInCloudSdk.ApiClient.instance;

var auth = defaultClient.authentications['OAuth2AuthenticationCodeFlow'];
auth.accessToken = "YOUR ACCESS TOKEN"

You can then retrieve one or more of the APIs, for example:

let suppliersApi = new fattureInCloudSdk.SuppliersApi();

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

Select the correct APIs!

If you want to use a method declared in two different APIs, 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:

let companyId = 12345; // Number | The ID of the company.
let opts = {
'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, // Number | The page to retrieve.
'perPage': 5 // Number | The size of the page.
};
suppliersApi.listSuppliers(companyId, opts).then((result) => {
console.log('API called successfully. Returned result: ' + JSON.stringify(result));
}, (error) => {
console.error(error);
});

let supplierId = 56; // Number | The ID of the supplier.
let opts = new fattureInCloudSdk.ModifySupplierRequest();
modifySupplierRequest.data.name = 'nuovo nome'; // ModifySupplierRequest | The modified Supplier.
modifySupplierRequest.data.phone = '03561234312';

suppliersApi.modifySupplier(companyId, supplierId, opts).then((result) => {
console.log('API called successfully. Returned result: ' + JSON.stringify(result));
}, (error) => {
console.error(error);
});
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:

console.log(JSON.stringify(modifySupplierRequest));

  What now?

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

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

  • JavaScript SDK GitHub Repository: the Readme file contains the full list of the available methods and models
  • API Reference: it contains the list of methods and models and provides autogenerated vanilla code examples in many programming languages
  • OpenAPI Specification: Our OpenAPI Specification contains the full description of the available methods and models
  • NPM page: The main package page on NPM
  • YarnPkg page: The main package page on Yarn

📚  Additional resources