change log link

1. Introduction

Aruba’s Electronic Invoicing Web Services are available to Premium users or basic users connected to them by proxy.

"Electronic invoicing" is the digital process of generating and managing invoices throughout their whole life cycle:

  • generating

  • sending/receiving

  • compliant storage

Electronic invoice refers to:

  • a digital document

  • structured in accordance with a standard language, in other words, tracked "PA invoice" .xml format

  • digitally signed by the issuer (for PAs)

  • with the minimum mandatory content stipulated by Ministerial Decree 55/2013 (Annex A)

  • to be stored in accordance with the relevant regulations (pursuant to the Prime Ministerial Decree of 3 December 2013) compulsorily both for tax purposes (Ministry of the Economy and Finance Decree of 17 June 2014) and for statutory accounting periods (Art. 2220 of the Italian Civil Code).

Those involved in the Electronic Invoicing process are:

  • The Economic Operator (EO): the transferor/provider that issues the invoice to the PA/PRIVATE INDIVIDUALS or the transferee/client that receives electronic invoices

  • The Intermediary (Aruba PEC S.p.A): the party appointed by the transferor/provider or the transferee/client to send and/or receive electronic invoices sent via the SDI on their behalf

  • Exchange System (Sistema di Interscambio, SDI): system under the control of the Ministry of the Economy and Finance, via which electronic invoices are sent to the Administration (art. 1, paragraph 211, law no. 244 of 24 December 2007) or to private individuals (art. 1, paragraph 2, legislative decree 127/2015)

The processes for sending (accounts receivable) and receiving (accounts payable) electronic invoices via Aruba’s Electronic Invoicing system are outlined in the figures below:

intro active cycle
  1. The Economic Operator creates the invoice as an .xml file (from its own management system or the Control Panel) and sends the invoice via web service channels.

  2. Aruba PEC (the intermediary) makes sure that the format is compliant

  3. Aruba PEC adds the qualified electronic signature (optional for B2B and B2C) via an automatic Aruba PEC or Client signature and sends it to the SDI.

  4. The SDI checks and approves the electronic invoice and sends it to the recipient (using the recipient code or PEC) or to a third party recipient used by the recipient

  5. The SDI sends Aruba PEC S.p.A. a notification explaining that the invoice has been rejected, not delivered or delivered.

  6. Once the notifications have been received confirming the outcome of the sending process (accepted/rejected) from the recipient, the SDI sends them to Aruba PEC S.p.A. (exchange not provided for B2b and B2C), which delivers them to the EO.

  7. Sent invoices digitally stored in accordance with regulations (mandatory).

intro passive cycle
  1. The Economic Operator or its intermediary sends the electronic invoice to the Exchange System using the seven-character recipient code for Aruba PEC (receiving intermediary), provided by the Exchange System.

  2. The SDI sends the invoice received from the sender to the Aruba PEC receipt channel (linked to the recipient code)

  3. Aruba PEC delivers the electronic invoice received to the Client according to the VAT number via WS, web application and/or PEC

  4. Aruba PEC stores the electronic invoices sent in accordance with the regulations via the compliant DocFly Digital Storage system

In order to receive electronic invoices via Aruba’s Electronic Invoicing system, they need to be sent to the recipient code KRRH6B9.

The Recipient Code is a unique 7-digit code issued by the Italian Revenue Agency to owners of a channel for receiving electronic invoices via the Exchange System (SDI). So this code is issued either to the VAT numbers for parties accredited by the Italian Revenue Agency, or to accredited intermediaries responsible for handling invoices to recipients (such as Aruba).

Aruba’s recipient code, which is required in order to receive electronic invoices via the Electronic Invoicing application, is: KRRH6B9.

This guide explains how to use the web services offered by Aruba’s Electronic Invoicing system properly. Aruba’s Electronic Invoicing system offers a series of REST APIs with which you can interface to send invoices to the SDI, find for sent and received invoices, as well as send financial communications about the "new spesometro" (regular VAT payments and Invoice data).

The system can also send received invoices (accounts payable) from Web Services shown by the user, which will have to implement a series of technical and functional requirements.

The system deals with requests received via the services, processes them, checks certain data and sends them to the SDI (Exchange System).

SDI processes the requests by running checks on the data sent and, in the case of Financial Communications, generates a result that the Aruba system verifies and notifies its customers accordingly.

In the case of an electronic invoice, SDI processes the data received, transmits it to the Public Administration or Private entities and notifies the ARUBA system directly of the results.

The web services shown allow you to provide Financial Communications:

intro web services

… both to accounts receivable:

intro web services active cycle

… and to accounts payable:

intro web services passive cycle

2. Environments

There are two environments for integration with Electronic Invoicing services.

DEMO: Environment with equivalent functionalities to the production environment, but only available temporarily, with specific login details. The details entered are confirmed and maintained for as long as the user account is valid.

PRODUCTION: Production environment available to holder users of the service.

The table below shows the base URLs that need to precede the paths for the authentication methods (Autenticazione Chapter) and for other methods (Chapters entitled: Financial Communications, Transmission of Electronic Invoices, Find Invoices Sent, Find Invoices Received, Send Customer Result, Find Notifications on Invoices Sent and Find Notifications on Invoices Received).

BASE URL

AMBIENTE

Demo

Production

Authentication

https://demoauth.fatturazioneelettronica.aruba.it

https://auth.fatturazioneelettronica.aruba.it

Other methods

https://demows.fatturazioneelettronica.aruba.it

https://ws.fatturazioneelettronica.aruba.it

Please note that once you have received your login details, you will need to complete the registration by using them to log in to the online control panel for Aruba Electronic Billing. From the online control panel, you can also view data (e.g. sent invoices, received invoices) and configure the Electronic Billing service (e.g. receive emails, mandate requests, assignors).

In the table below, you can find the link to the online control panel for electronic billing for the DEMO and PRODUCTION environments.

ONLINE CONTROL PANEL LINK

Demo

Production

https://demo.fatturazioneelettronica.aruba.it

https://fatturazioneelettronica.aruba.it

3. SLA (Service Level Agreement)

The Electronic Invoicing API limits clients to a certain number of calls. These limits can be found in the table below.

Service SLA

Maximum sent files size

5 MB

Maximum no. requests to send invoices per IP (Upload invoice)

30 per minute

Maximum no. requests to send invoices that have already been signed per IP (Upload invoice signed)

30 per minute

Maximum no. requests to find sent invoices per IP (Find Invoices Sent)

12 per minute

Maximum no. requests to find received invoices per IP (Find Invoices Received)

12 per minute

Maximum no. requests to find notifications for sent invoices per IP (Find Notifications on Invoices Sent)

12 per minute

Maximum no. requests to find notifications for received invoices per IP (Find Notifications on Invoices Received)

12 per minute

Comprehensive SLA

99.95% uptime for the Web interface and Web Services

Processing the invoice file

Within 24 hours of receipt by the client

Sending the invoice file to the SDI

Within 24 hours of processing the invoice file

Sending the outcome notification to the client

Within 24 hours of receipt by the Exchange System

Sending invoice file and outcome notification to the Storage System

Within the times stipulated by the regulations in force

4. HTTP status codes

The following are the HTTP status codes that might be received by an Electronic Invoicing API client.

Status code Meaning

200 OK

Standard response for successful HTTP requests.

201 Created

The request has been met, returning the creation of a new resource

204 No Content

The server has successfully processed the request and no content will be returned.

400 Bad Request

The request cannot be met due to syntax errors.

401 Unauthorized

Similar to 403/Forbidden, but designed for use when authentication is possible but it has failed and cannot be met.

403 Forbidden

The request is valid but is declined by the server. The user may not have the necessary authorization to access the resource.

404 Not Found

The resource requested has not been found.

413 Request Entity Too Large

Limits described in the SLA (Service Level Agreement) exceeded

429 Too Many Requests

Limits described in the SLA (Service Level Agreement) exceeded

500 Internal Server Error

Generic error message with no details.

5. Autenticazione

To access the Electronic Billing service, you will need to sign in as follows.

to invoke the authentication methods the path method is preceded by the relevant base URL

As calls to the Autentication methods involve providing sensitive information, when invoking them users need to protect their data as follows.

Sensitive information should not be transferred in the query string. Transferring sensitive information in this way renders it vulnerable to interception. Calls should therefore not be made as shown in this example:

POST /auth/signin?username=User&password=Password&grant_type=password HTTP/1.1 (1)
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
1 Sensitive information in the query string

In order to protect communications, Aruba S.p.A will block calls to Autentication methods that display sensitive information in the query string.

Sensitive information should be transferred in the request body, taking advantage of the benefits of HTTPS communication to protect it. An example of the correct use of Authentication methods is shown below:

POST /auth/signin HTTP/1.1 (1)
Content-Type: application/x-www-form-urlencoded;charset=UTF-8

username=User&password=Password&grant_type=password (2)
1 Query string empty
2 Sensitive information in the body

5.1. signin

POST authentication base url/auth/signin

The method is used to request a security token. This token is required to invoke the methods of the various Electronic Invoicing servers (Resource Servers) that are protected by the system.

The token expires after 30 minutes.

The following request parameters must be in the format application/x-www-form-urlencoded with UTF-8 encoding.

Parameter Description Constraints

grant_type

Type of grant used for authentication. Normally the same as "password"

Mandatory

username

The user’s username

Mandatory

password

The user’s password

Mandatory

HTTP request

POST /auth/signin HTTP/1.1
Content-Type: application/x-www-form-urlencoded;charset=UTF-8

grant_type=password&username=Utente&password=Password

HTTP response

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

{
  "access_token" : "873b60298d4e44f",
  "token_type" : "bearer",
  "expires_in" : 1800,
  "refresh_token" : "5e66d14ce5826879",
  "userName" : "Utente",
  "as:client_id" : "Auth",
  ".issued" : "Thu, 12 Nov 2020 16:39:57 GMT",
  ".expires" : "Thu, 12 Nov 2020 17:09:57 GMT"
}

Response fields

Field Type Description

access_token

String

Access token

token_type

String

Type of token returned. Constant = "bearer"

expires_in

Number

Number of seconds (remaining) before the token expires

refresh_token

String

Refresh Token to be used to obtain a new token

as:client_id

String

Client who has requested the token

userName

String

User logged in

['.issued']

String

Date/Time of ticket issue in the format: EEE, dd MMM yyyy HH:mm:ss z

['.expires']

String

Date/Time of expiry issue in the format: EEE, dd MMM yyyy HH:mm:ss z

If an error occurs, the system will return the Http status code 400 Bad Request with the following response

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Content-Length: 101

{
  "error" : "invalid_grant",
  "error_description" : "The user name or password is incorrect."
}

where

Field Type Description

error

String

Error Code

error_description

String

Description of the error

The access token must be used to invoke the following methods. In particular, a header must be entered in the HTTP request, consisting of the following:

Header Name Header Value

Authorization

Bearer <access_token>

Requests without a security token (or with an incorrect / expired token) will receive the Http status code 401 Unauthorized with the message: "Full authentication is required to access this resource".

5.2. refresh

POST authentication base url/auth/signin

The token can be renewed by submitting a refresh request, which requires the following parameters in the format application/x-www-form-urlencoded with UTF-8 encoding. Refreshing the token, avoiding sending login details, offers more security and a more efficient process than requesting a new token via signin.

If a valid refresh token is not specified, the refresh process returns an "invalid_grant" error message
The refresh token is valid for 60 minutes from the time of issue (.issued), thereby allowing a token to be updated for up to 30 minutes after its expiry (.expires)

The following request parameters must be in the format application/x-www-form-urlencoded with UTF-8 encoding.

Parameter Description Constraints

grant_type

Constant = "refresh_token"

Mandatory

refresh_token

Refresh token returned in the above request

Mandatory

For example:

POST /auth/signin HTTP/1.1
Content-Type: application/x-www-form-urlencoded;charset=UTF-8

grant_type=refresh_token&refresh_token=ee4aae0c9d754ad08a657510cae82efe

The response is identical to the previous one. Another access token (and relevant refresh token) is issued.

5.3. userInfo

GET authentication base url/auth/userInfo

This method lets you retrieve user information relating to the authentication token.

HTTP request

GET /auth/userInfo HTTP/1.1
Authorization: Bearer NLOGDVXLVaF3tzmnVPkTwpkuh7dG0i09uSCcog3u+rE=

Request headers

Name Description

Authorization

Authorization Access token obtained by signin

HTTP response

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

{
  "username" : "ARUBA0000",
  "pec" : "pec@pec.it",
  "userDescription" : "Aruba PEC S.p.A.",
  "countryCode" : "IT",
  "vatCode" : "01879020517",
  "fiscalCode" : "01879020517",
  "accountStatus" : {
    "expired" : false,
    "expirationDate" : "2021-02-12"
  },
  "usageStatus" : {
    "usedSpaceKB" : 262144,
    "maxSpaceKB" : 1048576
  }
}

Response fields

Field Type Description

username

String

Username

pec

String

Certified email address

userDescription

String

First name and surname or company name

countryCode

String

Country code (e.g. IT for Italy)

vatCode

String

VAT number

fiscalCode

String

Tax code

accountStatus.expired

