Skip to main content

Invoice totals calculation

If you are setting the payments list of your invoice you must know the total amount of your items list. Luckily for you, you don't have to take the calculator out of your drawer, we got you covered with a specific set of methods to suit your needs, so you won't be seeing the Il totale dei pagamenti non corrisponde al totale da pagare error anymore.

Beware of roundings!

If you use numbers with more than 2 decimal digits when specifying the amounts in the items list and payments list they will automatically be rounded to 2 digits before doing any calculation, so if you do not take this into consideration you probably will get the 'Il totale dei pagamenti non corrisponde al totale da pagare' error.

Retrieve your Company ID!

In this example, we'll suppose you have to manage just one Company, so we simply inserted its ID directly in the code. If instead, you need to be able to manage multiple companies, you'll need to retrieve the ID of the current company in some way. Check the Company-scoped Methods page for more info.

Are you using Zapier?

Zapier Actions provide all the fields offered by the APIs, but it does not mean you need to compile all of them!

To follow this guide, you will be required to search the fields used in our example on the Zapier page and insert the related values.

The code of the fields will follow the JSON structure: for example, the "type" field is included in the "data" object, so the Zapier code will be "data.type". You can use the CRTL + F command to search the field's code faster 😉

In this example, we'll insert the values directly, but please remember that Zapier was built to let you select the workflow's previous steps' outputs as input in the Action, for example selecting the values returned by a trigger!

👵  Old or new?​

We got methods for all the cases you would possibly think of, either you are creating a new invoice or editing an old one we have a specific call.

The two methods are:

Look out!

Invoking these methods will not create or edit your invoice, it will only show you a preview of the totals. You still need to use the appropriate methods to apply the modifications.

🌟  New invoice totals​

You can invoke the Get New Issued Document Totals method if you are creating a new invoice and want to know the totals after you added the items list to your invoice body: the response will contain all the info you need to finalize your invoice creation.

Here you can find an example request and response.

POST /c/2/issued_document/totals HTTP/1.1
Host: api-v2.fattureincloud.it
Accept: application/json
Content-Type: application/json
Content-Length: 500


{
    "data": {
        "entity": {
            "name": "test"
        },
        "type": "invoice",
        "items_list": [
            {
                "vat": {
                    "id": 1
                },
                "name": "prod1",
                "net_price": 35,
                "qty": 1
            },
            {
                "vat": {
                    "id": 1
                },
                "name": "prod2",
                "net_price": 39,
                "qty": 1
            }
        ]
    }
}

And here there are the examples to make this request with our SDKs:

using System;
using System.Collections.Generic;
using It.FattureInCloud.Sdk.Api;
using It.FattureInCloud.Sdk.Client;
using It.FattureInCloud.Sdk.Model;

namespace test {
    class Program {
        static void Main(string[] args) {
            Configuration config = new Configuration();

            //set your access token
            config.AccessToken = "YOUR_ACCESS_TOKEN";

            var apiInstance = new IssuedDocumentsApi(config);
            //set your company id
            var companyId = 12345;

            //set your invoice info
            IssuedDocument invoice = new IssuedDocument(
                type: IssuedDocumentType.Invoice,
                entity: new Entity(
                    name: "test"
                ),
                itemsList: new List < IssuedDocumentItemsListItem > {
                    new IssuedDocumentItemsListItem(
                        name: "prod1",
                        netPrice: 35,
                        qty: 1,
                        vat: new VatType(
                            id: 0
                        )
                    ),
                    new IssuedDocumentItemsListItem(
                        name: "prod2",
                        netPrice: 39,
                        qty: 1,
                        vat: new VatType(
                            id: 0
                        )
                    )
                }
            );

            // Here we put our invoice in the request object
            GetNewIssuedDocumentTotalsRequest getNewIssuedDocumentTotalsRequest = new GetNewIssuedDocumentTotalsRequest(
                data: invoice
            );

            // Now we are all set for the final call
            // Get new issued documents totals: https://github.com/fattureincloud/fattureincloud-csharp-sdk/blob/master/docs/IssuedDocumentsApi.md#getnewissueddocumenttotals
            try {
                GetNewIssuedDocumentTotalsResponse result = apiInstance.GetNewIssuedDocumentTotals(companyId, getNewIssuedDocumentTotalsRequest);
                Console.WriteLine(result);
            } catch (ApiException e) {
                Console.WriteLine("Exception when calling IssuedDocumentsApi.GetNewIssuedDocumentTotals: " + e.Message);
                Console.WriteLine("Status Code: " + e.ErrorCode);
                Console.WriteLine(e.StackTrace);
            }
        }
    }
}

📜  Existing invoice totals​

If you want to edit an existing invoice instead, for example, to add a new item, you can get the updated totals invoking the Get Existing Issued Document Totals method and passing the updated fields in the request body.

In the following example, we want to a third item to an existing invoice and we want to know what will be the resulting updated totals before making the modify issued document call, using the previously described method:

POST /c/2/issued_document/12345/totals HTTP/1.1
Host: api-v2.fattureincloud.it
Accept: application/json
Content-Type: application/json
Content-Length: 500


