change log link

Per consultare la documentazione v1 fare riferimento a Fatturazione Elettronica API Docs

1. Introduzione

I Web Services della Fatturazione Elettronica di Aruba sono a disposizione delle utenze Premium o utenze base a loro collegate mediante delega.

La "Fatturazione elettronica" è il processo digitale con cui si generano e si gestiscono le fatture nel corso del loro intero ciclo di vita:

  • generazione

  • emissione/ricezione

  • conservazione a norma

Per fattura elettronica si intende:

  • un documento informatico

  • strutturato secondo un linguaggio standard ovvero il formato .xml, tracciato «Fattura PA»

  • firmato digitalmente da chi la emette (per PA)

  • avente il contenuto minimo obbligatorio previsto dal DM 55/2013 (All. A)

  • da conservare a norma (ai sensi del DPCM 3 dicembre 2013) obbligatoriamente sia ai fini fiscali (decreto MEF 17 giugno 2014) che ai fini civilistici (Art.2220 del Codice Civile).

Gli attori coinvolti nel processo di Fatturazione Elettronica sono:

  • L’Operatore Economico (OE): il cedente/prestatore che emette fatture verso PA/PRIVATI o il soggetto cessionario/committente che riceve fatture elettroniche

  • L’Intermediario (Aruba PEC S.p.A): il soggetto incaricato dal cedente/prestatore o dal cessionario/committente di trasmettere e/o ricevere per proprio conto le fatture elettroniche veicolate tramite SDI

  • Sistema di Interscambio (SDI): struttura che fa capo al Ministero dell’Economia e delle Finanze attraverso la quale avviene la trasmissione delle fatture elettroniche verso l’Amministrazione (art.1, comma 211, legge 24 dicembre 2007 n. 244) o verso privati (art. 1, comma 2, decreto legislativo 127/2015)

I processi per l’invio (ciclo attivo) e ricezione (ciclo passivo) di fatture elettroniche mediante Fatturazione Elettronica di Aruba sono schematizzati nelle figure seguenti:

intro active cycle

  1. L’Operatore Economico crea la fattura in formato .xml (da proprio gestionale o da Pannello web) e invia la fattura mediante i canali web service.

  2. Aruba PEC (l’intermediario) controlla la conformità sul formato

  3. Aruba PEC appone la firma elettronica qualificata (facoltativa per B2b e B2C) tramite firma automatica Aruba PEC o del Cliente e la invia a SdI.

  4. SdI controlla e valida la fattura elettronica e la inoltra al destinatario (tramite codice destinatario o PEC) oppure a un terzo soggetto ricevente di cui il destinatario si avvale

  5. SdI restituisce ad Aruba PEC S.p.A. la notifica di scarto, mancata consegna o consegna della fattura.

  6. SdI, ricevute le notifiche di esito invio (accettazione/rifiuto) dal destinatario le inoltra ad Aruba PEC S.p.A. (flusso non previsto per B2b e B2C) che le recapita a OE.

  7. Passaggio in conservazione digitale a norma (obbligatoria) delle fatture inviate.

intro passive cycle

  1. L’Operatore economico o suo intermediario trasmette la fattura elettronica al Sistema di Interscambio utilizzando il codice destinatario di sette caratteri di Aruba PEC (intermediario in ricezione), fornito dal Sistema di Interscambio

  2. SdI invia la fattura ricevuta dal trasmittente al canale di ricezione WS di Aruba PEC (associato al codice destinatario)

  3. Aruba PEC recapita al Cliente la fattura elettronica ricevuta sulla base della Partita IVA mediante WS, applicazione web e/o PEC

  4. Aruba PEC conserva a norma le fatture elettroniche inviate tramite il sistema DocFly Conservazione digitale a norma

Per poter ricevere fatture elettroniche su Fatturazione Elettronica di Aruba, è necessario che vengano trasmesse al codice destinatario KRRH6B9.

Il Codice Destinatario è un codice numerico univoco a 7 cifre che viene rilasciato dall’Agenzia delle Entrate ai titolari di un canale di ricezione delle fatture elettroniche presso il Sistema di Interscambio (SdI). Tale codice, quindi, viene fornito o alle Partite IVA che hanno eseguito l’accreditamento presso l’Agenzia delle Entrate oppure agli intermediari accreditati che si occupano dello smistamento delle fatture ai destinatari (come Aruba).

Il codice destinatario di Aruba, necessario per ricevere le fatture elettroniche sull’applicazione Fatturazione Elettronica è: KRRH6B9.

Questa guida descrive il corretto utilizzo dei web service offerti dal sistema di Fatturazione Elettronica Aruba. La Fatturazione Elettronica Aruba mette a disposizione una serie di API REST con cui è possibile interfacciarsi per inviare fatture a SDI, ricercare le fatture inviate e ricevute, nonché inviare le comunicazioni finanziarie relative al "nuovo spesometro" (Liquidazioni periodiche IVA e Dati fatture).

Il sistema è inoltre predisposto per inviare le fatture ricevute (ciclo passivo) dai Web Services esposti dall’utente, che dovranno implementare una serie di requisiti tecnico-funzionali.

Il sistema prende in carico le richieste ricevute tramite i servizi, le elabora, controlla alcuni dati ed effettua l’invio al SdI (Sistema di Interscambio).

SdI elabora le richieste tramite controlli sui dati inviati e provvede, nel caso delle Comunicazioni Finanziarie, a generare un esito che il sistema di Aruba verifica e notifica ai propri clienti.

Nel caso della fattura elettronica SdI elabora i dati ricevuti, trasmette agli enti di Pubblica Amministrazione o Privati e notifica gli esiti direttamente al sistema di ARUBA.

I web services esposti permettono di provvedere alle Comunicazioni Finanziarie:

intro web services

… e al ciclo attivo di fatturazione:

intro web services active cycle

… e al ciclo passivo di fatturazione:

intro web services passive cycle

2. Ambienti

Sono previsti due ambienti per l’integrazione con i servizi di Fatturazione Elettronica.

DEMO: Ambiente con funzionalità equivalenti all’ambiente di produzione, ma accessibile solo temporaneamente, tramite uno specifico accreditamento. I dati inseriti sono validati e mantenuti per la duratà di validità dell’utente.

PRODUZIONE: Ambiente di produzione disponibile agli utenti titolari del servizio.

Nella tabella seguente vengono riportati i base url da anteporre ai path dei metodi di autenticazione (Capitolo Autenticazione) e degli altri metodi (Capitoli: Comunicazioni Finanziarie, Invio Fatture Elettroniche, Ricerca Fatture Inviate, Ricerca Fatture Ricevute, Invio Esito Committente, Ricerca Notifiche su Fatture Inviate e Ricerca Notifiche su Fatture Ricevute).

BASE URL

AMBIENTE

Demo

Produzione

Autenticazione

https://demoauth.fatturazioneelettronica.aruba.it

https://auth.fatturazioneelettronica.aruba.it

Altri metodi

https://demows.fatturazioneelettronica.aruba.it

https://ws.fatturazioneelettronica.aruba.it

Si ricorda che, ricevute le credenziali, è necessario completare la registrazione accedendo con esse al pannello web della Fatturazione Elettronica Aruba. Dal pannello web è inoltre possibile consultare i dati (es. fatture inviate, fatture ricevute) e configurare il servizio di Fatturazione Elettronica (es. ricezione email, richieste deleghe, cedenti).

Nella tabella seguente viene riportato il link al pannello web della fatturazione elettronica per gli ambienti di DEMO e PRODUZIONE.

LINK PANNELLO WEB

Demo

Produzione

https://demo.fatturazioneelettronica.aruba.it

https://fatturazioneelettronica.aruba.it

3. SLA (Service Level Agreement)

La API di Fatturazione Elettronica limita i client a un certo numero di chiamate, nella tabella seguente sono descritte tali limitazioni.

Servizio SLA

Nr. massimo richieste di autenticazione per IP

1 al minuto

Dimensione massima file inviati

5 MB

Nr. massimo richieste di invio fatture per IP (Upload invoice)

30 al minuto

Nr. massimo richieste di invio fatture già firmate per IP (Upload invoice signed)

30 al minuto

Nr. massimo richieste di ricerca fatture inviate per IP (Ricerca Fatture Inviate)

12 al minuto

Nr. massimo richieste di ricerca fatture ricevute per IP (Ricerca Fatture Ricevute)

12 al minuto

Nr. massimo richieste di ricerca notifiche di fatture inviate per IP (Ricerca Notifiche su Fatture Inviate)

12 al minuto

Nr. massimo richieste di ricerca notifiche di fatture ricevute per IP (Ricerca Notifiche su Fatture Ricevute)

12 al minuto

SLA complessivo sul servizio

99,95% uptime dell’interfaccia Web e dei Web Services

Presa in carico del file fattura

Entro 24 ore dal ricevimento da parte del cliente

Invio del file fattura al SDI

Entro 24 ore dalla presa in carico del file fattura

Invio della notifica esito al cliente

Entro 24 ore dalla ricezione dal Sistema di Interscambio

Invio file fattura e notifica esito al Sistema di Conservazione

Entro i tempi previsti dalla normativa vigente

4. HTTP status codes

Di seguito sono riportate gli HTTP status code che possono essere ricevuti da un client dell’API di Fatturazione Elettronica.

Status code Significato

200 OK

Risposta standard per le richieste HTTP andate a buon fine.

201 Created

La richiesta è stata soddisfatta, restituendo la creazione di una nuova risorsa

204 No Content

Il server ha processato con successo la richiesta e non restituirà nessun contenuto.

400 Bad Request

La richiesta non può essere soddisfatta a causa di errori di sintassi.

401 Unauthorized

Simile a 403/Forbidden, ma pensato per essere usato quando l’autenticazione è possibile ma è fallita o non può essere soddisfatta.

