Filter Results

Some of our APIs (e.g. the LIST methods) return a set of resources instead of a single one. This means that the returned response could be potentially huge, involving a high number of complex resources, making the response difficult to manage and send to your application. For this reason, you should filter the results to get only the data you need.

Check the fields

Our APIs let you apply a filter only on a certain set of fields. Please check the table below for the available fields for each method.

To filter the returned resources, all you have to do is to add the "q" parameter to the query string, containing the desired query filter. This parameter must be provided as an URL-encoded string to avoid issues related to special characters in the string.

For example, this request will filter all the clients, returning only the client with the specified vat_number. The query parameter value is the following:

Original value	URL-encoded value
vat_number = '11553420156'	vat_number%20%3D%20%2711553420156%27

This translates to the following code:

cURL

curl --request GET \
     --url 'https://api-v2.fattureincloud.it/c/company_id/entities/clients?q=vat_number%20%3D%20%2711553420156%27' \
     --header 'Accept: application/json'
     --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

HTTP

GET https://api-v2.fattureincloud.it/c/{companyId}/entities/clients?q=vat_number%20%3D%20%2711553420156%27

The corresponding code examples:

C#

// this code uses RestSharp Client: https://restsharp.dev
// you can install it with the following command:
// dotnet add package RestSharp

using System;
using RestSharp;

namespace restclient
{
    class Program
    {
        static void Main(string[] args)
        {
            // for this example we define the token as a string, but you should have obtained it in the previous steps
            // the token is valid for the "received_documents:r" scope needed to perform this operation
            var token = "YOUR_ACCESS_TOKEN";

            // these parameters are usually retrieved through our APIs or stored in a DB
            var companyId = 17;

            var query = System.Web.HttpUtility.ParseQueryString(string.Empty);
            query.Add("q", "vat_number = '11553420156'");

            var url = "https://api-v2.fattureincloud.it/c/" + companyId  + "/entities/clients" + "?" + query;

            var client = new RestClient(url);
            var request = new RestRequest(Method.GET);

            request.AddHeader("authorization", "Bearer " + token);
            IRestResponse response = client.Execute(request);
            Console.Write(response.Content.ToString());
        }
    }
}

Go

// NOTE: this is a complete request, but please customize it!!!
// In the next step we'll explain how to perform the request to the API.

// in this example we are using our Go SDK
// https://github.com/fattureincloud/fattureincloud-go-sdk
package main

import (
	"io/ioutil"
	"log"
	"net/http"
	"net/url"
)

func main() {

	var bearer = "Bearer " + "a/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJyZWYiOiJtUm80MXlpSVFTbHN0bXRadG5jNEZhYk5QaW41ejJmdiIsImV4cCI6MTY2MjU1NDg5NX0.bvYHc9et0p9lsaTIWGX8vGqE6uHKiwBPyQlXwZqIH3o"

	values := url.Values{}
	values.Add("q", "vat_number = '11553420156'")
	query := values.Encode()

	companyId := "2"
	uri := "http://api-v2.local.fattureincloud.it/c/" + companyId + "/received_documents?" + query

	req, _ := http.NewRequest("GET", uri, nil)
	req.Header.Add("Authorization", bearer)

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		log.Println("Error on response.\n[ERROR] -", err)
	}
	defer resp.Body.Close()

	body, err := ioutil.ReadAll(resp.Body)
	if err != nil {
		log.Println("Error while reading the response bytes:", err)
	}
	log.Println(string([]byte(body)))

}

Java

import okhttp3.HttpUrl;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;
import java.io.IOException;
import java.net.URL;

public class Application {
    public static void main(String[] args) throws IOException {

        // for this example we define the token as a string, but you should have obtained it in the previous steps
        // the token is valid for the "received_documents:r" scope needed to perform this operation
        String token = "YOUR_ACCESS_TOKEN";

        // these parameters are usually retrieved through our APIs or stored in a DB
        Integer companyId = 16;

        URL url = new HttpUrl.Builder()
                .scheme("https")
                .host("api-v2.fattureincloud.it")
                .addPathSegments("c/" + companyId  + "/entities/clients")
                .addQueryParameter("q", "vat_number='11553420156")
                .addQueryParameter("type", "expense")
                .build().url();

        OkHttpClient client = new OkHttpClient();
        Request request = new Request.Builder()
                .header("Authorization", "Bearer " + token)
                .url(url)
                .build();
        Response response = client.newCall(request).execute();
        System.out.println(response.body().string());
    }
}

