Customize response

Some of the Fatture in Cloud resources are huge, including a wide range of fields; in most cases, you won't be interested in the whole representation of a particular resource, but you would prefer to extract only a certain subset of the fields because other ones could be unuseful for the specific operation that you are trying to implement.

Response Customization lets you define the set of fields that you desire to retrieve, making the responses much lighter and manageable. This can be done in two ways, using two different parameters to be set in query string:

Parameter	Description
fields	This is the more granular way to customize the response. You can define the exact set of fields that must be retrieved, by providing the fields that you want to retrieve as a comma-separated list.
fieldset	Fatture in Cloud provides some pre-defined sets of fields that can be used to customize the response without having to define every single field. In the next section, you can check the list of fieldsets and the list of fields that they include for each resource.

If these two fields are not specified, we use default fieldsets for the methods that provide response customization. See below for further info.

This is not for everyone...

Please, notice that not all the requests support response customization. Usually, all the List and Get methods that return resources representations provide this functionality, while some other methods don't. You can check the API Reference section to find out if a method supports response customization: for example, List Suppliers supports it, while Get User Info doesn't.

This is a response customization example:

cURL

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

HTTP

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

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("fields", "type,description");
            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("fields", "type,description")
	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("fields", "type,description")
                .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 = {
  fields: "type,description",
  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(
  'fields' => 'type,description',
  '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 = {
    'fields': 'type,description',
    '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 = {
    'fields': 'type,description',
    '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 = {
  fields: "type,description",
  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);
}

This request will list all the expenses, showing only the type and description fields as in the following example:

{
  "current_page": 1,
  "data": [
    {
      "type": "expense",
      "description": "Ricarica Maracaibo"
    },
    {
      "type": "expense",
      "description": "Acquisto smartphone"
    },
    {
      "type": "expense",
      "description": "Assicurazione RCA"
    },
    {
      "type": "expense",
      "description": "Soggiorno di lavoro"
    }
  ],
  "first_page_url": "https://api-v2.fattureincloud.it/c/2/received_documents?fields=type%2Cdescription&type=expense&page=1",
  "from": 1,
  "last_page": 8,
  "last_page_url": "https://api-v2.fattureincloud.it/c/2/received_documents?fields=type%2Cdescription&type=expense&page=8",
  "next_page_url": "https://api-v2.fattureincloud.it/c/2/received_documents?fields=type%2Cdescription&type=expense&page=2",
  "path": "https://api-v2.fattureincloud.it/c/2/received_documents",
  "per_page": 4,
  "prev_page_url": null,
  "to": 4,
  "total": 31
}

Lower the pages number!

Using the response customization you can lower the size of each item of the list, making it easier to manage pages with a wider page size. Feel free to increment the number of items per page!

🔎  Available fieldsets

Here you can find a list of the fieldsets:

Check the default!

For the methods where the response customization is available, the basic is the default field set for the LIST methods, while the GET methods use the detailed fieldset as default.