Boolean

true if the user has expired or been suspended, otherwise false

accountStatus.expirationDate

String

Expiry date for user in the format yyyy-MM-dd

usageStatus.usedSpaceKB

Number

Storage space used in kilobytes

usageStatus.maxSpaceKB

Number

Storage space purchased in kilobytes

6. Financial Communications

financial reporting

The methods shown for Financial Communications enable the creation of a new transmission request to SDI or recovery of the status of the same request being processed by the Aruba system.

There are two types of transmission request:

  • Invoice Data (known as 'spesometro' data in Italy): xml containing the data relating to one or more invoices issued to several assignees/customers or one or more invoices received also from several assignors/providers. They can be transmitted in a single .xml file or in ZIP files containing several .xml files.

  • VAT payments: file in .xml format containing the communication data relating to the declarant. They can be transmitted in a single .xml file or in ZIP files containing several .xml files.

6.1. CreateTransmissionRequest

POST base url other methods/services/ClientRequest/CreateTransmissionRequest

Creation of a new request for the transmission of "Financial Communications" (single file transmission request).

The dataFile field must contain an xml document which conforms to the Revenue Agency specifications. The document must be Base64 codified and contain a CADES-based electronic signature.

HTTP request

POST /services/ClientRequest/CreateTransmissionRequest HTTP/1.1
Accept: application/json
Content-Type: application/json;charset=UTF-8

{
  "userName" : "ARUBA0000",
  "password" : "ArubaPwd",
  "userID" : "ARUBA0000",
  "comunicationType" : "LI",
  "dataFile" : "dGVzdA=="
}

Request fields

Field Type Description Constraints

userID

String

Unique ID of the client / user, the same as the username when called by an external client.

userName

String

User accredited on the system

Mandatory

password

String

Password

Mandatory

comunicationType

String

Enum identifying the type of communication CommunicationType

Mandatory

dataFile

String

Data attached in Base64 format

Mandatory

HTTP response

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

{
  "errorCode" : "",
  "errorDescription" : "",
  "requestID" : "KYI9RX7NAAT4WHUK"
}

Response fields

Field Type Description

errorCode

String

Request acceptance result code only has a value if an error occurs, otherwise it is empty.

errorDescription

String

The field contains the details of any error found in the request acceptance phase. For example: details of XSD validation of the .xml file, generic error etc.

requestID

String

Unique request code used in subsequent communications (callback / on demand). Only has a value in the case of a positive result (no error code)

6.2. CreateTransmissionRequestList

POST base url other methods/services/ClientRequest/CreateTransmissionRequestList

Creation of "Financial Communications" transmission request in zip format.

The dataFile must contain a Zip file, containing xml files which conform to the Revenue Agency specifications. The archive file must be Base64 codified and contain a CADES-based electronic signature.

HTTP request

POST /services/ClientRequest/CreateTransmissionRequestList HTTP/1.1
Accept: application/json
Content-Type: application/json;charset=UTF-8

{
  "userName" : "ARUBA0000",
  "password" : "ArubaPwd",
  "userID" : "ARUBA0000",
  "comunicationType" : "LI",
  "dataFile" : "dGVzdA=="
}

Request fields

Field Type Description Constraints

userID

String

Unique ID of the client / user, the same as the username when called by an external client.

userName

String

User accredited on the system

Mandatory

password

String

Password

Mandatory

comunicationType

String

Enum identifying the type of communication CommunicationType

Mandatory

dataFile

String

Data attached in Base64 format

Mandatory

HTTP response

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

{
  "errorCode" : "",
  "errorDescription" : "",
  "requestID" : "UTQVCG4IZXKUDSJV",
  "requestIDList" : [ {
    "fileName" : "ITADFSREETDSD_LI_0001.xml",
    "requestID" : "WJPMX5X4TNN7SGUU"
  }, {
    "fileName" : "ITADFSREETDSD_LI_0002.xml",
    "requestID" : "HDIVP61UAGRYEPSF"
  }, {
    "fileName" : "ITADFSREETDSD_LI_0003.xml",
    "requestID" : "4TXQELRAS28AHN1K"
  } ]
}

Response fields

Field Type Description

errorCode

String

Request acceptance result code only has a value if an error occurs, otherwise it is empty.

errorDescription

String

The field contains the details of any error found in the request acceptance phase. For example: details of XSD validation of the individual .xml file in the .zip file, generic error etc..

requestID

String

Unique ID of the file in Zip format

requestIDList

CreateTransmissionZipRequestIDList

Contains a list of objects consisting of: fileName and requestID

requestIDList[].fileName

String

The name of the file contained in the ZIP to be used for subsequent calls or callbacks

requestIDList[].requestID

String

The name of the file generated by the system to be used for subsequent calls or callbacks

6.3. GetTransmissionInfoRequest

POST base url other methods/services/ClientRequest/GetTransmissionInfoRequest

Service for querying the status of a request.

HTTP request

POST /services/ClientRequest/GetTransmissionInfoRequest HTTP/1.1
Accept: application/json
Content-Type: application/json;charset=UTF-8

{
  "userName" : "ARUBA0000",
  "password" : "ArubaPwd",
  "requestID" : "T17ITJIXBN"
}

Request fields

Field Type Description Constraints

userName

String

User accredited on the system

Mandatory

password

String

Password

Mandatory

requestID

String

Unique ID of the request provided in the creation phase

Mandatory

HTTP response

Field Type Description Constraints

userName

String

User accredited on the system

Mandatory

password

String

Password

Mandatory

requestID

String

Unique ID of the request provided in the creation phase

Mandatory

Response fields

Field Type Description

result

String

Result of request processing

notifyResult

String

XML Base64 with the response obtained from SDI, only when the file has been processed

elaboratedResult

String

Result code when the file has been processed by SDI

receiptTimestamp

String

Date and time of receipt of file from SDI

fileID

String

Unique ID provided by SDI in the request

fileName

String

Name of the file generated in accordance with the communication type specifications

pddAvailable

Boolean

true if the financial message and the associated outcome files have been saved (see pdd for downloading the preservation package), otherwise false.

error

String

Description of the result from the "result" field

6.4. pdd

POST base url other methods/services/ClientRequest/pdd

If pddAvailable is true then this method retrieves the Preservation package as a Zip file of financial messages, specifying its request ID (requestID). If however pddAvailable is false, in other words, the Preservation package is not available, the HTTP status code 404 is returned.

HTTP request

POST /services/ClientRequest/pdd HTTP/1.1
Accept: application/json
Content-Type: application/json;charset=UTF-8

{
  "userName" : "ARUBA0000",
  "password" : "ArubaPwd",
  "requestID" : "Y6VIUB3ZZH"
}

Request fields

Field Type Description Constraints

userName

String

User accredited on the system

Mandatory

password

String

Password

Mandatory

requestID

String

Unique ID of the request provided in the creation phase

Mandatory

HTTP response

HTTP/1.1 200 OK
Content-Disposition: attachment; filename="IT01879020517_LI_0001.conservazione.zip"
Content-Type: application/zip
Accept-Ranges: bytes
Content-Length: 8

<binary>

6.5. ComunicationType

Valore Descrizione

LI

Regular VAT payment

DF

Invoice data

6.6. ErrorCode

Valore Descrizione

SF01

Being processed

SF02

Processed

SF03

Error

AR01

Attached file empty or missing

AR02

Access denied

AR03

Incorrect file

AR04

Request ID missing

AR05

Remote signature missing

AR06

Transmission to SDI not executed

AR07

SDI result response not received

AR08

Incorrect signature

AR09

Third-party transmission not permitted

AR10

Maximum number of invoices and financial communications reached

AR20

Incorrect Communication Type

AR21

File not signed

AR99

Generic error

6.7. CodiceEsito

Valore Descrizione

ES01

Regular VAT payment

ES02

File valid with reports

ES03

Rejected

7. Transmission of Electronic Invoices

sending invoice

The methods shown enable the creation of a new request to transmit to SDI invoices issued to the Public Administration or private entities.

SDI verifies that the content of the files transmitted is correct and in order, and transmits them to the specified recipient.

The invoices, signed or to be signed, must be sent in an .xml file in accordance with a specific format established by SDI.

7.1. Sender Details

The synchronous check has been introduced for the Sender ID field (tag 1.1.1 <IdTrasmittente> [1] of the XML path),which will have to be filled in with the tax code for the intermediary Aruba PEC S.p.A.: 01879020517.

Below is an example of how to fill in section 1.1 <DatiTrasmissione> [1] of the XML invoice file:

    <DatiTrasmissione>
        <IdTrasmittente>
    	    <IdPaese>IT</IdPaese>
    	    <IdCodice>01879020517</IdCodice>
    	</IdTrasmittente>
    	<!--
    	     ...
    	     other XML 1.1 <DatiTrasmissione> tag data:
    	     - 1.1.2   <ProgressivoInvio>
    	     - 1.1.3   <FormatoTrasmissione>
    	     - 1.1.4   <CodiceDestinatario>
    	     ...
    	-->
    	<ContattiTrasmittente>
            <Telefono>05750505</Telefono>
            <Email>info@arubapec.it</Email>
        </ContattiTrasmittente>
        <!--
             ...
             other XML 1.1 <DatiTrasmissione> tag data:
             - 1.1.6 <PECDestinatario>
             ...
        -->
    </DatiTrasmissione>

7.2. Self-billed invoice

A self-billed invoice is a tax document similar to an invoice, issued by the transferee/client on behalf of the transferor/provider (supplier). This is a very specific type of invoice, characterized by the fact that it is the client that is responsible for applying VAT and issuing the invoice.

To issue an electronic self-billed invoice, you will need to fill in the XML file as follows:

  • Populate field 1.6 <SoggettoEmittente> with "CC". This value indicates that the invoice is issued by the Transferee/Client on behalf of the Transferor/Provider;

  • Populate section 1.4 <CessionarioCommittente> with the data for the issuer, or the Transferor/Provider indicated in Aruba’s Electronic Invoicing details (user’s VAT number);

  • Populate section 1.2 <CedentePrestatore> with the supplier’s details.

Aruba Electronic Invoicing will check the XML file received using the following checks on the issuer (transferor/provider indicated in the personal details):

  • if tag 1.6 is not present, a check is carried out to ensure that the VAT number of the issuer matches the VAT number mentioned for the transferor/provider (section 1.2 of the XML file);

  • if tag 1.6 is filled in with "CC", a check is carried out to ensure that the issuer’s VAT number matches the VAT number mentioned for the transferee/client (section 1.4 of the XML file);

  • if tag 1.6 is filled in with "TZ" or if the checks mentioned above are not passed, the system will not accept the invoice.

Self-billed invoices can either be issued with "Document Type" TD20 or TD01, depending on the type of self-billed invoice issued.

For more information about the different circumstances and how self-billed invoices are created, you can also refer to the FAQs for:

  • The Italian Revenue Agency, available at this link;

  • Assosoftware, available at this link.

7.3. Upload invoice

POST base url other methods/services/invoice/upload

This method must be used by the EO to send an invoice in XML format in accordance with AGID standards, but not yet digitally signed.

HTTP request

POST /services/invoice/upload HTTP/1.1
Accept: application/json
Authorization: Bearer NLOGDVXLVaF3tzmnVPkTwpkuh7dG0i09uSCcog3u+rE=
Content-Type: application/json;charset=UTF-8

{
  "dataFile" : "dGVzdA==",
  "credential" : "",
  "domain" : ""
}
The "domain" and "credential" fields represent the domain and the credentials for the automatic signature respectively, if the user has them, otherwise leave this fields empty or omit them.

Request headers

Name Description

Authorization

Authorization Access token obtained by signin

Request fields

Field Type Description Constraints

dataFile

String

Invoice file

Mandatory

credential

String

Signature credentials

domain

String

Signature domain

HTTP response

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

{
  "errorCode" : "0000",
  "errorDescription" : "Operazione effettuata - 521e052902be7b879d41e0fd586f0e21",
  "uploadFileName" : "IT01842873366_xnvyg.xml.p7m"
}

Response fields

Field Type Description

uploadFileName

String

File name assigned to the invoice

errorCode

String

File name assigned to the invoice Synchronous Checks

errorDescription

String

Error description, if any. Synchronous Checks and request ID

Request ID:
A request ID has been entered in the errorDescription field. This code can be used in the support requests to speed up resolution.

7.4. Upload invoice signed

POST base url other methods/services/invoice/uploadSigned

This method must be used by the EO to send an invoice in XML format that has already been digitally signed in accordance with AGID standards:

  • with the extension .p7m and in CAdES-BES format (CMS Advanced Electronic Signatures);

  • with.xml extension and in XAdES-BES format (XML Advanced Electronic Signatures).

HTTP request

POST /services/invoice/uploadSigned HTTP/1.1
Accept: application/json
Authorization: Bearer NLOGDVXLVaF3tzmnVPkTwpkuh7dG0i09uSCcog3u+rE=
Content-Type: application/json;charset=UTF-8

{
  "dataFile" : "dGVzdA=="
}

Request headers

Name Description

Authorization

Authorization Access token obtained by signin

Request fields

Field Type Description Constraints

dataFile

String

Invoice file encoded in Base64

