Skip to main content

Join & Transform issued documents

Fatture in Cloud makes it possible to transform a document into another type, for example, a proforma into an invoice, or to join two documents together. Of course, our APIs provide the same functionality, here we explain how to do it.

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.

❓ Join or Transform​

Although the transform and join use cases may seem very different, our APIs similarly treat them.

These calls will NOT create the document

Executing a join or transform call will NOT create the new document but, instead, it will return a body that you will need to pass to the create document method.

Before diving into the functionality details it's better to define the two methods:

👨‍👩‍👧‍👦  Join​

You can use the Join Issued Document method to merge two documents into an invoice. The type of documents that can be joined are delivery_notes, orders, quotes, and work_reports.

The required query parameters for the request are:

  • ids: List of the document ids you want to join (eg. "876991,876993,876997").
  • group: If this flag is set to 1, the request will group the items (e.g. if you have the same products in two different documents, they will be grouped); otherwise the items will be kept separate.
  • e_invoice: If this flag is set to 1, your new document will be electronic.
GET /c/1235/issued_documents/join?ids=876991,876993,876997&group=1&e_invoice=1 HTTP/1.1
Accept: application/json
Host: api-v2.fattureincloud.it

The corresponding code with our SDKs:

using System;
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";
            //set your company id
            var companyId = 12345;

            var apiInstance = new IssuedDocumentsApi(config);

            // Join documents: https://github.com/fattureincloud/fattureincloud-csharp-sdk/blob/master/docs/IssuedDocumentsApi.md#joinissueddocuments
            try
            {
                JoinIssuedDocumentsResponse result = apiInstance.JoinIssuedDocuments(companyId, "876991,876993,876997", 1, 1);
                Console.Write(result);
            }
            catch (ApiException e)
            {
                Console.WriteLine("Exception when calling IssuedDocumentsApi.JoinIssuedDocuments: " + e.Message);
                Console.WriteLine("Status Code: " + e.ErrorCode);
                Console.WriteLine(e.StackTrace);
            }
        }
    }
}

🔀  Transform​

The Transform Issued Document method makes it possible to transform a document into another type of document. Here you can find which types can be transformed and what they can become.

Actual TypeNew Type
QuoteOrder, Proforma, Receipt, Invoice
Work ReportOrder, Proforma, Receipt, Invoice
OrderProforma, Receipt, Invoice
ProformaReceipt, Invoice

The required query parameters for the request are:

  • original_document_id: The id of the document you want to transform (eg. 876993).
  • new_type: The type of document you want to obtain (eg. "invoice").
  • e_invoice: If this flag is set to 1, your new document will be electronic.
  • transform_keep_copy: If this flag is set to 1, your old document will be preserved.
GET /c/1235/issued_documents/transform?original_document_id=876993&new_type=invoice&e_invoice=1&transform_keep_copy=1 HTTP/1.1
Accept: application/json
Host: api-v2.fattureincloud.it

The correspondig code with our SDKs:

using System;
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";
            //set your company id
            var companyId = 12345;

            var apiInstance = new IssuedDocumentsApi(config);

            // Transform the document: https://github.com/fattureincloud/fattureincloud-csharp-sdk/blob/master/docs/IssuedDocumentsApi.md#transformissueddocument
            try
            {
                TransformIssuedDocumentResponse result = apiInstance.TransformIssuedDocument(companyId, 876993, "invoice", 1, 1);
                Console.Write(result);
            }
            catch (ApiException e)
            {
                Console.WriteLine("Exception when calling IssuedDocumentsApi.TransformIssuedDocument: " + e.Message);
                Console.WriteLine("Status Code: " + e.ErrorCode);
                Console.WriteLine(e.StackTrace);
            }
        }
    }
}

📬  Send It!​

The two methods above won't perform any modification, but they will just return the body that you'll need to use to perform the desired action. This lets you eventually review the final result and modify it if needed.

The request also includes an options section, that makes it possible for our APIs to distinguish a normal document creation from a join or transform request; it is critical that you don't modify this section, but you must send it exactly as it is returned by the API.

THE OPTIONS

Make sure to pass also the options field to the creation call, it's the most important part of the process.

The response will look like this:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "data": {
        "type": "invoice",
        "e_invoice": true,
        ...,
    },
    "options": {
        "create_from": [
            "89144071"
        ],
        "transform": true,
        "keep_copy": true
    }
}

To persist the operation you must use the Create Issued Document method, using the previously returned body as input of the request; of course, you can modify it if needed, but please remember to leave the options section as it is. You can also check the Issued Document Creation Guide for more details.