1. Introduzione

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

  • 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)

Il sistema, visto dall’alto, è schematizzato nella figura seguente:

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

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 tre ambienti per l’integrazione con i servizi di Fatturazione Elettronica.

TEST: Ambiente che espone un mock dei web services di integrazione, disponibile agli utenti senza necessità di accreditamento iniziale. Sono presentati dei dati pseudo-casuali al solo fine di verificare il funzionamento dei WS e le tipologie di richieste e risposte. I dati inseriti dagli utenti sono azzerati periodicamente.

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.

Ambiente URL

Test

https://testws.fatturazioneelettronica.aruba.it/

Demo

https://demoauth.fatturazioneelettronica.aruba.it/ (autenticazione)

https://demows.fatturazioneelettronica.aruba.it/ (altri metodi)

Produzione

https://auth.fatturazioneelettronica.aruba.it/ (autenticazione)

https://ws.fatturazioneelettronica.aruba.it/ (altri metodi)

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

Dimensione massima file inviati

5 MB

Nr. massimo richieste di ricerca fatture inviate/ricevute

1 sessione di ricerca ogni 30 minuti (*)

Nr. Massimo richieste di ricerca notifiche per fatture inviate/ricevute

1 sessione di ricerca ogni 30 minuti (*)

Nr. massimo richieste di invio (upload) fatture

30 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

(*) Una chiamata a findByUsername per ottenere la lista delle fatture inviate/ricevute, una serie(**) di chiamate a getByFilename, getByInvoiceId per scaricare le singole fatture e una serie di chiamate a getByInvoiceFilename/getByInvoiceId e getByFilename per scaricare le singole notifiche.
(**) Fino ad un massimo di 180 chiamate all'interno della singola sessione.

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.

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, di seguito sono riportati i metodi per l’autenticazione.

5.1. signin

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

TEST (mock)
Il token scade dopo 30 minuti.

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

Parameter Description

grant_type

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

username

Username dell’utente

password

Password dell’utente

HTTP request

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

grant_type=password&username=Utente&password=Password

HTTP response

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

{
  "access_token" : "2b4aed3faee95b2f",
  "token_type" : "bearer",
  "expires_in" : 1800,
  "refresh_token" : "1d6378b2eb038466",
  "client_id" : "123456",
  "userName" : "Utente",
  ".issued" : "Fri, 11 Jan 2019 10:27:53 GMT",
  ".expires" : "Fri, 11 Jan 2019 10:57:53 GMT"
}

Response fields

Path Type Description

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

client_id

String

Client che ha richiesto il token

userName

String

Utente Loggato

['.issued']

ZonedDateTime

Data/Ora di emissione del ticket

['.expires']

ZonedDateTime

Data/Ora di scadenza del ticket

In caso di errore, il sistema ritorna un errore 400 Bad Request con la seguente struttura

Path Type Description

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 errore HTTP 403 Unauthorized con il messaggio: "Authorization has been denied for this request."

5.2. refresh

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

TEST (mock):
Se durante una chiamata di refresh non viene specificato lo stesso token, ritorna l’errore: "invalid_grant"
Altrimenti viene generato un nuovo token.
Parameter Description

grant_type

Costante = “refresh_token”

refresh_token

Token di refresh ritornato nella richiesta precedente

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

6. Comunicazioni Finanziarie

financial reporting

I metodi esposti permettono per le Comunicazioni Finanziarie oppure per il recupero dello stato della propria richiesta, la creazione di una nuova richiesta di trasmissione a SdI 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 /services/ClientRequest/CreateTransmissionRequest

Creazione di una nuova richiesta per la trasmissione di tipo “Comunicazioni Finanziarie” (invio richiesta file singolo).

HTTP request

POST /services/ClientRequest/CreateTransmissionRequest?username=Utente&password=Password HTTP/1.1
Accept: application/json
Content-Type: application/json;charset=UTF-8

{
  "userName" : "Utente",
  "password" : "Password",
  "userID" : "Utente",
  "comunicationType" : "LI",
  "dataFile" : "dGVzdA=="
}

Request fields

Path Type Description

userID

String

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

userName

String

Utente accreditato sul sistema

password

String

Password

comunicationType

String

Enumerazione che identifica il tipo di comunicazione

dataFile

String

Dati allegato in formato Base64

HTTP response

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

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

Response fields

Path Type Description

errorCode

String

Codice esito accettazione richiesta Valorizzato solo in caso di errore, altrimenti è vuoto.

errorDescription

String

Il campo contiene i dettagli dell’eventuale errore rilevato nella fase di accettazione richiesta. Esempio: dettagli validazione XSD, errore generico, etc.

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

POST /services/ClientRequest/CreateTransmissionRequestList

Creazione richiesta di trasmissione “Comunicazioni Finanziarie” in formato zip.

HTTP request

POST /services/ClientRequest/CreateTransmissionRequestList?username=Utente&password=Password HTTP/1.1
Accept: application/json
Content-Type: application/json;charset=UTF-8

{
  "userName" : "Utente",
  "password" : "Password",
  "userID" : "Utente",
  "comunicationType" : "LI",
  "dataFile" : "dGVzdA=="
}

Request fields

Path Type Description

userID

String

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

userName

String

Utente accreditato sul sistema

password

String

Password

comunicationType

String

Enumerazione che identifica il tipo di comunicazione

dataFile

String

Dati allegato in formato Base64

HTTP response

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

{
  "errorCode" : "",
  "errorDescription" : "",
  "requestID" : "WZLP0RFYXUJOVUDK",
  "requestIDList" : [ {
    "fileName" : "ITADFSREETDSD_LI_0001.xml",
    "requestID" : "TQVOFUVQGIZMOPJS"
  }, {
    "fileName" : "ITADFSREETDSD_LI_0002.xml",
    "requestID" : "PMI88GV5M3WKKWCN"
  }, {
    "fileName" : "ITADFSREETDSD_LI_0003.xml",
    "requestID" : "FPXFREE7PMVPGNBB"
  } ]
}

Response fields

Path Type Description

errorCode

String

Codice esito accettazione richiesta Valorizzato solo in caso di errore, altrimenti è vuoto.

errorDescription

String

Il campo contiene i dettagli dell’eventuale errore rilevato nella fase di accettazione richiesta. Esempio: dettagli validazione XSD, errore generico, etc.

requestID

String

Identificativo univoco del file in formato Zip

requestIDList

CreateTransmissionZipRequestIDList

Contiene una lista di oggetti composti da: fileName e requestID

requestIDList[].fileName

String