Resource Type	Fieldset	Fields
ArchiveDocument	basic	id, date, category, description
ArchiveDocument	detailed	id, date, category, description, attachment_url
CashbookEntry	basic	id, date, amount_in, payment_accounts_in, amount_out, payment_account_out, description, kind, document
CashbookEntry	detailed	id, date, amount_in, payment_accounts_in, amount_out, payment_account_out, description, kind, document
Currency	basic	id, symbol, html_symbol, exchange_rate
Client	basic	id, name, code, vat_number, tax_code, address_city, address_province, country
Client	detailed	id, name, code, type, first_name, last_name, contact_person, vat_number, tax_code, address_street, address_postal_code, address_city, address_province, address_extra, country, email, certified_email, phone, fax, notes, default_vat, default_payment_terms, default_payment_terms_type, default_payment_method, bank_name, bank_iban, bank_swift_code, shipping_address, e_invoice, ei_code, default_discount, discount_highlight, created_at, updated_at
Supplier	basic	id, name, code, vat_number, tax_code, address_city, address_province, country
Supplier	detailed	id, code, name, type, first_name, last_name, contact_person, vat_number, tax_code, address_street, address_postal_code, address_city, address_province, address_extra, country, email, certified_email, phone, fax, notes, created_at, updated_at
F24	basic	id, due_date, status, amount, description, attachment_url
F24	detailed	id, due_date, status, payment_account, amount, description, attachment_url
IssuedDocument	basic	id, type, entity, date, number, numeration, amount_net, amount_vat, amount_gross, amount_due_discount, subject, visible_subject, next_due_date, url
IssuedDocument	detailed	id, type, entity, date, number, numeration, currency, language, subject, visible_subject, rc_center, notes, year, stamp_duty, payment_method, use_split_payment, use_gross_prices, merged_in, original_document, e_invoice, items_list, payments_list, extra_data, amount_net, amount_vat, amount_gross, amount_due_discount, rivalsa, amount_rivalsa, amount_rivalsa_taxable, rivalsa_taxable, cassa, cassa2, amount_global_cassa_taxable, global_cassa_taxable, amount_cassa, amount_cassa_taxable, cassa_taxable, amount_cassa2, amount_cassa2_taxable, cassa2_taxable, withholding_tax, amount_withholding_tax, withholding_tax_taxable, amount_withholding_tax_taxable, other_withholding_tax, amount_other_withholding_tax, other_withholding_tax_taxable, amount_other_withholding_tax_taxable, amount_enasarco_taxable, seen_date, next_due_date, template, h_margins, v_margins, show_payment_method, show_payments, show_totals, show_notification_button, show_tspay_button, url, dn_url, ai_url, is_marked, attachment_url, delivery_note, accompanying_invoice, dn_template, dn_date, dn_number, ai_template, dn_ai_packages_number, dn_ai_weight, dn_ai_causal, dn_ai_destination, dn_ai_transporter, dn_ai_notes, ei_data, ei_raw, ei_ts_data, ei_status, locked, has_ts_pay_pending_payment, ei_cassa_type, ei_cassa2_type, ei_withholding_tax_causal, ei_other_withholding_tax_causal, ei_other_withholding_tax_type, created_at, updated_at
PaymentAccount	basic	id, name
PaymentAccount	detailed	id, name, type, sia, iban, cuc, virtual
PaymentMethod	basic	id, name, is_default, default_payment_account
PaymentMethod	detailed	id, name, is_default, details, default_payment_account, type
Product	basic	id, name, code, use_gross_price, net_price, gross_price, default_vat, net_cost, measure, description, category, in_stock
Product	detailed	id, name, code, use_gross_price, net_price, gross_price, default_vat, net_cost, measure, description, category, notes, in_stock, stock_initial, stock_current, average_cost, average_price, extra_document, created_at, updated_at
Receipt	basic	id, date, type, number, numeration, amount_net, amount_vat, amount_gross, description, payment_account, rc_center
Receipt	detailed	id, date, type, number, numeration, amount_net, amount_vat, amount_gross, use_gross_prices, description, payment_account, rc_center, items_list, created_at, updated_at
ReceivedDocument	basic	id, type, description, entity, date, next_due_date, amount_net, amount_vat, amount_gross, url, is_marked
ReceivedDocument	detailed	id, type, description, entity, date, next_due_date, currency, amount_net, amount_vat, amount_gross, amount_withholding_tax, amount_other_withholding_tax, category, is_marked, is_detailed, tax_deductibility, vat_deductibility, amortization, rc_center, invoice_number, items_list, payments_list, attachment_url, attachment_preview_url, e_invoice, extra_data, created_at, updated_at
Solicit	basic	id, amount_greater_than, expire_delta_days, doc_types, created_at
Solicit	detailed	id, amount_greater_than, expire_delta_days, doc_types, localizations
Template	basic	id, name, support_custom_taxable
Template	detailed	id, name, support_custom_taxable
VatType	basic	id, value, description, is_disabled
VatType	detailed	id, value, description, notes, e_invoice, ei_type, ei_description, editable, is_disabled