change log link

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

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

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

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

{
  "access_token" : "131c9278cadbc200",
  "token_type" : "bearer",
  "expires_in" : 1800,
  "refresh_token" : "3fea8d679e68303d",
  "userName" : "Utente",
  "as:client_id" : "Auth",
  ".issued" : "Fri, 03 May 2019 13:39:43 GMT",
  ".expires" : "Fri, 03 May 2019 14:09:43 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: 101

{
  "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 durante una chiamata di refresh non viene specificato lo stesso token, ritorna l’errore: "invalid_grant"
Altrimenti viene generato un nuovo token.

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?grant_type=refresh_token&refresh_token=ee4aae0c9d754ad08a657510cae82efe 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).

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

Campo Tipo Descrizione Vincoli

userID

String

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

userName

String

Utente accreditato sul sistema

Obbligatorio

password

String

Password

Obbligatorio

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

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

Response fields

Campo Tipo Descrizione

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 del file .xml, 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 base url altri metodi/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

Campo Tipo Descrizione Vincoli

userID

String

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

userName

String

Utente accreditato sul sistema

Obbligatorio

password

String

Password

Obbligatorio

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

{
  "errorCode" : "",
  "errorDescription" : "",
  "requestID" : "DR3W8IB0WPRMRXKX",
  "requestIDList" : [ {
    "fileName" : "ITADFSREETDSD_LI_0001.xml",
    "requestID" : "TI0V8JJGCRONKA5B"
  }, {
    "fileName" : "ITADFSREETDSD_LI_0002.xml",
    "requestID" : "4XIAURE22LTFHHEG"
  }, {
    "fileName" : "ITADFSREETDSD_LI_0003.xml",
    "requestID" : "2BTH0XOOFFCQDASS"
  } ]
}

Response fields

Campo Tipo Descrizione

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 del singolo file .xml contenuto nel .zip, 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 base url altri metodi/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" : "5XEOVLQCDQ"
}

Request fields

Campo Tipo Descrizione Vincoli

userName

String

Utente accreditato sul sistema

Obbligatorio

password

String

Password

Obbligatorio

requestID

String

Identificativo univoco delle richiesta fornito nella fase di creazione

Obbligatorio

HTTP response

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

{
  "result" : "SF01",
  "error" : "In elaborazione",
  "notifyResult" : "",
  "elaboratedResult" : "",
  "receiptTimestamp" : "2017-04-18 18:30:30",
  "fileID" : "4163578250",
  "fileName" : "IT01879020517__LI_0001.xml"
}

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

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.

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>
    </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 sia con “Tipo Documento” TD20 che con TD01, a seconda della tipologia di autofattura emessa.

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" : ""
}
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 di firma

domain

String

Dominio di firma

HTTP response

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

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

Nome Descrizione

Authorization

Access token ottenuto da signin

Request fields

Campo Tipo Descrizione Vincoli

dataFile

String

File fattura codificato in Base64

Obbligatorio

HTTP response

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

{
  "errorCode" : "",
  "errorDescription" : "Operazione effettuata - 521e052902be7b879d41e0fd586f0e21",
  "uploadFileName" : "IT01879020517_oeadl.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 immediatamentecon 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 getByFilename getByInvoiceId 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)

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

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>

1.4.1.1.2 <IdCodice>: Se valorizzato e se l’elemento informativo 1.4.1.1.1 <IdPaese> vale "IT", viene verificato che la Partita IVA sia censita in Anagrafe Tributaria

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

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

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

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

2.2.2.2 <Natura>

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>

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 base url altri metodi/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)

HTTP request

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

Request headers

Nome Descrizione

Authorization

Authorization

Request parameters

Parametro Descrizione Vincoli

username

username proprietario della fattura inviata/ricevuta

Obbligatorio, deve coincidere con l’username con cui è stato richiesto il token di autenticazione

page

pagina richiesta (default 1)

Compreso tra 1 e totalPages

size