Il nome del file contenuto nello ZIP da utilizzare per le successive chiamate o callback

requestIDList[].requestID

String

Il nome del file generato dal sistema da utilizzare per le successive chiamate o callback

6.3. GetTransmissionInfoRequest

POST /services/ClientRequest/GetTransmissionInfoRequest

Servizio per l’interrogazione dello stato di una richiesta

HTTP request

POST /services/ClientRequest/GetTransmissionInfoRequest?username=Utente&password=Password HTTP/1.1
Accept: application/json
Content-Type: application/json;charset=UTF-8

{
  "userName" : "Utente",
  "password" : "Password",
  "requestID" : "3XNOAVDLBL"
}

Request fields

Path Type Description

userName

String

Utente accreditato sul sistema

password

String

Password

requestID

String

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

{
  "result" : "SF03",
  "error" : "Errore",
  "notifyResult" : "",
  "elaboratedResult" : "",
  "receiptTimestamp" : "2017-04-18 18:30:30",
  "fileID" : "1029166803",
  "fileName" : "ITADSQZVNMVBO_LI_0001.xml"
}

Response fields

Path Type Description

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

error

String

Descrizione esito del campo “result”

6.4. ComunicationType

Valore Descrizione

LI

Liquidazione periodica IVA

DF

Dati fatture

6.5. ErrorCode

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.

TEST (mock):
Per il test vengono memorizzati in una tabella in memory i file importati.
Per i dati ricercabili dal metodo FindByUsername, vengono inseriti valori casuali.
TEST (mock):
Passati circa 60 secondi dall’upload della fattura, viene associata ad essa una notifica di ricezione (RC) oppure di scarto (NS) in modo casuale.
Formato notifica RC: IT<piva>_<codice>_RC_001.xml.p7m
Formato notifica NS: IT<piva>_<codice>_NS_001.xml.p7m

Dopo circa 5 minuti, per i file ricevuti (non scartati) vengono inserite delle notifiche di Esito (NE).
Formato notifica NE: IT<piva>_<codice>_NE_001.xml.p7m

7.1. Upload invoice

POST /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" : ""
}
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.

Request headers

Name Description

Authorization

Provisioner access token

Request fields

Path Type Description

dataFile

String

Dati allegato in formato encoded Base64

credential

String

Credenziali firma

domain

String

Domain firma

HTTP response

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

{
  "errorCode" : "",
  "errorDescription" : "",
  "uploadFileName" : "IT03778032537_ltfaj.xml.p7m"
}

Response fields

Path Type Description

uploadFileName

String

Nome file fattura (inviato a SdI) restituito dal ws

errorCode

String

Eventuale codice di errore

errorDescription

String

Eventuale descrizione errore

7.2. Upload invoice signed

POST /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, ovvero con estension .p7m e formato CAdES-BES (CMS Advanced Electronic Signatures).

NOTA BENE:
Svolgendo ArubaPEC il ruolo del trasmittente verso SdI i dati della sezione DatiTrasmittente devono ArubaPEC come tale. Poichè nel caso specifico al sistema Fatturazione Elettronica arrivano file firmati dall’esterno, esso non è in grado di operare autonomamente in tal senso, pena l’invalidazione della firma digitale.

HTTP request

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

{
  "dataFile" : "dGVzdA=="
}

Request headers

Name Description

Authorization

Provisioner access token

Request fields

Path Type Description

dataFile

String

Dati allegato in formato encoded Base64

HTTP response

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

{
  "errorCode" : "",
  "errorDescription" : "",
  "uploadFileName" : "IT03037080155_tmkwj.xml.p7m"
}

Response fields

Path Type Description

uploadFileName

String

Nome file fattura (inviato a SdI) restituito dal ws

errorCode

String

Eventuale codice di errore

errorDescription

String

Eventuale descrizione errore

7.3. MonitorCheck

Metodo deprecato, verrà rimosso nelle future release

POST /services/invoice/MonitorCheck

Restituisce il valore del metodo check monitor

7.3.1. Request fields

Nessun parametro

HTTP request
POST /services/invoice/MonitorCheck HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer NLOGDVXLVaF3tzmnVPkTwpkuh7dG0i09uSCcog3u+rE=
Request headers
Name Description

Authorization

Provisioner access token

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

{
  "errorCode" : "",
  "errorDescription" : "",
  "checkValue" : "Service it.arubapec.fatturapa.uploadservice.UploadService STATUS UP"
}
Response fields
Path Type Description

checkValue

String

checkValue

errorCode

String

Eventuale codice di errore

errorDescription

String

Eventuale descrizione errore

7.4. ErrorCode

Valore Descrizione

0000

(ok)

0001

Errore Generico

0002

Errore parametri in input mancanti o non validi

0012

Errore Autenticazione (Si sta tentando di inviare una fattura per un cedente/prestatore per cui non si è abilitati. Nel file fattura l'IdCodice dei DatiAnagrafici del CedentePrestatore deve contenere una partita iva associata all’utenza in uso.)

0013

Si e' verificato un errore in fase di registrazione della richiesta

0018

Errore validazione firma fattura elettronica inviata, il file non risulta firmato

0033

Il file fattura elettronica inviato supera la dimensione massima accettata

0071

Errore in fase di verifica nome file per utente

0072

Errore in fase di caricamento lista fatture per utente

0082

Si e' verificato un’errore in fase di recupero notifiche

0092

Errore generico schema xsd

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

8.2. findByUsername

GET /services/invoice/out/findByUsername

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)

TEST (mock):
Ritorna i valori solo se USERNAME = Utente, in caso contrario ritorna una risposta vuota (0 risultati)

HTTP request

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

Request headers

Name Description

Authorization

Authorization

Request parameters

Parameter Description

username

username proprietario della fattura inviata/ricevuta

page

pagina richiesta (default 0)

size

dimensione della pagina (default 10)

startDate

data creazione fattura (da)

endDate

data creazione fattura (a)

countrySender

Codice Paese del cedente/prestatore

vatcodeSender

Partita iva del cedente/prestatore

fiscalcodeSender

Codice fiscale del cedente/prestatore

countryReceiver

Codice Paese del cessionario/committente

vatcodeReceiver

Partita iva del cessionario/committente

fiscalcodeReceiver

Codice fiscale del cessionario/committente

HTTP response

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

