Skip to main content

E-Invoice management

When you need to deal with an e-invoice, we provide a handful of methods that you can use to fulfill your needs: you can verify the XML of your e-invoice, download it, send it to the SDI and eventually obtain the rejection reason.

Create your e-invoice first!

In this guide, we suppose you already created your e-invoice in Fatture in Cloud, and you just need to send it to the SDI. If this is not the case, please check this guide to create your first invoice.

I already have an e-invoice XML, can't I just send it to the SDI?

Unfortunately, no. Fatture in Cloud lets you send documents to the SDI only if they were created through the Fatture in Cloud functionalities, so if you have an XML you can't just send it to the SDI using our APIs. Please, check this guide for a more detailed explanation.

🔍  Verify the E-Invoice XML​

With the Verify e-invoice XML method, you can verify your e-invoice XML before sending it to the SDI. If your XML contains an error or it is missing some fields, you can patch it by editing the invoice. A list of the most common validation errors can be found here.

Below you can find an example of a failed XML verification:

{
  "error": {
    "message": "Validation XML",
    "validation_result": [
      "Nei dati generali del documento, il contenuto \"0000-00-00\" del campo Data non è nel formato valido"
    ]
  }
}

The corresponding code with our SDKs:

  public class VerifyEInvoiceExample {
      public static void Main() {
          Configuration config = new Configuration();
          config.AccessToken = "YOUR_ACCESS_TOKEN";

          var apiInstance = new IssuedEInvoicesApi(config);
          var companyId = 12345;  // int | The ID of the company.
          var documentId = 56;  // int | The ID of the document.

          try {
              // Verify E-Invoice XML
              VerifyEInvoiceXmlResponse result = apiInstance.VerifyEInvoiceXml(companyId, documentId);
              Console.WriteLine(result);
          }
          catch (ApiException  e) {
              Console.WriteLine("Exception when calling IssuedEInvoicesApi.VerifyEInvoiceXml: " + e.Message);
              Console.WriteLine("Status Code: " + e.ErrorCode);
              Console.WriteLine(e.StackTrace);
          }
      }
  }

⬇️  Download the E-Invoice XML​

With the Get e-invoice XML method you can download your e-invoice XML if you need to.

HTTP/1.1 200 OK
Content-Type: text/xml;charset=UTF-8


<p:FatturaElettronica xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:p="http://ivaservizi.agenziaentrate.gov.it/docs/xsd/fatture/v1.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" versione="FPR12">
  <FatturaElettronicaHeader>
        ...
  </FatturaElettronicaHeader>
  <FatturaElettronicaBody>
        ...
  </FatturaElettronicaBody>
</p:FatturaElettronica>

The corresponding code with our SDKs:

  public class GetEInvoiceExample {
      public static void Main() {
          Configuration config = new Configuration();
          config.AccessToken = "YOUR_ACCESS_TOKEN";

          var apiInstance = new IssuedEInvoicesApi(config);
          var companyId = 12345;  // int | The ID of the company.
          var documentId = 56;  // int | The ID of the document.
          var includeAttachment = true;  // bool? | Include the attachment to the XML e-invoice. (optional)

          try {
              // Get E-Invoice XML
              string result = apiInstance.GetEInvoiceXml(companyId, documentId, includeAttachment);
              Console.WriteLine(result);
          }
          catch (ApiException  e) {
              Console.WriteLine("Exception when calling IssuedEInvoicesApi.GetEInvoiceXml: " + e.Message);
              Console.WriteLine("Status Code: " + e.ErrorCode);
              Console.WriteLine(e.StackTrace);
          }
      }
  }

📬  Send the E-Invoice​

If your e-invoice XML is valid you can now send it to the SDI using the Send e-invoice method.

The corresponding code with our SDKs:

  public class SendEInvoiceExample {
      public static void Main() {
          Configuration config = new Configuration();
          config.AccessToken = "YOUR_ACCESS_TOKEN";

          var apiInstance = new IssuedEInvoicesApi(config);
          var companyId = 12345;  // int | The ID of the company.
          var documentId = 56;  // int | The ID of the document.

          // Optional parameter used to test without actually sending the invoice to the SDI
          var send_options = new SendEInvoiceRequestOptions(true);  //set 'dry_run' true

          var sendEInvoiceRequest = new SendEInvoiceRequest(default,send_options); // SendEInvoiceRequest |  (optional)

          try {
              // Send E-Invoice
              SendEInvoiceResponse result = apiInstance.SendEInvoice(companyId, documentId, sendEInvoiceRequest);
              Console.WriteLine(result);
          }
          catch (ApiException  e) {
              Console.WriteLine("Exception when calling IssuedEInvoicesApi.SendEInvoice: " + e.Message);
              Console.WriteLine("Status Code: " + e.ErrorCode);
              Console.WriteLine(e.StackTrace);
          }
      }
  }