dimensione della pagina (default 10)

Compreso tra 1 e 100

startDate

data creazione fattura (da)

In formato ISO 8601

endDate

data creazione fattura (a)

In formato ISO 8601

countrySender

Codice Paese del cedente/prestatore

Obbligatorio se l’utente username è un’utenza Premium

vatcodeSender

Partita iva del cedente/prestatore

Obbligatorio se l’utente username è un’utenza Premium

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

{
  "errorCode" : "0000",
  "errorDescription" : null,
  "content" : [ {
    "errorCode" : null,
    "errorDescription" : null,
    "id" : "1",
    "sender" : {
      "description" : "Aruba SPA",
      "countryCode" : "IT",
      "vatCode" : "6372762541",
      "fiscalCode" : "N5Hnt9vvMZ"
    },
    "receiver" : {
      "description" : "Rossi SRL",
      "countryCode" : "IT",
      "vatCode" : "8767263441",
      "fiscalCode" : "LVZTeOJ8BN"
    },
    "invoiceType" : "FPR12",
    "docType" : "out",
    "file" : null,
    "filename" : "IT01879020517_jtlk1.xml.p7m",
    "invoices" : [ {
      "invoiceDate" : "2019-05-03T15:39:44.029+02:00",
      "number" : "1",
      "status" : "Inviata",
      "statusDescription" : ""
    } ],
    "username" : "Utente",
    "lastUpdate" : "2019-05-03T15:39:44.029+02:00",
    "creationDate" : "2019-05-03T15:39:44.029+02:00",
    "idSdi" : "7895"
  }, {
    "errorCode" : null,
    "errorDescription" : null,
    "id" : "2",
    "sender" : {
      "description" : "Aruba SPA",
      "countryCode" : "azc",
      "vatCode" : "6920813278",
      "fiscalCode" : "N7XBQXVWx6"
    },
    "receiver" : {
      "description" : "Rossi SRL",
      "countryCode" : "IT",
      "vatCode" : "7431187883",
      "fiscalCode" : "S5rPdEYCzj"
    },
    "invoiceType" : "FPR12",
    "docType" : "out",
    "file" : null,
    "filename" : "IT01879020517_oeadl.xml.p7m",
    "invoices" : [ {
      "invoiceDate" : "2019-05-03T15:39:44.029+02:00",
      "number" : "1",
      "status" : "Inviata",
      "statusDescription" : ""
    } ],
    "username" : "Utente",
    "lastUpdate" : "2019-05-03T15:39:44.029+02:00",
    "creationDate" : "2019-05-03T15:39:44.029+02:00",
    "idSdi" : "7895"
  }, {
    "errorCode" : null,
    "errorDescription" : null,
    "id" : "3",
    "sender" : {
      "description" : "Aruba SPA",
      "countryCode" : "IT",
      "vatCode" : "01004410933",
      "fiscalCode" : "14240575988"
    },
    "receiver" : {
      "description" : "Rossi SRL",
      "countryCode" : "IT",
      "vatCode" : "03239647393",
      "fiscalCode" : "76734101533"
    },
    "invoiceType" : "FPR12",
    "docType" : "out",
    "file" : null,
    "filename" : "IT07264785383_fkdpc.xml.p7m",
    "invoices" : [ {
      "invoiceDate" : "2019-05-03T15:39:44.029+02:00",
      "number" : "1",
      "status" : "Inviata",
      "statusDescription" : ""
    } ],
    "username" : "Utente",
    "lastUpdate" : "2019-05-03T15:39:44.029+02:00",
    "creationDate" : "2019-05-03T15:39:44.029+02:00",
    "idSdi" : "7895"
  }, {
    "errorCode" : null,
    "errorDescription" : null,
    "id" : "4",
    "sender" : {
      "description" : "Aruba SPA",
      "countryCode" : "IT",
      "vatCode" : "14911474696",
      "fiscalCode" : "58369323097"
    },
    "receiver" : {
      "description" : "Rossi SRL",
      "countryCode" : "IT",
      "vatCode" : "10242520654",
      "fiscalCode" : "60996224458"
    },
    "invoiceType" : "FPR12",
    "docType" : "out",
    "file" : null,
    "filename" : "IT07362188188_ltrkf.xml.p7m",
    "invoices" : [ {
      "invoiceDate" : "2019-05-03T15:39:44.029+02:00",
      "number" : "1",
      "status" : "Inviata",
      "statusDescription" : ""
    } ],
    "username" : "Utente",
    "lastUpdate" : "2019-05-03T15:39:44.029+02:00",
    "creationDate" : "2019-05-03T15:39:44.029+02:00",
    "idSdi" : "7895"
  } ],
  "last" : true,
  "totalElements" : 4,
  "totalPages" : 1,
  "size" : 10,
  "number" : 1,
  "first" : true,
  "numberOfElements" : 4
}