{
  "content" : [ {
    "id" : "1",
    "sender" : {
      "description" : "Aruba SPA",
      "countryCode" : "ITA",
      "vatCode" : "6372762541",
      "fiscalCode" : "N5Hnt9vvMZ"
    },
    "receiver" : {
      "description" : "Rossi SRL",
      "countryCode" : "ITA",
      "vatCode" : "8767263441",
      "fiscalCode" : "LVZTeOJ8BN"
    },
    "invoiceType" : "FPA12",
    "docType" : "in",
    "file" : null,
    "filename" : "IT07026037883_jtlkl.xml.p7m",
    "invoices" : [ {
      "invoiceDate" : "2019-01-11T11:27:56.664+01:00",
      "number" : "1",
      "status" : "Inviata"
    } ],
    "username" : "Utente",
    "lastUpdate" : "2019-01-11T11:27:56.664+01:00",
    "idSdi" : 7895
  }, {
    "id" : "2",
    "sender" : {
      "description" : "Aruba SPA",
      "countryCode" : "UGV",
      "vatCode" : "6645140497",
      "fiscalCode" : "thNGgskxqN"
    },
    "receiver" : {
      "description" : "Rossi SRL",
      "countryCode" : "LVu",
      "vatCode" : "8134103392",
      "fiscalCode" : "RVIoUS6ACS"
    },
    "invoiceType" : "FPA12",
    "docType" : "in",
    "file" : null,
    "filename" : "IT03037080155_tmkwj.xml.p7m",
    "invoices" : [ {
      "invoiceDate" : "2019-01-11T11:27:56.664+01:00",
      "number" : "1",
      "status" : "Inviata"
    } ],
    "username" : "Utente",
    "lastUpdate" : "2019-01-11T11:27:56.664+01:00",
    "idSdi" : 7895
  }, {
    "id" : "3",
    "sender" : {
      "description" : "Aruba SPA",
      "countryCode" : "IT",
      "vatCode" : "59715482367",
      "fiscalCode" : "46102366462"
    },
    "receiver" : {
      "description" : "Rossi SRL",
      "countryCode" : "IT",
      "vatCode" : "00656382404",
      "fiscalCode" : "34101127936"
    },
    "invoiceType" : "FPA12",
    "docType" : "in",
    "file" : null,
    "filename" : "IT03778032537_ltfaj.xml.p7m",
    "invoices" : [ {
      "invoiceDate" : "2019-01-11T11:27:56.664+01:00",
      "number" : "1",
      "status" : "Inviata"
    } ],
    "username" : "Utente",
    "lastUpdate" : "2019-01-11T11:27:56.664+01:00",
    "idSdi" : 7895
  }, {
    "id" : "4",
    "sender" : {
      "description" : "Aruba SPA",
      "countryCode" : "IT",
      "vatCode" : "84631737403",
      "fiscalCode" : "08975978923"
    },
    "receiver" : {
      "description" : "Rossi SRL",
      "countryCode" : "IT",
      "vatCode" : "44174222038",
      "fiscalCode" : "75383225221"
    },
    "invoiceType" : "FPA12",
    "docType" : "in",
    "file" : null,
    "filename" : "IT05692798961_imkbl.xml.p7m",
    "invoices" : [ {
      "invoiceDate" : "2019-01-11T11:27:56.664+01:00",
      "number" : "1",
      "status" : "Inviata"
    } ],
    "username" : "Utente",
    "lastUpdate" : "2019-01-11T11:27:56.664+01:00",
    "idSdi" : 7895
  } ],
  "last" : true,
  "totalElements" : 4,
  "totalPages" : 1,
  "size" : 10,
  "number" : 0,
  "first" : true,
  "numberOfElements" : 4
}

Response fields

Path Type Description

content

Array

Array delle fatture trovate

last

Boolean

True se la pagina trovata è l’ultima

totalElements

Number

numero totale fatture trovate

totalPages

Number

numero pagine

size

Number

dimensione della pagina

number

Number

numero della pagina ritornata

first

Boolean

true se la pagina trovata è la prima

numberOfElements

Number

numero di elementi ritornati

content[].id

String

ObjectId del DB Mongo

content[].sender

Company

Company sender

content[].receiver

Company

Company receiver

content[].invoiceType

String

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

content[].docType

String

'out':Fattura inviata, 'in': fattura ricevuta

content[].file

String

File in formato Base64

content[].filename

String

Filename (es. IT01234567890_abcde.xml.p7m)

content[].invoices

Array

Array delle singole fatture presenti nel lotto

content[].username

String

Username del proprietario della fattura

content[].lastUpdate

String

Data di ultimo aggiornamento

content[].idSdi

String

Id Sdi (Sistema di Interscambio)

content[].sender.description

String

ObjectId del DB Mongo

content[].sender.countryCode

String

Codice nazione (es. 'IT’, 'DE’, …)

content[].sender.vatCode

String

Partita IVA

content[].sender.fiscalCode

String

Codice fiscale

content[].receiver.description

String

ObjectId del DB Mongo

content[].receiver.countryCode

String

Codice nazione (es. 'IT’, 'DE’, …)

content[].receiver.vatCode

String

Partita IVA

content[].receiver.fiscalCode

String

Codice fiscale

content[].invoices.[].invoiceDate

String

Data della fattura

content[].invoices.[].number

String

Numero della fattura

content[].invoices.[].status

String

Stato della fattura

8.3. getByFilename

Questo metodo restituisce il dettaglio completo dello stato di una fattura elettronica.

GET /services/invoice/out/getByFilename

Ricerca una singola fattura per filename (IT01234567890_abcdef.xml.p7m)

HTTP request

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

Request headers

Name Description

Authorization

Authorization

Request parameters

Parameter Description

filename

File name

HTTP response

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

{
  "id" : "1",
  "sender" : {
    "description" : "Aruba SPA",
    "countryCode" : "ITA",
    "vatCode" : "6372762541",
    "fiscalCode" : "N5Hnt9vvMZ"
  },
  "receiver" : {
    "description" : "Rossi SRL",
    "countryCode" : "ITA",
    "vatCode" : "8767263441",
    "fiscalCode" : "LVZTeOJ8BN"
  },
  "invoiceType" : "FPA12",
  "docType" : "in",
  "file" : "ZEdWemRBPT0=",
  "filename" : "IT07026037883_jtlkl.xml.p7m",
  "invoices" : [ {
    "invoiceDate" : "2019-01-11T11:27:56.897+01:00",
    "number" : "1",
    "status" : "Inviata"
  }, {
    "invoiceDate" : "2019-01-11T11:27:56.897+01:00",
    "number" : "2",
    "status" : "Consegnata"
  } ],
  "username" : "Utente",
  "lastUpdate" : "2019-01-11T11:27:56.897+01:00",
  "idSdi" : null
}

Response fields