After the invoice has been sent, you can check its status as stated in the following section.

🏴‍☠️  The Dry-Run Flag​

If you are developing an integration and you want to test the Send e-invoice method without actually sending the invoice to the SDI we offer a proper field for this purpose, the options.dry_run flag.

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

The flag is optional, and the default is false; if you use it and you set it as true, all the e-invoice checks will be run but the actual dispatch.

Ensure e-invoicing is active

To use the options.dry_run flag, e-invoicing must be active for your account, even if the invoice will not be sent to the SDI.

👮  Check the E-Invoice status​

After the invoice has been sent, you can check its status by making a Get Issued Document request: the ei_status field will contain the status of your e-invoice.

Check your fieldset!

To show the ei_status field, you need to customize the response, selecting the detailed fieldset or including it in the fields list.

The corresponding code with our SDKs:


public class GetIssuedDocumentExample
{
public static void Main()
{
Configuration config = new Configuration();

// Configure OAuth2 access token for authorization: OAuth2AuthenticationCodeFlow
config.AccessToken = "YOUR_ACCESS_TOKEN";

    var apiInstance = new IssuedDocumentsApi(config);
    var companyId = 12345;  // int | The ID of the company.
    var documentId = 56;  // int | The ID of the document.
    var fields = "fields_example; // string | List of comma-separated fields. (optional)
    var fieldset = "detailed";  // This must be used to retrieve the ei_status field

    try
    {
      // Get Issued Document
      GetIssuedDocumentResponse result = apiInstance.GetIssuedDocument(companyId, documentId, fields, fieldset);
      Console.WriteLine(result);
    }
    catch (ApiException  e)
    {
      Console.WriteLine("Exception when calling IssuedDocumentsApi.GetIssuedDocument: " + e.Message);
      Console.WriteLine("Status Code: " + e.ErrorCode);
      Console.WriteLine(e.StackTrace);
    }

}
}

🚀  Real time updates!​

If you want to keep the e-invoice status updated on your application, you can use our Webhooks to be notified when a status change occurs. The Notification Type required to be notified is the following: it.fattureincloud.webhooks.issued_documents.e_invoices.status_update

Please, note that the notification will not contain the status of the e-invoice, but just the ID of the updated document: you still need to use the Get Issued Document method to retrieve the status, but the webhooks will enable you to avoid wasting API quotas by performing polling operations.

The steps required to update the e-invoice status using Subscriptions are the following (you can find more details on the Webhooks page):

  • (*) Require the Webhooks enablement by filling out the dedicated Google Form and waiting for the approval email
  • (*) Create a target endpoint to manage the incoming notifications (check out the Notifications page); to be able to successfully create a subscription we suggest starting with the Verification type
  • (*) Use the Create a Webhook Subscription method to require a new subscription
  • (*) When you receive the Verification Notification, verify your subscription as described in the Subscriptions
  • When an e-invoice status is updated, you'll receive the related Event Notification, containing the ID of the document involved
  • Perform the Get Issued Document API request using the document's ID as input, and read the ei_status field

Note: All the steps starting with (*) must be performed only once to create the subscription, while all the other steps must be performed each time a new Notification is received by your endpoint.

🚨  Get the E-Invoice rejection reason​

If your e-invoice gets rejected by the SDI, you can check the rejection reason with the Get rejection reason method. The list of the most common rejection reasons can be found here.

For example, you could get an error like the following one:

{
  "data": {
    "reason": "Il Codice Fiscale del cliente risulta sbagliato.",
    "code": "0036",
    "date": "2022-02-22"
  }
}

The corresponding code with our SDKs:

  public class GetEInvoiceRejectionReasonExample {
      public static void Main() {
          Configuration config = new Configuration();
          config.AccessToken = "YOUR_ACCESS_TOKEN";

          var apiInstance = new IssuedEInvoicesApi(config);
          var companyId = 12345;  // int | The ID of the company.
          var documentId = 56;  // int | The ID of the document.

          try {
              // Get E-Invoice Rejection Reason
              GetEInvoiceRejectionReasonResponse result = apiInstance.GetEInvoiceRejectionReason(companyId, documentId);
              Console.WriteLine(result);
          }
          catch (ApiException  e) {
              Console.WriteLine("Exception when calling IssuedEInvoicesApi.GetEInvoiceRejectionReason: " + e.Message);
              Console.WriteLine("Status Code: " + e.ErrorCode);
              Console.WriteLine(e.StackTrace);
          }
      }
  }