change log link

For v1 documentation refer to Electronic Invoicing API Docs

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 (Authentication 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 no. authentication requests per IP

1 per minute

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. Authentication

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: 278

{
  "access_token" : "711b398c61857ecc",
  "token_type" : "bearer",
  "expires_in" : 1800,
  "refresh_token" : "7a9aff46fad778ed",
  "userName" : "Utente",
  "as:client_id" : "Auth",
  ".issued" : "Thu, 21 Nov 2024 09:39:10 GMT",
  ".expires" : "Thu, 21 Nov 2024 10:09:10 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: 98

{
  "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: 347

{
  "username" : "ARUBA0000",
  "pec" : "pec@pec.it",
  "userDescription" : "Aruba PEC S.p.A.",
  "countryCode" : "IT",
  "vatCode" : "01879020517",
  "fiscalCode" : "01879020517",
  "accountStatus" : {
    "expired" : false,
    "expirationDate" : "2025-02-21"
  },
  "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

5.4. multicedenti

GET base url autenticazione/auth/multicedenti

This method allows you to recuperate information on the user’s multisellers Premium related to authentication token.

HTTP request

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

Request headers

Name Description

Authorization

Authorization Access token obtained by signin

Request parameters

Parameter Description Constraints

countryCode

Country code (e.g. IT for Italy)

Not required

vatCode

VAT number

Not required

status

Multiseller status

Not required

size

Page size (default 10)

Between 1 and 100

page

page requested (default 1)

Between 1 and totalPages

HTTP response

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

{
  "first" : true,
  "last" : true,
  "number" : 1,
  "numberOfElements" : 2,
  "size" : 2,
  "totalElements" : null,
  "totalPages" : 1,
  "content" : [ {
    "description" : "Multicedente di esempio 1",
    "countryCode" : "IT",
    "vatCode" : "98765123453",
    "usedSpaceKB" : 7,
    "creationDate" : "2022-08-04T10:50:05.571+02:00",
    "id" : "5dee624a18ba9a66af3ef417",
    "status" : "ACTIVE"
  }, {
    "description" : "Multicedente di esempio 2",
    "countryCode" : "IT",
    "vatCode" : "12345634512",
    "usedSpaceKB" : 123,
    "creationDate" : "2022-08-04T10:50:05.571+02:00",
    "id" : "62eb883d89ec1c5540f80cb1",
    "status" : "ACTIVE"
  } ]
}

Response fields

Field Type Description

content

Array

Array of multisellers found

first

Boolean

true if the page found is the first, otherwise false

last

Boolean

true if the page found is the last, otherwise false

number

Number

Current page number

numberOfElements

Number

Number of elements returned

size

Number

Page size

totalElements

Null

Total number of multisellers found

totalPages

Number

Total number of pages

content[].countryCode

String

Country code (e.g. IT for Italy)

content[].creationDate

String

Creation date

content[].description

String

Company name

content[].id

String

Multiseller IDs

content[].status

String

Multiseller status

content[].usedSpaceKB

Number

Storage space used in kilobytes

content[].vatCode

String

VAT number

5.5. multicedenteById

GET base url autenticazione/auth/multicedenti/{id}

This method allows you to recuperate information on a single multiseller.

HTTP request

GET /auth/multicedenti/62eb883d89ec1c5540f80cb1 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: 237

{
  "description" : "Multicedente di esempio 2",
  "countryCode" : "IT",
  "vatCode" : "12345634512",
  "usedSpaceKB" : 123,
  "creationDate" : "2022-08-04T10:50:05.571+02:00",
  "id" : "62eb883d89ec1c5540f80cb1",
  "status" : "ACTIVE"
}

Response fields

Field Type Description

countryCode

String

Country code (e.g. IT for Italy)

creationDate

String

Creation date

description

String

Company name

id

String

Multiseller IDs

status

String

Multiseller status

usedSpaceKB

Number

Storage space used in kilobytes

vatCode

String

VAT number

5.6. Status of multisellers

Status Status Code Description

Connected

ACTIVE

Multiseller connected

Suspended

SUSPEND

Multiseller suspended

Not active

INACTIVE

Multiseller not active

Pending approval

PENDING

Multiseller pending approval

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/api/v2/comfin

Creation of a new request for the transmission of "Financial Communications".

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 /api/v2/comfin HTTP/1.1
Accept: application/json
Authorization: Bearer NLOGDVXLVaF3tzmnVPkTwpkuh7dG0i09uSCcog3u+rE=
Content-Type: application/json;charset=UTF-8

{
  "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.

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: 38

{
  "requestId" : "8XVJQQY4CGVDIBQN"
}

Response fields

Field Type Description

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. GetTransmissionInfoRequest

GET base url other methods/api/v2/comfin/{requestId}

Service for querying the status of a request.

HTTP request

GET /api/v2/comfin/GPBJ95IEM9 HTTP/1.1
Authorization: Bearer NLOGDVXLVaF3tzmnVPkTwpkuh7dG0i09uSCcog3u+rE=

Path parameters

Parameter Description

requestId

Unique ID of the request provided in the creation phase

HTTP response

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

{
  "result" : "SF01",
  "notifyResult" : "",
  "elaboratedResult" : "",
  "receiptTimestamp" : "2017-04-18 18:30:30",
  "fileId" : "8054598261",
  "fileName" : "IT01879020517_LI_0001.xml",
  "status" : "",
  "pddAvailable" : false
}

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.

status

String

Status

6.3. pdd

GET base url other methods/api/v2/comfin/{requestId}/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

GET /api/v2/comfin/MUO040KWCP/pdd HTTP/1.1
Authorization: Bearer NLOGDVXLVaF3tzmnVPkTwpkuh7dG0i09uSCcog3u+rE=

Path parameters

Parameter Description

requestId

Unique ID of the request provided in the creation phase

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.4. ComunicationType

Valore Descrizione

LI

Regular VAT payment

DF

Invoice data

6.5. 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.6. 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 be issued with one of the following "Document Types", depending on the type of self-billed invoice issued: TD01, TD16, TD17, TD18, TD19, TD20, TD21, TD22, TD23, TD26, TD27.

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" : "",
  "senderPIVA" : "",
  "skipExtraSchema" : false,
  "dryRun" : false
}
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 encoded in Base64

Mandatory

credential

String

Signature credentials

domain

String

Signature domain

senderPIVA

String

If the invoice to be sent has code TD26 (disposal of depreciable assets and internal transfers pursuant to art.36 DPR 633/72) as "2.1.1.1 <TipoDocumento>", the senderPIVA field can be used to specifiy whether the assignor/lender or the assignee/client is the invoice sender. The senderPIVA field, if used, must contain the sender’s nation code and VAT number (e.g. IT99999999999 )

skipExtraSchema

Boolean

Default set to false. If set to true, Extra schema synchronous checks and Extra schema asynchronous checks will not be performed. Extra schema synchronous checks and Extra schema asynchronous checks will nevertheless be performed by the Exchange System

dryRun

Boolean

false by default. If set to 'true', the invoice will go through the validation steps but will not be sent to SdI

HTTP response

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

{
  "errorCode" : "0000",
  "errorDescription" : "Operazione effettuata - 521e052902be7b879d41e0fd586f0e21",
  "uploadFileName" : "IT07641803768_sykkr.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==",
  "senderPIVA" : "",
  "skipExtraSchema" : false,
  "dryRun" : false
}

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

senderPIVA

String

If the invoice to be sent has code TD26 (disposal of depreciable assets and internal transfers pursuant to art.36 DPR 633/72) as "2.1.1.1 <TipoDocumento>", the senderPIVA field can be used to specifiy whether the assignor/lender or the assignee/client is the invoice sender. The senderPIVA field, if used, must contain the sender’s nation code and VAT number (e.g. IT99999999999 )

skipExtraSchema

Boolean

Default set to false. If set to true, Extra schema synchronous checks and Extra schema asynchronous checks will not be performed. Extra schema synchronous checks and Extra schema asynchronous checks will nevertheless be performed by the Exchange System

dryRun

Boolean

false by default. If set to 'true', the invoice will go through the validation steps but will not be sent to SdI

HTTP response

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

{
  "errorCode" : "",
  "errorDescription" : "Operazione effettuata - 521e052902be7b879d41e0fd586f0e21",
  "uploadFileName" : "IT01879020517_eqcoo.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 findInvoices, getInvoiceDetail 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.

0096

Errore di validazione: "codice" - "messaggio"

Validation error (Extra schema checks)

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.

0098

Formato Base64 non valido.

The coding in Base64 of the invoice file is invalid.
Extra schema checks

Synchronous checks for the message 0096, "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

00313

L’elemento 1.1.4 <CodiceDestinatario> può essere valorizzato con "XXXXXXX" esclusivamente per le fatture emesse verso soggetti non residenti (1.4.1.1 <IdFiscaleIVA> deve essere valorizzato e 1.4.1.1.1 <IdPaese> deve essere diverso da "IT")

L’elemento 1.1.4 <CodiceDestinatario> può essere valorizzato con "XXXXXXX" per comunicare i dati di fatture emesse esclusivamente verso soggetti non residenti (1.3.1.1 <IdFiscaleIVA> deve essere valorizzato e 1.3.1.1.1 <IdPaese> deve essere diverso da "IT")

1.1.4 <CodiceDestinatario>

If line 1.1.4 <CodiceDestinatario> equals "XXXXXXX" (invoice issued to parties not resident, established or located in Italy) it must be verified that the IdPaese field of the transferee/customer contains a value other than "IT"

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>

Invalid <IdCodice>

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 (l’indicazione di un’aliquota IVA diversa da zero qualifica l’operazione come imponibile e quindi non è ammessa la presenza dell’elemento <Natura>, ad eccezione del caso in cui l’elemento TipoDocumento assume valore TD16)

2.2.4 <Natura> presente a fronte di 2.2.3.2 <Aliquota> diversa da zero (l’indicazione di un’aliquota IVA diversa da zero qualifica l’operazione come imponibile e quindi non è ammessa la presenza dell’elemento <Natura>, ad eccezione del caso in cui l’elemento TipoDocumento assume valore TD16)

2.2.1.14 <Natura> e 2.2.1.12 <AliquotaIVA>

Check that field contains a value, if item 2.2.1.12 <AliquotaIVA> equals "0.00", and that it does not contain a value if item 2.2.1.12 <AliquotaIVA> is something other than "0.00" (except when item 2.1.1.1 <TipoDocumento> equals TD16)

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>

Check that field contains a value, if item 2.2.1.1 <AliquotaIVA> equals "0.00", and that it does not contain a value if item 2.2.1.1 <AliquotaIVA> is something other than "0.00" (except when item 2.1.1.1 <TipoDocumento> equals TD16)

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 the values in this field if there is more than one block 2.2 <DatiBeniServizi>) cannot be greater than 400.00 Euros. This limit may only be exceeded if block 2.1.2 <DatiFatturaRettificata> is imposed

00471

Per il valore indicato nell’elemento 2.1.1.1 <TipoDocumento> il cedente/prestatore non può essere uguale al cessionario/committente (i valori del tipo documento TD01, TD02, TD03, TD06, TD16, TD17, TD18, TD19, TD20, TD24, TD25 e TD28 (fatture ordinarie) e TD07 (fatture semplificate) non ammettono l’indicazione in fattura dello stesso soggetto sia come cedente che come cessionario)

2.1.1.1 <TipoDocumento>

If item 2.1.1.1 <TipoDocumento> equals TD01, TD02, TD03, TD06, TD16, TD17, TD18, TD19, TD20, TD24, TD25 or TD28, a check is 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 (i valori TD21 e TD27 non ammettono l’indicazione in fattura di un cedente diverso dal cessionario)

2.1.1.1 <TipoDocumento>

If item 2.1.1.1 <TipoDocumento> equals TD21 or TD27, a check is 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> (i valoriTD17, TD18, TD19 e TD28 del tipo documento non ammettonol’indicazione in fattura di un cedente italiano. Nei casi di TD17 e TD19 è ammessa l’indicazione del valore 'OO' nell’elemento 1.2.1.1.1 <IdPaese>per operazioni effettuate da soggetti residenti in Livigno e Campione d’Italia. Inoltre, nel caso del TD28, l’elemento 1.2.1.1.1 <IdPaese> deve essere valorizzato con il valore SM)(vale solo per le fatture ordinarie)

2.1.1.1 <TipoDocumento> e 1.2.1.1.1 <IdPaese>

If item 2.1.1.1 <TipoDocumento> equals TD17, TD18, TD19 or TD28, a check is performed to verify that 1.2.1.1.1<IdPaese> of the supplier/provider is not "IT" and that, in the case of TD28, it is "SM"

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

00475

Per il valore indicato nell’elemento 2.1.1.1 <TipoDocumento> deve essere presente l’elemento 1.4.1.1 <IdFiscaleIVA> del cessionario/committente (i tipi documento TD16, TD17, TD18, TD19, TD20, TD22, TD23 e TD28 prevedono obbligatoriamente la presenza della partita IVA del cessionario/committente)

2.1.1.1 <TipoDocumento> e 1.4.1.1 <IdFiscaleIVA>

If item 2.1.1.1 <TipoDocumento> equals TD16, TD17, TD18, TD19, TD20, TD22, TD23 or TD28, a check is performed to verify that the block 1.4.1.1 <IdFiscaleIVA> of the assignee/customer contains a value

00476

Gli elementi 1.2.1.1.1 <IdPaese> e 1.4.1.1.1 <IdPaese> non possono essere entrambi valorizzati con codice diverso da IT (non è ammessa una fattura riportante contemporaneamente nel paese dell’identificativo fiscale del cedente/prestatore e del cessionario/committente un valore diverso da IT)

Gli elementi 1.2.1.1 <IdPaese> (cedente) e 1.3.1.1.1 <IdPaese> (cessionario) non possono essere entrambi valorizzati con codice diverso da IT (non è ammessa una fattura riportante contemporaneamente nel paese dell’identificativo fiscale del cedente/prestatore e del cessionario/committente un valore diverso da IT)

1.2.1.1.1 <IdPaese> (cedente) e 1.4.1.1.1 <IdPaese>

If item 1.2.1.1.1 <IdPaese> contains a value different from "IT", a check is performed to verify that item 1.4.1.1.1 <IdPaese> is not different from "IT" as well

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.

Ricevuta

MT

Invoices received come with the Metadata Notification that the SDI exchange system sends the recipient with the invoice.

8.2. findInvoices

GET base url other methods/api/v2/invoices-out

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 /api/v2/invoices-out 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

page

page requested (default 1)

Between 1 and totalPages

size

page size (default 10)

Between 1 and 100

creationStartDate

Invoice creation date (from)

Mandatory, in ISO 8601 format, the difference with creationEndDate cannot be more than 2 days

creationEndDate

Invoice creation date (to)

Mandatory, in ISO 8601 format, the difference with creationStartDate cannot be more than 2 days

senderCountry

Country Code of the assignor/provider

Mandatory if the user is a Premium user

senderVatcode

VAT number of the assignor/provider

Mandatory if the user is a Premium user

receiverCountry

Country Code of the assignee/customer

receiverVatcode

VAT number of the assignee/customer

receiverFiscalcode

Tax code of the assignee/customer

status

Invoice status

documentType

Document type

modifiedStartDate

Last invoice modification date (from)

In ISO 8601 format

modifiedEndDate

Last invoice modification date (to)

In ISO 8601 format

HTTP response

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

{
  "content" : [ {
    "channelGroup" : 2,
    "shopName" : "null",
    "invoices" : [ {
      "invoiceDate" : "2024-11-21T09:39:09.630Z",
      "number" : "1",
      "documentType" : "TD01",
      "status" : "Inviata",
      "statusDescription" : "",
      "totalDocument" : 100.0,
      "totalVat" : 27.0,
      "netPayable" : 100.0
    } ],
    "sdiErrors" : [ ],
    "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",
    "username" : "Utente",
    "creationDate" : "2024-11-21T09:39:09.630+0000",
    "lastUpdate" : "2024-11-21T09:39:09.630+0000",
    "idSdi" : "7895",
    "pddAvailable" : true
  }, {
    "channelGroup" : 2,
    "shopName" : "null",
    "invoices" : [ {
      "invoiceDate" : "2024-11-21T09:39:09.630Z",
      "number" : "1",
      "documentType" : "TD01",
      "status" : "Inviata",
      "statusDescription" : "",
      "totalDocument" : 100.0,
      "totalVat" : 27.0,
      "netPayable" : 100.0
    } ],
    "sdiErrors" : [ ],
    "id" : "2",
    "sender" : {
      "description" : "Aruba SPA",
      "countryCode" : "yBJ",
      "vatCode" : "1745663161",
      "fiscalCode" : "GFZ3LzV8wY"
    },
    "receiver" : {
      "description" : "Rossi SRL",
      "countryCode" : "IT",
      "vatCode" : "7180594879",
      "fiscalCode" : "HwDBzj6cjT"
    },
    "invoiceType" : "FPR12",
    "docType" : "out",
    "file" : null,
    "filename" : "IT01879020517_eqcoo.xml.p7m",
    "username" : "Utente",
    "creationDate" : "2024-11-21T09:39:09.630+0000",
    "lastUpdate" : "2024-11-21T09:39:09.630+0000",
    "idSdi" : "7895",
    "pddAvailable" : true
  }, {
    "channelGroup" : 2,
    "shopName" : "null",
    "invoices" : [ {
      "invoiceDate" : "2024-11-21T09:39:09.630Z",
      "number" : "1",
      "documentType" : "TD01",
      "status" : "Inviata",
      "statusDescription" : "",
      "totalDocument" : 100.0,
      "totalVat" : 27.0,
      "netPayable" : 100.0
    } ],
    "sdiErrors" : [ ],
    "id" : "3",
    "sender" : {
      "description" : "Aruba SPA",
      "countryCode" : "IT",
      "vatCode" : "31464730975",
      "fiscalCode" : "05361669693"
    },
    "receiver" : {
      "description" : "Rossi SRL",
      "countryCode" : "IT",
      "vatCode" : "47231866271",
      "fiscalCode" : "55896669261"
    },
    "invoiceType" : "FPR12",
    "docType" : "out",
    "file" : null,
    "filename" : "IT07641803768_sykkr.xml.p7m",
    "username" : "Utente",
    "creationDate" : "2024-11-21T09:39:09.630+0000",
    "lastUpdate" : "2024-11-21T09:39:09.630+0000",
    "idSdi" : "7895",
    "pddAvailable" : true
  }, {
    "channelGroup" : 2,
    "shopName" : "null",
    "invoices" : [ {
      "invoiceDate" : "2024-11-21T09:39:09.630Z",
      "number" : "1",
      "documentType" : "TD01",
      "status" : "Inviata",
      "statusDescription" : "",
      "totalDocument" : 100.0,
      "totalVat" : 27.0,
      "netPayable" : 100.0
    } ],
    "sdiErrors" : [ ],
    "id" : "4",
    "sender" : {
      "description" : "Aruba SPA",
      "countryCode" : "IT",
      "vatCode" : "49438996411",
      "fiscalCode" : "76718412753"
    },
    "receiver" : {
      "description" : "Rossi SRL",
      "countryCode" : "IT",
      "vatCode" : "52900309206",
      "fiscalCode" : "84120122783"
    },
    "invoiceType" : "FPR12",
    "docType" : "out",
    "file" : null,
    "filename" : "IT03452204191_ktpkf.xml.p7m",
    "username" : "Utente",
    "creationDate" : "2024-11-21T09:39:09.630+0000",
    "lastUpdate" : "2024-11-21T09:39:09.630+0000",
    "idSdi" : "7895",
    "pddAvailable" : true
  } ],
  "first" : true,
  "last" : true,
  "totalElements" : 4,
  "totalPages" : 1,
  "size" : 10,
  "number" : 1,
  "numberOfElements" : 4
}

Response fields

Field Type Description

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[].invoices

Array

Array of individual invoices in the batch

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[].username

String

Username of the owner of the invoice

content[].creationDate

String

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

content[].lastUpdate

String

Date of last update

content[].idSdi

String

SDI (Exchange System) ID

content[].pddAvailable

Boolean

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

content[].channelGroup

Number

Invoice channel

content[].shopName

String

Name of shop if invoice comes from ecommerce

content[].sdiErrors

Array

List of errors in the possible rejection notification

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.[].totalDocument

String

Total document

content[].invoices.[].totalVat

String

Total Vat

content[].invoices.[].netPayable

String

Net payable

content[].invoices.[].documentType

String

Document type

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. getInvoiceDetail

GET base url other methods/api/v2/invoices-out/detail

Finds for an individual invoice by id, invoice filename or idSdi.

HTTP request

GET /api/v2/invoices-out/detail?id=1 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

id

Invoice Id

Mandatory if neither idSdi nor filename are specified

filename

File name of invoice

Mandatory if neither id nor idSdi are specified

idSdi

SdI Id

Mandatory if neither id nor filename are specified

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: 948

{
  "channelGroup" : 2,
  "shopName" : "null",
  "invoices" : [ {
    "invoiceDate" : "2024-11-21T09:39:09.573Z",
    "number" : "1",
    "documentType" : "TD01",
    "status" : "Inviata",
    "statusDescription" : "",
    "totalDocument" : 100.0,
    "totalVat" : 27.0,
    "netPayable" : 100.0
  } ],
  "sdiErrors" : [ ],
  "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",
  "username" : "Utente",
  "creationDate" : "2024-11-21T09:39:09.573+0000",
  "lastUpdate" : "2024-11-21T09:39:09.573+0000",
  "idSdi" : "9998l",
  "pdfFile" : "ZEdWemRGQmtaZz09",
  "pddAvailable" : true
}

Response fields

Field Type Description

invoices

Array

Array of individual invoices in the batch

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)

username

String

Username of the owner of the invoice

creationDate

String

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

lastUpdate

String

Date of last update

idSdi

String

SDI (Exchange System) ID

pddAvailable

Boolean

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

channelGroup

Number

Invoice channel

shopName

String

Name of shop if invoice comes from ecommerce

sdiErrors

Array

List of errors in the possible rejection notification

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.[].totalDocument

String

Total document

invoices.[].totalVat

String

Total Vat

invoices.[].netPayable

String

Net payable

invoices.[].documentType

String

Document type

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. getInvoiceZip

GET base url other methods/api/v2/invoices-out/zip

Returns an invoice with all of its notifications in Zip format (e.g. IT01879020517_abcde.xml.p7m). Search performed by invoice id, invoice filename or idSdi.

HTTP request

GET /api/v2/invoices-out/zip?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 of invoice

Mandatory if neither id nor idSdi are specified

id

Invoice Id

Mandatory if neither idSdi nor filename are specified

idSdi

SdI Id

Mandatory if neither id nor filename are specified

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. getInvoicePdd

GET base url other methods/api/v2/invoices-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 (filename), ID (id) or sdiId (idSdi). If however pddAvailable is false, in other words, the Preservation package is not available, the HTTP status code 404 is returned.

HTTP request

GET /api/v2/invoices-out/pdd?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 of invoice

Mandatory if neither id nor idSdi are specified

id

Invoice Id

Mandatory if neither idSdi nor filename are specified

idSdi

SdI Id

Mandatory if neither id nor filename are 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. findInvoices

GET base url other methods/api/v2/invoices-in

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

HTTP request

GET /api/v2/invoices-in 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

page

page requested (default 1)

Between 1 and totalPages

size

Page size (default 10)

Between 1 and 100

creationStartDate

Invoice creation date (from)

Mandatory, in ISO 8601 format, the difference with creationEndDate cannot be more than 2 days

creationEndDate

Invoice creation date (to)

Mandatory, in ISO 8601 format, the difference with creationStartDate cannot be more than 2 days

senderCountry

Country Code of the assignor/provider

senderVatcode

VAT number of the assignor/provider

senderFiscalcode

Tax code of the assignor/provider

receiverCountry

Country Code of the assignee/customer

Mandatory if the user is a Premium user

receiverVatcode

VAT number of the assignee/customer

Mandatory if the user is a Premium user

documentType

Document type

modifiedStartDate

Last invoice modification date (from)

In ISO 8601 format

modifiedEndDate

Last invoice modification date (to)

In ISO 8601 format

HTTP response

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

{
  "content" : [ {
    "invoices" : [ {
      "invoiceDate" : "2024-11-21T09:39:05.972Z",
      "number" : "2024/0001",
      "documentType" : "TD01",
      "totalDocument" : 100.0,
      "totalVat" : 22.0,
      "netPayable" : 100.0
    } ],
    "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",
    "username" : "Utente",
    "creationDate" : "2024-11-21T09:39:05.973+0000",
    "lastUpdate" : "2024-11-21T09:39:05.973+0000",
    "idSdi" : "11110",
    "pddAvailable" : true
  }, {
    "invoices" : [ {
      "invoiceDate" : "2024-11-21T09:39:05.973Z",
      "number" : "2024/0002",
      "documentType" : "TD01",
      "totalDocument" : 100.0,
      "totalVat" : 22.0,
      "netPayable" : 100.0
    } ],
    "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",
    "username" : "Utente",
    "creationDate" : "2024-11-21T09:39:05.973+0000",
    "lastUpdate" : "2024-11-21T09:39:05.973+0000",
    "idSdi" : "11111",
    "pddAvailable" : true
  }, {
    "invoices" : [ {
      "invoiceDate" : "2024-11-21T09:39:05.973Z",
      "number" : "2024/0003",
      "documentType" : "TD01",
      "totalDocument" : 100.0,
      "totalVat" : 22.0,
      "netPayable" : 100.0
    } ],
    "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",
    "username" : "Utente",
    "creationDate" : "2024-11-21T09:39:05.973+0000",
    "lastUpdate" : "2024-11-21T09:39:05.973+0000",
    "idSdi" : "11112",
    "pddAvailable" : true
  }, {
    "invoices" : [ {
      "invoiceDate" : "2024-11-21T09:39:05.973Z",
      "number" : "2024/0004",
      "documentType" : "TD01",
      "totalDocument" : 100.0,
      "totalVat" : 22.0,
      "netPayable" : 100.0
    } ],
    "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",
    "username" : "Utente",
    "creationDate" : "2024-11-21T09:39:05.973+0000",
    "lastUpdate" : "2024-11-21T09:39:05.973+0000",
    "idSdi" : "11113",
    "pddAvailable" : true
  } ],
  "first" : true,
  "last" : true,
  "totalElements" : 4,
  "totalPages" : 1,
  "size" : 10,
  "number" : 1,
  "numberOfElements" : 4
}

Response fields

Field Type Description

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[].invoices

Array

Array of individual invoices in the batch

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[].username

String

Username of the owner of the invoice

content[].creationDate

String

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

content[].lastUpdate

String

Date of last update

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.[].totalDocument

String

Total document

content[].invoices.[].totalVat

String

Total Vat

content[].invoices.[].netPayable

String

Net payable

content[].invoices.[].documentType

String

Document type

9.2. getInvoiceDetail

GET base url other methods/api/v2/invoices-in/detail

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

HTTP request

GET /api/v2/invoices-in/detail?id=1 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

id

Invoice Id

Mandatory if neither idSdi nor filename are specified

filename

File name of invoice

Mandatory if neither id nor idSdi are specified

idSdi

SdI Id

Mandatory if neither id nor filename are specified

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

includeUnsignedFile

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

Not required. Default value is false

HTTP response

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

{
  "invoices" : [ {
    "invoiceDate" : "2024-11-21T09:39:05.972Z",
    "number" : "2024/0001",
    "documentType" : "TD01",
    "totalDocument" : 100.0,
    "totalVat" : 22.0,
    "netPayable" : 100.0
  } ],
  "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",
  "username" : "Utente",
  "creationDate" : "2024-11-21T09:39:05.973+0000",
  "lastUpdate" : "2024-11-21T09:39:05.973+0000",
  "idSdi" : "11110",
  "pdfFile" : "ZEdWemRGQmtaZz09",
  "signed" : "true",
  "unsignedFile" : "ZEdWemRGVnVjMmxuYm1Waw==",
  "pddAvailable" : true
}

Response fields

Field Type Description

invoices

Array

Array of individual invoices in the batch

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)

username

String

Username of the owner of the invoice

creationDate

String

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

lastUpdate

String

Date of last update

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

signed

String

true if the invoice file is digitally signed, otherwise false

unsignedFile

String

Content of unsigned file in Base64 format

pdfFile

String

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

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.[].totalDocument

String

Total document

invoices.[].totalVat

String

Total Vat

invoices.[].netPayable

String

Net payable

invoices.[].documentType

String

Document type

9.3. getInvoiceZip

GET base url other methods/api/v2/invoices-in/zip

Returns an invoice with all of its notifications in Zip format (e.g. IT01879020517_abcde.xml.p7m). Search performed by invoiceId, invoice filename or idSdi.

HTTP request

GET /api/v2/invoices-in/zip?filename=IT01879020517_jtlk1.xml.p7m HTTP/1.1
Authorization: Bearer NLOGDVXLVaF3tzmnVPkTwpkuh7dG0i09uSCcog3u+rE=

Request headers

Unresolved directive in docs_EN.adoc - include::../../../target/generated-snippets/invoice-controller-v2-test/int_get-invoice-zip/request-headers.adoc[]

Request parameters

Parameter Description Constraints

filename

File name of invoice

Mandatory if neither id nor idSdi are specified

id

Invoice Id

Mandatory if neither idSdi nor filename are specified

idSdi

SdI Id

Mandatory if neither id nor filename are specified

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. pdd

GET base url other methods/api/v2/invoices-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), his ID(invoiceId) or his idSdi. If however pddAvailable is false, in other words, the Preservation package is not available, the HTTP status code 404 is returned.

HTTP request

GET /api/v2/invoices-in/pdd?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 of invoice

Mandatory if neither id nor idSdi are specified

id

Invoice Id

Mandatory if neither idSdi nor filename are specified

idSdi

SdI Id

Mandatory if neither id nor filename are 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>

10. Send Customer Result

10.1. sendEsitoCommittente

POST base url altri metodi/services/invoice/in/sendEsitoCommittente

The method enables the user to generate and send the Customer Result notification to SDI. A Customer Result notification can only be sent for invoices in FPA12 format, received within the previous 15 days.

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 (Exchange system) ID of invoice received

Mandatory

esito

String

Customer result: EC01 for Accepted, EC02 for Declined

Mandatory

numero

String

Invoice number

anno

Number

Year of the invoice

posizione

Number

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

descrizione

String

Description to be entered in the result, if any

messageId

String

ID of the message created by the customer

HTTP response

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

{
  "errorCode" : "000",
  "errorDescription" : "Operazione effettuata",
  "esitoFileName" : "IT01879020517_jtlk1_EC_001.xml"
}

Response fields

Field Type Description

errorCode

String

Error code

errorDescription

String

Error description

esitoFileName

String

Filename assigned by Aruba to customer result notification

Errors

errorCode errorDescription Description

000

Operazione effettuata

Result notification generated correctly

001

Fattura precedente a 15 giorni

Cannot generate a result notification for this invoice because it was received more than 15 days ago

002

Fattura non FPA12

Cannot generate a result notification for this invoice because it was not in FPA12 format

003

Deleghe non trovate

User with mandates is invalid

004

Fattura non trovata o precedente a 30 giorni

Cannot generate a result notification for this invoice because it does not exist or is older than 30 days

999

Errore generico

Cannot generate a result notification due to a general error, contact support

10.2. sendEsitoCommittente Status

GET base url altri metodi/services/invoice/in/sendEsitoCommittente/{filename}

HTTP request

GET /services/invoice/in/sendEsitoCommittente/IT01879020517_jtlk1_EC_001.xml 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

filename

Filename of customer result notification

HTTP response

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

{
  "filename" : "IT01879020517_jtlk1_EC_001.xml",
  "sdiId" : 1263,
  "esito" : "EC01",
  "numero" : "1",
  "anno" : 2024,
  "posizione" : 1,
  "descrizione" : "Fattura accettata",
  "messageId" : "7865",
  "status" : "OK",
  "errorDescription" : null
}

Response fields

Field Type Description

filename

String

Filename of customer result notification

sdiId

Number

SdI (Exchange system) ID of invoice received

esito

String

Customer result: EC01 for Accepted, EC02 for Declined

numero

String

Invoice number

anno

Number

Year of the invoice

posizione

Number

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

descrizione

String

Description to be entered in the result, if any

messageId

String

ID of the message created by the customer

status

String

Customer result status

errorDescription

Null

Description of error, if any

Status

status Descrizione

OK

Processed correctly

In elaborazione

Being processed

Errore Creazione

Error while creating

Errore SDI

Error sending SDI

Errore Archiviazione

Error occurred when archiving

Errore Elaborazione

Error occurred when processing

11. Find Notifications on Invoices Sent

Methods of finding notifications of sent invoices.

11.1. getNotifications

GET base url other methods/api/v2/invoices-out/notifications Finds notifications of an invoice by invoice ID or invoice filename (e.g. IT01879020517_abcde.xml.p7m).

HTTP request

GET /api/v2/invoices-out/notifications?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

id

Invoice Id

Mandatory if filename is not specified

filename

File name of invoice

Mandatory if id is not specified

HTTP response

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

{
  "count" : 1,
  "notifications" : [ {
    "date" : "2024-11-21T09:39:09.017Z",
    "docType" : "RC",
    "file" : "ZEdWemRBPT0=",
    "filename" : "IT01879020517_33825_RC_001.xml",
    "invoiceId" : "1",
    "notificationDate" : "2024-11-21T09:39:09.018Z",
    "number" : null,
    "result" : null
  } ]
}

Response fields

Field Type Description

count

Number

Number of notifications associated with the invoice

notifications

Array

Notifications associated with the invoice

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.2. getNotificationDetail

GET base url other methods/api/v2/invoices-out/notifications/detail

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

HTTP request

GET /api/v2/invoices-out/notifications/detail?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 of notification

Mandatory

HTTP response

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

{
  "date" : "2024-11-21T09:39:08.913Z",
  "docType" : "RC",
  "file" : "ZEdWemRBPT0=",
  "filename" : "IT01879020517_33825_RC_001.xml",
  "invoiceId" : "1",
  "notificationDate" : "2024-11-21T09:39:08.915Z",
  "number" : null,
  "result" : "EC01"
}

Response fields

Field Type Description

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. Find Notifications on Invoices Received

Methods of finding notifications of received invoices.

12.1. getNotifications

GET base url other methods/api/v2/invoices-in/notifications Finds notifications of an invoice by invoice ID or invoice filename (e.g. IT01879020517_abcde.xml.p7m).

HTTP request

GET /api/v2/invoices-in/notifications?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

id

Invoice Id

Mandatory if filename is not specified

filename

File name of invoice

Mandatory if id is not specified

HTTP response

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

{
  "count" : 1,
  "notifications" : [ {
    "date" : "2024-11-21T09:39:05.987Z",
    "docType" : "NS",
    "file" : "ZEdWemRBPT0=",
    "filename" : "IT01879020517_33822_RC_001.xml",
    "invoiceId" : "2",
    "notificationDate" : "2024-11-21T09:39:05.987Z",
    "number" : null,
    "result" : "EC01"
  } ]
}

Response fields

Field Type Description

count

Number

Number of notifications associated with the invoice

notifications

Array

Notifications associated with the invoice

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.2. getNotificationDetail

GET base url other methods/api/v2/invoices-in/notifications/detail

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

HTTP request

GET /api/v2/invoices-in/notifications/detail?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 of notification

Mandatory

HTTP response

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

{
  "date" : "2024-11-21T09:39:05.987Z",
  "docType" : "NS",
  "file" : "ZEdWemRBPT0=",
  "filename" : "IT01879020517_33825_RC_001.xml",
  "invoiceId" : "5",
  "notificationDate" : "2024-11-21T09:39:05.987Z",
  "number" : null,
  "result" : "EC01"
}

Response fields

Field Type Description

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)

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

  • 217.61.9.4

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.

  • Private users can only receive the createNotification callback for messages relating to invoices sent;

  • PA users can also receive the createNotification callback for messages relating to invoices received, for example DT notifications;

  • MT notification is not sent using the createNotification callback, both for private and PA users, but is sent using the createInvoice callback at the same time as the invoice in question.

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

notificationDate

String

Delivery date of notification in ISO 8601 format (e.g. 2022-09-15T15:37:15.840+02:00)

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)

updateDate

String

Date of update in ISO 8601 format (e.g. 2022-09-15T15:37:15.840+02:00)

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.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

POST https://demows.fatturazioneelettronica.aruba.it/services/sdisimulator/invoiceIn

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: 147

{
  "countryReceiver" : "IT",
  "vatcodeReceiver" : "01879020517",
  "fiscalcodeReceiver" : null,
  "invoiceFileName" : "IT81228079456_7i8tk.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

POST https://demows.fatturazioneelettronica.aruba.it/services/sdisimulator/notificationOut

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: 144

{
  "invoiceFileName" : "IT01879020517_aBcDe.xml.p7m",
  "notificationFileName" : "ITIT01879020517_aBcDe_175.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

2.1.0 - from 12/04/2024

Fixed

2.0.0 - from 21/03/2024

Changed

Version two

Financial comunication

Invoices sent

Invoices received

Notifications of invoices sent

Notifications of invoices received

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