Mandatory

HTTP response

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

{
  "errorCode" : "",
  "errorDescription" : "Operazione effettuata - 521e052902be7b879d41e0fd586f0e21",
  "uploadFileName" : "IT01879020517_zwwuz.xml.p7m"
}

Response fields

Field Type Description

uploadFileName

String

File name assigned to the invoice

errorCode

String

File name assigned to the invoice Synchronous Checks

errorDescription

String

Error description, if any. Synchronous Checks and request ID

Request ID:
A request ID has been entered in the errorDescription field. This code can be used in the support requests to speed up resolution.

7.5. Checks

In order to limit the risk of rejection, Aruba’s Electronic Invoicing system carries out some checks on XML electronic invoices received from Web Services. Specifically, the check carried out on the uploaded files involves 2 stages:

  • Synchronous checks: these are carried out when the invoice is received by Aruba’s Electronic Invoicing system, allowing a preliminary analysis of the file. The outcome of these checks decides whether to accept or reject the invoice received. The outcome of synchronous checks is returned immediately with one of the messages indicated in Synchronous Checks.

  • Asynchronous checks: these are carried out after our systems have processed the file. The outcome of these checks results in the invoice being assigned a status:

    • If the invoice passes the checks, it is sent to the Exchange System and marked as "Sent";

    • o If the invoice does not pass the checks, it is not sent to the Exchange System and is marked as "Processing Error"; The outcome of these checks can be retrieved by finding the sent invoices using getByFilename, getByInvoiceId or Callbacks.

upload checks

7.5.1. Synchronous Checks

Code Message Description of the Check

0000

Operazione effettuata

Invoice sent successfully

0001

Errore imprevisto generico

Unexpected generic error

0002

Errore parametri in input: emailnotifica, formato mail inserita non valido

Invalid email format

0002

Errore parametri in input: dataFile, formato fattura errato o non presente

Invoice not present

0012

Errore di autenticazione al sistema

User has failed to sign in to the system

0013

Errore in fase di salvataggio dati

Error when saving on to the db

0033

Il file inviato supera la dimensione massima

Invoice bigger than the maximum size SLA (Service Level Agreement)

0034

File già inviato di recente

Invoice already sent and being processed by the system

0092

Errore in validazione XSD: "errore specifico"

XSD validation with the specific description of the error

0093

Errore deleghe non valide

Invalid delegated user

0094

La fattura che stai inviando contiene ID e/o contatti dei trasmittenti differenti dai dati dell’intermediario Aruba PEC.

Sender ID not present or different from Aruba PEC S.p.A

0095

Servizio momentaneamente non disponibile. Il controllo dei permessi è fallito. Si prega di riprovare più tardi.

The service is temporarily unavailable, the user permissions cannot be verified.

0097

Spazio esaurito o non sufficiente, è necessario effettuare un aumento di spazio.

You need to increase your space, sign in to the web panel for more information.

7.5.2. Asynchronous Checks

Message Description of the check

FATRSM201 - Errore nella validazione formale della Fattura verificare il file XML, contattare l’assistenza

Error when formally validating the Invoice, check the XML file, contact support

FATRSM202 - Partita IVA o Paese del Cedente/Prestatore non presente

VAT number or Country of the Transferor/Provider not present

FATRSM205 - Partita IVA non associato ad un utente Aruba

VAT number not linked to an Aruba user

FATRSM208 - User non trovata contattare l’assistenza

Username not found, contact support

FATRSM212 - Errore di validazione: "code" - "message"

Validation error (Extra schema checks)

FATRSM217 - User non trovata contattare l’assistenza

Username not found, contact support

FATRSM218 - Delega non trovata contattare l’assistenza

Delegated user not found, contact support

FATRSM302 - Verifica della firma o firma errata in fattura

Check signature or incorrect signature on the invoice

FATRSM401 - File xml vuoto, contattare l’assistenza

Empty xml file, contact support

FATRSM403 - Utenza ARUBA disabilitata, contattare l’assistenza

ARUBA user disabled, contact support

NOTRSM201 - Errore formale nella notifica, contattare l’assistenza

Formal error in the notification, contact support

NOTRSM202 - Nome file assente nella notifica, contattare l’assistenza

File name not present in notification, contact support

Extra schema checks

Asynchronous checks for the message FATRSM212, "code" and "message" can be those shown in the table below:

Sdi Code Ordinary Invoice Message [1] Simplified invoice message (if different) [1] Field in which the check is carried out Check complete

00305

1.4.1.1.2 <IdCodice> non valido

1.4.1.1.2 <IdCodice>

1.4.1.1.2 <IdCodice>: If completed and if information element 1.4.1.1.1 <IdPaese> is "IT", the VAT number has been confirmed as being included in the Tax Register

00306

1.4.1.2 <CodiceFiscale> non valido

1.4.1.2 <CodiceFiscale>

Invalid <CodiceFiscale>

00400

2.2.1.14 < Natura> non presente a fronte di 2.2.1.12 <AliquotaIVA> pari a zero

2.2.4 <Natura> non presente a fronte di 2.2.3.2 <Aliquota> pari a zero

2.2.1.14 <Natura>

A check is carried out to ensure that it has been entered, if information element 2.2.1.12 <AliquotaIVA> is equal to "0.00", and that it has not been entered, if information element 2.2.1.12 <AliquotaIVA> is anything else

00401

2.2.1.14 <Natura> presente a fronte di 2.2.1.12 <AliquotaIVA> diversa da zero

2.2.4 <Natura> presente a fronte di 2.2.3.2 <Aliquota> diversa da zero

2.2.1.14 <Natura> and 2.2.1.12 <AliquotaIVA>

A check is carried out to ensure that it has been entered, if information element 2.2.1.12 <AliquotaIVA> is equal to "0.00", and that it has not been entered, if information element 2.2.1.12 <AliquotaIVA> is anything else

00403

2.1.1.3 <Data> successiva alla data di ricezione

2.1.1.3 <Data>

Check to ensure that this date is not after the date on which the file was received by the Exchange System. In addition, if information element 2.1.1.1 <TipoDocumento> is "TD04", a check is carried out to ensure that it is not before the one provided in information element 2.1.6.3 <Data>

00411

2.1.1.5 <DatiRitenuta> non presente a fronte di almeno un blocco 2.2.1 <DettaglioLinee> con 2.2.1.13 <Ritenuta> uguale a SI

2.1.1.5 <DatiRitenuta>

A check is carried out to ensure that this block is present with at least one block 2.2.1 <DettaglioLinee> with element 2.2.1.13 <Ritenuta> equal to 'SI' and/or a block 2.1.1.7 <DatiCassaPrevidenziale> with element 2.1.1.7.6 <Ritenuta> equal to 'SI'

00413

2.1.1.7.7 <Natura> non presente a fronte di 2.1.1.7.5 <AliquotaIVA> pari a zero

2.1.1.7.7 <Natura>

A check is carried out to ensure that it has been entered, of information element 2.1.1.7.5 <AliquotaIVA> is equal to "0.00", and that it has not been entered, if information element 2.1.1.7.5 <AliquotaIVA> is different from "0.00"

00415

2.1.1.5 <DatiRitenuta> non presente a fronte di 2.1.1.7.6 <Ritenuta> uguale a SI

2.1.1.7.6 <Ritenuta>

If it is set to "SI", a check is carried out to ensure that there is the block 2.1.1.5 <DatiRitenuta>

00417

1.4.1.1 <IdFiscaleIVA> e 1.4.1.2 <CodiceFiscale> non valorizzati (almeno uno dei due deve essere valorizzato)

1.4.1.1 <IdFiscaleIVA> and 1.4.1.2 <CodiceFiscale>

1.4.1.2 <CodiceFiscale>: If it is not entered, a check is carried out to ensure that block 1.4.1.1 <IdFiscaleIVA> is entered, if entered, a check is carried out that it exists in the Tax Register

00418

2.1.1.3 <Data> antecedente a 2.1.6.3 <Data>

2.1.1.3 <Data>

2.1.1.3 <Data> before 2.1.6.3 <Data>

00419

2.2.2 <DatiRiepilogo> non presente in corrispondenza di almeno un valore di 2.1.1.7.5 <AliquotaIVA> o 2.2.1.12 <AliquotaIVA>

2.2.2 <DatiRiepilogo>

A check is carried out to ensure that the number of blocks 2.2.2. <DatiRiepilogo> is more than or equal to the number of VAT rates in the document

00420

2.2.2.2 <Natura> con valore N6 (inversione contabile) a fronte di 2.2.2.7 <EsigibilitaIVA> uguale a S (scissione pagamenti)

2.2.2.2 <Natura> or 2.2.2.7 <EsigibilitaIVA>

If 2.2.2.2 <Natura> is entered as "N6", a check is carried out to ensure information element 2.2.2.7 <EsigibilitaIVA> is not entered as "S". A check is carried out to ensure that it has been entered, if information element 2.2.2.1 <AliquotaIVA> is equal to "0.00", and that it has not been entered, if information element 2.2.2.1 <AliquotaIVA> is different from "0.00".

00424

2.2.1.12 <AliquotaIVA> o 2.2.2.1< AliquotaIVA> o 2.1.1.7.5 <AliquotaIVA> non indicata in termini percentuali

2.2.3.2 <Aliquota> non indicata in termini percentuali

2.2.1.12 <AliquotaIVA> or 2.2.2.1< AliquotaIVA> or 2.1.1.7.5 <AliquotaIVA>

Check to ensure that the value is expressed as a percentage (e.g.: "22.00" and not "0.22")

00425

2.1.1.4 <Numero> non contenente caratteri numerici

2.1.1.4 <Numero>

Check to ensure it contains at least one number

00427

1.1.4 <CodiceDestinatario> di 7 caratteri a fronte di 1.1.3 <FormatoTrasmissione> con valore "FPA12" o 1.1.4 <CodiceDestinatario> di 6 caratteri a fronte di 1.1.3 <FormatoTrasmissione> con valore "FPR12"

1.1.4 <CodiceDestinatario>

<CodiceDestinatario> with 7 characters against 1.1.3 <FormatoTrasmissione> with the value "FPA12" or 1.1.4 <CodiceDestinatario> with 6 characters against 1.1.3 <FormatoTrasmissione> with the value "FPR12"

00428

1.1.3 <FormatoTrasmissione> con valore diverso da "FPA12" e "FPR12"

1.1.3 <FormatoTrasmissione>

A check is carried out to ensure consistency with information element 1.1.4 <CodiceDestinatario>: if "FPA12", information element 1.1.4 must be 6 characters; if "FPR12", information element 1.1.4 must be 7 characters.

00429

2.2.2.2 < Natura> non presente a fronte di 2.2.2.1 <AliquotaIVA> pari a zero

2.2.2.2 <Natura>

2.2.2.2 < Natura> not present against 2.2.2.1 <AliquotaIVA> equal to zero

00430

2.2.2.2 <Natura> presente a fronte di 2.2.2.1 <AliquotaIVA> diversa da zero

2.2.2.2 <Natura>

2.2.2.2 < Natura> not present against 2.2.2.1 <AliquotaIVA> equal to zero

00437

2.1.1.8.2 <Percentuale> e 2.1.1.8.3 <Importo> non presenti a fronte di 2.1.1.8.1 <Tipo> valorizzato

<ScontoMaggiorazione> 2.1.1.8

2.1.1.8.1 <Tipo>: If entered, a check is carried out to ensure that there is at least one of the two elements 2.1.1.8.2 <Percentuale> and 2.1.1.8.3 <Importo>

00438

2.2.1.10.2 <Percentuale> e 2.2.1.10.3 <Importo> non presenti a fronte di 2.2.1.10.1 <Tipo> valorizzato

<ScontoMaggiorazione> 2.2.1.10.1

If entered, a check is carried out to ensure that there is at least one of the two elements 2.2.1.10.2 <Percentuale> and 2.2.1.10.3 <Importo>

00443

Non c’è corrispondenza tra i valori indicati nell’elemento 2.2.1.12 <AliquotaIVA> o 2.1.1.7.5 <AliquotaIVA> e quelli dell’elemento 2.2.2.1 <AliquotaIVA>

2.1.1.7.5 <AliquotaIVA> o 2.2.1.12 <AliquotaIVA> e 2.2.2.1 <AliquotaIVA>

Check is performed to verify that the value provided in this item also appears in item 2.2.2.1 <AliquotaIVA> of one of the 2.2.2 <DatiRiepilogo> blocks listed in the invoice. Check is performed to verify that the value provided in this item also appears in item 2.2.1.12 <AliquotaIVA> of one of the 2.2.1 <DettaglioLinee> blocks listed in the invoice or in item 2.1.1.7.5 <AliquotaIVA> in one of the 2.1.1.7 <DatiCassaPrevidenziale> blocks listed in the invoice

00444

Non c’è corrispondenza tra i valori indicati nell’elemento 2.2.1.14 <Natura> o 2.1.1.7.7 <Natura> e quelli dell’elemento 2.2.2.2 <Natura>

2.1.1.7.7 <Natura> o 2.2.1.14 <Natura> e 2.2.2.2 <Natura>

