Skip to main content

Client creation

In this guide, you will learn how to successfully create Clients and Suppliers from scratch. We'll build the request step by step, so wait until the end of the guide to send your first request!

You can find the technical documentation of this API method in the Create Client section of the API Reference.

Client and Supplier

The models for Clients and Suppliers differ only for a small subset of parameters; this guide will show in detail how to create a new Client, but it can be used in both cases. In the Suppliers case, you will need to use the Create Supplier method.

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! For example, while creating a new Client the Document ID must be left blank!

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!

0️⃣  Step Zero: The Client Type​

Fatture in Cloud lets you to define four different types of clients.

The available types are:

  • company: in an electronic document Denominazione will be automatically set
  • person: in an electronic document Nome and Cognome will be automatically set
  • pa: in an electronic document the flag Pubblica Amministrazione and Split payment will be automatically set
  • condo

In the next step we'll suppose to create a company, but the procedure is the same for the other clients types too.

1️⃣  Step One: The Client Data​

Every Client can be defined by a set of basic values, here you can find a list of the main ones:

  • name: [required] the client denomination.

  • vat_number: the client P.IVA.

  • tax_code: the client codice fiscale.

  • code: your internal client code.

  • ei_code: client SDI code.

  • email: the client email.

  • certified_email: the client PEC.

  • phone: the client's phone number.

  • address_*: the client address fields.

  • notes: the client extra notes.

  • country: optional client country (eg. Repubblica Ceca).

  • country_iso: optional client country ISO-3166 (eg. CZ).

The partial request looks like this:

// NOTE: this is a partial request, please wait before sending it
{
  "data": {
    "type": "company",
    "name": "Mario Rossi",
    "vat_number": "47803200154",
    "tax_code": "RSSMRA91M20B967Q",
    "address_street": "Via Italia, 66",
    "address_postal_code": "20900",
    "address_city": "Milano",
    "address_province": "MI"
  }
}

The corresponding code with our SDKs:

// NOTE: this is a partial request, please wait before sending it
// in this example we are using our C# SDK
// https://www.nuget.org/packages/It.FattureInCloud.Sdk/

ModelClient entity = new ModelClient(
    type: ClientType.Company,
    name: "Mario Rossi",
    vatNumber: "47803200154",
    taxCode: "RSSMRA91M20B967Q",
    addressStreet: "Via Italia, 66",
    addressPostalCode: "20900",
    addressCity: "Milano",
    addressProvince: "MI"
);

2️⃣  Step Two: Advanced Options​

In addition to the basic data explained in the previous step, some advanced fields can be used:

  • default_*: all the default fields will not be set automatically when creating a document, however, you can save the defaults, retrieve them before creating the document and insert them with the other fields when creating a document.

  • bank_*: client bank details.

  • has_intent_declaration: flag that adds Lettera d'intento fields to the electronic document, intent_declaration_protocol_number and intent_declaration_protocol_date also need to be set.

We have strong checks to ensure clients' uniqueness. The applied rule differs based on the defined fields:

  • if you are only setting the client's name, then you will receive an error if a client with the same name already exists.
  • if you are setting code, vat_number, and tax_code, these values must be unique for all your clients.

✅  Create the client!​

Now we are ready to create a client, so let's create a client using the request we just built:

POST /c/1235/entities/clients HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: api-v2.fattureincloud.it
Content-Length: 200

{"data":{"name":"Mario Rossi","vat_number":"47803200154","tax_code":"RSSMRA91M20B967Q","address_street":"Via Italia, 66","address_postal_code":"20900","address_city":"Milano","address_province":"MI"}}

The corresponding code 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 ClientsApi(config);
            //set your company id
            var companyId = 12345;

            // 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 C# SDK
            // https://www.nuget.org/packages/It.FattureInCloud.Sdk/

            ModelClient entity = new ModelClient(
                type: ClientType.Company,
                name: "Mario Rossi",
                vatNumber: "47803200154",
                taxCode: "RSSMRA91M20B967Q",
                addressStreet: "Via Italia, 66",
                addressPostalCode: "20900",
                addressCity: "Milano",
                addressProvince: "MI"
            );

            // Here we put our entity in the request object
            CreateClientRequest createClientRequest = new CreateClientRequest(
                data: entity
            );

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

You just created your first client. Congratulations!