Paginate 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, we paginate the results to make sure responses are easier to handle.

In general, asking for a list of resources will result in a paginated response; this means that the resources will be divided into multiple pages, each of those containing a subset of the entire result.

Please note that Pagination is strictly related to the Sorting functionality: contiguous pages will always contain contiguous elements with respect to the ordering rules defined through the sort parameter.

The pagination parameters are the following, and must be passed in query string:

Request parameters	Description	Info
page	The page number you want to retrieve.	Default: 1
per_page	The number of items per page.	Default: 50 Max: 100

The response to a paginated request will contain additional information to help you navigate through the list:

Response parmeter	Description
current_page	Current page number.
last_page	Last page number of the list.
per_page	Number of items per page.
from	Number of the first item of the current page.
to	Number of the last item of the current page.
total	Total number of items.
path	Current endpoint.
first_page_url	Link to get the first page of the list.
last_page_url	Link to get the last page of the list.
prev_page_url	Link to get the previous page of the list.
next_page_url	Link to get the next page of the list.

Here you can find an example of a request:

cURL
HTTP

curl --request GET \
     --url 'https://api-v2.fattureincloud.it/c/company_id/received_documents?page=2&per_page=5&type=expense' \
     --header 'Accept: application/json'
     --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

GET  https://api-v2.fattureincloud.it/c/{companyId}/received_documents?page=2&per_page=5&type=expense

// 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("page", "2");
            query.Add("per_page", "5");
            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());
        }
    }
}

// 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("page", "2")
	values.Add("per_page", "5")
	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)))

}

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("page", "2")
                .addQueryParameter("per_page", "5")
                .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());
    }
}

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 = {
  page: 2,
  per_page: 5,
  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();

// 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(
  'page' => 2,
  'per_page' => 5,
  '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());
}

# 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 = {
    'page': 2,
    'per_page': 5,
    '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())

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 = {
    'page': 2,
    'per_page': 5,
    '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

// 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 = {
  page: "2",
  per_page: "5",
  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);
}

It's easier with our SDKs!

The SDK methods include the pagination parameters as function arguments, taking care of building the query string for you!

Retrieve your ACCESS TOKEN!

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

The example request will retrieve the second page of the expenses list, with a page size of 5 items. An example result could be the following:

{
  "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": "2013-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": "2014-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": "2014-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": "1970-01-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-05-29",
      "next_due_date": "2014-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"
}

📚 Additional Resources

REST API Design: Filtering, Sorting, and Pagination

📚 Additional Resources​

📚 Additional Resources