Response fields

Campo Tipo Descrizione

errorCode

String

Codice di errore

errorDescription

String

Eventuale descrizione errore

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

String

Codice di errore

content[].errorDescription

String

Eventuale descrizione errore

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

String

Data di creazione

content[].idSdi

String

Identificativo SdI (Sistema di Interscambio)

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

String

Stato della fattura

content[].invoices.[].statusDescription

String

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

8.3. getByFilename

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

GET base url altri metodi/services/invoice/out/getByFilename

Ricerca una singola fattura per filename (es. IT01879020517_abcde.xml.p7m)

HTTP request

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

Request headers

Nome Descrizione

Authorization

Authorization

Request parameters

Parametro Descrizione Vincoli

filename

File name

Obbligatorio

HTTP response

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

{
  "errorCode" : null,
  "errorDescription" : null,
  "id" : "1",
  "sender" : {
    "description" : "Aruba SPA",
    "countryCode" : "IT",
    "vatCode" : "6372762541",
    "fiscalCode" : "N5Hnt9vvMZ"
  },
  "receiver" : {
    "description" : "Rossi SRL",
    "countryCode" : "IT",
    "vatCode" : "8767263441",
    "fiscalCode" : "LVZTeOJ8BN"
  },
  "invoiceType" : "FPR12",
  "docType" : "out",
  "file" : "ZEdWemRBPT0=",
  "filename" : "IT01879020517_jtlk1.xml.p7m",
  "invoices" : [ {
    "invoiceDate" : "2019-05-03T15:39:44.092+02:00",
    "number" : "1",
    "status" : "Inviata",
    "statusDescription" : ""
  } ],
  "username" : "Utente",
  "lastUpdate" : "2019-05-03T15:39:44.092+02:00",
  "creationDate" : "2019-05-03T15:39:44.092+02:00",
  "idSdi" : "9995"
}

Response fields

Campo Tipo Descrizione

errorCode

String

Codice di errore

errorDescription

String

Eventuale descrizione errore

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)

invoices

Array

Array delle singole fatture presenti nel lotto

username

String

Username del proprietario della fattura

lastUpdate

String

Data di ultimo aggiornamento

creationDate

String

Data di creazione

idSdi

String

Identificativo SdI (Sistema di Interscambio)

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

String

Stato della fattura

invoices.[].statusDescription

String

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

8.4. getByInvoiceId

GET base url altri metodi/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

Nome Descrizione

Authorization

Authorization

Path parameters

Parametro Descrizione

invoiceId

Identificativo fattura

HTTP response

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