Path Type Description

id

String

ObjectId del DB Mongo

sender

Company

Company sender

receiver

Company

Company receiver

invoiceType

String

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

docType

String

'out':Fattura inviata, 'in': fattura ricevuta

file

String

File in formato Base64

filename

String

Filename (es. IT01234567890_abcde.xml.p7m)

invoices

Array

Array delle singole fatture presenti nel lotto

username

String

Username del proprietario della fattura

lastUpdate

String

Data di ultimo aggiornamento

idSdi

String

Id Sdi (Sistema di Interscambio)

sender.description

String

ObjectId del DB Mongo

sender.countryCode

String

Codice nazione (es. 'IT’, 'DE’, …)

sender.vatCode

String

Partita IVA

sender.fiscalCode

String

Codice fiscale

receiver.description

String

ObjectId del DB Mongo

receiver.countryCode

String

Codice nazione (es. 'IT’, 'DE’, …)

receiver.vatCode

String

Partita IVA

receiver.fiscalCode

String

Codice fiscale

invoices.[].invoiceDate

String

Data della fattura

invoices.[].number

String

Numero della fattura

invoices.[].status

String

Stato della fattura

8.4. getByInvoiceId

GET /services/invoice/out/{invoiceId}

Ricerca una singola fattura per Id

HTTP request

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

Request headers

Name Description

Authorization

Authorization

Path parameters

Table 1. /services/invoice/out/{invoiceId}
Parameter Description

invoiceId

Invoice id

HTTP response

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

{
  "id" : "1",
  "sender" : {
    "description" : "Aruba SPA",
    "countryCode" : "ITA",
    "vatCode" : "6372762541",
    "fiscalCode" : "N5Hnt9vvMZ"
  },
  "receiver" : {
    "description" : "Aruba SPA",
    "countryCode" : "ITA",
    "vatCode" : "8767263441",
    "fiscalCode" : "LVZTeOJ8BN"
  },
  "invoiceType" : "FPA12",
  "docType" : "in",
  "file" : "ZEdWemRBPT0=",
  "filename" : "IT07026037883_jtlkl.xml.p7m",
  "invoices" : [ {
    "invoiceDate" : "2019-01-11T11:27:57.014+01:00",
    "number" : "1",
    "status" : "Inviata"
  }, {
    "invoiceDate" : "2019-01-11T11:27:57.014+01:00",
    "number" : "2",
    "status" : "Consegnata"
  } ],
  "username" : "Utente",
  "lastUpdate" : "2019-01-11T11:27:57.014+01:00",
  "idSdi" : null
}

Response fields

Path Type Description

id

String

ObjectId del DB Mongo

sender

Company

Company sender

receiver

Company

Company receiver

invoiceType

String

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

docType

String

'out':Fattura inviata, 'in': fattura ricevuta

file

String

File in formato Base64

filename

String

Filename (es. IT01234567890_abcde.xml.p7m)

invoices

Array

Array delle singole fatture presenti nel lotto

username

String

Username del proprietario della fattura

lastUpdate

String

Data di ultimo aggiornamento

idSdi

String

Id Sdi (Sistema di Interscambio)

sender.description

String

ObjectId del DB Mongo

sender.countryCode

String

Codice nazione (es. 'IT’, 'DE’, …)

sender.vatCode

String

Partita IVA

sender.fiscalCode

String

Codice fiscale

receiver.description

String

ObjectId del DB Mongo

receiver.countryCode

String

Codice nazione (es. 'IT’, 'DE’, …)

receiver.vatCode

String

Partita IVA

receiver.fiscalCode

String

Codice fiscale

invoices.[].invoiceDate

String

Data della fattura

invoices.[].number

String

Numero della fattura

invoices.[].status

String

Stato della fattura

9. Ricerca Fatture Ricevute

searching received invoice

Metodi di ricerca fatture ricevute

TEST (mock):
All’avvio dell’applicativo, per l’utente con username "Utente", verranno precaricate 10 fatture con dati fittizzi. All’inizio tali fatture non avranno notifiche associate.

9.1. findByUsername

GET /services/invoice/in/findByUsername

Ricerca una lista di fatture. Ritorna le fatture senza il contenuto in base64 (lazy loading)

HTTP request

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

Request headers

Name Description

Authorization

Authorization

Request parameters

Parameter Description

username

username proprietario della fattura inviata/ricevuta

page

pagina richiesta (default 0)

size

dimensione della pagina (default 10)

startDate

data creazione fattura (da)

endDate

data creazione fattura (a)

countrySender

Codice Paese del cedente/prestatore

vatcodeSender

Partita iva del cedente/prestatore

fiscalcodeSender

Codice fiscale del cedente/prestatore

countryReceiver

Codice Paese del cessionario/committente

vatcodeReceiver

Partita iva del cessionario/committente

fiscalcodeReceiver

Codice fiscale del cessionario/committente

HTTP response

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