Check is performed to verify that the value provided in this item also appears in item 2.2.2.2 <Natura> of one of the 2.2.2 <DatiRiepilogo> blocks listed in the invoice. Check is performed to verify that the value provided in this item also appears in item 2.2.1.14 <Natura> of one of the 2.2.1 <DettaglioLinee> blocks listed in the invoice or in item 2.1.1.7.7 <Natura> of one of the 2.1.1.7 <DatiCassaPrevidenziale> blocks listed in the invoice

00445

Non è più ammesso il valore generico N2, N3 o N6 come codice natura dell’operazione

Non è più ammesso il valore generico N2 o N3 come codice natura dell’operazione

2.1.1.7.7 <Natura> o 2.2.1.14 <Natura> o 2.2.2.2 <Natura> o 2.2.4 <Natura> (semplificata)

From 1 January 2021 a check will be performed to verify that the value provided in this item is different from N2, N3 and N6 (values no longer permitted)

00460

Importo totale superiore al limite previsto per le fatture semplificate ai sensi del DPR 633/72, art. 21 bis

2.2.2 <Importo>

The value in this field (or the sum of values in this field, in the case of there being more than one 2.2 <DatiBeniServizi> block) must not exceed the 400.00 euro limit. This limit may only be exceeded if the 2.1.2 <DatiFatturaRettificata> block is present

00471

Per il valore indicato nell’elemento 2.1.1.1 <TipoDocumento> il cedente/prestatore non può essere uguale al cessionario/committente

2.1.1.1 <TipoDocumento>

If the informative item 2.1.1.1 <TipoDocumento> equals to TD16, TD17, TD18, TD19 or TD20, a check will be performed to verify that the supplier/provider and the assignee/customer are different persons

00472

Per il valore indicato nell’elemento 2.1.1.1 <TipoDocumento> il cedente/prestatore deve essere uguale al cessionario/committente

2.1.1.1 <TipoDocumento>

If the informative item 2.1.1.1 <TipoDocumento> equals to TD21, a check will be performed to verify that the supplier/provider and the assignee/customer are the same person

00473

Per il valore indicato nell’elemento 2.1.1.1 <TipoDocumento> non è ammesso il valore IT nell’elemento 1.2.1.1.1 <IdPaese>

2.1.1.1 <TipoDocumento> e 1.2.1.1.1 <IdPaese>

If the informative item 2.1.1.1 <TipoDocumento> equals to TD17, TD18 or TD19, in addition to the aforementioned, field 1.2.1.1.1 <IdPaese> of the supplier/provider will also be checked to verify that it is not "IT"

00474

Per il valore indicato nell’elemento 2.1.1.1 <TipoDocumento> non sono ammesse linee di dettaglio con l’elemento 2.2.1.12 <AliquotaIVA> contenente valore zero

2.1.1.1 <TipoDocumento> e 2.2.1.12 <AliquotaIVA>

A check is performed to verify that no lines in the invoice contain a 2.2.1.12<AliquotaIVA> field with a zero value

8. Find Invoices Sent

Methods of finding sent invoices.

8.1. Invoice status

Below is the list of Invoice Statuses that can be achieved by employing the methods described in this and the following chapter.

Status Status Code SDI Notification Type Description

Presa in carico

1

The invoice is waiting to be processed by Aruba’s systems and has not yet been sent to the SDI.

Errore Elaborazione

2

An error has occurred when processing the invoice (technical problem sending to the SDI).

Inviata

3

The invoice has been sent to the Exchange System (SDI).

Scartata

4

NS

The invoice has been rejected by the Exchange System (SDI), which has returned a specific error code.

Non Consegnata

5

MC

Delivery of the invoice by the Exchange System (SDI) has failed. For PAs only, the system will attempt to deliver again in the next 10 days.

Recapito Impossibile

6

AT

Delivery of the invoice by the Exchange System (SDI) has not been successful. No further attempts will be made to deliver it.

Consegnata

7

RC

The invoice has been delivered by the Exchange System (SDI).

Accettata

8

NE (EC01)

The client has accepted the invoice delivered by the Exchange System (SDI).

Rifiutata

9

NE (EC02)

The client has rejected the invoice delivered by the Exchange System (SDI).

Decorrenza Termini

10

DT

The invoice has been delivered by the Exchange System (SDI) but the client has not responded within 15 days of delivery.

8.2. findByUsername

GET base url other methods/services/invoice/out/findByUsername

This method returns the list of electronic invoices sent by the user and processed by the system. The list of Invoices is returned without the content in base64 (lazy loading).

HTTP request

GET /services/invoice/out/findByUsername?username=Username HTTP/1.1
Accept: application/json
Authorization: Bearer NLOGDVXLVaF3tzmnVPkTwpkuh7dG0i09uSCcog3u+rE=

Request headers

Name Description

Authorization

Authorization Access token obtained by signin

Request parameters

Parameter Description Constraints

username

username of the owner of the invoice sent/received

Mandatory, the username must match the one with which the security token was requested

page

page requested (default 1)

Between 1 and totalPages

size

page size (default 10)

Between 1 and 100

startDate

invoice creation date (from)

In ISO 8601 format

endDate

invoice creation date (to)

In ISO 8601 format

countrySender

Country Code of the assignor/provider

Mandatory if the user username is a Premium user

vatcodeSender

VAT number of the assignor/provider

Mandatory if the user username is a Premium user

fiscalcodeSender

Tax code of the assignor/provider

countryReceiver

Country Code of the assignee/customer

vatcodeReceiver

VAT number of the assignee/customer

fiscalcodeReceiver

Tax code of the assignee/customer

HTTP response

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

{
  "errorCode" : "0000",
  "errorDescription" : null,
  "content" : [ {
    "errorCode" : null,
    "errorDescription" : null,
    "id" : "1",
    "sender" : {
      "description" : "Aruba SPA",
      "countryCode" : "IT",
      "vatCode" : "6372762541",
      "fiscalCode" : "N5Hnt9vvMZ"
    },
    "receiver" : {
      "description" : "Rossi SRL",
      "countryCode" : "IT",
      "vatCode" : "8767263441",
      "fiscalCode" : "LVZTeOJ8BN"
    },
    "invoiceType" : "FPR12",
    "docType" : "out",
    "file" : null,
    "filename" : "IT01879020517_jtlk1.xml.p7m",
    "invoices" : [ {
      "invoiceDate" : "2020-11-12T17:39:58.899+01:00",
      "number" : "1",
      "status" : "Inviata",
      "statusDescription" : ""
    } ],
    "username" : "Utente",
    "lastUpdate" : "2020-11-12T16:39:58.899+0000",
    "creationDate" : "2020-11-12T16:39:58.899+0000",
    "idSdi" : "7895",
    "pddAvailable" : true
  }, {
    "errorCode" : null,
    "errorDescription" : null,
    "id" : "2",
    "sender" : {
      "description" : "Aruba SPA",
      "countryCode" : "gXV",
      "vatCode" : "7653434968",
      "fiscalCode" : "AHGKAqlz9V"
    },
    "receiver" : {
      "description" : "Rossi SRL",
      "countryCode" : "IT",
      "vatCode" : "5124351625",
      "fiscalCode" : "WCJBASC6SS"
    },
    "invoiceType" : "FPR12",
    "docType" : "out",
    "file" : null,
    "filename" : "IT01879020517_zwwuz.xml.p7m",
    "invoices" : [ {
      "invoiceDate" : "2020-11-12T17:39:58.899+01:00",
      "number" : "1",
      "status" : "Inviata",
      "statusDescription" : ""
    } ],
    "username" : "Utente",
    "lastUpdate" : "2020-11-12T16:39:58.899+0000",
    "creationDate" : "2020-11-12T16:39:58.899+0000",
    "idSdi" : "7895",
    "pddAvailable" : true
  }, {
    "errorCode" : null,
    "errorDescription" : null,
    "id" : "3",
    "sender" : {
      "description" : "Aruba SPA",
      "countryCode" : "IT",
      "vatCode" : "30008582713",
      "fiscalCode" : "48337789423"
    },
    "receiver" : {
      "description" : "Rossi SRL",
      "countryCode" : "IT",
      "vatCode" : "77952179325",
      "fiscalCode" : "19516379527"
    },
    "invoiceType" : "FPR12",
    "docType" : "out",
    "file" : null,
    "filename" : "IT01842873366_xnvyg.xml.p7m",
    "invoices" : [ {
      "invoiceDate" : "2020-11-12T17:39:58.899+01:00",
      "number" : "1",
      "status" : "Inviata",
      "statusDescription" : ""
    } ],
    "username" : "Utente",
    "lastUpdate" : "2020-11-12T16:39:58.899+0000",
    "creationDate" : "2020-11-12T16:39:58.899+0000",
    "idSdi" : "7895",
    "pddAvailable" : true
  }, {
    "errorCode" : null,
    "errorDescription" : null,
    "id" : "4",
    "sender" : {
      "description" : "Aruba SPA",
      "countryCode" : "IT",
      "vatCode" : "60761466888",
      "fiscalCode" : "97723051674"
    },
    "receiver" : {
      "description" : "Rossi SRL",
      "countryCode" : "IT",
      "vatCode" : "28767308133",
      "fiscalCode" : "02303509412"
    },
    "invoiceType" : "FPR12",
    "docType" : "out",
    "file" : null,
    "filename" : "IT01089392967_jwnmq.xml.p7m",
    "invoices" : [ {
      "invoiceDate" : "2020-11-12T17:39:58.899+01:00",
      "number" : "1",
      "status" : "Inviata",
      "statusDescription" : ""
    } ],
    "username" : "Utente",
    "lastUpdate" : "2020-11-12T16:39:58.899+0000",
    "creationDate" : "2020-11-12T16:39:58.899+0000",
    "idSdi" : "7895",
    "pddAvailable" : true
  } ],
  "last" : true,
  "totalElements" : 4,
  "totalPages" : 1,
  "size" : 10,
  "number" : 1,
  "first" : true,
  "numberOfElements" : 4
}

Response fields

Field Type Description

errorCode

String

Error code

errorDescription

String

Error description, if any

content

Array

Array of invoices found

last

Boolean

true if the page found is the last, otherwise false

totalElements

Number

Total number of invoices found

totalPages

Number

Total number of pages

size

Number

Page size

number

Number

Current page number

first

Boolean

true if the page found is the first, otherwise false

numberOfElements

Number

Number of elements returned

content[].errorCode

String

Error code

content[].errorDescription

String

Error description, if any

content[].id

String

Invoice ID

content[].sender

Company

Company sender

content[].receiver

Company

Company receiver

content[].invoiceType

String

Transmission format (e.g. 'FPA12' or 'FPR12', etc.)

content[].docType

String

out for sent invoice, in for received invoice

content[].file

String

File in Base64 format

content[].filename

String

Filename (es. IT01879020517_abcde.xml.p7m)

content[].invoices

Array

Array of individual invoices in the batch

content[].username

String

Username of the owner of the invoice

content[].lastUpdate

String

Date of last update

content[].creationDate

String

Creation date, i.e. the date on which the invoice was received by Aruba Electronic Billing

content[].idSdi

String

SDI (Exchange System) ID

content[].pddAvailable

Boolean

true if the invoice and associated notifications have been saved (see pdd for downloading the preservation package), otherwise _false _

content[].sender.description

String

Name of transferor provider

content[].sender.countryCode

String

Country code of transferor provider (e.g.) 'IT', 'DE' etc.)

content[].sender.vatCode

String

VAT number transferor provider

content[].sender.fiscalCode

String

Tax code transferor provider

content[].receiver.description

String

Name of transferee client

content[].receiver.countryCode

String

Country code of transferee client (e.g. 'IT', 'DE' etc.)

content[].receiver.vatCode

String

VAT number of transferee client

content[].receiver.fiscalCode

String

Tax code of transferee client

content[].invoices.[].invoiceDate

String

Invoice date

content[].invoices.[].number

String

Invoice number

content[].invoices.[].status

String

Invoice status

content[].invoices.[].statusDescription

String

Contains one of the messages in Asynchronous Checks if status is Errore Elaborazione, otherwise null

8.3. getByFilename

GET base url other methods/services/invoice/out/getByFilename This method returns the full details of the status of an electronic invoice. Finds an individual invoice by filename (es. IT01879020517_abcde.xml.p7m).

HTTP request

GET /services/invoice/out/getByFilename?filename=IT01879020517_jtlk1.xml.p7m&includePdf=true HTTP/1.1
Accept: application/json
Authorization: Bearer NLOGDVXLVaF3tzmnVPkTwpkuh7dG0i09uSCcog3u+rE=

Request headers

Name Description

Authorization

Authorization Access token obtained by signin

Request parameters

Parameter Description Constraints

filename

File name

Mandatory

includePdf

If value is true, pdfFile field is included in the response

Not required. Default value is false

includeFile

If value is false, file field is not included in the response

Not required. Default value is true

HTTP response

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