403 Forbidden

La richiesta è valida ma il server si rifiuta di soddisfarla. L’utente potrebbe non disporre delle autorizzazioni necessarie per accedere alla risorsa.

404 Not Found

La risorsa richiesta non è stata trovata.

413 Request Entity Too Large

Superate le limitazioni descritte in SLA (Service Level Agreement)

429 Too Many Requests

Superate le limitazioni descritte in SLA (Service Level Agreement)

500 Internal Server Error

Messaggio di errore generico senza alcun dettaglio.

5. Autenticazione

Per poter accedere al servizio di Fatturazione Elettronica è necessario procedere con l’autenticazione utilizzando i seguenti metodi.

per invocare i metodi di autenticazione il path del metodo va preceduto dall’apposito base URL

Poichè le chiamate ai metodi di Autenticazione vengono effettuate fornendo informazioni sensibili, è necessario che gli utenti li invochino proteggendo i propri dati come indicato di seguito.

Le informazioni sensibili non vanno passate nella query string. Passare informazioni sensibili in tale modalità le rende vulnerabili ad essere intercettate. Pertanto non devono essere effettuare chiamate come in questo esempio:

POST /auth/signin?username=Utente&password=Password&grant_type=password HTTP/1.1 (1)
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
1 Informazioni sensibili nella query string

Allo scopo di proteggere le comunicazioni, Aruba S.p.A bloccherà le chiamate verso i metodi di Autenticazione che presentano informazioni sensibili nella query string.

Le informazioni sensibili vanno passate nel request body, in modo da proteggerle sfruttando i benefici offerti dalla comunicazione HTTPS. Di seguito si riporta un esempio sul corretto utilizzo dei metodi di Autenticazione:

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

username=Utente&password=Password&grant_type=password (2)
1 Query string vuota
2 Informazioni sensibili nel body

5.1. signin

POST base url autenticazione/auth/signin

Il metodo serve a richiedere un token di autenticazione. Tale token è necessario per invocare i metodi dei vari server della Fatturazione Elettronica (Resource Server) che sono protetti dal sistema.

Il token scade dopo 30 minuti.

I seguenti parametri della richiesta devono essere in formato application/x-www-form-urlencoded con encoding UTF-8.

Parametro Descrizione Vincoli

grant_type

Tipologia di grant utilizzata per l’autenticazione. Normalmente uguale a "password"

Obbligatorio

username

Username dell’utente

Obbligatorio

password

Password dell’utente

Obbligatorio

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

Campo Tipo Descrizione

access_token

String

Token di accesso

token_type

String

Tipologia del token restituito. Costante = "bearer"

expires_in

Number

Numero di secondi di validità (rimanente) del token

refresh_token

String

Refresh Token da utilizzare per ottenere un nuovo token

as:client_id

String

Client che ha richiesto il token

userName

String

Utente Loggato

['.issued']

String

Data/Ora di emissione del ticket in formato: EEE, dd MMM yyyy HH:mm:ss z

['.expires']

String

Data/Ora di scadenza del ticket in formato: EEE, dd MMM yyyy HH:mm:ss z

In caso di errore, il sistema ritorna un HTTP status codes 400 Bad Request con la seguente 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."
}

dove

Campo Tipo Descrizione

error

String

Codice di Errore

error_description

String

Descrizione dell’errore

Il token di accesso deve essere utilizzato per richiamare i metodi seguenti. In particolare deve essere inserita nella richiesta HTTP un header così composto:

Nome Header Valore Header

Authorization

Bearer <access_token>
Le richieste prive di token autorizzativo (o con token errato / scaduto) riceveranno un HTTP status codes 401 Unauthorized con il messaggio: "Full authentication is required to access this resource".

5.2. refresh

POST base url autenticazione/auth/signin

Il token può essere rinnovato attraverso una richiesta di refresh che richiede i seguenti parametri in formato application/x-www-form-urlencoded con encoding UTF-8. Il refresh del token,evitando di inviare le credenziale di autenticazione, offre maggiore sicurezza ed è un’operazione più performante rispetto alla richiesta di un nuovo token mediante signin.

Se non viene specificato un refresh token valido, il metodo refresh restituisce l’errore "invalid_grant"
Il refresh token è valido per 60 minuti dopo l’emissione (.issued), pertanto permette di rinnovare il token fino a 30 minuti dopo la scadenza (.expires)

I seguenti parametri della richiesta devono essere in formato application/x-www-form-urlencoded con encoding UTF-8.

Parametro Descrizione Vincoli

grant_type

Costante = "refresh_token"

Obbligatorio

refresh_token

Token di refresh ritornato nella richiesta precedente

Obbligatorio

Ad esempio:

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

grant_type=refresh_token&refresh_token=ee4aae0c9d754ad08a657510cae82efe

La risposta è identica alla precedente, viene rilasciato un altro token di accesso (e relativo token di refresh).

5.3. userInfo

GET base url autenticazione/auth/userInfo

Questo metodo permette di recuperare le informazioni dell’utente relativo al token di autenticazione.

HTTP request

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

Request headers

Nome Descrizione

Authorization

Access token ottenuto da 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

Campo Tipo Descrizione

username

String

Nome utente

pec

String

Indirizzo pec

userDescription

String

Nome e cognome o ragione sociale

countryCode

String

Codice paese (es. IT per Italia)

vatCode

String

Partita IVA

fiscalCode

String

Codice fiscale

accountStatus.expired

Boolean

true se l’utenza è scaduta o sospesa, false altrimenti

accountStatus.expirationDate

String

Data scadenza utenza in formato yyyy-MM-dd

usageStatus.usedSpaceKB

Number

Spazio di conservazione utilizzato espresso in kilobyte

usageStatus.maxSpaceKB

Number

Spazio di conservazione acquistato espresso in kilobyte

5.4. multicedenti

GET base url autenticazione/auth/multicedenti

Questo metodo permette di recuperare le informazioni dei multicecedenti dell’utente Premium relativo al token di autenticazione.

HTTP request

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

Request headers

Nome Descrizione

Authorization

Access token ottenuto da signin

Request parameters

Parametro Descrizione Vincoli

countryCode

Codice paese (es. IT per Italia)

Non obbligatorio

vatCode

Partita IVA

Non obbligatorio

status

Stato multicedente

Non obbligatorio

size

dimensione della pagina (default 10)

Compreso tra 1 e 100

page

pagina richiesta (default 1)

compreso tra 1 e 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

Campo Tipo Descrizione

content

Array

Array dei multicedenti trovati

first

Boolean

true se la pagina trovata è la prima, altrimenti false

last

Boolean

true se la pagina trovata è l’ultima, altrimenti false

number

Number

Numero della pagina corrente

numberOfElements

Number

Numero di elementi ritornati

size

Number

Dimensione della pagina

totalElements

Null

Numero totale multicedenti trovati

totalPages

Number

Numero totale pagine

content[].countryCode

String

Codice paese (es. IT per Italia)

content[].creationDate

String

Date creazione

content[].description

String

Ragione sociale

content[].id

String

Identificativo multicedente

content[].status

String

Stato multicedente

content[].usedSpaceKB

Number

Spazio di conservazione utilizzato espresso in kilobyte

content[].vatCode

String

Partita IVA

5.5. multicedenteById

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

Questo metodo permette di recuperare le informazioni di un singolo multicedente.

HTTP request

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

Request headers

Nome Descrizione

Authorization

Access token ottenuto da 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

Campo Tipo Descrizione

countryCode

String

Codice paese (es. IT per Italia)

creationDate

String

Date creazione

description

String

Ragione sociale

id

String

Identificativo multicedente

status

String

Stato multicedente

usedSpaceKB

Number

Spazio di conservazione utilizzato espresso in kilobyte

vatCode

String

Partita IVA

5.6. Stato dei multicedenti

Stato Codice Stato Descrizione

Connesso

ACTIVE

Multicedente connesso

Sospeso

SUSPEND

Multicedente sospeso

Non Attivo

INACTIVE

Multicedente non attivo

In attesa di approvazione

PENDING

Multicedente in attesa di approvazione

6. Comunicazioni Finanziarie

financial reporting

I metodi esposti per le Comunicazioni Finanziarie permettono la creazione di una nuova richiesta di trasmissione a SdI oppure il recupero dello stato della propria richiesta presa in carico dal sistema di Aruba.

Le richieste di invio possono essere di due tipi:

  • Dati Fattura (cosiddetto spesometro): xml contenente i dati relativi a una o più fatture emesse verso più cessionari/committenti oppure una o più fatture ricevute anche da più cedenti /prestatori. Possono essere trasmessi in singolo file .xml oppure file ZIP contenenti più .xml.

  • Liquidazioni iva: file in formato .xml contenente i dati della comunicazione relativa al soggetto dichiarante. Possono essere trasmessi in singolo file .xml oppure file ZIP contenenti più .xml.

6.1. CreateTransmissionRequest

POST base url altri metodi /api/v2/comfin

Creazione di una nuova richiesta per la trasmissione di tipo "Comunicazioni Finanziarie".

Il campo dataFile deve contenere un documento xml che rispetta le specifiche dell’Agenzia delle Entrate. Tale documento deve essere firmato in modalità CADES e codificato in formato Base64.

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

Campo Tipo Descrizione Vincoli

userId

String

Identificativo univoco del cliente / utente, è uguale all’username quando viene chiamato da un cliente esterno.

comunicationType

String

Enumerazione che identifica il tipo di comunicazione CommunicationType

Obbligatorio

dataFile

String

Dati allegato in formato Base64

Obbligatorio

HTTP response

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

{
  "requestId" : "8XVJQQY4CGVDIBQN"
}

Response fields

Campo Tipo Descrizione