JavaScript

var http = require("https");

// for this example we define the token as a string, but you should have obtained it in the previous steps
// the token is valid for the "received_documents:r" scope needed to perform this operation
var token = "YOUR_ACCESS_TOKEN";

// these parameters are usually retrieved through our APIs or stored in a DB
var companyId = 16;

var params = {
  q: "vat_number = '11553420156'",
};

var query = new URLSearchParams(params).toString(); // url-encoded query string

var options = {
  method: "GET",
  hostname: "api-v2.fattureincloud.it",
  port: null,
  path: "/c/" + companyId + "/entities/clients" + query,
  headers: {
    authorization: "Bearer " + token,
  },
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

PHP

// this code uses Guzzle HTTP Client: https://docs.guzzlephp.org/en/stable/
// and also ext-json
// you can install them with the following command:
// composer require guzzlehttp/guzzle ext-json
require 'vendor/autoload.php';
use GuzzleHttp\Client;
use GuzzleHttp\Exception\ClientException;
use GuzzleHttp\Psr7;


// for this example we define the token as a string, but you should have obtained it in the previous steps
// the token is valid for the "received_documents:r" scope needed to perform this operation
$token = 'YOUR_ACCESS_TOKEN';

// these parameters are usually retrieved through our APIs or stored in a DB
$companyId = 17;

$client = new Client();

$params = array(
  'q' => "vat_number = '11553420156'"
);

$query = http_build_query($params); // url-encoded query string

$url = "https://api-v2.fattureincloud.it/c/$companyId/entities/clients". '?' . $query;

try {
  $response = $client->request('GET', $url, [
    'headers' => [
      'Accept' => 'application/json',
      'Authorization' => 'Bearer ' . $token,
    ],
  ]);

    echo $response->getBody();
} catch (ClientException $e) {
    echo Psr7\Message::toString($e->getRequest());
    echo Psr7\Message::toString($e->getResponse());
}

Python

# pip install requests
import requests

# for this example we define the token as a string, but you should have obtained it in the previous steps
# the token is valid for the "received_documents:r" scope needed to perform this operation
token = "YOUR_ACCESS_TOKEN"

# these parameters are usually retrieved through our APIs or stored in a DB
company_id = 2

params = {
    "q": "vat_number = '11553420156'"
}
headers = { 'authorization': "Bearer " + token }
response = requests.get(f"https://api-v2.fattureincloud.it/c/\{company_id\}/entities/clients", params=params, headers=headers)

print(response.json())

Ruby

require 'uri'
require 'net/http'

# for this example we define the token as a string, but you should have obtained it in the previous steps
# the token is valid for the "received_documents:r" scope needed to perform this operation
token = "YOUR_ACCESS_TOKEN"

# these parameters are usually retrieved through our APIs or stored in a DB
company_id = 16

params = {
    "q": "vat_number = '11553420156'"
}

uri = URI("https://api-v2.fattureincloud.it/c/#\{company_id\}/entities/clients")
uri.query = URI.encode_www_form(params)
headers = { authorization: "Bearer " + token}
res = Net::HTTP.get_response(uri, headers)

puts res.body

TypeScript

// in this example we are using the node-fetch library to make the request
import fetch, { Headers } from "node-fetch";

// for this example we define the token as a string, but you should have obtained it in the previous steps
// the token is valid for the "received_documents:r" scope needed to perform this operation
var token = "YOUR_ACCESS_TOKEN";

// these parameters are usually retrieved through our APIs or stored in a DB
var companyId = 16;

var params = {
  q: "vat_number = '11553420156'",
};

var query = new URLSearchParams(params).toString(); // url-encoded query string

var headers = new Headers({
  "Content-Type": "application/json",
  Authorization: "Bearer " + token,
});

var options = {
  method: "GET",
  headers: headers,
};

try {
  var res = await fetch(
    "https://api-v2.fattureincloud.it/c/" +
      companyId +
      "/entities/clients?" +
      query,
    options
  );
  var json = await res.json();
  console.log(json);
} catch (err) {
  console.log(err);
}

Here you can find an example response:

{
  "current_page": 1,
  "data": [
    {
      "id": 25330671,
      "code": "",
      "name": "ACEA S.P.A.",
      "vat_number": "2711553420156",
      "tax_code": "",
      "address_city": "Marioloso",
      "address_province": "RM",
      "country": "Italia"
    }
  ],
  "first_page_url": "https://api-v2.fattureincloud.it/c/2/entities/clients?q=vat_number+%3D+%2707305361003%27&page=1",
  "from": 1,
  "last_page": 1,
  "last_page_url": "https://api-v2.fattureincloud.it/c/2/entities/clients?q=vat_number+%3D+%2707305361003%27&page=1",
  "next_page_url": null,
  "path": "https://api-v2.fattureincloud.it/c/2/entities/clients",
  "per_page": 50,
  "prev_page_url": null,
  "to": 1,
  "total": 1
}

🔧  Building a query

Our API uses a SQL-like query language, which means that it is a subset of the where clause of the SQL language and can be used in a similar way to build the filter string.

The string is based on triplets: field op value

The field is a lowercase string, with dots and underscores, containing the name of the field the filter applies to; all the fields used in a single query must be included in the list of the authorized fields for the specific request type that is going to be performed, otherwise, an error will be returned. Check below for the list of authorized fields.

The op is one of the following (unquoted):

Operator	Symbol
Equal	'='
Greater than	'>'
Greater than or equal to	'>='
Less than	'<'
Less than or equal to	'<='
Not equal	'<>', '!='

Some additional operators are available to match a string against a Pattern (unquoted), they can't be used on another kind of parameters:

Operator	Symbol
Like	'like', 'LIKE'
Contains	'contains', 'CONTAINS'
Starts with	'starts with', 'STARTS WITH'
Ends with	'ends with', 'ENDS WITH'

The value can be one of the following types:

Type	Example
String	'value'
Boolean	true, false
Int	46
Double	12.34

Additionally, it is possible to check if a field has a value or not, using NULL:

Type	Value
The value is Null (doesn't have a value)	1. IS NULL 2. is null 3. = NULL 4. = null
The value is Not Null (has a value)	1. IS NOT NULL 2. is not null 3. != NULL 4. != null 5. <> NULL 6. <> null

You can combine multiple triplets to compose a more complex filter, using the following boolean operators and using parenthesis to define the order of the composition.

Operator	Symbol
Conjunction	'and', 'AND'
Disjunction	'or', 'OR'

Here you can find some syntactically-valid queries (the field names used in the examples could not exist in our API):

vat_number = '11553420156'

age < 30

credit >= 123.45

dev = true

surname is not null

employer starts with 'Fatture'

name like '%Pier%'

surname = 'Rossi' and name contains 'Luca'

city = 'Bergamo' and (age < 30 or (dev = true and (name = 'Giorgio' and surname is not null) or employer starts with 'Fatture'))

Once the query is composed, it must be URL-encoded before using it in a query; most HTTP frameworks perform this step automatically while composing the request, otherwise, you can use dedicated libraries to apply the encoding explicitly.

🔍  Filterable fields

Here you can find the list of fields that can be used to filter the result for each List method:

Method	Fields
listClients	id, code, name, type, vat_number, tax_code, address_street, address_postal_code, address_city, address_province, country, email, certified_email, phone, fax, notes, imported, atoka_show, e_invoice, ei_code, created_at, updated_at
listSuppliers	id, code, name, type, vat_number, tax_code, address_street, address_postal_code, address_city, address_province, country, email, certified_email, phone, fax, notes, imported, atoka_show, e_invoice, ei_code, created_at, updated_at
listProducts	id, name, code, net_price, gross_price, net_cost, description, category, notes, in_stock, created_at, updated_at
listIssuedDocuments	type, entity.id, entity.name, entity.vat_number, entity.tax_code, entity.city, entity.province, entity.country, date, number, numeration, any_subject, amount_net, amount_vat, amount_gross, next_due_date, created_at, updated_at
listReceivedDocuments	id, type, category, description, entity.id, entity.name, date, next_due_date, amount_gross, amount_net, amount_vat, invoice_number, created_at, updated_at
listReceipts	date, type, description, rc_center, created_at, updated_at
listF24	due_date, status, amount, description
listArchiveDocuments	date, category, description

📚  Additional Resources

• Percent Encoding (also known as URL-encoding)
• HTTP Request
• Query string
• HTML Url Encoding Reference
• SQL (Structured Query Language)
• SQL Tutorial
• Online URL Decoder/Encoder (for testing purposes)