{
  "errorCode" : "0000",
  "errorDescription" : null,
  "id" : "1",
  "sender" : {
    "description" : "Aruba SPA",
    "countryCode" : "IT",
    "vatCode" : "6372762541",
    "fiscalCode" : "N5Hnt9vvMZ"
  },
  "receiver" : {
    "description" : "Aruba SPA",
    "countryCode" : "IT",
    "vatCode" : "8767263441",
    "fiscalCode" : "LVZTeOJ8BN"
  },
  "invoiceType" : "FPR12",
  "docType" : "out",
  "file" : "ZEdWemRBPT0=",
  "filename" : "IT01879020517_jtlk1.xml.p7m",
  "invoices" : [ {
    "invoiceDate" : "2019-05-03T15:39:44.123+02:00",
    "number" : "1",
    "status" : "Inviata",
    "statusDescription" : null
  } ],
  "username" : "Utente",
  "lastUpdate" : "2019-05-03T15:39:44.123+02:00",
  "creationDate" : "2019-05-03T15:39:44.123+02:00",
  "idSdi" : "9998l"
}

Response fields

Campo Tipo Descrizione

errorCode

String

Codice di errore

errorDescription

String

Eventuale descrizione errore

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)

invoices

Array

Array delle singole fatture presenti nel lotto

username

String

Username del proprietario della fattura

lastUpdate

String

Data di ultimo aggiornamento

creationDate

String

Data di creazione

idSdi

String

Identificativo SdI (Sistema di Interscambio)

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

String

Stato della fattura

invoices.[].statusDescription

String

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

9. Ricerca Fatture Ricevute

searching received invoice

Metodi di ricerca fatture ricevute

9.1. findByUsername

GET base url altri metodi/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

Nome Descrizione

Authorization

Authorization

Request parameters

Parametro Descrizione Vincoli

username

username proprietario della fattura inviata/ricevuta

Obbligatorio, deve coincidere con l'`username` con cui è stato richiesto il token di autenticazione

page

pagina richiesta (default 1)

Compreso tra 1 e totalPages

size

dimensione della pagina (default 10)

Compreso tra 1 e 100

startDate

data creazione fattura (da)

In formato ISO 8601

endDate

data creazione fattura (a)

In formato ISO 8601

countrySender

Codice Paese del cedente/prestatore

vatcodeSender

Partita iva del cedente/prestatore

fiscalcodeSender

Codice fiscale del cedente/prestatore

countryReceiver

Codice Paese del cessionario/committente

Obbligatorio se l’utente username è un’utenza Premium

vatcodeReceiver

Partita iva del cessionario/committente

Obbligatorio se l’utente username è un’utenza Premium

fiscalcodeReceiver

Codice fiscale del cessionario/committente

HTTP response

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

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

Response fields

Campo Tipo Descrizione

errorCode

String

Codice di errore

errorDescription

String

Eventuale descrizione errore

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

String

Codice di errore

content[].errorDescription

String

Eventuale descrizione errore

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

String

Data di creazione

content[].idSdi

String

Identificativo SdI (Sistema di Interscambio)

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

String

Stato della fattura

content[].invoices.[].statusDescription

String

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

9.2. getByFilename

GET base url altri metodi/services/invoice/in/getByFilename

Ricerca una singola fattura per filename (es. IT01879020517_abcde.xml.p7m)

HTTP request

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

Request headers

Nome Descrizione

Authorization

Authorization

Request parameters

Parametro Descrizione Vincoli

filename

File name

Example constraints

HTTP response

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

{
  "errorCode" : null,
  "errorDescription" : null,
  "id" : "2",
  "sender" : {
    "description" : "Aruba SPA",
    "countryCode" : "IT",
    "vatCode" : "22222222",
    "fiscalCode" : "11111111111"
  },
  "receiver" : {
    "description" : "Aruba SPA",
    "countryCode" : "IT",
    "vatCode" : "4444444",
    "fiscalCode" : "333333333"
  },
  "invoiceType" : "FPR12",
  "docType" : "in",
  "file" : "dGVzdA==",
  "filename" : "IT01879020517_jtlk1.xml.p7m",
  "invoices" : [ {
    "invoiceDate" : "2019-05-03T15:39:40.139+02:00",
    "number" : "2019/0002",
    "status" : "Inviata",
    "statusDescription" : ""
  } ],
  "username" : "Utente",
  "lastUpdate" : "2019-05-03T15:39:40.139+02:00",
  "creationDate" : "2019-05-03T15:39:40.139+02:00",
  "idSdi" : "11111"
}