requestId

String

Codice univoco della richiesta utilizzato nelle successive comunicazioni (callback / on demand). Valorizzato solo in caso di esito positivo (nessun codice di errore).

6.2. GetTransmissionInfoRequest

GET base url altri metodi/api/v2/comfin/{requestId}

Servizio per l’interrogazione dello stato di una richiesta.

HTTP request

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

Path parameters

Parametro Descrizione

requestId

Identificativo univoco delle richiesta fornito nella fase di creazione

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

Campo Tipo Descrizione

result

String

Esito elaborazione richiesta

notifyResult

String

XML Base64 con la risposta ottenuta da SDI, solo quando il file è stato elaborato

elaboratedResult

String

Codice esito quando il file risulta essere elaborato da SDI

receiptTimestamp

String

Data e ora ricezione file da SDI

fileId

String

Identificativo univoco fornito da SDI nella richiesta

fileName

String

Nome del file generato secondo le specifiche del tipo di comunicazione

pddAvailable

Boolean

true se la comunicazione finanziaria e i relativi file di esito sono stati conservati (si veda pdd per il download del pacchetto di conservazione), false altrimenti

status

String

Stato

6.3. pdd

GET base url altri metodi/api/v2/comfin/{requestID}/pdd

Se pddAvailable è true, tale metodo permette di recuperare il pacchetto di Conservazione in formato Zip di una comunicazione finanziaria, specificando l’identificativo richiesta (requestID) di quest’ultima. Se invece pddAvailable è false, ovvero il pacchetto di Conservazione non è disponibile, viene restituito HTTP status code 404.

HTTP request

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

Path parameters

Parametro Descrizione

requestId

Identificativo univoco delle richiesta fornito nella fase di creazione

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

Liquidazione periodica IVA

DF

Dati fatture

6.5. Result

Valore Descrizione

SF01

In elaborazione

SF02

Elaborato

SF03

Errore

AR01

File allegato vuoto o non presente

AR02

Accesso non consentito

AR03

File non corretto

AR04

ID Richiesta non presente

AR05

Firma remota non effettuata

AR06

Invio a SDI non eseguito

AR07

Risposta esito SDI non pervenuta

AR08

Firma non corretta

AR09

Invio conto terzi non consentito

AR10

Raggiunto massimo numero fatture e comunicazioni finanziarie

AR20

ComunicationType errato

AR21

File non firmato

AR99

Errore generico

6.6. CodiceEsito

Valore Descrizione

ES01

Liquidazione periodica IVA

ES02

File valido con segnalazioni

ES03

Scartato

7. Invio Fatture Elettroniche

sending invoice

I metodi esposti permettono la creazione di una nuova richiesta di trasmissione a SdI di fatture verso la Pubblica Amministrazione o privati.

SdI verifica la correttezza formale del contenuto dei file trasmessi e li veicola verso il destinatario in essi indicato.

Le fatture, firmate o da firmare, devono essere inviate tramite file .xml secondo uno specifico formato stabilito da SdI.

7.1. Dati Trasmittente

E' stato introdotto il controllo sincrono sul campo ID Trasmittente (tag 1.1.1 <IdTrasmittente> [1] del tracciato XML), il quale dovrà essere valorizzato con il codice fiscale dell’intermediario Aruba PEC S.p.A.: 01879020517.

Sotto è riportato un esempio di compilazione della sezione 1.1 <DatiTrasmissione> [1] del file fattura XML:

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

7.2. Autofattura

L’autofattura è un documento fiscale simile alla fattura, emessa dal cessionario/committente (cliente) per conto del cedente/prestatore (fornitore). Si tratta di una tipologia di fattura molto particolare caratterizzata dal fatto che l’obbligo di applicazione dell’IVA e dell’emissione di fattura è a carico del cliente.

Per emettere una autofattura in formato elettronico è necessario avere cura di compilare il file XML nel seguente modo:

  • Popolare il campo 1.6 <SoggettoEmittente> con il valore "CC". Tale valore indica che la fattura è emessa dal Cessionario/Committente per conto del Cedente/Prestatore;

  • Popolare la sezione 1.4 <CessionarioCommittente> con i dati del soggetto emittente, ossia del Cedente/Prestatore indicato nell’anagrafica di Fatturazione Elettronica di Aruba (PIVA dell’utente);

  • Popolare la sezione 1.2 <CedentePrestatore> con i dati del fornitore.

Fatturazione Elettronica di Aruba verificherà il file XML ricevuto mediante i seguenti controlli sul soggetto emittente (cedente/prestatore indicato in anagrafica):

  • se non presente il tag 1.6 viene controllato che la P.IVA del soggetto emittente corrisponda alla P.IVA riportata sul cedente/prestatore (sezione 1.2 del file XML);

  • se presente il tag 1.6 compilato con il valore "CC" viene controllato che la P.IVA del soggetto emittente corrisponda alla P.IVA riportata sul cessionario/committente (sezione 1.4 del file XML);

  • se presente il tag 1.6 compilato con il valore "TZ" o se non rispettati i controlli sopra, la fattura non viene accettata dal sistema.

Le autofatture potranno essere emesse con uno dei seguenti "Tipo Documento", a seconda della tipologia di autofattura emessa: TD01, TD16, TD17, TD18, TD19, TD20, TD21, TD22, TD23, TD26, TD27.

Per maggiori informazioni sulle casistiche e modalità di creazione delle autofatture è possibile visionare anche le FAQ di:

  • Agenzia delle Entrate, disponibili al seguente link;

  • Assosoftware, disponibili al seguente link.

7.3. Upload invoice

POST base url altri metodi/services/invoice/upload

Questo metodo deve essere utilizzato dall’OE per effettuare l’invio di una fattura già nel formato XML secondo norme AGID, ma non ancora firmata digitalmente.

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
}
I parametri "domain" e "credential" rappresentano rispettivamente il dominio e le credenziali di firma automatica se possedute dall’utente, in caso contrario lasciare tali campi vuoti o ometterli.

Request headers

Nome Descrizione

Authorization

Access token ottenuto da signin

Request fields

Campo Tipo Descrizione Vincoli

dataFile

String

File fattura codificato in Base64

Obbligatorio

credential

String

Credenziali firma

domain

String

Domain firma

senderPIVA

String

Nel caso in cui la fattura che si intende trasmettere abbia TD26 (cessione di beni ammortizzabili e per passaggi interni ex art.36 DPR 633/72) come "2.1.1.1 <TipoDocumento>", il campo senderPIVA può essere utilizzato per specificare quale tra il cedente /prestatore e il cessionario/committente sia il mittente della fattura. Il campo senderPIVA, nel caso in cui venga utilizzato, deve riportare il codice nazione e la partita iva del mittente (es. IT99999999999 )

skipExtraSchema

Boolean

false di default. Se impostato a true non vengono effettuati i Controlli extraschema sincroni e i Controlli extraschema asincroni. I Controlli extraschema sincroni e i Controlli extraschema asincroni vengono in ogni caso effettuati dal Sistema di Interscambio

dryRun

Boolean

false di default. Se impostato a 'true' la fattura attraverserà le fasi di validazione ma non verrà inviata a 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

Campo Tipo Descrizione

uploadFileName

String

Nome file assegnato alla fattura

errorCode

String

Eventuale codice di errore Controlli Sincroni

errorDescription

String

Eventuale descrizione errore Controlli Sincroni e identificativo richiesta
Identificativo richiesta:
Nel campo errorDescription è stato inserito un identificativo richiesta, questo codice può essere riportato nelle richieste di assistenza al fine di velocizzarne la risoluzione.

7.4. Upload invoice signed

POST base url altri metodi/services/invoice/uploadSigned

