Sort Results

Some of our APIs (e.g. the LIST methods) return a set of resources instead of a single one. This means that a certain order is established between them and that your application could take advantage of a certain order.

Sorting lets you choose the rule that must be used to order the returned resources, delegating this task to our APIs.

Check the fields!

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

To order the returned resources, all you have to do is to add the sort parameter to the query string, containing a comma-separated set of the fields that define the sorting rule. The default order for each field is the ascending order, which doesn't require any prefix, while the descending order can be selected by adding the prefix "-" to the field name.

For example, this request will sort all the expenses first by the "date" field in descending order and then by the "amount_net" field in ascending order.

cURL

curl --request GET \
     --url 'https://api-v2.fattureincloud.it/c/company_id/received_documents?sort=-date,amount_net&type=expense' \
     --header 'Accept: application/json'
     --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

HTTP

GET https://api-v2.fattureincloud.it/c/{companyId}/received_documents?sort=-date,amount_net&type=expense

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("sort", "-date,amount_net");
            query.Add("type", "expense");

            var url = "https://api-v2.fattureincloud.it/c/" + companyId  + "/received_documents" + "?" + 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("sort", "-date,amount_net")
	values.Add("type", "expense")
	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  + "/received_documents")
                .addQueryParameter("sort", "-date,net_amount")
                .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 = {
  sort: "-date,net_amount",
  type: "expense",
};

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

var options = {
  method: "GET",
  hostname: "api-v2.fattureincloud.it",
  port: null,
  path: "/c/" + companyId + "/received_documents" + 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(
  'sort' => '-date,amount_net',
  'type' => 'expense'
);

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

$url = "https://api-v2.fattureincloud.it/c/$companyId/received_documents". '?' . $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 = {
    'sort': '-date,net_amount',
    'type': 'expense'
}
headers = { 'authorization': "Bearer " + token }
response = requests.get(f"https://api-v2.fattureincloud.it/c/\{company_id\}/received_documents", 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 = {
    'sort': '-date,net_amount',
    'type': 'expense'
}

uri = URI("https://api-v2.fattureincloud.it/c/#\{company_id\}/received_documents")
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 = {
  sort: "-date,net_amount",
  type: "expense",
};

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 +
      "/received_documents?" +
      query,
    options
  );
  var json = await res.json();
  console.log(json);
} catch (err) {
  console.log(err);
}

Retrieve your ACCESS TOKEN!

You can set the Access Token in the dedicated section, for more informations look here.

Here you can find an example response, please note that sorting is strictly related to the Pagination functionality:

{
  "data": [
    {
      "id": 251,
      "type": "expense",
      "description": "Catene auto",
      "amount_net": 68.03,
      "amount_vat": 14.97,
      "is_marked": false,
      "entity": {
        "id": 109,
        "name": "Catene e catenacci S.r.l."
      },
      "date": "2021-12-23",
      "next_due_date": "2013-12-23",
      "amount_gross": 83
    },
    {
      "id": 104328,
      "type": "expense",
      "description": "Ricarica Telefonica",
      "amount_net": 20,
      "amount_vat": 0,
      "is_marked": false,
      "entity": {
        "id": 35,
        "name": "Maracaibo Mobile S.p.a."
      },
      "date": "2021-08-01",
      "next_due_date": "1970-01-01",
      "amount_gross": 20
    },
    {
      "id": 134828,
      "type": "expense",
      "description": "Soggiorno di lavoro",
      "amount_net": 592,
      "amount_vat": 0,
      "is_marked": false,
      "entity": {
        "id": -1,
        "name": "Hotel Paradiso"
      },
      "date": "2014-10-29",
      "next_due_date": "2020-10-29",
      "amount_gross": 592
    },
    {
      "id": 134830,
      "type": "expense",
      "description": "SmartPhone Y",
      "amount_net": 130,
      "amount_vat": 0,
      "is_marked": false,
      "entity": {
        "id": 14542,
        "name": "Pear Inc."
      },
      "date": "2014-04-16",
      "next_due_date": "2020-09-01",
      "amount_gross": 130
    },
    {
      "id": 134832,
      "type": "expense",
      "description": "BestBook Pro 2020",
      "amount_net": 430,
      "amount_vat": 0,
      "is_marked": false,
      "entity": {
        "id": 14542,
        "name": "Pear Inc."
      },
      "date": "2014-04-16",
      "next_due_date": "2020-05-29",
      "amount_gross": 430
    }
  ],
  "current_page": 2,
  "last_page": 67,
  "per_page": "5",
  "from": 6,
  "to": 10,
  "total": 335,
  "path": "https://api-v2.fattureincloud.it/received_documents",
  "first_page_url": "https://api-v2.fattureincloud.it/received_documents?per_page=5&type=expense&fieldset=basic&page=1",
  "last_page_url": "https://api-v2.fattureincloud.it/received_documents?per_page=5&type=expense&fieldset=basic&page=67",
  "next_page_url": "https://api-v2.fattureincloud.it/received_documents?per_page=5&type=expense&fieldset=basic&page=3",
  "prev_page_url": "https://api-v2.fattureincloud.it/received_documents?per_page=5&type=expense&fieldset=basic&page=1"
}

📔  Sortable fields

Here you can find the list of fields that can be used to order the result for each List method; for every field, it is possible to use the ascending or descending order.

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

📚  Additional Resources

• Descending Order VS Ascending Order – What Does it Mean?
• REST API Design: Filtering, Sorting, and Pagination