Response fields

Campo Tipo Descrizione

errorCode

String

Codice di errore

errorDescription

String

Eventuale descrizione errore

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)

invoices

Array

Array delle singole fatture presenti nel lotto

username

String

Username del proprietario della fattura

lastUpdate

String

Data di ultimo aggiornamento

creationDate

String

Data di creazione

idSdi

String

Identificativo SdI (Sistema di Interscambio)

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

String

Stato della fattura

invoices.[].statusDescription

String

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

9.3. getZipByFilename

GET base url altri metodi/services/invoice/in/getZipByFilename

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

HTTP request

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

Request headers

Nome Descrizione

Authorization

Authorization

Request parameters

Parametro Descrizione Vincoli

filename

File name

Example constraints

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 base url altri metodi/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

Nome Descrizione

Authorization

Authorization

Path parameters

Parametro Descrizione

invoiceId

Identificativo fattura

HTTP response

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

{
  "errorCode" : "0000",
  "errorDescription" : null,
  "id" : "1",
  "sender" : {
    "description" : "Aruba SPA",
    "countryCode" : "IT",
    "vatCode" : "22222222",
    "fiscalCode" : "11111111111"
  },
  "receiver" : {
    "description" : "Aruba SPA",
    "countryCode" : "IT",
    "vatCode" : "4444444",
    "fiscalCode" : "333333333"
  },
  "invoiceType" : "FPR12",
  "docType" : "in",
  "file" : "ZEdWemRBPT0=",
  "filename" : "IT01879020517_jtlk0.xml.p7m",
  "invoices" : [ {
    "invoiceDate" : "2019-05-03T15:39:40.123+02:00",
    "number" : "2019/0001",
    "status" : "Inviata",
    "statusDescription" : ""
  } ],
  "username" : "Utente",
  "lastUpdate" : "2019-05-03T15:39:40.139+02:00",
  "creationDate" : "2019-05-03T15:39:40.139+02:00",
  "idSdi" : "11110"
}

Response fields

Campo Tipo Descrizione

errorCode

String

Codice di errore

errorDescription

String

Eventuale descrizione errore

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)

invoices

Array

Array delle singole fatture presenti nel lotto

username

String

Username del proprietario della fattura

lastUpdate

String

Data di ultimo aggiornamento

creationDate

String

Data di creazione

idSdi

String

Identificativo SdI (Sistema di Interscambio)

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

String

Stato della fattura

invoices.[].statusDescription

String

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

10. Invio Esito Committente

10.1. sendEsitoCommittente

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

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

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

Authorization

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: Accettata, EC02: Rifiutata)

Obbligatorio

numero

String

Numero della fattura

Obbligatorio

anno

Number

Anno della fattura

Obbligatorio

posizione

Number

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

Obbligatorio

descrizione

String

Eventuale descrizione da inserire nell’esito

Obbligatorio

messageId

String

ID del messaggio a cura del committente

Obbligatorio

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 base url altri metodi/services/notification/out/getByFilename

Ricerca una notifica per filename (es IT01879020517_abcdef_RC_001.xml)

HTTP request

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

Request headers

Nome Descrizione

Authorization

Authorization

Request parameters

Parametro Descrizione Vincoli

filename

filename

Obbligatorio

HTTP response

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

{
  "date" : "2019-05-03T15:39:44.467+02:00",
  "docType" : "RC",
  "file" : "ZEdWemRBPT0=",
  "filename" : "IT01879020517_33825_RC_001.xml",
  "invoiceId" : "1",
  "notificationDate" : "2019-05-03T15:39:44.467+02:00",
  "number" : null,
  "result" : null,
  "errorCode" : "0000",
  "errorDescription" : null
}

Response fields

Campo Tipo Descrizione

errorCode

String

Codice di errore

