Skip to main content

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:

ParameterDescription
fieldsThis 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.
fieldsetFatture 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 --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'

The corresponding code examples:

// 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());
}
}
}

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 TypeFieldsetFields
ArchiveDocumentbasicid, date, category, description
ArchiveDocumentdetailedid, date, category, description, attachment_url
CashbookEntrybasicid, date, amount_in, payment_accounts_in, amount_out, payment_account_out, description, kind, document
CashbookEntrydetailedid, date, amount_in, payment_accounts_in, amount_out, payment_account_out, description, kind, document
Currencybasicid, symbol, html_symbol, exchange_rate
Clientbasicid, name, code, vat_number, tax_code, address_city, address_province, country
Clientdetailedid, 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
Supplierbasicid, name, code, vat_number, tax_code, address_city, address_province, country
Supplierdetailedid, 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
F24basicid, due_date, status, amount, description, attachment_url
F24detailedid, due_date, status, payment_account, amount, description, attachment_url
IssuedDocumentbasicid, type, entity, date, number, numeration, amount_net, amount_vat, amount_gross, amount_due_discount, subject, visible_subject, next_due_date, url
IssuedDocumentdetailedid, 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_paypal_button, 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
PaymentAccountbasicid, name
PaymentAccountdetailedid, name, type, sia, iban, cuc, virtual
PaymentMethodbasicid, name, is_default, default_payment_account
PaymentMethoddetailedid, name, is_default, details, default_payment_account, type
Productbasicid, name, code, use_gross_price, net_price, gross_price, default_vat, net_cost, measure, description, category, in_stock
Productdetailedid, 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
Receiptbasicid, date, type, number, numeration, amount_net, amount_vat, amount_gross, description, payment_account, rc_center
Receiptdetailedid, date, type, number, numeration, amount_net, amount_vat, amount_gross, use_gross_prices, description, payment_account, rc_center, items_list, created_at, updated_at
ReceivedDocumentbasicid, type, description, entity, date, next_due_date, amount_net, amount_vat, amount_gross, url, is_marked
ReceivedDocumentdetailedid, 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
Solicitbasicid, amount_greater_than, expire_delta_days, doc_types, created_at
Solicitdetailedid, amount_greater_than, expire_delta_days, doc_types, localizations
Templatebasicid, name, support_custom_taxable
Templatedetailedid, name, support_custom_taxable
VatTypebasicid, value, description, is_disabled
VatTypedetailedid, value, description, notes, e_invoice, ei_type, ei_description, editable, is_disabled