{
  "errorCode" : null,
  "errorDescription" : null,
  "id" : "1",
  "sender" : {
    "description" : "Aruba SPA",
    "countryCode" : "IT",
    "vatCode" : "6372762541",
    "fiscalCode" : "N5Hnt9vvMZ"
  },
  "receiver" : {
    "description" : "Rossi SRL",
    "countryCode" : "IT",
    "vatCode" : "8767263441",
    "fiscalCode" : "LVZTeOJ8BN"
  },
  "invoiceType" : "FPR12",
  "docType" : "out",
  "file" : "ZEdWemRBPT0=",
  "filename" : "IT01879020517_jtlk1.xml.p7m",
  "invoices" : [ {
    "invoiceDate" : "2020-11-12T17:39:58.993+01:00",
    "number" : "1",
    "status" : "Inviata",
    "statusDescription" : ""
  } ],
  "username" : "Utente",
  "lastUpdate" : "2020-11-12T16:39:58.993+0000",
  "creationDate" : "2020-11-12T16:39:58.993+0000",
  "idSdi" : "9995",
  "pdfFile" : "ZEdWemRGQmtaZz09",
  "pddAvailable" : true
}

Response fields

Field Type Description

errorCode

String

Error code

errorDescription

String

Error description, if any

id

String

Invoice ID

sender

Company

Company sender

receiver

Company

Company receiver

invoiceType

String

Transmission format (e.g. 'FPA12' or 'FPR12', etc.)

docType

String

out for sent invoice, in for received invoice

file

String

File in Base64 format

filename

String

Filename (es. IT01879020517_abcde.xml.p7m)

invoices

Array

Array of individual invoices in the batch

username

String

Username of the owner of the invoice

lastUpdate

String

Date of last update

creationDate

String

Creation date, i.e. the date on which the invoice was received by Aruba Electronic Billing

idSdi

String

SDI (Exchange System) ID

pddAvailable

Boolean

true if the invoice and associated notifications have been saved (see pdd for downloading the preservation package), otherwise _false _

pdfFile

String

Pdf file in Base64 format. pdfFile found if the request parameter includePdf is set to true

sender.description

String

Name of transferor provider

sender.countryCode

String

Country code of transferor provider (e.g.) 'IT', 'DE' etc.)

sender.vatCode

String

VAT number transferor provider

sender.fiscalCode

String

Tax code transferor provider

receiver.description

String

Name of transferee client

receiver.countryCode

String

Country code of transferee client (e.g. 'IT', 'DE' etc.)

receiver.vatCode

String

VAT number of transferee client

receiver.fiscalCode

String

Tax code of transferee client

invoices.[].invoiceDate

String

Invoice date

invoices.[].number

String

Invoice number

invoices.[].status

String

Invoice status

invoices.[].statusDescription

String

Contains one of the messages in Asynchronous Checks if status is Errore Elaborazione, otherwise null

8.4. getZipByFilename

GET base url other methods/services/invoice/out/getZipByFilename

Returns an invoice with all of its notifications in Zip format (e.g. IT01879020517_abcde.xml.p7m).

HTTP request

GET /services/invoice/out/getZipByFilename?filename=IT01879020517_jtlk1.xml.p7m HTTP/1.1
Authorization: Bearer NLOGDVXLVaF3tzmnVPkTwpkuh7dG0i09uSCcog3u+rE=

Request headers

Name Description

Authorization

Authorization Access token obtained by signin

Request parameters

Parameter Description Constraints

filename

File name

Mandatory

HTTP response

HTTP/1.1 200 OK
Content-Disposition: attachment; filename="IT01879020517_jtlk1.xml.p7m.zip"
Content-Type: application/zip
Accept-Ranges: bytes
Content-Length: 8

<binary>

8.5. getByInvoiceId

GET base url other methods/services/invoice/out/{invoiceId}

Find an individual invoice by ID.

HTTP request

GET /services/invoice/out/1 HTTP/1.1
Accept: application/json
Authorization: Bearer NLOGDVXLVaF3tzmnVPkTwpkuh7dG0i09uSCcog3u+rE=

Request headers

Name Description

Authorization

Authorization Access token obtained by signin

Path parameters

Parameter Description

invoiceId

Invoice Id

Request parameters

Parameter Description Constraints

includePdf

If value is true, pdfFile field is included in the response

Not required. Default value is false

includeFile

If value is false, file field is not included in the response

Not required. Default value is true

HTTP response

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

{
  "errorCode" : "0000",
  "errorDescription" : null,
  "id" : "1",
  "sender" : {
    "description" : "Aruba SPA",
    "countryCode" : "IT",
    "vatCode" : "6372762541",
    "fiscalCode" : "N5Hnt9vvMZ"
  },
  "receiver" : {
    "description" : "Aruba SPA",
    "countryCode" : "IT",
    "vatCode" : "8767263441",
    "fiscalCode" : "LVZTeOJ8BN"
  },
  "invoiceType" : "FPR12",
  "docType" : "out",
  "file" : "ZEdWemRBPT0=",
  "filename" : "IT01879020517_jtlk1.xml.p7m",
  "invoices" : [ {
    "invoiceDate" : "2020-11-12T17:39:59.024+01:00",
    "number" : "1",
    "status" : "Inviata",
    "statusDescription" : null
  } ],
  "username" : "Utente",
  "lastUpdate" : "2020-11-12T16:39:59.024+0000",
  "creationDate" : "2020-11-12T16:39:59.024+0000",
  "idSdi" : "9998l",
  "pddAvailable" : true
}

Response fields

Field Type Description

errorCode

String

Error code

errorDescription

String

Error description, if any

id

String

Invoice ID

sender

Company

Company sender

receiver

Company

Company receiver

invoiceType

String

Transmission format (e.g. 'FPA12' or 'FPR12', etc.)

docType

String

out for sent invoice, in for received invoice

file

String

File in Base64 format

filename

String

Filename (es. IT01879020517_abcde.xml.p7m)

invoices

Array

Array of individual invoices in the batch

username

String

Username of the owner of the invoice

lastUpdate

String

Date of last update

creationDate

String

Creation date, i.e. the date on which the invoice was received by Aruba Electronic Billing

idSdi

String

SDI (Exchange System) ID

pddAvailable

Boolean

true if the invoice and associated notifications have been saved (see pdd for downloading the preservation package), otherwise _false _

pdfFile

String

Pdf file in Base64 format. pdfFile found if the request parameter includePdf is set to true

sender.description

String

Name of transferor provider

sender.countryCode

String

Country code of transferor provider (e.g.) 'IT', 'DE' etc.)

sender.vatCode

String

VAT number transferor provider

sender.fiscalCode

String

Tax code transferor provider

receiver.description

String

Name of transferee client

receiver.countryCode

String

Country code of transferee client (e.g. 'IT', 'DE' etc.)

receiver.vatCode

String

VAT number of transferee client

receiver.fiscalCode

String

Tax code of transferee client

invoices.[].invoiceDate

String

Invoice date

invoices.[].number

String

Invoice number

invoices.[].status

String

Invoice status

invoices.[].statusDescription

String

Contains one of the messages in Asynchronous Checks if status is Errore Elaborazione, otherwise null

8.6. pdd

GET base url other methods/services/invoice/out/pdd

If pddAvailable is true then this method retrieves the Preservation package as a Zip file of a sent invoice, specifying its file name (invoiceFilename) or ID (invoiceId). If however pddAvailable is false, in other words, the Preservation package is not available, the HTTP status code 404 is returned.

HTTP request

GET /services/invoice/out/pdd?invoiceFilename=IT01879020517_jtlk1.xml.p7m HTTP/1.1
Authorization: Bearer NLOGDVXLVaF3tzmnVPkTwpkuh7dG0i09uSCcog3u+rE=

Request headers

Name Description

Authorization

Authorization Access token obtained by signin

Request parameters

Parameter Description Constraints

invoiceFilename

Invoice file name

Mandatory if invoiceId is not specified

invoiceId

Invoice Id

Mandatory if invoiceFilename is not specified

HTTP response

HTTP/1.1 200 OK
Content-Disposition: attachment; filename="IT01879020517_jtlk1.conservazione.zip"
Content-Type: application/zip
Accept-Ranges: bytes
Content-Length: 8

<binary>

9. Find Invoices Received

searching received invoice

Methods of finding received invoices.

9.1. findByUsername

GET base url other methods/services/invoice/in/findByUsername

Finds a list of invoices. Returns invoices without content in base64 (lazy loading)

HTTP request

GET /services/invoice/in/findByUsername?username=Username HTTP/1.1
Accept: application/json
Authorization: Bearer NLOGDVXLVaF3tzmnVPkTwpkuh7dG0i09uSCcog3u+rE=

Request headers

Name Description

Authorization

Authorization Access token obtained by signin

Request parameters

Parameter Description Constraints

username

username of the owner of the invoice sent/received

Mandatory, the username must match the one with which the security token was requested

page

page requested (default 1)

Between 1 and totalPages

size

Page size (default 10)

Between 1 and 100

startDate

invoice creation date (from)

In ISO 8601 format

endDate

invoice creation date (to)

In ISO 8601 format

countrySender

Country Code of the assignor/provider

vatcodeSender

VAT number of the assignor/provider

fiscalcodeSender

Tax code of the assignor/provider

countryReceiver

Country Code of the assignee/customer

Mandatory if the user username is a Premium user

vatcodeReceiver

VAT number of the assignee/customer

Mandatory if the user username is a Premium user

fiscalcodeReceiver

Tax code of the assignee/customer

HTTP response

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

{
  "errorCode" : "0000",
  "errorDescription" : null,
  "content" : [ {
    "errorCode" : null,
    "errorDescription" : null,
    "id" : "1",
    "sender" : {
      "description" : "Aruba SPA",
      "countryCode" : "IT",
      "vatCode" : "22222222",
      "fiscalCode" : "11111111111"
    },
    "receiver" : {
      "description" : "Aruba SPA",
      "countryCode" : "IT",
      "vatCode" : "4444444",
      "fiscalCode" : "333333333"
    },
    "invoiceType" : "FPR12",
    "docType" : "in",
    "file" : null,
    "filename" : "IT01879020517_jtlk0.xml.p7m",
    "invoices" : [ {
      "invoiceDate" : "2020-11-12T17:39:54.134+01:00",
      "number" : "2020/0001",
      "status" : "Inviata",
      "statusDescription" : ""
    } ],
    "username" : "Utente",
    "lastUpdate" : "2020-11-12T16:39:54.134+0000",
    "creationDate" : "2020-11-12T16:39:54.134+0000",
    "idSdi" : "11110",
    "pddAvailable" : true
  }, {
    "errorCode" : null,
    "errorDescription" : null,
    "id" : "2",
    "sender" : {
      "description" : "Aruba SPA",
      "countryCode" : "IT",
      "vatCode" : "22222222",
      "fiscalCode" : "11111111111"
    },
    "receiver" : {
      "description" : "Aruba SPA",
      "countryCode" : "IT",
      "vatCode" : "4444444",
      "fiscalCode" : "333333333"
    },
    "invoiceType" : "FPR12",
    "docType" : "in",
    "file" : null,
    "filename" : "IT01879020517_jtlk1.xml.p7m",
    "invoices" : [ {
      "invoiceDate" : "2020-11-12T17:39:54.134+01:00",
      "number" : "2020/0002",
      "status" : "Inviata",
      "statusDescription" : ""
    } ],
    "username" : "Utente",
    "lastUpdate" : "2020-11-12T16:39:54.134+0000",
    "creationDate" : "2020-11-12T16:39:54.134+0000",
    "idSdi" : "11111",
    "pddAvailable" : true
  }, {
    "errorCode" : null,
    "errorDescription" : null,
    "id" : "3",
    "sender" : {
      "description" : "Aruba SPA",
      "countryCode" : "IT",
      "vatCode" : "22222222",
      "fiscalCode" : "11111111111"
    },
    "receiver" : {
      "description" : "Aruba SPA",
      "countryCode" : "IT",
      "vatCode" : "4444444",
      "fiscalCode" : "333333333"
    },
    "invoiceType" : "FPR12",
    "docType" : "in",
    "file" : null,
    "filename" : "IT01879020517_jtlk2.xml.p7m",
    "invoices" : [ {
      "invoiceDate" : "2020-11-12T17:39:54.134+01:00",
      "number" : "2020/0003",
      "status" : "Inviata",
      "statusDescription" : ""
    } ],
    "username" : "Utente",
    "lastUpdate" : "2020-11-12T16:39:54.134+0000",
    "creationDate" : "2020-11-12T16:39:54.134+0000",
    "idSdi" : "11112",
    "pddAvailable" : true
  }, {
    "errorCode" : null,
    "errorDescription" : null,
    "id" : "4",
    "sender" : {
      "description" : "Aruba SPA",
      "countryCode" : "IT",
      "vatCode" : "22222222",
      "fiscalCode" : "11111111111"
    },
    "receiver" : {
      "description" : "Aruba SPA",
      "countryCode" : "IT",
      "vatCode" : "4444444",
      "fiscalCode" : "333333333"
    },
    "invoiceType" : "FPR12",
    "docType" : "in",
    "file" : null,
    "filename" : "IT01879020517_jtlk3.xml.p7m",
    "invoices" : [ {
      "invoiceDate" : "2020-11-12T17:39:54.134+01:00",
      "number" : "2020/0004",
      "status" : "Inviata",
      "statusDescription" : ""
    } ],
    "username" : "Utente",
    "lastUpdate" : "2020-11-12T16:39:54.134+0000",
    "creationDate" : "2020-11-12T16:39:54.134+0000",
    "idSdi" : "11113",
    "pddAvailable" : true
  } ],
  "last" : true,
  "totalElements" : 4,
  "totalPages" : 1,
  "size" : 10,
  "number" : 1,
  "first" : true,
  "numberOfElements" : 4
}