errorDescription

String

Eventuale descrizione errore

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: Accettata, EC02: Rifiutata)

11.2. getByInvoiceFilename

GET base url altri metodi/services/notification/out/getByInvoiceFilename

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

HTTP request

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

Request headers

Nome Descrizione

Authorization

Authorization

Request parameters

Parametro Descrizione Vincoli

invoiceFilename

Invoice Filename

Obbligatorio

HTTP response

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

{
  "count" : 1,
  "notifications" : [ {
    "date" : "2019-05-03T15:39:44.529+02:00",
    "docType" : "RC",
    "file" : "ZEdWemRBPT0=",
    "filename" : "IT01879020517_33825_RC_001.xml",
    "invoiceId" : "1",
    "notificationDate" : "2019-05-03T15:39:44.529+02:00",
    "number" : null,
    "result" : null,
    "errorCode" : "0000",
    "errorDescription" : null
  } ],
  "errorCode" : "0000",
  "errorDescription" : null
}

Response fields

Campo Tipo Descrizione

errorCode

String

Codice di errore

errorDescription

String

Eventuale descrizione errore

count

Number

Numero notifiche associate alla fattura

notifications

Array

Notifiche associate alla fattura

notifications[].errorCode

String

Codice di errore

notifications[].errorDescription

String

Eventuale descrizione errore

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: Accettata, EC02: Rifiutata)

11.3. getByInvoiceId

GET base url altri metodi/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

Nome Descrizione

Authorization

Authorization

Path parameters

Parametro Descrizione

invoiceId

Identificativo fattura

HTTP response

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

{
  "count" : 1,
  "notifications" : [ {
    "date" : "2019-05-03T15:39:44.498+02:00",
    "docType" : "RC",
    "file" : "ZEdWemRBPT0=",
    "filename" : "IT01879020517_33825_RC_001.xml",
    "invoiceId" : "1",
    "notificationDate" : "2019-05-03T15:39:44.498+02:00",
    "number" : "1",
    "result" : "esito",
    "errorCode" : null,
    "errorDescription" : null
  } ],
  "errorCode" : "0000",
  "errorDescription" : null
}

Response fields

Campo Tipo Descrizione

errorCode

String

Codice di errore

errorDescription

String

Eventuale descrizione errore

count

Number

Numero notifiche associate alla fattura

notifications

Array

Notifiche associate alla fattura

notifications[].errorCode

String

Codice di errore

notifications[].errorDescription

String

Eventuale descrizione errore

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: Accettata, EC02: Rifiutata)

12. Ricerca Notifiche su Fatture Ricevute

Metodi di ricerca notifiche ricevute

12.1. getByFilename

GET base url altri metodi/services/notification/in/getByFilename

Ricerca una notifica per filename (es. IT01879020517_abcde_RC_nnn.xml)

HTTP request

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

Request headers

Nome Descrizione

Authorization

Authorization

Request parameters

Parametro Descrizione Vincoli

filename

filename

Obbligatorio

HTTP response

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

{
  "date" : "2019-05-03T15:39:40.139+02:00",
  "docType" : "NS",
  "file" : "ZEdWemRBPT0=",
  "filename" : "IT01879020517_33822_RC_001.xml",
  "invoiceId" : "2",
  "notificationDate" : "2019-05-03T15:39:40.139+02:00",
  "number" : null,
  "result" : null,
  "errorCode" : "0000",
  "errorDescription" : null
}

Response fields

Campo Tipo Descrizione

errorCode

String

Codice di errore

errorDescription

String

Eventuale descrizione errore

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: Accettata, EC02: Rifiutata)

12.2. getByInvoiceFilename

GET base url altri metodi/services/notification/in/getByInvoiceFilename

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

HTTP request

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

Request headers

Nome Descrizione

Authorization

Authorization

Request parameters

Parametro Descrizione Vincoli

invoiceFilename

Invoice Filename

Obbligatorio

HTTP response

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