{
  "content" : [ {
    "id" : "0",
    "sender" : {
      "description" : "Aruba SPA",
      "countryCode" : "IT",
      "vatCode" : "22222222",
      "fiscalCode" : "11111111111"
    },
    "receiver" : {
      "description" : "Aruba SPA",
      "countryCode" : "IT",
      "vatCode" : "4444444",
      "fiscalCode" : "333333333"
    },
    "invoiceType" : "FPA12",
    "docType" : "in",
    "file" : null,
    "filename" : "IT07026037880_jtlkl.xml.p7m",
    "invoices" : [ {
      "invoiceDate" : "2019-01-11T11:27:44.382+01:00",
      "number" : "1",
      "status" : "Inviata"
    }, {
      "invoiceDate" : "2019-01-11T11:27:44.383+01:00",
      "number" : "2",
      "status" : "Consegnata"
    } ],
    "username" : "Utente",
    "lastUpdate" : "2019-01-11T11:27:44.392+01:00",
    "idSdi" : null
  }, {
    "id" : "1",
    "sender" : {
      "description" : "Aruba SPA",
      "countryCode" : "IT",
      "vatCode" : "22222222",
      "fiscalCode" : "11111111111"
    },
    "receiver" : {
      "description" : "Aruba SPA",
      "countryCode" : "IT",
      "vatCode" : "4444444",
      "fiscalCode" : "333333333"
    },
    "invoiceType" : "FPA12",
    "docType" : "in",
    "file" : null,
    "filename" : "IT07026037881_jtlkl.xml.p7m",
    "invoices" : [ {
      "invoiceDate" : "2019-01-11T11:27:44.392+01:00",
      "number" : "1",
      "status" : "Inviata"
    }, {
      "invoiceDate" : "2019-01-11T11:27:44.392+01:00",
      "number" : "2",
      "status" : "Consegnata"
    } ],
    "username" : "Utente",
    "lastUpdate" : "2019-01-11T11:27:44.392+01:00",
    "idSdi" : null
  }, {
    "id" : "2",
    "sender" : {
      "description" : "Aruba SPA",
      "countryCode" : "IT",
      "vatCode" : "22222222",
      "fiscalCode" : "11111111111"
    },
    "receiver" : {
      "description" : "Aruba SPA",
      "countryCode" : "IT",
      "vatCode" : "4444444",
      "fiscalCode" : "333333333"
    },
    "invoiceType" : "FPA12",
    "docType" : "in",
    "file" : null,
    "filename" : "IT07026037882_jtlkl.xml.p7m",
    "invoices" : [ {
      "invoiceDate" : "2019-01-11T11:27:44.392+01:00",
      "number" : "1",
      "status" : "Inviata"
    }, {
      "invoiceDate" : "2019-01-11T11:27:44.392+01:00",
      "number" : "2",
      "status" : "Consegnata"
    } ],
    "username" : "Utente",
    "lastUpdate" : "2019-01-11T11:27:44.392+01:00",
    "idSdi" : null
  }, {
    "id" : "3",
    "sender" : {
      "description" : "Aruba SPA",
      "countryCode" : "IT",
      "vatCode" : "22222222",
      "fiscalCode" : "11111111111"
    },
    "receiver" : {
      "description" : "Aruba SPA",
      "countryCode" : "IT",
      "vatCode" : "4444444",
      "fiscalCode" : "333333333"
    },
    "invoiceType" : "FPA12",
    "docType" : "in",
    "file" : null,
    "filename" : "IT07026037883_jtlkl.xml.p7m",
    "invoices" : [ {
      "invoiceDate" : "2019-01-11T11:27:44.392+01:00",
      "number" : "1",
      "status" : "Inviata"
    }, {
      "invoiceDate" : "2019-01-11T11:27:44.392+01:00",
      "number" : "2",
      "status" : "Consegnata"
    } ],
    "username" : "Utente",
    "lastUpdate" : "2019-01-11T11:27:44.392+01:00",
    "idSdi" : null
  }, {
    "id" : "4",
    "sender" : {
      "description" : "Aruba SPA",
      "countryCode" : "IT",
      "vatCode" : "22222222",
      "fiscalCode" : "11111111111"
    },
    "receiver" : {
      "description" : "Aruba SPA",
      "countryCode" : "IT",
      "vatCode" : "4444444",
      "fiscalCode" : "333333333"
    },
    "invoiceType" : "FPA12",
    "docType" : "in",
    "file" : null,
    "filename" : "IT07026037884_jtlkl.xml.p7m",
    "invoices" : [ {
      "invoiceDate" : "2019-01-11T11:27:44.392+01:00",
      "number" : "1",
      "status" : "Inviata"
    }, {
      "invoiceDate" : "2019-01-11T11:27:44.392+01:00",
      "number" : "2",
      "status" : "Consegnata"
    } ],
    "username" : "Utente",
    "lastUpdate" : "2019-01-11T11:27:44.392+01:00",
    "idSdi" : null
  }, {
    "id" : "5",
    "sender" : {
      "description" : "Aruba SPA",
      "countryCode" : "IT",
      "vatCode" : "22222222",
      "fiscalCode" : "11111111111"
    },
    "receiver" : {
      "description" : "Aruba SPA",
      "countryCode" : "IT",
      "vatCode" : "4444444",
      "fiscalCode" : "333333333"
    },
    "invoiceType" : "FPA12",
    "docType" : "in",
    "file" : null,
    "filename" : "IT07026037885_jtlkl.xml.p7m",
    "invoices" : [ {
      "invoiceDate" : "2019-01-11T11:27:44.392+01:00",
      "number" : "1",
      "status" : "Inviata"
    }, {
      "invoiceDate" : "2019-01-11T11:27:44.392+01:00",
      "number" : "2",
      "status" : "Consegnata"
    } ],
    "username" : "Utente",
    "lastUpdate" : "2019-01-11T11:27:44.393+01:00",
    "idSdi" : null
  }, {
    "id" : "6",
    "sender" : {
      "description" : "Aruba SPA",
      "countryCode" : "IT",
      "vatCode" : "22222222",
      "fiscalCode" : "11111111111"
    },
    "receiver" : {
      "description" : "Aruba SPA",
      "countryCode" : "IT",
      "vatCode" : "4444444",
      "fiscalCode" : "333333333"
    },
    "invoiceType" : "FPA12",
    "docType" : "in",
    "file" : null,
    "filename" : "IT07026037886_jtlkl.xml.p7m",
    "invoices" : [ {
      "invoiceDate" : "2019-01-11T11:27:44.393+01:00",
      "number" : "1",
      "status" : "Inviata"
    }, {
      "invoiceDate" : "2019-01-11T11:27:44.393+01:00",
      "number" : "2",
      "status" : "Consegnata"
    } ],
    "username" : "Utente",
    "lastUpdate" : "2019-01-11T11:27:44.393+01:00",
    "idSdi" : null
  }, {
    "id" : "7",
    "sender" : {
      "description" : "Aruba SPA",
      "countryCode" : "IT",
      "vatCode" : "22222222",
      "fiscalCode" : "11111111111"
    },
    "receiver" : {
      "description" : "Aruba SPA",
      "countryCode" : "IT",
      "vatCode" : "4444444",
      "fiscalCode" : "333333333"
    },
    "invoiceType" : "FPA12",
    "docType" : "in",
    "file" : null,
    "filename" : "IT07026037887_jtlkl.xml.p7m",
    "invoices" : [ {
      "invoiceDate" : "2019-01-11T11:27:44.393+01:00",
      "number" : "1",
      "status" : "Inviata"
    }, {
      "invoiceDate" : "2019-01-11T11:27:44.393+01:00",
      "number" : "2",
      "status" : "Consegnata"
    } ],
    "username" : "Utente",
    "lastUpdate" : "2019-01-11T11:27:44.393+01:00",
    "idSdi" : null
  }, {
    "id" : "8",
    "sender" : {
      "description" : "Aruba SPA",
      "countryCode" : "IT",
      "vatCode" : "22222222",
      "fiscalCode" : "11111111111"
    },
    "receiver" : {
      "description" : "Aruba SPA",
      "countryCode" : "IT",
      "vatCode" : "4444444",
      "fiscalCode" : "333333333"
    },
    "invoiceType" : "FPA12",
    "docType" : "in",
    "file" : null,
    "filename" : "IT07026037888_jtlkl.xml.p7m",
    "invoices" : [ {
      "invoiceDate" : "2019-01-11T11:27:44.393+01:00",
      "number" : "1",
      "status" : "Inviata"
    }, {
      "invoiceDate" : "2019-01-11T11:27:44.393+01:00",
      "number" : "2",
      "status" : "Consegnata"
    } ],
    "username" : "Utente",
    "lastUpdate" : "2019-01-11T11:27:44.393+01:00",
    "idSdi" : null
  }, {
    "id" : "9",
    "sender" : {
      "description" : "Aruba SPA",
      "countryCode" : "IT",
      "vatCode" : "22222222",
      "fiscalCode" : "11111111111"
    },
    "receiver" : {
      "description" : "Aruba SPA",
      "countryCode" : "IT",
      "vatCode" : "4444444",
      "fiscalCode" : "333333333"
    },
    "invoiceType" : "FPA12",
    "docType" : "in",
    "file" : null,
    "filename" : "IT07026037889_jtlkl.xml.p7m",
    "invoices" : [ {
      "invoiceDate" : "2019-01-11T11:27:44.393+01:00",
      "number" : "1",
      "status" : "Inviata"
    }, {
      "invoiceDate" : "2019-01-11T11:27:44.393+01:00",
      "number" : "2",
      "status" : "Consegnata"
    } ],
    "username" : "Utente",
    "lastUpdate" : "2019-01-11T11:27:44.393+01:00",
    "idSdi" : null
  } ],
  "last" : true,
  "totalElements" : 10,
  "totalPages" : 1,
  "size" : 10,
  "number" : 0,
  "first" : true,
  "numberOfElements" : 10
}