Response fields

Field Type Description

errorCode

String

Error code

errorDescription

String

Error description, if any

content

Array

Array of invoices found

last

Boolean

true if the page found is the last, otherwise false

totalElements

Number

Total number of invoices found

totalPages

Number

Total number of pages

size

Number

Page size

number

Number

Current page number

first

Boolean

true if the page found is the first, otherwise false

numberOfElements

Number

Number of elements returned

content[].errorCode

String

Error code

content[].errorDescription

String

Error description, if any

content[].id

String

Invoice ID

content[].sender

Company

Company sender

content[].receiver

Company

Company receiver

content[].invoiceType

String

Transmission format (e.g. 'FPA12' or 'FPR12', etc.)

content[].docType

String

out for sent invoice, in for received invoice

content[].file

String

File in Base64 format

content[].filename

String

Filename (es. IT01879020517_abcde.xml.p7m)

content[].invoices

Array

Array of individual invoices in the batch

content[].username

String

Username of the owner of the invoice

content[].lastUpdate

String

Date of last update

content[].creationDate

String

Creation date, i.e. the date on which the invoice was received by Aruba Electronic Billing

content[].idSdi

String

SDI (Exchange System) ID

content[].pddAvailable

Boolean

true if the invoice and associated notifications have been saved (see pdd for downloading the preservation package), otherwise false

content[].sender.description

String

Name of transferor provider

content[].sender.countryCode

String

Country code of transferor provider (e.g.) 'IT', 'DE' etc.)

content[].sender.vatCode

String

VAT number transferor provider

content[].sender.fiscalCode

String

Tax code transferor provider

content[].receiver.description

String

Name of transferee client

content[].receiver.countryCode

String

Country code of transferee client (e.g. 'IT', 'DE' etc.)

content[].receiver.vatCode

String

VAT number of transferee client

content[].receiver.fiscalCode

String

Tax code of transferee client

content[].invoices.[].invoiceDate

String

Invoice date

content[].invoices.[].number

String

Invoice number

content[].invoices.[].status

String

Invoice status

content[].invoices.[].statusDescription

String

Contains one of the messages in Asynchronous Checks if status is Errore Elaborazione, otherwise null

9.2. getByFilename

GET base url other methods/services/invoice/in/getByFilename

Finds for an individual invoice by filename (e.g. IT01879020517_abcde.xml.p7m).

HTTP request

GET /services/invoice/in/getByFilename?filename=IT01879020517_jtlk1.xml.p7m&includePdf=true HTTP/1.1
Accept: application/json
Authorization: Bearer NLOGDVXLVaF3tzmnVPkTwpkuh7dG0i09uSCcog3u+rE=

Request headers

Name Description

Authorization

Authorization Access token obtained by signin

Request parameters

Parameter Description Constraints

filename

File name

Mandatory

includePdf

If value is true, pdfFile field is included in the response

Not required. Default value is false

includeFile

If value is false, file field is not included in the response

Not required. Default value is true

HTTP response

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

{
  "errorCode" : null,
  "errorDescription" : null,
  "id" : "2",
  "sender" : {
    "description" : "Aruba SPA",
    "countryCode" : "IT",
    "vatCode" : "22222222",
    "fiscalCode" : "11111111111"
  },
  "receiver" : {
    "description" : "Aruba SPA",
    "countryCode" : "IT",
    "vatCode" : "4444444",
    "fiscalCode" : "333333333"
  },
  "invoiceType" : "FPR12",
  "docType" : "in",
  "file" : "dGVzdA==",
  "filename" : "IT01879020517_jtlk1.xml.p7m",
  "invoices" : [ {
    "invoiceDate" : "2020-11-12T17:39:54.134+01:00",
    "number" : "2020/0002",
    "status" : "Inviata",
    "statusDescription" : ""
  } ],
  "username" : "Utente",
  "lastUpdate" : "2020-11-12T16:39:54.134+0000",
  "creationDate" : "2020-11-12T16:39:54.134+0000",
  "idSdi" : "11111",
  "pdfFile" : "ZEdWemRGQmtaZz09",
  "pddAvailable" : true
}

Response fields

Field Type Description

errorCode

String

Error code

errorDescription

String

Error description, if any

id

String

Invoice ID

sender

Company

Company sender

receiver

Company

Company receiver

invoiceType

String

Transmission format (e.g. 'FPA12' or 'FPR12', etc.)

docType

String

out for sent invoice, in for received invoice

file

String

File in Base64 format

filename

String

Filename (es. IT01879020517_abcde.xml.p7m)

invoices

Array

Array of individual invoices in the batch

username

String

Username of the owner of the invoice

lastUpdate

String

Date of last update

creationDate

String

Creation date, i.e. the date on which the invoice was received by Aruba Electronic Billing

idSdi

String

SDI (Exchange System) ID

pddAvailable

Boolean

true if the invoice and associated notifications have been saved (see pdd for downloading the preservation package), otherwise false

pdfFile

String

Pdf file in Base64 format. pdfFile found if the request parameter includePdf is set to true

sender.description

String

Name of transferor provider

sender.countryCode

String

Country code of transferor provider (e.g.) 'IT', 'DE' etc.)

sender.vatCode

String

VAT number transferor provider

sender.fiscalCode

String

Tax code transferor provider

receiver.description

String

Name of transferee client

receiver.countryCode

String

Country code of transferee client (e.g. 'IT', 'DE' etc.)

receiver.vatCode

String

VAT number of transferee client

receiver.fiscalCode

String

Tax code of transferee client

invoices.[].invoiceDate

String

Invoice date

invoices.[].number

String

Invoice number

invoices.[].status

String

Invoice status

invoices.[].statusDescription

String

Contains one of the messages in Asynchronous Checks if status is Errore Elaborazione, otherwise null

9.3. getZipByFilename

GET base url other methods/services/invoice/in/getZipByFilename

Returns an invoice with all of its notifications in Zip format (e.g. IT01879020517_abcde.xml.p7m).

HTTP request

GET /services/invoice/in/getZipByFilename?filename=IT01879020517_jtlk1.xml.p7m HTTP/1.1
Accept: application/json
Authorization: Bearer NLOGDVXLVaF3tzmnVPkTwpkuh7dG0i09uSCcog3u+rE=

Request headers

Name Description

Authorization

Authorization Access token obtained by signin

Request parameters

Parameter Description Constraints

filename

File name

Mandatory

HTTP response

HTTP/1.1 200 OK
Content-Disposition: attachment; filename="IT01879020517_jtlk1.xml.p7m.zip"
Content-Type: application/zip
Accept-Ranges: bytes
Content-Length: 8

<binary>

9.4. getByInvoiceId

GET base url other methods/services/invoice/in/{invoiceId}

Find an individual invoice by ID.

HTTP request

GET /services/invoice/in/1 HTTP/1.1
Accept: application/json
Authorization: Bearer NLOGDVXLVaF3tzmnVPkTwpkuh7dG0i09uSCcog3u+rE=

Request headers

Name Description

Authorization

Authorization Access token obtained by signin

Path parameters

Parameter Description

invoiceId

Invoice Id

Request parameters

Parameter Description Constraints

includePdf

If value is true, pdfFile field is included in the response

Not required. Default value is false

includeFile

If value is false, file field is not included in the response

Not required. Default value is true

HTTP response

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

{
  "errorCode" : "0000",
  "errorDescription" : null,
  "id" : "1",
  "sender" : {
    "description" : "Aruba SPA",
    "countryCode" : "IT",
    "vatCode" : "22222222",
    "fiscalCode" : "11111111111"
  },
  "receiver" : {
    "description" : "Aruba SPA",
    "countryCode" : "IT",
    "vatCode" : "4444444",
    "fiscalCode" : "333333333"
  },
  "invoiceType" : "FPR12",
  "docType" : "in",
  "file" : "ZEdWemRBPT0=",
  "filename" : "IT01879020517_jtlk0.xml.p7m",
  "invoices" : [ {
    "invoiceDate" : "2020-11-12T17:39:54.134+01:00",
    "number" : "2020/0001",
    "status" : "Inviata",
    "statusDescription" : ""
  } ],
  "username" : "Utente",
  "lastUpdate" : "2020-11-12T16:39:54.134+0000",
  "creationDate" : "2020-11-12T16:39:54.134+0000",
  "idSdi" : "11110",
  "pddAvailable" : true
}

Response fields

Field Type Description

errorCode

String

Error code

errorDescription

String

Error description, if any

id

String

Invoice ID

sender

Company

Company sender

receiver

Company

Company receiver

invoiceType

String

Transmission format (e.g. 'FPA12' or 'FPR12', etc.)

docType

String

out for sent invoice, in for received invoice

file

String

File in Base64 format

filename

String

Filename (es. IT01879020517_abcde.xml.p7m)

invoices

Array

Array of individual invoices in the batch

username

String

Username of the owner of the invoice

lastUpdate

String

Date of last update

creationDate

String

Creation date, i.e. the date on which the invoice was received by Aruba Electronic Billing

idSdi

String

SDI (Exchange System) ID

pddAvailable

Boolean

true if the invoice and associated notifications have been saved (see pdd for downloading the preservation package), otherwise false

pdfFile

String

Pdf file in Base64 format. pdfFile found if the request parameter includePdf is set to true

sender.description

String

Name of transferor provider

sender.countryCode

String

Country code of transferor provider (e.g.) 'IT', 'DE' etc.)

sender.vatCode

String

VAT number transferor provider

sender.fiscalCode

String

Tax code transferor provider

receiver.description

String

Name of transferee client

receiver.countryCode

String

Country code of transferee client (e.g. 'IT', 'DE' etc.)

receiver.vatCode

String

VAT number of transferee client

receiver.fiscalCode

String

Tax code of transferee client

invoices.[].invoiceDate

String

Invoice date

invoices.[].number

String

Invoice number

invoices.[].status

String

Invoice status

invoices.[].statusDescription

String

Contains one of the messages in Asynchronous Checks if status is Errore Elaborazione, otherwise null

9.5. getInvoiceWithUnsignedFile

GET base url other methods/services/invoice/in/getInvoiceWithUnsignedFile

This operation allows you to retrieve a single invoice by id or by filename, returning the file content without digital signature. If the invoice is signed, it returns signed equals true and the invoice file without digital signature is returned in the unsignedFile field. If the invoice is unsigned, signed is returned equal to false and the original invoice file is returned in the unsignedFile field. If the value in the optional parameter includeFile equals true, the original invoice file is returned in the file field of the reply. By default, the parameter includeFile equals false, therefore by default file is returned as null.

HTTP request

GET /services/invoice/in/getInvoiceWithUnsignedFile?filename=IT01879020517_jtlk1.xml.p7m HTTP/1.1
Accept: application/json
Authorization: Bearer NLOGDVXLVaF3tzmnVPkTwpkuh7dG0i09uSCcog3u+rE=

Request headers

Name Description

Authorization

Authorization Access token obtained by signin

Request parameters

Parameter Description Constraints

invoiceId

Invoice Id

Mandatory if filename is not specified

filename

nvoice file name

Mandatory if invoiceId is not specified

includeFile

If the value is true the original invoice file is returned in the file field.

Not required, false by default.

HTTP response

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

{
  "errorCode" : null,
  "errorDescription" : null,
  "id" : "2",
  "sender" : {
    "description" : "Aruba SPA",
    "countryCode" : "IT",
    "vatCode" : "22222222",
    "fiscalCode" : "11111111111"
  },
  "receiver" : {
    "description" : "Aruba SPA",
    "countryCode" : "IT",
    "vatCode" : "4444444",
    "fiscalCode" : "333333333"
  },
  "invoiceType" : "FPR12",
  "docType" : "in",
  "file" : null,
  "filename" : "IT01879020517_jtlk1.xml.p7m",
  "invoices" : [ {
    "invoiceDate" : "2020-11-12T17:39:54.134+01:00",
    "number" : "2020/0002",
    "status" : "Inviata",
    "statusDescription" : ""
  } ],
  "username" : "Utente",
  "lastUpdate" : "2020-11-12T16:39:54.134+0000",
  "creationDate" : "2020-11-12T16:39:54.134+0000",
  "idSdi" : "11111",
  "pddAvailable" : true,
  "unsignedFile" : "ZFc1emFXZHVaV1FnWm1sc1pRPT0=",
  "signed" : true
}

Response fields

Field Type Description

errorCode

String

Error code

errorDescription

String

Error description, if any

id

String

Invoice ID

sender

Company

Company sender

receiver

Company

Company receiver

invoiceType

String

Transmission format (e.g. 'FPA12' or 'FPR12', etc.)

docType

String

out for sent invoice, in for received invoice

file

String

File in Base64 format

filename

String

Filename (es. IT01879020517_abcde.xml.p7m)

invoices