{
  "count" : 2,
  "notifications" : [ {
    "date" : "2019-05-03T15:39:40.139+02:00",
    "docType" : "NS",
    "file" : "ZEdWemRBPT0=",
    "filename" : "IT01879020517_33822_RC_001.xml",
    "invoiceId" : "2",
    "notificationDate" : "2019-05-03T15:39:40.139+02:00",
    "number" : null,
    "result" : null,
    "errorCode" : "0000",
    "errorDescription" : null
  }, {
    "date" : "2019-05-03T15:39:44.154+02:00",
    "docType" : "EC",
    "file" : "ZEdWemRBPT0=",
    "filename" : "IT01879020517_33825_EC_001.xml.p7m",
    "invoiceId" : "2",
    "notificationDate" : "2019-05-03T15:39:44.154+02:00",
    "number" : "1",
    "result" : "esito",
    "errorCode" : "0000",
    "errorDescription" : null
  } ],
  "errorCode" : "0000",
  "errorDescription" : null
}

Response fields

Campo Tipo Descrizione

errorCode

String

Codice di errore

errorDescription

String

Eventuale descrizione errore

count

Number

Numero notifiche associate alla fattura

notifications

Array

Notifiche associate alla fattura

notifications[].errorCode

String

Codice di errore

notifications[].errorDescription

String

Eventuale descrizione errore

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: Accettata, EC02: Rifiutata)

12.3. getByInvoiceId

GET base url altri metodi/services/notification/in/{invoiceId}

Ricerca le notifiche di una fattura per id della fattura

HTTP request

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

Request headers

Nome Descrizione

Authorization

Authorization

Path parameters

Parametro Descrizione

invoiceId

Identificativo fattura

HTTP response

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

{
  "count" : 2,
  "notifications" : [ {
    "date" : "2019-05-03T15:39:40.139+02:00",
    "docType" : "NS",
    "file" : "ZEdWemRBPT0=",
    "filename" : "IT01879020517_33822_RC_001.xml",
    "invoiceId" : "2",
    "notificationDate" : "2019-05-03T15:39:40.139+02:00",
    "number" : null,
    "result" : null,
    "errorCode" : "0000",
    "errorDescription" : null
  }, {
    "date" : "2019-05-03T15:39:44.154+02:00",
    "docType" : "EC",
    "file" : "ZEdWemRBPT0=",
    "filename" : "IT01879020517_33825_EC_001.xml.p7m",
    "invoiceId" : "2",
    "notificationDate" : "2019-05-03T15:39:44.154+02:00",
    "number" : "1",
    "result" : "esito",
    "errorCode" : "0000",
    "errorDescription" : null
  } ],
  "errorCode" : "0000",
  "errorDescription" : null
}

Response fields

Campo Tipo Descrizione

errorCode

String

Codice di errore

errorDescription

String

Eventuale descrizione errore

count

Number

Numero notifiche associate alla fattura

notifications

Array

Notifiche associate alla fattura

notifications[].errorCode

String

Codice di errore

notifications[].errorDescription

String

Eventuale descrizione errore

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: Accettata, EC02: 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 effettuare uno specifico accreditamento tramite l’assistenza dedicata, esponendo un Web Service che implementi i metodi descritti nei paragrafi seguenti. L’endpoint esposto dall’utente dovrà utilizzare per la comunicazione la porta 80 se in http, o la porta 443 se in https.

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

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.

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.

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

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.

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 solo se status è Inviata

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

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

Changelog


1.2.0 - dal 13/05/2019

Changed

  • Aggiornamento SLA con numeri di richieste al minuto per IP

  • Migliorata documentazione metodo refresh


1.1.0 - dal 25/02/2019

Removed

  • Rimosso ambiente di Test dalla documentazione

  • Rimosso metodo MonitorCheck dalla documentazione

Deprecated

  • Metodo MonitorCheck

Fixed


1.0.0 - dal 01/12/2018

Prima versione


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