{
    "data": {
        "items_list": [
            {
                "vat": {
                    "id": 1
                },
                "name": "prod1",
                "net_price": 35,
                "qty": 1
            },
            {
                "vat": {
                    "id": 1
                },
                "name": "prod2",
                "net_price": 39,
                "qty": 1
            },
            {
                "vat": {
                    "id": 1
                },
                "name": "prod3",
                "net_price": 48,
                "qty": 1
            }
        ]
    }
}

And here there are the examples to make this request with our SDKs:

using System;
using System.Collections.Generic;
using It.FattureInCloud.Sdk.Api;
using It.FattureInCloud.Sdk.Client;
using It.FattureInCloud.Sdk.Model;

namespace test {
    class Program {
        static void Main(string[] args) {
            Configuration config = new Configuration();

            //set your access token
            config.AccessToken = "YOUR_ACCESS_TOKEN";

            var apiInstance = new IssuedDocumentsApi(config);

            //set your company id
            var companyId = 12345;

            //set your existing invoice id
            var invoiceId = 54321;

            //set your invoice info
            IssuedDocument invoice = new IssuedDocument(
                itemsList: new List < IssuedDocumentItemsListItem > {
                    new IssuedDocumentItemsListItem(
                        name: "prod1",
                        netPrice: 35,
                        qty: 1,
                        vat: new VatType(
                            id: 0
                        )
                    ),
                    new IssuedDocumentItemsListItem(
                        name: "prod2",
                        netPrice: 39,
                        qty: 1,
                        vat: new VatType(
                            id: 0
                        )
                    ),
                    new IssuedDocumentItemsListItem(
                        name: "prod3",
                        netPrice: 48,
                        qty: 1,
                        vat: new VatType(
                            id: 0
                        )
                    )
                }
            );

            // Here we put our invoice in the request object
            GetExistingIssuedDocumentTotalsRequest getExistingIssuedDocumentTotalsRequest = new GetExistingIssuedDocumentTotalsRequest(
                data: invoice
            );

            // Now we are all set for the final call
            // Get existing issued documents totals: https://github.com/fattureincloud/fattureincloud-csharp-sdk/blob/master/docs/IssuedDocumentsApi.md#getexistingissueddocumenttotals
            try {
                GetExistingIssuedDocumentTotalsResponse result = apiInstance.GetExistingIssuedDocumentTotals(companyId, invoiceId, getExistingIssuedDocumentTotalsRequest);
                Console.WriteLine(result);
            } catch (ApiException e) {
                Console.WriteLine("Exception when calling IssuedDocumentsApi.GetExistingIssuedDocumentTotals: " + e.Message);
                Console.WriteLine("Status Code: " + e.ErrorCode);
                Console.WriteLine(e.StackTrace);
            }
        }
    }
}

🎩  The magic field​

If you don't mind about the amounts of each payment, but you just want them to match the expected totals, we provide a magic field that could be perfect for you.

The options.fix_payments field, when set to true, adjusts your last payment amount of the payments list to match your document total, incrementing or reducing the amount accordingly. Of course, if you have only one payment it will be modified to match the document total.

The options.fix_payment field must be used in the invoice creation request. Please, notice that this field is not included in the data field that contains the main section of the request, as you can see in the following example.

{
    "data": {
            ...
    },
    "options": {
        "fix_payments": true
    }
}

And here there is the example to make this request with our SDKs:

using System;
using System.Collections.Generic;
using It.FattureInCloud.Sdk.Api;
using It.FattureInCloud.Sdk.Client;
using It.FattureInCloud.Sdk.Model;

namespace test {
    class Program {
        static void Main(string[] args) {
            Configuration config = new Configuration();

            //set your access token
            config.AccessToken = "YOUR_ACCESS_TOKEN";

            var apiInstance = new IssuedDocumentsApi(config);
            //set your company id
            var companyId = 12345;

            // NOTE: this is not a complete request, for it to work you must set the invoice details!!
            IssuedDocument invoice = new IssuedDocument(
                // ...
            );

            // Here we put our invoice in the request object
            CreateIssuedDocumentRequest createIssuedDocumentRequest = new CreateIssuedDocumentRequest(
                data: invoice,
                // And here we set the magic field
                options: new IssuedDocumentOptions(
                    fixPayments: true
                )
            );

            // Now we are all set for the final call
            // Create the invoice: https://github.com/fattureincloud/fattureincloud-csharp-sdk/blob/master/docs/IssuedDocumentsApi.md#createissueddocument
            try {
                CreateIssuedDocumentResponse result = apiInstance.CreateIssuedDocument(companyId, createIssuedDocumentRequest);
                Console.WriteLine(result);
            } catch (ApiException e) {
                Console.WriteLine("Exception when calling IssuedDocumentsApi.CreateIssuedDocument: " + e.Message);
                Console.WriteLine("Status Code: " + e.ErrorCode);
                Console.WriteLine(e.StackTrace);
            }
        }
    }
}