Response fields

Path Type Description

content

Array

Array delle fatture trovate

last

Boolean

True se la pagina trovata è l’ultima

totalElements

Number

numero totale fatture trovate

totalPages

Number

numero pagine

size

Number

dimensione della pagina

number

Number

numero della pagina ritornata

first

Boolean

true se la pagina trovata è la prima

numberOfElements

Number

numero di elementi ritornati

content[].id

String

ObjectId del DB Mongo

content[].sender

Company

Company sender

content[].receiver

Company

Company receiver

content[].invoiceType

String

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

content[].docType

String

'out':Fattura inviata, 'in': fattura ricevuta

content[].file

String

File in formato Base64

content[].filename

String

Filename (es. IT01234567890_abcde.xml.p7m)

content[].invoices

Array

Array delle singole fatture presenti nel lotto

content[].username

String

Username del proprietario della fattura

content[].lastUpdate

String

Data di ultimo aggiornamento

content[].idSdi

String

Id Sdi (Sistema di Interscambio)

content[].sender.description

String

ObjectId del DB Mongo

content[].sender.countryCode

String

Codice nazione (es. 'IT’, 'DE’, …)

content[].sender.vatCode

String

Partita IVA

content[].sender.fiscalCode

String

Codice fiscale

content[].receiver.description

String

ObjectId del DB Mongo

content[].receiver.countryCode

String

Codice nazione (es. 'IT’, 'DE’, …)

content[].receiver.vatCode

String

Partita IVA

content[].receiver.fiscalCode

String

Codice fiscale

content[].invoices.[].invoiceDate

String

Data della fattura

content[].invoices.[].number

String

Numero della fattura

content[].invoices.[].status

String

Stato della fattura

9.2. getByFilename

GET /services/invoice/in/getByFilename

Ricerca una singola fattura per filename (IT01234567890_abcdef.xml.p7m)

HTTP request

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

Request headers

Name Description

Authorization

Authorization

Request parameters

Parameter Description

filename

File name

HTTP response

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

{
  "id" : "3",
  "sender" : {
    "description" : "Aruba SPA",
    "countryCode" : "IT",
    "vatCode" : "22222222",
    "fiscalCode" : "11111111111"
  },
  "receiver" : {
    "description" : "Aruba SPA",
    "countryCode" : "IT",
    "vatCode" : "4444444",
    "fiscalCode" : "333333333"
  },
  "invoiceType" : "FPA12",
  "docType" : "in",
  "file" : "dGVzdA==",
  "filename" : "IT07026037883_jtlkl.xml.p7m",
  "invoices" : [ {
    "invoiceDate" : "2019-01-11T11:27:44.392+01:00",
    "number" : "1",
    "status" : "Inviata"
  }, {
    "invoiceDate" : "2019-01-11T11:27:44.392+01:00",
    "number" : "2",
    "status" : "Consegnata"
  } ],
  "username" : "Utente",
  "lastUpdate" : "2019-01-11T11:27:44.392+01:00",
  "idSdi" : null
}

Response fields

Path Type Description

id

String

ObjectId del DB Mongo

sender

Company

Company sender

receiver

Company

Company receiver

invoiceType

String

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

docType

String

'out':Fattura inviata, 'in': fattura ricevuta

file

String

File in formato Base64

filename

String

Filename (es. IT01234567890_abcde.xml.p7m)

invoices

Array

Array delle singole fatture presenti nel lotto

username

String

Username del proprietario della fattura

lastUpdate

String

Data di ultimo aggiornamento

idSdi

String

Id Sdi (Sistema di Interscambio)

sender.description

String

ObjectId del DB Mongo

sender.countryCode

String

Codice nazione (es. 'IT’, 'DE’, …)

sender.vatCode

String

Partita IVA

sender.fiscalCode

String

Codice fiscale

receiver.description

String

ObjectId del DB Mongo

receiver.countryCode

String

Codice nazione (es. 'IT’, 'DE’, …)

receiver.vatCode

String

Partita IVA

receiver.fiscalCode

String

Codice fiscale

invoices.[].invoiceDate

String

Data della fattura

invoices.[].number

String

Numero della fattura

invoices.[].status

String

Stato della fattura

9.3. getZipByFilename

GET /services/invoice/in/getZipByFilename

Ritorna una fattura con tutte le sue notifiche in formato Zip (IT01234567890_abcdef.xml.p7m)

HTTP request

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

Request headers

Name Description

Authorization

Authorization

Request parameters

Parameter Description

filename

File name

HTTP response

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

<binary>

9.4. getByInvoiceId

GET /services/invoice/in/{invoiceId}

Ricerca una singola fattura per Id

HTTP request

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

Request headers

Name Description

Authorization

Authorization

Path parameters

Table 1. /services/invoice/in/{invoiceId}
Parameter Description