Array

Array of individual invoices in the batch

username

String

Username of the owner of the invoice

lastUpdate

String

Date of last update

creationDate

String

Creation date, i.e. the date on which the invoice was received by Aruba Electronic Billing

idSdi

String

SDI (Exchange System) ID

pddAvailable

Boolean

true if the invoice and associated notifications have been saved (see pdd for downloading the preservation package), otherwise false

unsignedFile

String

Content of unsigned file in Base64 format

signed

Boolean

true if the invoice file is digitally signed, otherwise false

sender.description

String

Name of transferor provider

sender.countryCode

String

Country code of transferor provider (e.g.) 'IT', 'DE' etc.)

sender.vatCode

String

VAT number transferor provider

sender.fiscalCode

String

Tax code transferor provider

receiver.description

String

Name of transferee client

receiver.countryCode

String

Country code of transferee client (e.g. 'IT', 'DE' etc.)

receiver.vatCode

String

VAT number of transferee client

receiver.fiscalCode

String

Tax code of transferee client

invoices.[].invoiceDate

String

Invoice date

invoices.[].number

String

Invoice number

invoices.[].status

String

Invoice status

invoices.[].statusDescription

String

Contains one of the messages in Asynchronous Checks if status is Errore Elaborazione, otherwise null

9.6. pdd

GET base url other methods/services/invoice/in/pdd

If pddAvailable is true then this method retrieves the Preservation package as a Zip file of a received invoice, specifying its file name (invoiceFilename) or ID(invoiceId). If however pddAvailable is false, in other words, the Preservation package is not available, the HTTP status code 404 is returned.

HTTP request

GET /services/invoice/out/pdd?invoiceFilename=IT01879020517_jtlk1.xml.p7m HTTP/1.1
Authorization: Bearer NLOGDVXLVaF3tzmnVPkTwpkuh7dG0i09uSCcog3u+rE=

Request headers

Name Description

Authorization

Authorization Access token obtained by signin

Request parameters

Parameter Description Constraints

invoiceFilename

Invoice file name

Mandatory if invoiceId is not specified

invoiceId

Invoice Id

Mandatory if invoiceFilename is not specified

HTTP response

HTTP/1.1 200 OK
Content-Disposition: attachment; filename="IT01879020517_jtlk1.conservazione.zip"
Content-Type: application/zip
Accept-Ranges: bytes
Content-Length: 8

<binary>

9.7. getInvoiceWithUnsignedFile

GET /services/invoice/in/getInvoiceWithUnsignedFile

Ricerca una singola fattura per id o per filename restituendo anche l’eventuale contenuto del file senza la firma digitale. Nel caso in cui la fattura sia firmata, restituisce signed uguale a true e restituisce il file fattura senza firma digitale nel campo unsignedFile. Nel caso in cui la fattura non sia firmata, restituisce signed uguale a false e unsignedFile uguale a null. In ogni caso restituisce il contenuto originale del file fattura nel campo file.

HTTP request

GET /services/invoice/in/getInvoiceWithUnsignedFile?filename=IT01879020517_jtlk1.xml.p7m HTTP/1.1
Accept: application/json
Authorization: Bearer NLOGDVXLVaF3tzmnVPkTwpkuh7dG0i09uSCcog3u+rE=

HTTP response

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

{
  "errorCode" : null,
  "errorDescription" : null,
  "id" : "2",
  "sender" : {
    "description" : "Aruba SPA",
    "countryCode" : "IT",
    "vatCode" : "22222222",
    "fiscalCode" : "11111111111"
  },
  "receiver" : {
    "description" : "Aruba SPA",
    "countryCode" : "IT",
    "vatCode" : "4444444",
    "fiscalCode" : "333333333"
  },
  "invoiceType" : "FPR12",
  "docType" : "in",
  "file" : null,
  "filename" : "IT01879020517_jtlk1.xml.p7m",
  "invoices" : [ {
    "invoiceDate" : "2020-11-12T17:39:54.134+01:00",
    "number" : "2020/0002",
    "status" : "Inviata",
    "statusDescription" : ""
  } ],
  "username" : "Utente",
  "lastUpdate" : "2020-11-12T16:39:54.134+0000",
  "creationDate" : "2020-11-12T16:39:54.134+0000",
  "idSdi" : "11111",
  "pddAvailable" : true,
  "unsignedFile" : "ZFc1emFXZHVaV1FnWm1sc1pRPT0=",
  "signed" : true
}

10. Send Customer Result

10.1. sendEsitoCommittente

POST base url other methods/services/invoice/in/sendEsitoCommittente

The method enables the user to send the Customer Result notification to SDI.

HTTP request

POST /services/invoice/in/sendEsitoCommittente HTTP/1.1
Accept: application/json
Authorization: Bearer NLOGDVXLVaF3tzmnVPkTwpkuh7dG0i09uSCcog3u+rE=
Content-Type: application/json;charset=UTF-8

{
  "filename" : "IT01879020517_jtlk1.xml.p7m",
  "sdiId" : 1263,
  "esito" : "EC01",
  "numero" : "1",
  "anno" : 2018,
  "posizione" : 1,
  "descrizione" : "Desc",
  "messageId" : "7865"
}

Request headers

Name Description

Authorization

Authorization Access token obtained by signin

Request fields

Field Type Description Constraints

filename

String

Name of the invoice received

Mandatory

sdiId

Number

SDI ID of the invoice received

Mandatory

esito

String

Customer result: (EC01: Accepted, EC02: Declined)

Mandatory

numero

String

Invoice number

Mandatory

anno

Number

Year of the invoice

Mandatory

posizione

Number

Position of the invoice in the file (1, 2 etc.)

Mandatory

descrizione

String

Description to be entered in the result, if any

Mandatory

messageId

String

ID of the message created by the customer

Mandatory

HTTP response

HTTP/1.1 200 OK
If successful, HTTP status code 200 is returned, otherwise HTTP status code 500.

11. Find Notifications on Invoices Sent

Methods of finding notifications of sent invoices.

11.1. getByFilename

GET base url other methods/services/notification/out/getByFilename

Finds a notification by filename (e.g. IT01879020517_abcdef_RC_001.xml).

HTTP request

GET /services/notification/out/getByFilename?filename=IT01879020517_33825_RC_001.xml HTTP/1.1
Accept: application/json
Authorization: Bearer NLOGDVXLVaF3tzmnVPkTwpkuh7dG0i09uSCcog3u+rE=

Request headers

Name Description

Authorization

Authorization Access token obtained by signin

Request parameters

Parameter Description Constraints

filename

File name

Mandatory

HTTP response

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

{
  "date" : "2020-11-12T17:39:59.415+01:00",
  "docType" : "RC",
  "file" : "ZEdWemRBPT0=",
  "filename" : "IT01879020517_33825_RC_001.xml",
  "invoiceId" : "1",
  "notificationDate" : "2020-11-12T17:39:59.415+01:00",
  "number" : null,
  "result" : null,
  "errorCode" : "0000",
  "errorDescription" : null
}

HTTP response

Field Type Description

errorCode

String

Error code

errorDescription

String

Error description, if any

date

String

Date of receipt of notification

docType

String

Type of notification (RC, NS, etc.)

file

String

File in Base64 format

filename

String

Filename of notification (e.g. IT01879020517_abcde_RC_001.xml)

invoiceId

String

Invoice ID

notificationDate

String

Delivery date of notification

number

String

Associated invoice reference

result

String

Invoice result (EC01: Accepted, EC02: Rejected)

11.2. getByInvoiceFilename

GET base url other methods/services/notification/out/getByInvoiceFilename

Finds notifications of an invoice by invoice filename (e.g. IT01879020517_abcde.xml.p7m).

HTTP request

GET /services/notification/out/getByInvoiceFilename?invoiceFilename=IT01879020517_jtlk1.xml.p7m HTTP/1.1
Accept: application/json
Authorization: Bearer NLOGDVXLVaF3tzmnVPkTwpkuh7dG0i09uSCcog3u+rE=

Request headers

Name Description

Authorization

Authorization Access token obtained by signin

Request parameters

Parameter Description Constraints

invoiceFilename

Invoice file name

Mandatory

HTTP response

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

{
  "count" : 1,
  "notifications" : [ {
    "date" : "2020-11-12T17:39:59.509+01:00",
    "docType" : "RC",
    "file" : "ZEdWemRBPT0=",
    "filename" : "IT01879020517_33825_RC_001.xml",
    "invoiceId" : "1",
    "notificationDate" : "2020-11-12T17:39:59.509+01:00",
    "number" : null,
    "result" : null,
    "errorCode" : "0000",
    "errorDescription" : null
  } ],
  "errorCode" : "0000",
  "errorDescription" : null
}

Response fields

Field Type Description

errorCode

String

Error code

errorDescription

String

Error description, if any

count

Number

Number of notifications associated with the invoice

notifications

Array

Notifications associated with the invoice

notifications[].errorCode

String

Error code

notifications[].errorDescription

String

Error description, if any

notifications[].date

String

Date of receipt of notification

notifications[].docType

String

Type of notification (RC, NS, etc.)

notifications[].file

String

File in Base64 format

notifications[].filename

String

Filename of notification (e.g. IT01879020517_abcde_RC_001.xml)

notifications[].invoiceId

String

Invoice ID

notifications[].notificationDate

String

Delivery date of notification

notifications[].number

String

Associated invoice reference

notifications[].result

String

Invoice result (EC01: Accepted, EC02: Rejected)

11.3. getByInvoiceId

GET base url other methods/services/notification/out/{invoiceId}

Finds notifications of an invoice by invoice ID.

HTTP request

GET /services/notification/out/1 HTTP/1.1
Accept: application/json
Authorization: Bearer NLOGDVXLVaF3tzmnVPkTwpkuh7dG0i09uSCcog3u+rE=

Request headers

Name Description

Authorization

Authorization Access token obtained by signin

Path parameters

Parameter Description

invoiceId

Invoice Id

HTTP response

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

{
  "count" : 1,
  "notifications" : [ {
    "date" : "2020-11-12T17:39:59.446+01:00",
    "docType" : "RC",
    "file" : "ZEdWemRBPT0=",
    "filename" : "IT01879020517_33825_RC_001.xml",
    "invoiceId" : "1",
    "notificationDate" : "2020-11-12T17:39:59.446+01:00",
    "number" : "1",
    "result" : "esito",
    "errorCode" : null,
    "errorDescription" : null
  } ],
  "errorCode" : "0000",
  "errorDescription" : null
}

Response fields

Field Type Description

errorCode

String

Error code

errorDescription

String

Error description, if any

count

Number

Number of notifications associated with the invoice

notifications

Array

Notifications associated with the invoice

notifications[].errorCode

String

Error code

notifications[].errorDescription

String

Error description, if any

notifications[].date

String

Date of receipt of notification

notifications[].docType

String

Type of notification (RC, NS, etc.)

notifications[].file

String

File in Base64 format

notifications[].filename

String

Filename of notification (e.g. IT01879020517_abcde_RC_001.xml)

notifications[].invoiceId

String

Invoice ID

notifications[].notificationDate

String

Delivery date of notification

notifications[].number

String

Associated invoice reference

notifications[].result

String

Invoice result (EC01: Accepted, EC02: Rejected)

12. Find Notifications on Invoices Received

Methods of finding notifications of received invoices.

12.1. getByFilename

GET base url other methods/services/notification/in/getByFilename

Finds a notification by filename (e.g. IT01879020517_abcde_DT_nnn.xml).

HTTP request

GET /services/notification/in/getByFilename?filename=IT01879020517_33822_RC_001.xml HTTP/1.1
Accept: application/json
Authorization: Bearer NLOGDVXLVaF3tzmnVPkTwpkuh7dG0i09uSCcog3u+rE=

Request headers

Name Description

Authorization

Authorization Access token obtained by signin

Request parameters

Parameter Description Constraints

filename

File name

Mandatory

HTTP response

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

{
  "date" : "2020-11-12T17:39:54.165+01:00",
  "docType" : "NS",
  "file" : "ZEdWemRBPT0=",
  "filename" : "IT01879020517_33822_RC_001.xml",
  "invoiceId" : "2",
  "notificationDate" : "2020-11-12T17:39:54.165+01:00",
  "number" : null,
  "result" : null,
  "errorCode" : "0000",
  "errorDescription" : null
}

Response fields

Field Type Description

errorCode

String

Error code

errorDescription

String

Error description, if any

date

String

Date of receipt of notification

docType

String

Type of notification (RC, NS, etc.)

file

String

File in Base64 format

filename

String

Filename of notification (e.g. IT01879020517_abcde_RC_001.xml)

invoiceId

String

Invoice ID

notificationDate

String

Delivery date of notification

number

String

Associated invoice reference

result

String

Invoice result (EC01: Accepted, EC02: Rejected)

12.2. getByInvoiceFilename

GET base url other methods/services/notification/in/getByInvoiceFilename

Finds notifications of an invoice by invoice filename (e.g. IT01879020517_abcde.xml.p7m).

HTTP request

GET /services/notification/in/getByInvoiceFilename?invoiceFilename=IT01879020517_jtlk1.xml.p7m HTTP/1.1
Accept: application/json
Authorization: Bearer NLOGDVXLVaF3tzmnVPkTwpkuh7dG0i09uSCcog3u+rE=