Questo metodo deve essere utilizzato dall’OE per effettuare l’invio di una fattura nel formato XML e già firmata digitalmente secondo norme AGID:

  • con estensione .p7m e formato CAdES-BES (CMS Advanced Electronic Signatures);

  • con estensione .xml e formato XAdES-BES (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

Nome Descrizione

Authorization

Access token ottenuto da signin

Request fields

Campo Tipo Descrizione Vincoli

dataFile

String

File fattura codificato in Base64

Obbligatorio

senderPIVA

String

Nel caso in cui la fattura che si intende trasmettere abbia TD26 (cessione di beni ammortizzabili e per passaggi interni ex art.36 DPR 633/72) come "2.1.1.1 <TipoDocumento>", il campo senderPIVA può essere utilizzato per specificare quale tra il cedente /prestatore e il cessionario/committente sia il mittente della fattura. Il campo senderPIVA, nel caso in cui venga utilizzato, deve riportare il codice nazione e la partita iva del mittente (es. IT99999999999 )

skipExtraSchema

Boolean

false di default. Se impostato a true non vengono effettuati i Controlli extraschema sincroni e i Controlli extraschema asincroni. I Controlli extraschema sincroni e i Controlli extraschema asincroni vengono in ogni caso effettuati dal Sistema di Interscambio

dryRun

Boolean

false di default. Se impostato a 'true' la fattura attraverserà le fasi di validazione ma non verrà inviata a 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

Campo Tipo Descrizione

uploadFileName

String

Nome file assegnato alla fattura

errorCode

String

Eventuale codice di errore Controlli Sincroni

errorDescription

String

Eventuale descrizione errore Controlli Sincroni e identificativo richiesta
Identificativo richiesta:
Nel campo errorDescription è stato inserito un identificativo richiesta, questo codice può essere riportato nelle richieste di assistenza al fine di velocizzarne la risoluzione.

7.5. Controlli

Al fine di limitare il rischio di scarto il sistema Fatturazione Elettronica di Aruba effettua alcuni controlli sulle fatture elettroniche XML ricevute da Web Services. In particolare, il controllo dei file caricati viene eseguito in 2 fasi:

  • Controlli sincroni: vengono eseguiti nel momento in cui viene ricevuta la fattura da parte del sistema Fatturazione Elettronica di Aruba, consentendo un’analisi preliminare del file. L’esito di tali controlli comporta la presa in carico o il rifiuto della fattura ricevuta. L’esito dei controlli sincroni viene restituito immediatamente con uno dei messaggi indicati in Controlli Sincroni.

  • Controlli asincroni: vengono eseguiti successivamente alla presa in carico del file dai nostri sistemi. L’esito di tali controlli comporta l’assegnazione di uno stato alla fattura:

    • Se la fattura supera i controlli, viene inviata al Sistema di Interscambio e assegnato lo stato "Inviata";

    • Se la fattura non supera i controlli, non viene inviata al Sistema di Interscambio e viene assegnato lo stato "Errore Elaborazione". L’esito di tali controlli può essere recuperato mediante i metodi di ricerca delle fatture inviate findInvoices, getInvoiceDetail o mediante le Callback.

upload checks

7.5.1. Controlli Sincroni

Codice Messaggio Descrizione Controllo

0000

Operazione effettuata

Invio fattura effettuato correttamente

0001

Errore imprevisto generico

Errore generico

0002

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

Formato email non valido

0002

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

Fattura non presente

0012

Errore di autenticazione al sistema

Autenticazione dell’utente sul sistema fallita

0013

Errore in fase di salvataggio dati

Errore salvataggio su db

0033

Il file inviato supera la dimensione massima

Fattura superiore alla dimensione massima SLA (Service Level Agreement)

0034

File già inviato di recente

Il file è stato già inviato precedentemente ed è stato preso in carico dal sistema

0092

Errore in validazione XSD: "errore specifico"

Validazione xsd con la descrizione dell’errore specifico

0093

Errore deleghe non valide

Utente con deleghe non valide

0094

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

Id Trasmittente non presente o diverso da Aruba PEC S.p.A

0095

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

Il servizio è momentaneamente non disponibile, non è possibile verificare i permessi dell’utente.

0096

Errore di validazione: "codice" - "messaggio"

Errore di validazione (Controlli extra schema)

0097

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

E' necessario effettuare un aumento di spazio, ulteriori informazioni disponibili collegandosi al pannello web.

0098

Formato Base64 non valido.

La codifica in Base64 del file fattura non è valida.
Controlli extra schema

Per quanto riguarda i controlli sincroni per il messaggio 0096, "codice" e "messaggio" possono essere quelli nella seguente tabella:

Codice SdI Messaggio Fattura Ordinaria [1] Messaggio fattura semplificata (se differente) [1] Campo su cui si effettua il controllo Controllo effettuato

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>

Nel caso in cui l’elemento 1.1.4 <CodiceDestinatario> sia valorizzato con "XXXXXXX" (fattura emessa verso soggetti non residenti, non stabiliti, non identificati in Italia) viene controllato che il campo IdPaese del cessionario/committente contenga un valore diverso da "IT"

7.5.2. Controlli Asincroni

Messaggio Descrizione controllo

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

Errore nel parsing del file fattura

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

Iva cedente prestatore o paese ced prestatore null

FATRSM205 - Partita IVA non associato ad un utente Aruba

Partita iva non trovata

FATRSM208 - User non trovata contattare l’assistenza

Username non trovato

FATRSM212 - Errore di validazione: "codice" - "messaggio"

Errore di validazione (Controlli extra schema)

FATRSM217 - User non trovata contattare l’assistenza

Username non trovato

FATRSM218 - Delega non trovata contattare l’assistenza

Deleghe non trovate

FATRSM302 - Verifica della firma o firma errata in fattura

Firma non valida

FATRSM401 - File xml vuoto, contattare l’assistenza

File vuoto

FATRSM403 - Utenza ARUBA disabilitata, contattare l’assistenza

Utente disabilitato

NOTRSM201 - Errore formale nella notifica, contattare l’assistenza

Errore nel parsing del file notifica

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

Nome file notifica assente
Controlli extra schema

Per quanto riguarda i controlli asincroni per il messaggio FATRSM212, "codice" e "messaggio" possono essere quelli nella seguente tabella:

Codice SdI Messaggio Fattura Ordinaria [1] Messaggio fattura semplificata (se differente) [1] Campo su cui si effettua il controllo Controllo effettuato

00305

1.4.1.1.2 <IdCodice> non valido

1.4.1.1.2 <IdCodice>

00306

1.4.1.2 <CodiceFiscale> non valido

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

Viene controllato che sia valorizzato, se l’elemento informativo 2.2.1.12 <AliquotaIVA> è pari a "0.00", e che non sia valorizzato, se l’elemento informativo 2.2.1.12 <AliquotaIVA> è diverso

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>

Viene controllato che sia valorizzato, se l’elemento informativo 2.2.1.12 <AliquotaIVA> è pari a "0.00", e che non sia valorizzato, se l’elemento informativo 2.2.1.12 <AliquotaIVA> è diverso da "0.00" (salvo il caso in cui l’elemento 2.1.1.1 <TipoDocumento> sia pari a TD16)

00403

2.1.1.3 <Data> successiva alla data di ricezione

2.1.1.3 <Data>

Viene controllato che non sia successiva alla data in cui il file è stato ricevuto dal Sistema di Interscambio. Inoltre, se l’elemento informativo 2.1.1.1 <TipoDocumento> vale "TD04", viene controllato che non sia antecedente a quella presente nell’elemento informativo 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>

Viene controllata la presenza di questo blocco in presenza di almeno un blocco 2.2.1 <DettaglioLinee> con l’elemento 2.2.1.13 <Ritenuta> uguale a 'SI' e/o di un blocco 2.1.1.7 <DatiCassaPrevidenziale> con l’elemento 2.1.1.7.6 <Ritenuta> uguale a '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>

Viene controllato che sia valorizzato, se l’elemento informativo 2.1.1.7.5 <AliquotaIVA> è pari a "0.00", e che non sia valorizzato, se l’elemento informativo 2.1.1.7.5 <AliquotaIVA> è diverso da "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>

Se è valorizzato a "SI", viene controllato che esista il blocco 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> e 1.4.1.2 <CodiceFiscale>

1.4.1.2 <CodiceFiscale>: Se non è valorizzato, viene controllato che sia valorizzato il blocco 1.4.1.1 <IdFiscaleIVA>, se valorizzato, viene controllata la sua esistenza in Anagrafe Tributaria

00418

2.1.1.3 <Data> antecedente a 2.1.6.3 <Data>

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

Viene controllato che il numero di blocchi 2.2.2. <DatiRiepilogo> sia maggiore o uguale al numero di aliquote IVA presenti nel documento

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> o 2.2.2.7 <EsigibilitaIVA>

Se 2.2.2.2 <Natura> è valorizzato a "N6", viene controllato che l’elemento informativo 2.2.2.7 <EsigibilitaIVA> non sia valorizzato a "S". Viene controllato che sia valorizzato, se l’elemento informativo 2.2.2.1 <AliquotaIVA> è pari a "0.00", e che non sia valorizzato, se l’elemento informativo 2.2.2.1 <AliquotaIVA> è diverso da "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> o 2.2.2.1< AliquotaIVA> o 2.1.1.7.5 <AliquotaIVA>

Viene controllato che il valore sia espresso in termini percentuali (es.: "22.00" e non "0.22")

00425

2.1.1.4 <Numero> non contenente caratteri numerici

2.1.1.4 <Numero>

Viene controllato che contenga almeno un carattere numerico

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>

00428

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

1.1.3 <FormatoTrasmissione>

Viene controllata la coerenza con l’elemento informativo 1.1.4 <CodiceDestinatario>: se vale "FPA12", l’elemento informativo 1.1.4 deve essere di 6 caratteri; se vale "FPR12", l’elemento informativo 1.1.4 deve essere di 7 caratteri.

00429

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

2.2.2.2 <Natura>

00430

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

2.2.2.2 <Natura>

Viene controllato che sia valorizzato, se l’elemento informativo 2.2.2.1 <AliquotaIVA> è pari a "0.00", e che non sia valorizzato, se l’elemento informativo 2.2.2.1 <AliquotaIVA> è diverso da "0.00" (salvo il caso in cui l’elemento 2.1.1.1 <TipoDocumento> sia pari a 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>: Se valorizzato, viene controllato che esista almeno uno dei due elementi 2.1.1.8.2 <Percentuale> e 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

Se valorizzato, viene controllato che esista almeno uno dei due elementi 2.2.1.10.2 <Percentuale> e 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>

Viene controllato che il valore espresso in questo elemento sia anche presente nell’elemento 2.2.2.1 <AliquotaIVA> di uno dei blocchi 2.2.2 <DatiRiepilogo> presenti in fattura. Viene controllato che il valore espresso in questo elemento sia anche presente nell’elemento 2.2.1.12 <AliquotaIVA> di uno dei blocchi 2.2.1 <DettaglioLinee> presenti in fattura o nell’elemento 2.1.1.7.5 <AliquotaIVA> di uno dei blocchi 2.1.1.7 <DatiCassaPrevidenziale> presenti in fattura

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>

Viene controllato che il valore espresso in questo elemento sia anche presente nell’elemento 2.2.2.1 <AliquotaIVA> di uno dei blocchi 2.2.2 <DatiRiepilogo> presenti in fattura. Viene controllato che il valore espresso in questo elemento sia anche presente nell’elemento 2.2.1.14 <Natura> di uno dei blocchi 2.2.1 <DettaglioLinee> presenti in fattura o nell’elemento 2.1.1.7.7 <Natura> di uno dei blocchi 2.1.1.7 <DatiCassaPrevidenziale> presenti in fattura

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)

Dal primo gennaio 2021 viene controllato che il valore espresso in questo elemento sia diverso da N2, N3 e N6 (valori non più ammessi)

00460

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

2.2.2 <Importo>

Il valore di questo campo (o la somma dei valori di questo campo in caso di presenza di più blocchi 2.2 <DatiBeniServizi>) non deve eccedere il limite di 400,00 euro. Il superamento di tale limite è consentiro solo se presente il blocco 2.1.2 <DatiFatturaRettificata>

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>

Se l’elemento informativo 2.1.1.1 <TipoDocumento> vale TD01, TD02, TD03, TD06, TD16, TD17, TD18, TD19, TD20, TD24, TD25 o TD28, viene controllato che il cedente/prestatore e il cessionario/committente siano soggetti diversi

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>

Se l’elemento informativo 2.1.1.1 <TipoDocumento> vale TD21 o TD27, viene controllato che il cedente/prestatore e il cessionario/committente siano uguali

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>

Se l’elemento informativo 2.1.1.1 <TipoDocumento> vale TD17, TD18, TD19 o TD28, viene effettuato il controllo sul campo 1.2.1.1.1<IdPaese> del cedente/prestatore che deve essere diverso da "IT" e, nel caso di TD28, deve essere uguale a "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>

Se l’elemento informativo 2.1.1.1 <TipoDocumento> vale TD21, viene controllato che non esista alcuna riga di fattura con il campo 2.2.1.12<AliquotaIVA> valorizzato a zero

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>

Se l’elemento informativo 2.1.1.1 <TipoDocumento> vale TD16, TD17, TD18, TD19, TD20, TD22, TD23 o TD28, viene controllato che sia valorizzato il blocco 1.4.1.1 <IdFiscaleIVA> del cessionario/committente

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>

Se l’elemento informativo 1.2.1.1.1 <IdPaese> ha un valore diverso da "IT", viene verificato che l’elemento informativo 1.4.1.1.1 <IdPaese> non sia anche esso diverso da "IT"

8. Ricerca Fatture Inviate

Metodi di ricerca fatture inviate.

8.1. Stati delle fatture

Di seguito l’elenco degli Stati delle fatture che è possibile ottenere invocando i metodi descritti in questo capitolo e nel prossimo.

Stato Codice Stato Tipo Notifica SDI Descrizione

Presa in carico

1

La fattura è in attesa di essere elaborata dai sistemi di Aruba e non risulta ancora trasmessa a SDI.

Errore Elaborazione

2

Si è verificato un errore nell’elaborazione della fattura (Problema tecnico nell' invio allo SDI).

Inviata

3

La fattura è stata inviata al Sistema di Interscambio (SDI).

Scartata

4

NS

La fattura è stata rifiutata dal Sistema di Interscambio (SDI) che ha restituito un codice di errore specifico.

Non Consegnata

5

MC

La consegna della fattura da parte del Sistema di Interscambio (SDI) è fallita. Solo per le PA, verranno fatti ulteriori tentativi di consegna nei 10 giorni seguenti.

Recapito Impossibile

6

AT

La consegna della fattura da parte del Sistema di Intercambio (SDI) non è andata a buon fine. Non verranno effettuati ulteriori tentativi di consegna.

Consegnata

7

RC

La fattura è stata consegnata da parte del Sistema di Interscambio (SDI).

Accettata

8

NE (EC01)

Il cliente ha accettato la fattura consegnata dal Sistema di Interscambio (SDI).

Rifiutata

9

NE (EC02)

Il cliente ha rifiutato la fattura consegnata dal Sistema di Interscambio (SDI).

Decorrenza Termini

10

DT

La fattura è stata consegnata da parte del Sistema di Interscambio (SDI) ma il cliente non ha inoltrato alcuna risposta nei 15 successivi alla consegna.

Ricevuta

MT

Le fatture ricevute sono accompagnate dalla Notifica Metadati che il Sistema di Interscambio (SDI) invia al destinatario insieme alla fattura

8.2. findInvoices

GET base url altri metodi/api/v2/invoices-out

Questo metodo restituisce l’elenco delle fatture elettroniche inviate dall’utente e prese in carico dal sistema. La lista di Fatture ritorna senza il contenuto in base64 (lazy loading).

HTTP request

GET /api/v2/invoices-out HTTP/1.1
Accept: application/json
Authorization: Bearer NLOGDVXLVaF3tzmnVPkTwpkuh7dG0i09uSCcog3u+rE=

Request headers

Nome Descrizione

Authorization

Access token ottenuto da signin

Request parameters

Parametro Descrizione Vincoli

page

pagina richiesta (default 1)

Compreso tra 1 e totalPages

size

dimensione della pagina (default 10)

Compreso tra 1 e 100

creationStartDate

Data creazione fattura (da)

Obbligatorio, in formato ISO 8601, la differenza con creationEndDate non può essere maggiore di 2 giorni

creationEndDate

Data creazione fattura (a)

Obbligatorio, in formato ISO 8601, la differenza con creationStartDate non può essere maggiore di 2 giorni

senderCountry

Codice Paese del cedente/prestatore

Obbligatorio se si utilizza un’utenza Premium

senderVatcode

Partita iva del cedente/prestatore

Obbligatorio se si utilizza un’utenza Premium

receiverCountry

Codice Paese del cessionario/committente

receiverVatcode

Partita iva del cessionario/committente

receiverFiscalcode

Codice fiscale del cessionario/committente

status

Stato della fattura

documentType

Tipo di documento

modifiedStartDate

Data ultima modifica fattura (da)

In formato ISO 8601

modifiedEndDate

Data ultima modifica fattura (a)

In formato ISO 8601

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

Campo Tipo Descrizione

content

Array

Array delle fatture trovate

last

Boolean

true se la pagina trovata è l’ultima, altrimenti false

totalElements

Number

Numero totale fatture trovate

totalPages

Number

Numero totale pagine

size

Number

Dimensione della pagina

number

Number

Numero della pagina corrente

first

Boolean

true se la pagina trovata è la prima, altrimenti false

numberOfElements

Number

Numero di elementi ritornati

content[].invoices

Array

Array delle singole fatture presenti nel lotto

content[].id

String

Identificativo fattura

content[].sender

Company

Company sender

content[].receiver

Company

Company receiver

content[].invoiceType

String

Formato trasmissione (es. 'FPA12' o 'FPR12', …​)

content[].docType

String

out per fattura inviata, in per fattura ricevuta

content[].file

String

File in formato Base64

content[].filename

String

Filename (es. IT01879020517_abcde.xml.p7m)

content[].username

String

Username del proprietario della fattura

content[].creationDate

String

Data di creazione, ovvero la data in cui la fattura è stata recepita dalla Fatturazione Elettronica Aruba

content[].lastUpdate

String

Data di ultimo aggiornamento

content[].idSdi

String

Identificativo SdI (Sistema di Interscambio)

content[].pddAvailable

Boolean

true se la fattura e le relative notifiche sono state conservate (si veda getInvoicePdd per il download del pacchetto di conservazione), false altrimenti

content[].channelGroup

Number

Canale della fattura

content[].shopName

String

Nome dello shop nel caso la fattura provenga da ecommerce

content[].sdiErrors

Array

Lista di errori presenti nell’eventuale notifica di scarto

content[].sender.description

String

Denominazione cedente prestatore

content[].sender.countryCode

String

Codice nazione cedente prestatore(es. 'IT', 'DE', …​)

content[].sender.vatCode

String

Partita IVA cedente prestatore

content[].sender.fiscalCode

String

Codice fiscale cedente prestatore

content[].receiver.description

String

Denominazione cessionario committente

content[].receiver.countryCode

String

Codice nazione cessionario committente(es. 'IT', 'DE', …​)

content[].receiver.vatCode

String

Partita IVA cessionario committente

content[].receiver.fiscalCode

String

Codice fiscale cessionario committente

content[].invoices.[].invoiceDate

String

Data della fattura

content[].invoices.[].number

String

Numero della fattura

content[].invoices.[].totalDocument

String

Totale documento

content[].invoices.[].totalVat

String

Totale iva

content[].invoices.[].netPayable

String

Netto

content[].invoices.[].documentType

String

Tipo documento

content[].invoices.[].status

String

Stato della fattura

content[].invoices.[].statusDescription

String

Contiene uno dei messaggi in Controlli asincroni se status è Errore Elaborazione,altrimenti null

8.3. getInvoiceDetail

GET base url altri metodi/api/v2/invoices-out/detail

Ricerca una singola fattura per Id, invoice filename o idSdi.

HTTP request

GET /api/v2/invoices-out/detail?id=1 HTTP/1.1
Accept: application/json
Authorization: Bearer NLOGDVXLVaF3tzmnVPkTwpkuh7dG0i09uSCcog3u+rE=

Request headers

Nome Descrizione

Authorization

Access token ottenuto da signin

Request parameters

Parametro Descrizione Vincoli

id

Identificativo fattura

Obbligatorio se non sono specificati né filename né idSdi

filename

Nome del file fattura

Obbligatorio se non sono specificati né id né idSdi

idSdi

Identificativo SdI

Obbligatorio se non sono specificati né id né filename

includePdf

Se impostato a true, viene incluso il campo pdfFile nella response

Non obbligatorio, di default è false

includeFile

Se impostato a false, viene escluso il campo file dalla response

Non obbligatorio, di default è 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

Campo Tipo Descrizione

invoices

Array

Array delle singole fatture presenti nel lotto

id

String

Identificativo fattura

sender

Company

Company sender

receiver

Company

Company receiver

invoiceType

String

Formato trasmissione (es. 'FPA12' o 'FPR12', …​)

docType

String

out per fattura inviata, in per fattura ricevuta

file

String

File in formato Base64

filename

String

Filename (es. IT01879020517_abcde.xml.p7m)

username

String

Username del proprietario della fattura

creationDate

String

Data di creazione, ovvero la data in cui la fattura è stata recepita dalla Fatturazione Elettronica Aruba

lastUpdate

String

Data di ultimo aggiornamento

idSdi

String

Identificativo SdI (Sistema di Interscambio)

pddAvailable

Boolean

true se la fattura e le relative notifiche sono state conservate (si veda getInvoicePdd per il download del pacchetto di conservazione), false altrimenti

channelGroup

Number

Canale della fattura

shopName

String

Nome dello shop nel caso la fattura provenga da ecommerce

sdiErrors

Array

Lista di errori presenti nell’eventuale notifica di scarto

pdfFile

String

File pdf in formato Base64. pdfFile è presente se il request parameter includePdf è impostato a true

sender.description

String

Denominazione cedente prestatore

sender.countryCode

String

Codice nazione cedente prestatore(es. 'IT', 'DE', …​)

sender.vatCode

String

Partita IVA cedente prestatore

sender.fiscalCode

String

Codice fiscale cedente prestatore

receiver.description

String

Denominazione cessionario committente

receiver.countryCode

String

Codice nazione cessionario committente(es. 'IT', 'DE', …​)

receiver.vatCode

String

Partita IVA cessionario committente

receiver.fiscalCode

String

Codice fiscale cessionario committente

invoices.[].invoiceDate

String

Data della fattura

invoices.[].number

String

Numero della fattura

invoices.[].totalDocument

String

Totale documento

invoices.[].totalVat

String

Totale iva

invoices.[].netPayable

String

Netto

invoices.[].documentType

String

Tipo documento

invoices.[].status

String

Stato della fattura

invoices.[].statusDescription

String

Contiene uno dei messaggi in Controlli asincroni se status è Errore Elaborazione,altrimenti null

8.4. getInvoiceZip

GET base url altri metodi/api/v2/invoices-out/zip

Ritorna una fattura con tutte le sue notifiche in formato Zip (es. IT01879020517_abcde.xml.p7m). Ricerca eseguita per Id fattura, invoice filename o idSdi.

HTTP request

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

Request headers

Nome Descrizione

Authorization

Access token ottenuto da signin

Request parameters

Parametro Descrizione Vincoli

filename

Nome del file fattura

Obbligatorio se non sono specificati né id né idSdi

id

Identificativo fattura

Obbligatorio se non sono specificati né filename né idSdi

idSdi

Identificativo SdI

Obbligatorio se non sono specificati né id né filename

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

Se pddAvailable è true, tale metodo permette di recuperare il pacchetto di Conservazione in formato Zip di una fattura inviata, specificando il nome file (filename), l’identificativo (id) o l’idSdi (idSdi) di quest’ultima. Se invece pddAvailable è false, ovvero il pacchetto di Conservazione non è disponibile, viene restituito HTTP status code 404.

HTTP request

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

Request headers

Nome Descrizione

Authorization

Access token ottenuto da signin

Request parameters

Parametro Descrizione Vincoli

filename

Nome del file fattura

Obbligatorio se non sono specificati né id né idSdi

id

Identificativo fattura

Obbligatorio se non sono specificati né filename né idSdi

idSdi

Identificativo SdI

Obbligatorio se non sono specificati né id né filename

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. Ricerca Fatture Ricevute

searching received invoice

Metodi di ricerca fatture ricevute.

9.1. findInvoices

GET base url altri metodi/api/v2/invoices-in

Questo metodo restituisce l’elenco delle fatture elettroniche ricevute dall’utente e prese in carico dal sistema. La lista di Fatture ritorna senza il contenuto in base64 (lazy loading).

HTTP request

GET /api/v2/invoices-in HTTP/1.1
Accept: application/json
Authorization: Bearer NLOGDVXLVaF3tzmnVPkTwpkuh7dG0i09uSCcog3u+rE=

Request headers

Nome Descrizione

Authorization

Access token ottenuto da signin

Request parameters

Parametro Descrizione Vincoli

page

pagina richiesta (default 1)

Compreso tra 1 e totalPages

size

dimensione della pagina (default 10)

Compreso tra 1 e 100

creationStartDate

Data creazione fattura (da)

Obbligatorio, in formato ISO 8601, la differenza con creationEndDate non può essere maggiore di 2 giorni

creationEndDate

Data creazione fattura (a)

Obbligatorio, in formato ISO 8601, la differenza con creationStartDate non può essere maggiore di 2 giorni

senderCountry

Codice Paese del cedente/prestatore

senderVatcode

Partita iva del cedente/prestatore

senderFiscalcode

Codice fiscale del cedente/prestatore

receiverCountry

Codice Paese del cessionario/committente

Obbligatorio se si utilizza un’utenza Premium

receiverVatcode

Parita iva del cessionario/committente

Obbligatorio se si utilizza un’utenza Premium

documentType

Tipo di documento

modifiedStartDate

Data ultima modifica fattura (da)

In formato ISO 8601

modifiedEndDate

Data ultima modifica fattura (a)

In formato ISO 8601

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

Campo Tipo Descrizione

content

Array

Array delle fatture trovate

last

Boolean

true se la pagina trovata è l’ultima, altrimenti false

totalElements

Number

Numero totale fatture trovate

totalPages

Number

Numero totale pagine

size

Number

Dimensione della pagina

number

Number

Numero della pagina corrente

first

Boolean

true se la pagina trovata è la prima, altrimenti false

numberOfElements

Number

Numero di elementi ritornati

content[].invoices

Array

Array delle singole fatture presenti nel lotto

content[].id

String

Identificativo fattura

content[].sender

Company

Company sender

content[].receiver

Company

Company receiver

content[].invoiceType

String

Formato trasmissione (es. 'FPA12' o 'FPR12', …​)

content[].docType

String

out per fattura inviata, in per fattura ricevuta

content[].file

String

File in formato Base64

content[].filename

String

Filename (es. IT01879020517_abcde.xml.p7m)

content[].username

String

Username del proprietario della fattura

content[].creationDate

String

Data di creazione, ovvero la data in cui la fattura è stata recepita dalla Fatturazione Elettronica Aruba

content[].lastUpdate

String

Data di ultimo aggiornamento

content[].idSdi

String

Identificativo SdI (Sistema di Interscambio)

content[].pddAvailable

Boolean

true se la fattura e le relative notifiche sono state conservate (si veda getInvoicePdd per il download del pacchetto di conservazione), false altrimenti

content[].sender.description

String

Denominazione cedente prestatore

content[].sender.countryCode

String

Codice nazione cedente prestatore(es. 'IT', 'DE', …​)

content[].sender.vatCode

String

Partita IVA cedente prestatore

content[].sender.fiscalCode

String

Codice fiscale cedente prestatore

content[].receiver.description

String

Denominazione cessionario committente

content[].receiver.countryCode

String

Codice nazione cessionario committente(es. 'IT', 'DE', …​)

content[].receiver.vatCode

String

Partita IVA cessionario committente

content[].receiver.fiscalCode

String

Codice fiscale cessionario committente

content[].invoices.[].invoiceDate

String

Data della fattura

content[].invoices.[].number

String

Numero della fattura

content[].invoices.[].totalDocument

String

Totale documento

content[].invoices.[].totalVat

String

Totale iva

content[].invoices.[].netPayable

String

Netto

content[].invoices.[].documentType

String

Tipo documento

9.2. getInvoiceDetail

GET base url altri metodi/api/v2/invoices-in/detail

Ricerca una singola fattura per Id, invoice filename o idSdi.

HTTP request

GET /api/v2/invoices-in/detail?id=1 HTTP/1.1
Accept: application/json
Authorization: Bearer NLOGDVXLVaF3tzmnVPkTwpkuh7dG0i09uSCcog3u+rE=

Request headers

Nome Descrizione

Authorization

Access token ottenuto da signin

Request parameters

Parametro Descrizione Vincoli

id

Identificativo fattura

Obbligatorio se non sono specificati né filename né idSdi

filename

Nome del file fattura

Obbligatorio se non sono specificati né id né idSdi

idSdi

Identificativo SdI

Obbligatorio se non sono specificati né id né filename

includePdf

Se impostato a true, viene incluso il campo pdfFile nella response

Non obbligatorio, di default è false

includeFile

Se impostato a false, viene escluso il campo file dalla response

Non obbligatorio, di default è true

includeUnsignedFile

Se impostato a true, viene incluso il campo unsignedFile dalla response

Non obbligatorio, di default è 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

Campo Tipo Descrizione

invoices

Array

Array delle singole fatture presenti nel lotto

id

String

Identificativo fattura

sender

Company

Company sender

receiver

Company

Company receiver

invoiceType

String

Formato trasmissione (es. 'FPA12' o 'FPR12', …​)

docType

String

out per fattura inviata, in per fattura ricevuta

file

String

File in formato Base64

filename

String

Filename (es. IT01879020517_abcde.xml.p7m)

username

String

Username del proprietario della fattura

creationDate

String

Data di creazione, ovvero la data in cui la fattura è stata recepita dalla Fatturazione Elettronica Aruba

lastUpdate

String

Data di ultimo aggiornamento

idSdi

String

Identificativo SdI (Sistema di Interscambio)

pddAvailable

Boolean

true se la fattura e le relative notifiche sono state conservate (si veda getInvoicePdd per il download del pacchetto di conservazione), false altrimenti

signed

String

true se il file fattura è firmato digitalmente, false altrimenti

unsignedFile

String

Contenuto del file senza la firma in formato Base64

pdfFile

String

File pdf in formato Base64. pdfFile è presente se il request parameter includePdf è impostato a true

pdfFile

String

File pdf in formato Base64. pdfFile è presente se il request parameter includePdf è impostato a true

sender.description

String

Denominazione cedente prestatore

sender.countryCode

String

Codice nazione cedente prestatore(es. 'IT', 'DE', …​)

sender.vatCode

String

Partita IVA cedente prestatore

sender.fiscalCode

String

Codice fiscale cedente prestatore

receiver.description

String

Denominazione cessionario committente

receiver.countryCode

String

Codice nazione cessionario committente(es. 'IT', 'DE', …​)

receiver.vatCode

String

Partita IVA cessionario committente

receiver.fiscalCode

String

Codice fiscale cessionario committente

invoices.[].invoiceDate

String

Data della fattura

invoices.[].number

String

Numero della fattura

invoices.[].totalDocument

String

Totale documento

invoices.[].totalVat

String

Totale iva

invoices.[].netPayable

String

Netto

invoices.[].documentType

String

Tipo documento

9.3. getInvoiceZip

GET base url altri metodi/api/v2/invoices-in/zip

Ritorna una fattura con tutte le sue notifiche in formato Zip (es. IT01879020517_abcde.xml.p7m). Ricerca eseguita per Id fattura, invoice filename o 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.adoc - include::../../../target/generated-snippets/invoice-controller-v2-test/int_get-invoice-zip/request-headers.adoc[]

Request parameters

Parametro Descrizione Vincoli

filename

Nome del file fattura

Obbligatorio se non sono specificati né id né idSdi

id

Identificativo fattura

Obbligatorio se non sono specificati né filename né idSdi

idSdi

Identificativo SdI

Obbligatorio se non sono specificati né id né filename

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

GET base url altri metodi/api/v2/invoices-in/pdd

Se pddAvailable è true, tale metodo permette di recuperare il pacchetto di Conservazione in formato Zip di una fattura inviata, specificando il nome file (filename), l’identificativo (id) o l’idSdi (idSdi) di quest’ultima. Se invece pddAvailable è false, ovvero il pacchetto di Conservazione non è disponibile, viene restituito HTTP status code 404.

HTTP request

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

Request headers

Nome Descrizione

Authorization

Access token ottenuto da signin

Request parameters

Parametro Descrizione Vincoli

filename

Nome del file fattura

Obbligatorio se non sono specificati né id né idSdi

id

Identificativo fattura

Obbligatorio se non sono specificati né filename né idSdi

idSdi

Identificativo SdI

Obbligatorio se non sono specificati né id né filename

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. Invio Esito Committente

10.1. sendEsitoCommittente

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

Il metodo consente all’utente di generare e inviare a SDI la notifica di Esito Committente. É possibile inviare una notifica di Esito Committente solo per fatture ricevute da meno di 15 giorni che abbiano formato trasmissione FPA12.

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

Nome Descrizione

Authorization

Access token ottenuto da signin

Request fields

Campo Tipo Descrizione Vincoli

filename

String

Nome della fattura ricevuta

Obbligatorio

sdiId

Number

Identificativo SdI (Sistema di Interscambio) della fattura ricevuta

Obbligatorio

esito

String

Esito committente: EC01 per Accettata, EC02 per Rifiutata

Obbligatorio

numero

String

Numero della fattura

anno

Number

Anno della fattura

posizione

Number

Posizione della fattura nel file (1, 2 ecc.)

descrizione

String

Eventuale descrizione da inserire nell’esito

messageId

String

ID del messaggio a cura del committente

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

Campo Tipo Descrizione

errorCode

String

Codice errore

errorDescription

String

Descrizione errore

esitoFileName

String

Nome file assegnato da Aruba alla notifica di esito committente

Errori

errorCode errorDescription Descrizione

000

Operazione effettuata

Notifica di esito generata correttamente

001

Fattura precedente a 15 giorni

Non è possibile generare una notifica di esito per la fattura perchè quest’ultima è stata ricevuta da piu' di 15 giorni

002

Fattura non FPA12

Non è possibile generare una notifica di esito per la fattura perchè il formato trasmissione di quest’ultima non è FPA12

003

Deleghe non trovate

Utente con deleghe non valide

004

Fattura non trovata o precedente a 30 giorni

Non è possibile generare una notifica di esito per la fattura perchè non esiste o è precedente a 30 giorni

999

Errore generico

Non è possibile generare una notifica di esito per un errore generico, contattare l’assistenza

10.2. Stato sendEsitoCommittente

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

Nome Descrizione

Authorization

Access token ottenuto da signin

Path parameters

Parametro Descrizione

filename

Nome file della notifica di esito committente

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

Campo Tipo Descrizione

filename

String

Nome file della notifica di esito committente

sdiId

Number

Identificativo SdI (Sistema di Interscambio) della fattura ricevuta

esito

String

Esito committente: EC01 per Accettata, EC02 per Rifiutata

numero

String

Numero della fattura

anno

Number

Anno della fattura

posizione

Number

Posizione della fattura nel file (1, 2 ecc.)

descrizione

String

Eventuale descrizione da inserire nell’esito

messageId

String

ID del messaggio a cura del committente

status

String

Stato esito committente

errorDescription

Null

Eventuale descrizione dell’errore

Stati

status Descrizione

OK

Elaborato correttamente

In elaborazione

In corso di elaborazione

Errore Creazione

Errore in creazione

Errore SDI

Errore nell’invio a SDI

Errore Archiviazione

Errore in archiviazione

Errore Elaborazione

Errore in elaborazione

11. Ricerca Notifiche su Fatture Inviate

Metodi di ricerca notifiche di fatture inviate.

11.1. getNotifications

GET base url altri metodi/api/v2/invoices-out/notifications

Ricerca le notifiche di una fattura per id fattura o per filename della fattura (es. 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

Nome Descrizione

Authorization

Access token ottenuto da signin

Request parameters

Parametro Descrizione Vincoli

id

Identificativo fattura

Obbligatorio se filename non è specificato

filename

Nome file fattura

Obbligatorio se id non è specificato

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

Campo Tipo Descrizione

count

Number

Numero notifiche associate alla fattura

notifications

Array

Notifiche associate alla fattura

notifications[].date

String

Data ricezione della notifica

notifications[].docType

String

Tipo della notifica (RC, NS, …​)

notifications[].file

String

File in formato Base64

notifications[].filename

String

Nome file della notifica (es. IT01879020517_abcde_RC_001.xml)

notifications[].invoiceId

String

Identificativo della fattura

notifications[].notificationDate

String

Data consegna della notifica

notifications[].number

String

Riferimento della fattura associata

notifications[].result

String

Esito della fattura: EC01: per Accettata, EC02 per Rifiutata)

11.2. getNotificationDetail

GET base url altri metodi/api/v2/invoices-out/notifications/detail

Ricerca una notifica per nome del file (es 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

Nome Descrizione

Authorization

Access token ottenuto da signin

Request parameters

Parametro Descrizione Vincoli

filename

Nome file notifica

Obbligatorio

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

Campo Tipo Descrizione

date

String

Data ricezione della notifica

docType

String

Tipo della notifica (RC, NS, …​)

file

String

File in formato Base64

filename

String

Nome file della notifica (es. IT01879020517_abcde_RC_001.xml)

invoiceId

String

Identificativo della fattura

notificationDate

String

Data consegna della notifica

number

String

Riferimento della fattura associata

result

String

Esito della fattura: EC01: per Accettata, EC02 per Rifiutata)

12. Ricerca Notifiche su Fatture Ricevute

Metodi di ricerca notifiche di fatture ricevute.

12.1. getNotifications

GET base url altri metodi/api/v2/invoices-in/notifications

Ricerca le notifiche di una fattura per id fattura o per filename della fattura (es. 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

Nome Descrizione

Authorization

Access token ottenuto da signin

Request parameters

Parametro Descrizione Vincoli

id

Identificativo fattura

Obbligatorio se filename non è specificato

filename

Nome file fattura

Obbligatorio se id non è specificato

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

Campo Tipo Descrizione

count

Number

Numero notifiche associate alla fattura

notifications

Array

Notifiche associate alla fattura

notifications[].date

String

Data ricezione della notifica

notifications[].docType

String

Tipo della notifica (RC, NS, …​)

notifications[].file

String

File in formato Base64

notifications[].filename

String

Nome file della notifica (es. IT01879020517_abcde_RC_001.xml)

notifications[].invoiceId

String

Identificativo della fattura

notifications[].notificationDate

String

Data consegna della notifica

notifications[].number

String

Riferimento della fattura associata

notifications[].result

String

Esito della fattura: EC01: per Accettata, EC02 per Rifiutata)

12.2. getNotificationDetail

GET base url altri metodi/api/v2/invoices-in/notifications/detail

Ricerca una notifica per nome del file (es 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

Nome Descrizione

Authorization

Access token ottenuto da signin

Request parameters

Parametro Descrizione Vincoli

filename

Nome file notifica

Obbligatorio

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

Campo Tipo Descrizione

date

String

Data ricezione della notifica

docType

String

Tipo della notifica (RC, NS, …​)

file

String

File in formato Base64

filename

String

Nome file della notifica (es. IT01879020517_abcde_RC_001.xml)

invoiceId

String

Identificativo della fattura

notificationDate

String

Data consegna della notifica

number

String

Riferimento della fattura associata

result

String

Esito della fattura: EC01: per Accettata, EC02 per Rifiutata)

13. Specifica callback

In aggiunta ai metodi di ricerca in modalità POP, descritti nei capitoli precedenti (Ricerca Fatture Inviate, Ricerca Notifiche su Fatture Inviate, Ricerca Fatture Ricevute e Ricerca Notifiche su Fatture Ricevute), il sistema di Fatturazione Elettronica Aruba permette di inviare agli utenti in modalità PUSH, le fatture e le notifiche ricevute, nonché gli aggiornamenti relativi allo stato delle fatture inviate.

Gli utenti interessati dovranno esporre un Web Service che implementi i metodi descritti nei paragrafi seguenti e dovranno accreditarsi. Gli utenti Premium e i loro cedenti potranno accreditarsi autonomamente mediante la sezione "Configurazione" del pannello web. Per maggiori informazioni è possibile visionare la guida relativa all’account Premium. Le utenze connesse in delega ad account Premium, che hanno a questa concesso i permessi "Web Service Ciclo Attivo" e "Web Service Ciclo Passivo", riceveranno le callback agli endpoint specificati dall’utenza Premium delegata.

L’endpoint esposto dall’utente dovrà utilizzare per la comunicazione la porta 80 se in http, o la porta 443 se in https.

Per gli utenti che necessitano configurare firewall, le callback vengono inviate dagli IP riportati di seguito:

  • 46.37.19.5

  • 46.37.19.6

  • 62.149.180.5

  • 62.149.180.6

  • 217.61.9.4

La sicurezza delle chiamate sarà assicurata tramite una api-key statica da passare tramite header Authorization. L’utente può scegliere l’api-key durante la fase di accreditamento.

Nome Descrizione

Authorization

API-KEY statica. Viene scelta dall’utente durante la fase di accreditamento
Retry: Nel caso in cui una callback non venga recapitata correttamente verranno effettuati 10 tentativi ad intervalli di 3 ore.

13.1. createInvoice (POST)

Il metodo ha lo scopo di comunicare all’utente una nuova fattura ricevuta.

Il metodo dovrà accettare i seguenti parametri in formato application/json con encoding UTF-8.

Campo Tipo Descrizione Vincoli

username

String

Nome utente

Obbligatorio

countryCode

String

Codice paese (es. IT per Italia )

Obbligatorio

vatCode

String

Partita IVA

Obbligatorio

fiscalCode

String

Codice fiscale

Obbligatorio

sdiIdentification

String

Identificativo SDI

Obbligatorio

sdiInvoiceFileName

String

Nome file fattura

Obbligatorio

invoiceXmlBase64

String

Stringa xml della fattura in base64

Obbligatorio

sdiMetadataFileName

String

Nome file notifica metadati (MT)

Obbligatorio

metadataXmlBase64

String

Stringa xml della notifica metadati (MT) in base64

Obbligatorio

Il metodo dovrà ritornare i seguenti codici HTTP, la risposta dovrà essere in formato application/json con encoding UTF-8.

Codice Descrizione

200

Operazione effettuata con successo

400

Parametri di input mancanti o non validi

500

Errore interno

13.2. createNotification (POST)

Il metodo ha lo scopo di comunicare all’utente una nuova notifica per una fattura esistente inviata o ricevuta.

  • Gli utenti privati possono ricevere la callback createNotification solo per le notifiche relative a fatture inviate;

  • Gli utenti PA possono ricevere la callback createNotification anche per notifiche relative a fatture ricevute, ad esempio per notifiche DT;

  • Sia per utenti privati e sia per gli utenti PA, la notifica MT non viene inviata mediante la callback createNotification ma viene inviata con la callback createInvoice contestualmente alla fattura a cui fa riferimento.

Il metodo dovrà accettare i seguenti parametri in formato application/json con encoding UTF-8.

Campo Tipo Descrizione Vincoli

username

String

Nome utente

Obbligatorio

countryCode

String

Codice paese (es. IT per Italia)

Obbligatorio

vatCode

String

Partita IVA

Obbligatorio

fiscalCode

String

Codice fiscale

Obbligatorio

inOut

String

OUT per fatture inviate, IN per fatture ricevute

Obbligatorio

notifyType

String

Tipo notifica, per i possibili valori si veda la colonna Tipo Notifica SDI della tabella Stati delle fatture

Obbligatorio

sdiIdentification

String

Identificativo SDI

Obbligatorio

notifyFileName

String

Nome file notifica

Obbligatorio

notifyXmlBase64

String

Stringa xml della notifica in base64

Obbligatorio

notificationDate

String

Data consegna della notifica in formato ISO 8601 (es. 2022-09-15T15:37:15.840+02:00)

Obbligatorio

Il metodo dovrà ritornare i seguenti codici HTTP, la risposta dovrà essere in formato application/json con encoding UTF-8.

Codice Descrizione

200

Operazione effettuata con successo

400

Parametri di input mancanti o non validi

500

Errore interno

13.3. updateInvoiceStatus (POST)

Il metodo ha lo scopo di comunicare all’utente aggiornamenti relativi allo stato delle fatture inviate. Gli stati che vengono comunicati sono Inviata o Errore Elaborazione, gli altri stati (Stati delle fatture), che fanno riferimento a una notifica SDI, vengono comunicati mediante il metodo createNotification (POST).

Il metodo dovrà accettare i seguenti parametri in formato application/json con encoding UTF-8.

Campo Tipo Descrizione Vincoli

username

String

Nome utente

Obbligatorio

countryCode

String

Codice paese (es. IT per Italia)

Obbligatorio

vatCode

String

Partita IVA

Obbligatorio

fiscalCode

String

Codice fiscale

Obbligatorio

invoiceFileName

String

Nome file fattura

Obbligatorio

sdiIdentification

String

Identificativo SDI, presente nel caso in cui la fattura sia stata inviata a SDI, altrimenti null

Obbligatorio

status

String

Stato della fattura, può essere Inviata oppure Errore Elaborazione

Obbligatorio

errorDescription

String

Descrizione errore, può essere uno dei messaggi elencati in Controlli Asincroni

Obbligatorio nel caso in cui status sia Errore Elaborazione

updateDate

String

Data di aggiornamento in formato ISO 8601 (es. 2022-09-15T15:37:15.840+02:00)

Obbligatorio

Il metodo dovrà ritornare i seguenti codici HTTP, la risposta dovrà essere in formato application/json con encoding UTF-8.

Codice Descrizione

200

Operazione effettuata con successo

400

Parametri di input mancanti o non validi

500

Errore interno

13.4. updateUsage (POST)

Il metodo ha lo scopo di comunicare all’utente aggiornamenti relativi allo spazio di conservazione utilizzato.

Il metodo dovrà accettare i seguenti parametri in formato application/json con encoding UTF-8.

Campo Tipo Descrizione Vincoli

username

String

Nome utente

Obbligatorio

maxSpaceKB

String

Spazio di conservazione acquistato espresso in kilobyte

Obbligatorio

usedSpaceKB

String

Spazio di conservazione utilizzato espresso in kilobyte

Obbligatorio

Il metodo dovrà ritornare i seguenti codici HTTP, la risposta dovrà essere in formato application/json con encoding UTF-8.

Codice Descrizione

200

Operazione effettuata con successo

400

Parametri di input mancanti o non validi

500

Errore interno

14. Simulazione Sistema di Interscambio in ambiente Demo

Nel solo ambiente di Demo è possibile riprodurre l’operatività del Sistema di Interscambio simulando la ricezione di una fattura o simulando una notifica di un fattura trasmessa.

14.1. Simulazione fattura ricevuta

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

Questo metodo permette di simulare la ricezione di una fattura specificando la partita IVA del cessionario/committente. Viene generata una fattura a partire da un modello selezionato a caso, in cui vengono inseriti i dati del cessionario/committente specificati nel request body. Il servizio restituisce il nome file della fattura generata.

Request headers

Nome Descrizione

Authorization

Access token ottenuto da 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

Campo Tipo Descrizione Vincoli

countryReceiver

String

Codice paese (es. IT per Italia) del cessionario committente

Obbligatorio

vatcodeReceiver

String

Partita IVA del cessionario committente

Obbligatorio

fiscalcodeReceiver

String

Codice fiscale del cessionario committente

Non obbligatorio, se specificato sarà presente nella fattura

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

Campo Tipo Descrizione

invoiceFileName

String

Codice paese (es. IT per Italia) del cessionario committente

countryReceiver

String

Partita IVA del cessionario committente

vatcodeReceiver

String

Nome file della fattura generata

fiscalcodeReceiver

String

Codice fiscale del cessionario committente

14.2. Simulazione notifica fattura trasmessa

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

Questo metodo permette di simulare una notifica per una fattura trasmessa. A partire da un modello selezionato a caso, viene generata una notifica del tipo specificato tramite notificationType che viene associata alla fattura specificata tramite invoiceFileName. I tipi di notifica che è possibile specificare sono elencati nella colonna Tipo Notifica SDI riportata nella tabella degli Stati delle fatture .

Per simulare una notifica di esito "Accettata" è necessario specificare NE_EC01 come notificationType. Allo stesso modo, per simulare una notifica di esito "Rifiutata" è necessario specificare NE_EC02 come notificationType. Pertanto come notificationType sono ammessi i seguenti valori: NS, MC, AT, RC, NE_EC01, NE_EC02, DT.

Request headers

Nome Descrizione

Authorization

Access token ottenuto da 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

Campo Tipo Descrizione Vincoli

invoiceFileName

String

Nome file fattura a cui si intende associare la notifica

Obbligatorio

notificationType

String

Tipo notifica

Obbligatorio

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

Campo Tipo Descrizione

notificationFileName

String

Nome file della notifica

invoiceFileName

String

Nome file della fattura a cui è stata associate la notifica

notificationType

String

Tipo notifica

Changelog

2.1.0 - dal 12/04/2024

Fixed

2.0.0 - dal 21/03/2024

Changed

Seconda versione

Comunicazioni finanziarie

Fatture Inviate

Fatture Ricevute

Notifiche su fatture inviate

Notifiche su fatture ricevute

1. Si veda la Rappresentazione tabellare del tracciato fattura ordinaria e semplificata reperibile dalle specifiche tecniche dell’Agenzia delle Entrate.