invoiceId

Invoice id

HTTP response

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

{
  "id" : "1",
  "sender" : {
    "description" : "Aruba SPA",
    "countryCode" : "IT",
    "vatCode" : "22222222",
    "fiscalCode" : "11111111111"
  },
  "receiver" : {
    "description" : "Aruba SPA",
    "countryCode" : "IT",
    "vatCode" : "4444444",
    "fiscalCode" : "333333333"
  },
  "invoiceType" : "FPA12",
  "docType" : "in",
  "file" : "dGVzdA==",
  "filename" : "IT07026037881_jtlkl.xml.p7m",
  "invoices" : [ {
    "invoiceDate" : "2019-01-11T11:27:44.392+01:00",
    "number" : "1",
    "status" : "Inviata"
  }, {
    "invoiceDate" : "2019-01-11T11:27:44.392+01:00",
    "number" : "2",
    "status" : "Consegnata"
  } ],
  "username" : "Utente",
  "lastUpdate" : "2019-01-11T11:27:44.392+01:00",
  "idSdi" : null
}

Response fields

Path Type Description

id

String

ObjectId del DB Mongo

sender

Company

Company sender

receiver

Company

Company receiver

invoiceType

String

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

docType

String

'out':Fattura inviata, 'in': fattura ricevuta

file

String

File in formato Base64

filename

String

Filename (es. IT01234567890_abcde.xml.p7m)

invoices

Array

Array delle singole fatture presenti nel lotto

username

String

Username del proprietario della fattura

lastUpdate

String

Data di ultimo aggiornamento

idSdi

String

Id Sdi (Sistema di Interscambio)

sender.description

String

ObjectId del DB Mongo

sender.countryCode

String

Codice nazione (es. 'IT’, 'DE’, …)

sender.vatCode

String

Partita IVA

sender.fiscalCode

String

Codice fiscale

receiver.description

String

ObjectId del DB Mongo

receiver.countryCode

String

Codice nazione (es. 'IT’, 'DE’, …)

receiver.vatCode

String

Partita IVA

receiver.fiscalCode

String

Codice fiscale

invoices.[].invoiceDate

String

Data della fattura

invoices.[].number

String

Numero della fattura

invoices.[].status

String

Stato della fattura

10. Invio Esito Committente

10.1. sendEsitoCommittente

POST /services/invoice/in/sendEsitoCommittente

Il metodo consente all’utente di inviare a SDI la notifica di Esito Committente.

TEST (mock):
Una volta inviata la notifica di esito, viene allegata alla fattura relativa con codice EC e nome file IT<piva>_<codice>_EC_001.xml.p7m.

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" : "IT07026037883_jtlkl.xml.p7m",
  "sdiId" : 1263,
  "esito" : "EC01",
  "numero" : "1",
  "anno" : 2018,
  "posizione" : 1,
  "descrizione" : "Desc",
  "messageId" : "7865"
}

Request headers

Name Description

Authorization

Authorization

Request fields

Path Type Description

filename

String

Nome della fattura ricevuta

sdiId

Number

Id Sdi della fattura ricevuta

esito

String