Request headers

Name Description

Authorization

Authorization Access token obtained by signin

Request parameters

Parameter Description Constraints

invoiceFilename

Invoice file name

Mandatory

HTTP response

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

{
  "count" : 2,
  "notifications" : [ {
    "date" : "2020-11-12T17:39:54.165+01:00",
    "docType" : "NS",
    "file" : "ZEdWemRBPT0=",
    "filename" : "IT01879020517_33822_RC_001.xml",
    "invoiceId" : "2",
    "notificationDate" : "2020-11-12T17:39:54.165+01:00",
    "number" : null,
    "result" : null,
    "errorCode" : "0000",
    "errorDescription" : null
  }, {
    "date" : "2020-11-12T17:39:59.134+01:00",
    "docType" : "EC",
    "file" : "ZEdWemRBPT0=",
    "filename" : "IT01879020517_33825_EC_001.xml.p7m",
    "invoiceId" : "2",
    "notificationDate" : "2020-11-12T17:39:59.134+01:00",
    "number" : "1",
    "result" : "esito",
    "errorCode" : "0000",
    "errorDescription" : null
  } ],
  "errorCode" : "0000",
  "errorDescription" : null
}

Response fields

Field Type Description

errorCode

String

Error code

errorDescription

String

Error description, if any

count

Number

Number of notifications associated with the invoice

notifications

Array

Notifications associated with the invoice

notifications[].errorCode

String

Error code

notifications[].errorDescription

String

Error description, if any

notifications[].date

String

Date of receipt of notification

notifications[].docType

String

Type of notification (RC, NS, etc.)

notifications[].file

String

File in Base64 format

notifications[].filename

String

Filename of notification (e.g. IT01879020517_abcde_RC_001.xml)

notifications[].invoiceId

String

Invoice ID

notifications[].notificationDate

String

Delivery date of notification

notifications[].number

String

Associated invoice reference

notifications[].result

String

Invoice result (EC01: Accepted, EC02: Rejected)

12.3. getByInvoiceId

GET base url other methods/services/notification/in/{invoiceId}

Finds notifications of an invoice by invoice ID.

HTTP request

GET /services/notification/in/2 HTTP/1.1
Accept: application/json
Authorization: Bearer NLOGDVXLVaF3tzmnVPkTwpkuh7dG0i09uSCcog3u+rE=

Request headers

Name Description

Authorization

Authorization Access token obtained by signin

Path parameters

Parameter Description

invoiceId

Invoice Id

HTTP response

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

{
  "count" : 2,
  "notifications" : [ {
    "date" : "2020-11-12T17:39:54.165+01:00",
    "docType" : "NS",
    "file" : "ZEdWemRBPT0=",
    "filename" : "IT01879020517_33822_RC_001.xml",
    "invoiceId" : "2",
    "notificationDate" : "2020-11-12T17:39:54.165+01:00",
    "number" : null,
    "result" : null,
    "errorCode" : "0000",
    "errorDescription" : null
  }, {
    "date" : "2020-11-12T17:39:59.134+01:00",
    "docType" : "EC",
    "file" : "ZEdWemRBPT0=",
    "filename" : "IT01879020517_33825_EC_001.xml.p7m",
    "invoiceId" : "2",
    "notificationDate" : "2020-11-12T17:39:59.134+01:00",
    "number" : "1",
    "result" : "esito",
    "errorCode" : "0000",
    "errorDescription" : null
  } ],
  "errorCode" : "0000",
  "errorDescription" : null
}

Response fields

Field Type Description

errorCode

String

Error code

errorDescription

String

Error description, if any

count

Number

Number of notifications associated with the invoice

notifications

Array

Notifications associated with the invoice

notifications[].errorCode

String

Error code

notifications[].errorDescription

String

Error description, if any

notifications[].date

String

Date of receipt of notification

notifications[].docType

String

Type of notification (RC, NS, etc.)

notifications[].file

String

File in Base64 format

notifications[].filename

String

Filename of notification (e.g. IT01879020517_abcde_RC_001.xml)

notifications[].invoiceId

String

Invoice ID

notifications[].notificationDate

String

Delivery date of notification

notifications[].number

String

Associated invoice reference

notifications[].result

String

Invoice result (EC01: Accepted, EC02: Rejected)

13. Callback specification

In addition to the POP mode search methods, described in the previous chapters (Find Invoices Sent, Find Notifications on Invoices Sent, Find Invoices Received and Find Notifications on Invoices Received), Aruba’s Electronic Invoicing system allows you to send users received invoices and notifications in PUSH mode, as well as updates on the status of sent invoices.

Users must have a Web Service that implements the methods described in the following paragraphs and will have to be accredited. Premium users and their assignors will have to obtain accreditation independently via the "Configuration" section of the web panel. For more information, please refer to the guide for your Premium account. Users connected by proxy to a Premium account, who have granted it the "Active Cycle Web Service" and "Passive Cycle Web Service" permissions, will receive callbacks at the endpoints specified by the authorized Premium user.

The endpoint presented by the user must use port 80 if in http, or port 443 if in https to communicate.

For users who need to configure firewalls, callbacks will be sent from the following IPs:

  • 46.37.19.5

  • 46.37.19.6

  • 62.149.180.5

  • 62.149.180.6

Call security will be guaranteed thanks to a static api-key to be passed through the Authorization header. The user can choose the api-key during accreditation.

Nome Descrizione

Authorization

Static API-KEY to be agreed with the user, during the accreditation phase

Retry: If a callback is not successful, 10 more attempts will be made at 3-hour intervals

13.1. createInvoice (POST)

The purpose of this method is to send the user a new received invoice.

The method must accept the following parameters in the format application/json with UTF-8 encoding.

Field Type Description Constraints

username

String

Username

Mandatory

countryCode

String

Country code (e.g. IT for Italy)

Mandatory

vatCode

String

VAT number

Mandatory

fiscalCode

String

Tax code

Mandatory

sdiIdentification

String

SDI ID

Mandatory

sdiInvoiceFileName

String

Invoice file name

Mandatory

invoiceXmlBase64

String

Xml string for the invoice in base64

Mandatory

sdiMetadataFileName

String

Notification file name metadata (MT)

Mandatory

metadataXmlBase64

String

Notification xml string metadata (MT) in base64

Mandatory

The method should return the following HTTP code, the response should be in the application/json format with UTF-8 encoding.

Code Description

200

Operation completed successfully

400

Missing or invalid input parameters

500

Internal error

13.2. createNotification (POST)

The purpose of this method is to send the user a new notification for an existing sent or received invoice.

The method must accept the following parameters in the format application/json with UTF-8 encoding.

Field Type Description Constraints

username

String

Username

Mandatory

countryCode

String

Country code (e.g. IT for Italy)

Mandatory

vatCode

String

VAT number

Mandatory

fiscalCode

String

Tax code

Mandatory

inOut

String

OUT for sent invoices, IN for received invoices

Mandatory

notifyType

String

Notification type, for possible values see the SDI Notification Type column in the Invoice status table

Mandatory

sdiIdentification

String

SDI ID

Mandatory

notifyFileName

String

Notification file name

Mandatory

notifyXmlBase64

String

Xml string for the notification in base64

Mandatory

The method should return the following HTTP code, the response should be in the application/json format with UTF-8 encoding.

Code Description

200

Operation completed successfully

400

Missing or invalid input parameters

500

Internal error

13.3. updateInvoiceStatus (POST)

The purpose of this method is to send the user updates about the status of sent invoices. The statuses sent are Inviata (i.e. Sent) or Errore Elaborazione (i.e. Processing Error), other statuses (Invoice status), which refer to an SDI notification, are sent via the createNotification method (POST).

The method must accept the following parameters in the format application/json with UTF-8 encoding..

Field Type Description Constraints

username

String

Username

Mandatory

countryCode

String

Country code (e.g. IT for Italy)

Mandatory

vatCode

String

VAT number

Mandatory

fiscalCode

String

Tax code

Mandatory

invoiceFileName

String

Invoice file name

Mandatory

sdiIdentification

String

SDI ID, present if the invoice has been sent to the SDI, otherwise null

Mandatory

status

String

Invoice status, can be Inviata (i.e. Sent) or Errore Elaborazione (i.e. Processing Error)

Mandatory

errorDescription

String

Error description, can be one of the messages listed in Asynchronous Checks

Mandatory if the status is Errore Elaborazione (i.e Processing Error)

The method should return the following HTTP code, the response should be in the application/json format with UTF-8 encoding.

Code Description

200

Operation completed successfully

400

Missing or invalid input parameters

500

Internal error

13.4. updateUsage (POST)

The aim of the process is to inform the user of updates relating to the storage used.

The method must accept the following parameters in the format application/json with UTF-8 encoding.

Field Type Description Constraints

username

String

Username

Mandatory

maxSpaceKB

String

Storage space purchased in kilobytes

Mandatory

usedSpaceKB

String

Storage space used in kilobytes

Mandatory

The method should return the following HTTP code, the response should be in the application/json format with UTF-8 encoding.

Code Description

200

Operation completed successfully

400

Missing or invalid input parameters

500

Internal error

14. Exchange System Simulation in a Demo environment

In a Demo environment only, it is possible to reproduce the Exchange System operation by simulating the receipt of an invoice or by simulating a notification that an invoice has been sent.

14.1. Invoice received simulation

This method lets you simulate receiving an invoice by specifying the VAT number of the assignee/customer. An invoice is generated from a randomly selected template, with the details of the assignee/customer specified in the body of the request. The service returns the file name of the invoice that is generated.

Request headers

Name Description

Authorization

Authorization Access token obtained by signin

HTTP request

POST /services/sdisimulator/invoiceIn HTTP/1.1
Accept: application/json
Authorization: Bearer NLOGDVXLVaF3tzmnVPkTwpkuh7dG0i09uSCcog3u+rE=
Content-Type: application/json;charset=UTF-8

{
  "countryReceiver" : "IT",
  "vatcodeReceiver" : "01879020517",
  "fiscalcodeReceiver" : null
}

Request fields

Field Type Description Constraints

countryReceiver

String

Country code (e.g. IT for Italy) for the assignee/customer

Mandatory

vatcodeReceiver

String

VAT number of the assignee/customer

Mandatory

fiscalcodeReceiver

String

Tax code of the assignee/customer

Not mandatory, if specified it will appear on the invoice

HTTP response

HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8
Content-Length: 152

{
  "countryReceiver" : "IT",
  "vatcodeReceiver" : "01879020517",
  "fiscalcodeReceiver" : null,
  "invoiceFileName" : "IT54311352267_D8MlQ.xml"
}

Response fields

Field Type Description

invoiceFileName

String

Country code (e.g. IT for Italy) for the assignee/customer

countryReceiver

String

VAT number of the assignee/customer

vatcodeReceiver

String

File name of the invoice generated

fiscalcodeReceiver

String

Tax code of the assignee/customer

14.2. Simulation of notification of sent invoice

This method lets you simulate a notification for a sent invoice. Starting with a randomly selected template, a notification is generated according to the type specified by notificationType and associated with the invoice specified by invoiceFileName. The types of notification that you can specify are listed in the SDI notification Type column in the Invoice Status table.

To simulate an "Accepted" outcome, NE_EC01 needs to be specified as the notificationType. Likewise, to simulate a "Rejected" outcome, NE_EC02 needs to be specified as notificationType. Therefore, the following values are acceptable for notificationType: NS, MC, AT, RC, NE_EC01, NE_EC02, DT.

Request headers

Name Description

Authorization

Authorization Access token obtained by signin

HTTP request

POST /services/sdisimulator/notificationOut HTTP/1.1
Accept: application/json
Authorization: Bearer NLOGDVXLVaF3tzmnVPkTwpkuh7dG0i09uSCcog3u+rE=
Content-Type: application/json;charset=UTF-8

{
  "invoiceFileName" : "IT01879020517_aBcDe.xml.p7m",
  "notificationType" : "RC"
}

Request fields

Field Type Description Constraints

invoiceFileName

String

File name of invoice to be linked to the notification

Mandatory

notificationType

String

Notification type

Mandatory

HTTP response

HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8
Content-Length: 148

{
  "invoiceFileName" : "IT01879020517_aBcDe.xml.p7m",
  "notificationFileName" : "ITIT01879020517_aBcDe_448.xml",
  "notificationType" : "RC"
}

Response fields

Field Type Description

notificationFileName

String

File name of the notification

invoiceFileName

String

File name of the invoice to which the notification is linked

notificationType

String

Notification type

Changelog

1.7.0 - from 22/07/2020

Added

1.4.0 - from 30/03/2020

Added

Changed


1.2.0 - from 13/05/2019

Added

Changed

  • Update SLA with number of requests per minute per IP

  • Improved refresh method documentation


1.1.0 - from 25/02/2019

Removed

  • Test environment removed from the documentation

  • MonitorCheck method removed from the documentation

Deprecated

  • MonitorCheck method

Fixed



1. Refer to the tables showing the ordinary and simplified invoice layout available in the technical specifications provided by the Italian Revenue Agency.