Esito committente: (EC01: Accettata, EC02: 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

HTTP response

HTTP/1.1 200 OK
In caso di successo ritorna HTTP status code 200 altrimenti HTTP status code 500

11. Ricerca Notifiche su Fatture Inviate

Questo metodo restituisce la lista di tutte le notifiche di riferimento ricevute in base al nome di una determinata fattura inviata.

11.1. getByFilename

GET /services/notification/out/getByFilename

Ricerca una notifica per filename (IT01234567890_abcdef_XX_nnn.xml)

HTTP request

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

Request headers

Name Description

Authorization

Authorization

Request parameters

Parameter Description

filename

filename

HTTP response

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

{
  "date" : "2019-01-11T11:27:57.896+01:00",
  "docType" : "RC",
  "file" : "ZEdWemRBPT0=",
  "filename" : "IT8767263441_33825_RC_001.xml",
  "invoiceId" : "1",
  "notificationDate" : "2019-01-11T11:27:57.897+01:00",
  "number" : "1",
  "result" : "esito"
}

Response fields

Path Type Description

date

String

data ricezione della notifica

docType

String

Tipo della notifica (RC, NS, …)

file

String

File in formato Base64

filename

String

filename della notifica (es. IT01234567890_abcde_XX_nnn.xml)

invoiceId

String

Id Mongo della fattura

notificationDate

String

Data consegna della notifica

number

String

Riferimento della fattura associata

result

String

Esito della fattura

11.2. getByInvoiceFilename

GET /services/notification/out/getByInvoiceFilename

Ricerca le notifiche di una fattura per filename della fattura (IT01234567890_abcdef.xml.p7m)

HTTP request

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

Request headers

Name Description

Authorization

Authorization

Request parameters

Parameter Description

invoiceFilename

Invoice Filename

HTTP response

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

{
  "count" : 1,
  "notifications" : [ {
    "date" : "2019-01-11T11:27:58.292+01:00",
    "docType" : "RC",
    "file" : "ZEdWemRBPT0=",
    "filename" : "IT8767263441_33825_RC_001.xml",
    "invoiceId" : "1",
    "notificationDate" : "2019-01-11T11:27:58.292+01:00",
    "number" : "1",
    "result" : "esito"
  } ]
}

Response fields

Path Type Description

count

Number

count

notifications

Array

notification

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

filename della notifica (es. IT01234567890_abcde_XX_nnn.xml)

notifications[].invoiceId

String

Id Mongo della fattura

notifications[].notificationDate

String

Data consegna della notifica

notifications[].number

String

Riferimento della fattura associata

notifications[].result

String

Esito della fattura

11.3. getByInvoiceId

GET /services/notification/out/{invoiceId}

Ricerca le notifiche di una fattura per id della fattura

HTTP request

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

Request headers

Name Description

Authorization

Authorization

Path parameters

Table 1. /services/notification/out/{invoiceId}
Parameter Description

invoiceId

Invoice id

HTTP response

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

{
  "count" : 1,
  "notifications" : [ {
    "date" : "2019-01-11T11:27:58.037+01:00",
    "docType" : "RC",
    "file" : "ZEdWemRBPT0=",
    "filename" : "IT8767263441_33825_RC_001.xml",
    "invoiceId" : "1",
    "notificationDate" : "2019-01-11T11:27:58.037+01:00",
    "number" : "1",
    "result" : "esito"
  } ]
}

Response fields

Path Type Description

count

Number

count

notifications

Array

notification

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

filename della notifica (es. IT01234567890_abcde_XX_nnn.xml)

notifications[].invoiceId

String

Id Mongo della fattura

notifications[].notificationDate

String

Data consegna della notifica

notifications[].number

String

Riferimento della fattura associata

notifications[].result

String

Esito della fattura

12. Ricerca Notifiche su Fatture Ricevute

Metodi di ricerca notifiche ricevute

12.1. getByFilename

GET /services/notification/in/getByFilename

Ricerca una notifica per filename (IT01234567890_abcdef_XX_nnn.xml)

HTTP request

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

Request headers

Name Description

Authorization

Authorization

Request parameters

Parameter Description

filename

filename

HTTP response

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

{
  "date" : "2019-01-11T11:27:44.422+01:00",
  "docType" : "NS",
  "file" : "ZEdWemRBPT0=",
  "filename" : "IT8767263443_33825_RC_001.xml",
  "invoiceId" : "3",
  "notificationDate" : "2019-01-11T11:27:44.422+01:00",
  "number" : "1",
  "result" : "esito"
}

Response fields

Path Type Description

date

String

data ricezione della notifica

docType

String

Tipo della notifica (RC, NS, …)

file

String

File in formato Base64

filename

String

filename della notifica (es. IT01234567890_abcde_XX_nnn.xml)

invoiceId

String

Id Mongo della fattura

notificationDate

String

Data consegna della notifica

number

String

Riferimento della fattura associata

result

String

Esito della fattura

12.2. getByInvoiceFilename

GET /services/notification/in/getByInvoiceFilename

Ricerca le notifiche di una fattura per filename della fattura (IT01234567890_abcdef.xml.p7m)

HTTP request

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

Request headers

Name Description

Authorization

Authorization

Request parameters

Parameter Description

invoiceFilename

Invoice Filename

HTTP response

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

{
  "count" : 2,
  "notifications" : [ {
    "date" : "2019-01-11T11:27:44.422+01:00",
    "docType" : "NS",
    "file" : "ZEdWemRBPT0=",
    "filename" : "IT8767263443_33825_RC_001.xml",
    "invoiceId" : "3",
    "notificationDate" : "2019-01-11T11:27:44.422+01:00",
    "number" : "1",
    "result" : "esito"
  }, {
    "date" : "2019-01-11T11:27:57.098+01:00",
    "docType" : "EC",
    "file" : "ZEdWemRBPT0=",
    "filename" : "IT22222222_33825_EC_001.xml.p7m",
    "invoiceId" : "3",
    "notificationDate" : "2019-01-11T11:27:57.098+01:00",
    "number" : "1",
    "result" : "esito"
  } ]
}

Response fields

Path Type Description

count

Number

count

notifications

Array

notification

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

filename della notifica (es. IT01234567890_abcde_XX_nnn.xml)

notifications[].invoiceId

String

Id Mongo della fattura

notifications[].notificationDate

String

Data consegna della notifica

notifications[].number

String

Riferimento della fattura associata

notifications[].result

String

Esito della fattura

12.3. getByInvoiceId

GET /services/notification/in/{invoiceId}

Ricerca le notifiche di una fattura per id della fattura

HTTP request

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

Request headers

Name Description

Authorization

Authorization

Path parameters

Table 1. /services/notification/in/{invoiceId}
Parameter Description

invoiceId

Invoice id

HTTP response

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

{
  "count" : 2,
  "notifications" : [ {
    "date" : "2019-01-11T11:27:44.422+01:00",
    "docType" : "NS",
    "file" : "ZEdWemRBPT0=",
    "filename" : "IT8767263443_33825_RC_001.xml",
    "invoiceId" : "3",
    "notificationDate" : "2019-01-11T11:27:44.422+01:00",
    "number" : "1",
    "result" : "esito"
  }, {
    "date" : "2019-01-11T11:27:57.098+01:00",
    "docType" : "EC",
    "file" : "ZEdWemRBPT0=",
    "filename" : "IT22222222_33825_EC_001.xml.p7m",
    "invoiceId" : "3",
    "notificationDate" : "2019-01-11T11:27:57.098+01:00",
    "number" : "1",
    "result" : "esito"
  } ]
}

Response fields

Path Type Description

count

Number

count

notifications

Array

notification

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

filename della notifica (es. IT01234567890_abcde_XX_nnn.xml)

notifications[].invoiceId

String

Id Mongo della fattura

notifications[].notificationDate

String

Data consegna della notifica

notifications[].number

String

Riferimento della fattura associata

notifications[].result

String

Esito della fattura

13. Specifica callback

Le callback saranno disponibili a partire dal 15 Gennaio 2019.

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 effettuare uno specifico accreditamento, esponendo un Web Service che implementi i seguenti metodi REST.

La sicurezza delle chiamate sarà assicurata tramite una api-key statica da passare tramite header Authorization.

Nome Descrizione

Authorization

API-KEY statica da concordare con l’utente, durante la fase di accreditamento

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.

Path Type Description

username

String

Nome utente

countryCode

String

Codice paese (es. IT per )

vatCode

String

Partita IVA

fiscalCode

String

Codice fiscale

sdiIdentification

String

Identificativo SDI

sdiInvoiceFileName

String

Nome file fattura

invoiceXmlBase64

String

Stringa xml della fattura in base64

sdiMetadataFileName

String

Nome file notifica metadati (MT)

metadataXmlBase64

String

Stringa xml della notifica metadati (MT) in base64

Il metodo dovrà ritornare i seguenti codici HTTP.

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.

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

Path Type Description

username

String

Nome utente

countryCode

String

Codice paese (es. IT per )

vatCode

String

Partita IVA

fiscalCode

String

Codice fiscale

inOut

String

OUT per fatture inviate, IN per fatture ricevute

notifyType

String

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

sdiIdentification

String

Identificativo SDI

notifyFileName

String

Nome file notifica

notifyXmlBase64

String

Stringa xml della notifica in base64

Il metodo dovrà ritornare i seguenti codici HTTP.

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.

Path Type Description

username

String

Nome utente

countryCode

String

Codice paese (es. IT per )

vatCode

String

Partita IVA

fiscalCode

String

Codice fiscale

invoiceFileName

String

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

status

String

Stato della fattura, può essere Inviata oppure Errore Elaborazione

errorDescription

String

Descrizione errore nel caso in cui lo stato sia Errore Elaborazione

Il metodo dovrà ritornare i seguenti codici HTTP.

Codice Descrizione

200

Operazione effettuata con successo

400

Parametri di input mancanti o non validi

500

Errore interno