Versioni del documentocs-test.teamsystem.com/knos/wcf/cs/doc/CS-WebServices... · Web viewLa...

TeamSystem®

Servizio CCT

Servizio CCTWeb Services

Versione

0.58 Luglio 2015

Servizio CCTWeb Services – Specifiche Tecniche

Specifiche Tecniche

1


SommarioVersioni del documento 3

Parte 1 5

1 Introduzione 5

2 Terminologia 6

3 Logica generale di funzionamento 83.1 Tecnologia utilizzata 83.2 Convenzioni sui nomi utilizzati 83.3 Localizzazione messaggi 103.4 Parametri di input e output 103.5 Gestione delle Versioni 113.6 Modalità di test, documentazione ed esempi 123.7 Flusso operativo: schema generale ed esempio 13

Parte 2 14

4 Web Services del Servizio CCT 144.1 Utilizzo degli Endpoint 154.2 Servizio: UserAuthentication 15

4.2.1 Operazione: BasicAuthentication 164.2.2 Operazione: GetTicket 174.2.3 Operazione: DigestAuthentication 18

4.3 Servizio: FileTransfer 204.3.1 Operazione: UploadPdI 204.3.2 Operazione: DownloadFile 22

4.4 Servizio: ServizioCS 234.4.1 Operazione: GetPdI 234.4.2 Operazione: SearchPdI 26

Appendice A 31

5 Workflow del PdI 31

Appendice B 33

6 Parametri di tipo oggetto 336.1 ServiceInfo 336.2 NameValue 336.3 BaseUserIdentity 346.4 UserIdentity 346.5 BasicAuthentication 346.6 DigestAuthentication 346.7 SoggettoProduttore, SoggettoTitolare, SoggettoOrigine, SoggettoDestinazione 356.8 DatiDocumento 366.9 InfoPdI 456.10 FileInfo 456.11 SearchFilterPdI 466.12 SearchResultPdI 46

1


Appendice C 47

7 Valori enumerati 477.1 PdIFileType 477.2 HashType 487.3 Operator 487.4 ArgType 497.5 Direction 49

Appendice D 50

8 Parametri di ricerca 508.1 SearchExpression 508.2 OrderBy 51

Appendice E 52

9 Elenco errori 529.1 Errori nei dati della richiesta 539.2 Errori di sicurezza 549.3 Errori in fase di elaborazione 55

2


Versioni del documento

Versione 0.5

Data 08/07/2015

Autori Davide Nani, Giampiero Levo

Descrizione

Aggiornato il DataContract DatiDocumenti e i codici di errore.

Versione 0.4

Data 06/07/2015


Descrizione

Modificata l'OperationContract GetPdI del servizio ServizioCS e l'OperationContract DownloadFile del servizio FileTransfer.

Versione 0.3

Data 29/06/2015


Descrizione

Aggiornamento data contract servizi e codici di errore.

Versione 0.2

Data 23/06/2015


Descrizione

Aggiornamento data contract servizi e codici di errore.

3


Versione 0.1

Data 11/03/2015


Descrizione

Documentazione preliminare di progetto.Mancano ancora le specifiche dettagliate sulle modalità di ricerca che verranno illustrate nell’appendice D.Alcuni aspetti dell’interfaccia possono ancora subire delle modifiche per iniziativa di TeamSystem o su suggerimenti delle parti interessate.

4


1 IntroduzioneMotivazioni e finalità del presente documento

Lo scopo di questo documento è fornire la documentazione tecnica sui Web Services esposti dal Servizio di Conservazione Sostitutiva in Cloud di TeamSystem (Servizio CCT).

Questo documento è rivolto agli utenti accreditati che vogliono interfacciarsi programmaticamente al servizio per:

trasmettere documenti da conservare monitorare/scaricare pacchetti di archiviazione

5

Parte 1


2 TerminologiaSignificato dei termini utilizzati nel presente documento

Conservazione Sostitutiva

E’ la procedura prevista dalle attuali leggi in materia fiscale (DPR 59 del 12-3-2014)) che consente di dematerializzare i documenti cartacei e conservare gli equivalenti digitali rispettando certe regole (firma digitale, marcatura temporale, ecc.) in grado di garantire i requisiti di legge (autenticità, integrità, affidabilità, leggibilità, reperibilità) che attribuiscono piena validità ai fini legali e fiscali.

La normativa stabilisce anche le regole con cui devono essere conservati i documenti fiscali emessi direttamente in formato elettronico. Per questi non si ha una dematerializzazione ovvero una sostituzione del documento cartaceo originale e ultimamente ci si sta orientando verso il termine di Conservazione Digitale o in modo più neutro di Conservazione a Norma come sinonimi più qualificati per la Conservazione Sostitutiva.

Pacchetto Informativo E’ un contenitore che racchiude uno o più oggetti da conservare (documenti informatici, fascicoli informatici, aggregazioni documentali informatiche), o anche solo i metadati riferiti agli oggetti da conservare.

Pacchetto di Versamento (PdV)

E’ un pacchetto informativo inviato dal produttore al sistema di conservazione secondo un formato predefinito e concordato descritto nel manuale di conservazione.

Pacchetto di Archiviazione(PdA)

E’ un pacchetto informativo composto dalla trasformazione di uno o più pacchetti di versamento secondo le specifiche definite dall’attuale normativa.

Pacchetto di Distribuzione(PdD)

E’ un pacchetto informativo inviato dal sistema di conservazione all’utente in risposta ad una sua richiesta.

KnoS E’ il DMS che ospita le personalizzazioni richieste.

Pubblicazione E’ l’elemento base per l’organizzazione delle informazioni su KnoS. Una pubblicazione è un oggetto caratterizzato da attributi che può ospitare uno o più file allegati ed essere messo in relazione con altre pubblicazioni.

Tipologia Le tipologie definiscono categorie di pubblicazioni che hanno in comune gli stessi attributi e uno stesso workflow. Una pubblicazione è

6


sostanzialmente un’istanza di una certa tipologia.

Attributi Sono i metadati associati alle pubblicazioni definibili e valorizzabili dagli utenti o da programma.Gli attributi si dividono in due classi principali: gli attributi semplici (o mono valore) e gli attributi di tipo elenco (pubblicazioni o valori enumerati).

Documenti Sono i file allegati alle pubblicazioni dagli utenti o da programmi. Comprendono sia i file destinati alla Conservazione Sostitutiva che i file intermedi di indicizzazione, ecc.

Web Services CS Sono i web services esposti da KnoS per consentire l’accesso in via programmatica al servizio in alternativa all’interfaccia web.

7


3 Logica generale di funzionamentoA cosa servono i Web Services e qual è la logica di funzionamento

I Web Services sono stati introdotti sulla piattaforma del Servizio CCT per consentire ai clienti l’automatizzazione completa delle operazioni coinvolte nel processo della conservazione sostitutiva.

La logica di funzionamento del Servizio CCT non cambia con l’introduzione dei Web Services e vengono comunque mantenute le modalità tradizionali di upload e download da interfaccia web.

Oltre a sostituire le procedure manuali di upload e download i Web Services permetteranno anche il monitoraggio dello stato dei documenti conservati e l’ottenimento di dati statistici consentendo agli utenti di realizzare all’occorrenza una propria interfaccia completa verso il Servizio CCT.

3.1 Tecnologia utilizzataI Web Services del Servizio CCT TeamSystem sono realizzati utilizzando Microsoft WCF 4.5 come componente per l’infrastruttura di base.

Il protocollo di scambio implementato è SOAP 1.2.

Per lo scambio di file (upload/download) si utilizza MTOM (Message Transmission Optimization Mechanism).

I Web Services implementati restituiscono i dettagli sull’interfaccia implementata se richiamati con ?wsdl o ?singlewsdl.

Oltre alle informazioni contenute in questo documento e all’auto-documentazione restituita dai Web Services verrà fornito anche un progetto sviluppato in C# con esempi dettagliati di richiamo per tutte le operazioni disponibili.

3.2 Convenzioni sui nomi utilizzatiLa piattaforma su cui si basa l’applicativo utilizza nei propri Web Services interni una nomenclatura basata su termini inglesi. Dovendo mettere in comunicazione la terminologia inglese con la termilogia italiana relativa all’argomento conservazione sostitutiva si è adottato un approccio neutrale che cercasse di mantenere i nomi originali per semplificare la comprensione dei concetti che stanno alla base dei servizi, delle operazioni e dei parametri implementati.

8


Si è quindi ritenuto inutile operare una scelta per una lingua o per l’altra e quindi tradurre termini come “Soggetto Conservante”, “PdI”, ecc. in inglese o, viceversa, ritradurre in italiano una quantità di termini molto superiore che deriva dal DMS KnoS alla base del Servizio CCT. Questo approccio ha il pregio di mantenere la corrispondenza con i termini originali in entrambe le lingue ed elimina il rischio, sempre in agguato quando si procede a tradurre concetti locali specifici nella lingua di altre nazioni, di trovare parole non traducibili o almeno non traducibili in termini sintetici o con un significato perfettamente equivalente all’originale.

In conclusione la convenzione adottata è la seguente:

tutti i nomi relativi a concetti provenienti da KnoS sono espressi con i termini originali in inglese (IdStatus, StatusName, DateCreation, ecc.);

tutti i nomi relativi a concetti provenienti dalla conservazione sostitutiva hanno mantenuto il loro nome originale con l’eventuale aggiunta del suffisso o del prefisso PdI, PdD per rimarcarne la tipologia;

per i concetti generali che sono però collegati a concetti locali è ammesso l’uso di nomi ibridi quando il termine originato risulta chiaramente comprensibile e non eccessivamente stravagante. Ad esempio UploadPdI è stato utilizzato come nome del metodo atto all’invio di documenti da conservare poiché il termine upload è di uso generico ed è diventato comune anche nella lingua italiana.

nei casi ambigui si è lasciata agli sviluppatori la libertà di scelta dei nomi per cui ad esempio si sono preferiti termini come ElencoInfoPdI a cose tipo InfoPdIList, mentre per indicare gli elenchi dei file di un PdI il termine FileList è sembrato più appropriato in quanto facilmente comprensibile e già presente all’interno di KnoS

Ci auguriamo, con le scelte fatte, di non urtare troppo la sensibilità e il gusto linguistico degli utilizzatori dei nostri Web Services.

“Stat rosa pristina nomine, nomina nuda tenemus”(Umberto Eco – Il nome della rosa)

“What’s in a name? That which we call a roseBy any other name would smell as sweet.”

(William Shakespeare – Romeo and Juliet)

9


3.3 Localizzazione messaggi La lingua di default dei messaggi, tipicamente di eccezione, restituiti dai vari metodi dei web services è l’italiano.

È possibile però impostare i web services affinchè utilizzino la lingua inglese per i messaggi restituiti; per far ciò occorre aggiungere il nodo “Language” all’header della richiesta soap come illustrato di seguito:

<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope"><s:Header>

<Language xmlns="KnosCSServices">en</Language></s:Header><s:Body>

<BasicAuthentication xmlns="http://www.teamsystem.com/"><BasicAuthentication

xmlns:a="http://schemas.datacontract.org/2004/07/KnosCS.Services.DataContracts.Input" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

<a:Password>Password</a:Password><a:UserName>Username</a:UserName>

</BasicAuthentication></BasicAuthentication>

</s:Body></s:Envelope>Si vedano le applicazioni di demo in ASP.NET e Java per approfondire l’implementazione.

3.4 Parametri di input e outputTutti i Web Service del Servizio CCT sono auto-documentati tramite WSDL, in questo documento vengono fornite le specifiche in termini descrittivi ponendo l’accento sulle regole non specificabili tramite WSDL. I parametri di tipo semplice utilizzati sono:

o stringa stringa unicode con lunghezza massima fino a 200 caratterio testo testo unicode di lunghezza superiore ai 200 caratterio intero numero intero con segno a 32 bito data-ora data e ora o enumerato valore di tipo stringa preso da un elenco di valori predefinitio file file allegato alla richiesta/risposta

Per il tipo stringa la presenza di un eventuale numero tra parentesi indica la lunghezza massima accettata, ad esempio:

stringa (100) indica una stringa di testo di lunghezza massima di 100 caratteri unicode

Eventuali restrizioni o indicazioni sui caratteri utilizzabili (ad esempio per i nomi dei file) sono indicate nei capitoli che descrivono l’operazione specifica.

10


Per il tipo testo si indica sempre la dimensione massima accettata, che sarebbe altrimenti arbitraria e potenzialmente invasiva, con la stessa sintassi utilizzata per la stringa:

testo (1000) indica un testo di lunghezza massima di 1000 caratteri unicode

I parametri di tipo oggetto sono costituiti da insiemi di tipi semplici, elenchi di tipi semplici o elenchi di oggetti.

Il contenuto di questi tipi è dettagliato solo la prima volta che vengono descritti. L’appendice B documenta nel dettaglio i parametri di tipo oggetto utilizzati nei DataContract.

3.5 Gestione delle VersioniTutte le operazioni esposte dai servizi restituisco in output il parametro ServiceInfo che contiene nella proprietà ServiceVersion (di tipo stringa) la versione corrente del servizio.

Parametro di Output Tipo Descrizione

ServiceInfo oggetto Contenitore per la versione corrente del Servizio ed eventuali informazioni aggiuntive.

ServiceVersion stringa Versione corrente del servizio.

La versione è espressa come sequenza di tre numeri separati da punto:

VersionNumber . ReleaseNumber . BuildNumber

Ad esempio Version = “1.2.3” indica che:

VersionNumber = 1 è il numero di versioneReleaseNumber = 2 è il numero di rilascioBuildNumber = 3 è il numero di compilazione

La regola adottata internamente è che ogni volta che si ricompilano i Web Services a fronte di una modifica significativa si incrementa il numero di compilazione.

Se la modifica determina una variazione nell’interfaccia dei Web Services (ad esempio l’aggiunta di una operazione o di un parametro) che non altera la compatibilità con la versione precedente si incrementa il numero di rilascio e si azzera il numero di compilazione.

Se la modifica è tale da rendere incompatibile il servizio con la versione precedente allora si crea un nuovo servizio con lo stesso nome a cui si appende il numero di versione, fa eccezione a questa regola la versione iniziale del servizio che non riporta il numero di versione.

Ad esempio le operazioni del servizio ServizioCS restituiranno come versioni:

1.0.0, 1.0.1, … , 1.2.0, 1.2.1, …

11


Quando si renderà necessaria una modifica di versione (rottura della compatibilità con l’interfaccia precedente) si realizzerà il servizio ServizioCS2 le cui operazioni restituiranno come versioni:

2.0.0, 2.0.1, … , 2.2.0, 2.2.1, …

L’introduzione di una nuova versione non elimina (a meno che non sia indispensabile) la versione precedente, per cui il client sarà libero di richiamare il servizio ServizioCS o il servizio ServizioCS2. Ovviamente uno dei due servizi potrebbe non offrire tutte le funzionalità dell’altro.

È anche possibile avere scenari misti per cui un client continua a richiamare il servizio ServizioCS per le operazioni già implementate mentre richiama ServizioCS2 solo per le nuove funzionalità introdotte.

3.6 Modalità di test, documentazione ed esempiÈ disponibile un sito di test per lo sviluppo dell’integrazione. I Web Services del Servizio CCT sono ospitati nella cartella all’indirizzo:

http://CS-test.teamsystem.com/knos/wcf/CS

La cartella:http://CS-test.teamsystem.com/knos/wcf/CS/samples

contiene un progetto di esempio in Visual Studio 2013.

La cartella:http://CS-test.teamsystem.com/knos/wcf/CS/doc

contiene la documentazione di progetto nelle varie versioni, per semplificare il controllo su eventuali novità all’indirizzo:

http://CS-test.teamsystem.com/knos/wcf/CS/news.htm

è presente una semplice pagina HTML di testo che riepiloga lo stato di avanzamento.

Le credenziali di accesso al sito di demo vengono rilasciate su richiesta.

12

http://CS-test.teamsystem.com/knos/wcf/CS/news.htm

http://CS-test.teamsystem.com/knos/wcf/CS/doc

http://CS-test.teamsystem.com/knos/wcf/CS/samples

http://CS-test.teamsystem.com/knos/wcf/CS


3.7 Flusso operativo: schema generale ed esempioPrima di poter eseguire una qualunque altra operazione l’utente deve autenticarsi fornendo l’utente e la password rilasciati dagli operatori del Servizio CCT.

All’utente che esegue correttamente la procedura di autenticazione viene rilasciato un SecurityToken (Token di sicurezza) che andrà passato come parametro in tutte le richieste successive.

Ecco una sequenza tipica di richiamo Web Services per la gestione di una fattura:

13

Servizi CS Utente

UserAuthentication

UserName, Ticket, Digest Password/Digest Token di sicurezza

UploadPdISecurityToken, Documento da conservare

IdPdI

StatoPdI Stato PdI, notifiche, file

SecurityToken, IdPdI

RicercaPdI

SecurityToken, IdObject, IdDoc

File della conservazione sostitutiva

GetTicket

DigestAuthentication

BasicAuthentication

Ticket

ServizioCS

SecurityToken, Parametri di ricerca

Elenco PdI paginato

DownloadFile

FileTransfer

FileTransfer


4 Web Services del Servizio CCT Definizione e logica dei servizi implementati

L’architettura dei Web Services implementati dal Servizio CCT di TeamSystem prevede due servizi comuni per l’autenticazione e trasferimento file e poi servizi separati per tipologia di operazione o per classe di utenza che verranno rilasciati gradualmente.

L’implementazione completa dei Web Services avverrà in fasi successive. Allo stato attuale si prevede l’implementazione dei seguenti servizi:

UserAuthentication /knos/wcf/CS/UserAuthentication.svc

FileTransfer /knos/wcf/CS/FileTransfer.svc

ServizioCS /knos/wcf/CS/ServizioCS.svc

I primi due servizi sono di uso generale e consentono l’autenticazione e il trasferimento di file in upload e download.

Nella prima fase l’interazione via Web Services verrà offerta ai soli utenti degli Enti di Caricamento tramite ServizioCS.

In seguito verranno aggiunte nuove operazioni e/o servizi utili alla gestione amministrativa del servizio (recupero dei dati statistici, gestione dei dati di fatturazione, ecc.) alle altre categorie di utenti (amministratori, rivenditori, ecc.).

14

Parte 2


4.1 Utilizzo degli EndpointAttualmente i servizi sono raggiungibili sia via HTTP (solamente in ambiente di test) sia via HTTPS e per ciascun protocollo espongono 3 Endpoint: uno con codifica “classica” Text, uno con codifica MTOM (Message Transmission Optimization Mechanism) e una con codifica Binary.

L’utilizzo della codifica MTOM riduce la dimensione dei messaggi SOAP inviati/ricevuti e quindi è da preferirsi, soprattutto per l’upload/download di file, quando il client utilizzato lo supporta (ASP.NET, Java, ecc.); discorso analogo per la codifica Binary che è ancora più compatta di quella MTOM: essa però è utilizzabile solamente interfacciandosi da client sviluppati in ASP.NET.

Il servizio FileTransfer espone quindi i seguenti Endpoint:

/knos/wcf/CS/FileTransfer.svc/http

/knos/wcf/CS/FileTransfer.svc/http/mtom

/knos/wcf/CS/FileTransfer.svc/http/binary

/knos/wcf/CS/FileTransfer.svc/https

/knos/wcf/CS/FileTransfer.svc/https/mtom

/knos/wcf/CS/FileTransfer.svc/https/binary

Si vedano le applicazioni demo di esempio per l’utilizzo specifico.

4.2 Servizio: UserAuthenticationÈ un servizio trasversale a tutti gli utenti che consente di ottenere il Token di Sicurezza da utilizzare per tutte le chiamate successive ai web service esposti.

Per ottenere il Token di Sicurezza l’applicativo deve disporre delle credenziali (UserName e Password) dell’utente corrente. Il token ottenuto è valido a tempo indeterminato (salvo eventuali operazioni di reset eseguite sul server che sono però eventi eccezionali) e garantisce a chiunque ne sia in possesso le credenziali di accesso dell’utente per cui è stato rilasciato.

È cura dell’applicativo che ottiene il Token di Sicurezza mantenerlo segreto per evitare che possa essere utilizzato da soggetti diversi dall’utente autorizzato.

Le operazioni offerte dal servizio UserAuthentication sono:

BasicAuthentication GetTicket DigestAuthentication

15


16


4.2.1 Operazione: BasicAuthenticationL’autenticazione di base è fornita ai client che non intendono utilizzare la procedura di autenticazione con Digest SHA1. Questo tipo di autenticazione è normalmente sconsigliato perché la password viaggia in chiaro ma poiché il servizio CCT è offerto in HTTPS anche questo metodo di autenticazione è da considerarsi sufficientemente sicuro.

Parametri di Input Tipo Descrizione

BasicAuthentication oggetto Contenitore per i parametri di autenticazione di base

UserName stringa nome utente (non importa se LowerCase oppure no)

Password stringa password

e ottenendo in risposta:

Parametri di Output Tipo Descrizione

ServiceInfo oggetto Oggetto contenente la versione corrente del Servizio ed eventuali informazioni aggiuntive (vedi Appendice B).


Info elenco Elenco di oggetti di tipo NameValueDC contenenti eventuali informazioni aggiuntive relative all’operazione corrente (vedi Appendice B).

UserIdentity oggetto Contenitore per SecurityToken.

SecurityToken stringa Token di sicurezza utilizzato per l’autenticazione dell’utente.

oppure un errore SOAP.

17


4.2.2 Operazione: GetTicketQuesta operazione consente di ottenere dal server un Ticket da utilizzare nell’operazione di DigestAuthentication. Non è necessario richiamare questa operazione se l’autenticazione è fatta con l’operazione di BasicAuthentication.

La richiesta va formulata con i seguenti parametri:


BaseUserIdentity oggetto Contenitore per i parametri di base di identificazione dell’utente

Username stringa nome utente (non importa se LowerCase oppure no)

e la risposta restituisce:





Ticket stringa Ticket da utilizzare nell’operazione di DigestAuthentication.

ClientIPAddress Stringa Indirizzo IP del client che ha effettuato la richiesta


ServiceInfo è un contenitore per informazioni relative al servizio corrente. Ospita sempre almeno la proprietà ServiceVersion che indica la versione corrente del servizio.

18


4.2.3 Operazione: DigestAuthenticationLa DigestAuthentication viene eseguita in due passi:

- il client richiama l’operazione GetTicket per ottenere il Ticket- una volta ottenuto il Ticket viene utilizzato per produrre un Digest così calcolato:

Digest = SHA1(LowerCase(UserName) + clientIPAddress +

UpperCase(SHA1(LowerCase(UserName) + LowerCase(password))) + Ticket)

Dove:SHA1(argomento) indica l’applicazione dell’hashing SHA1 sull’argomento

LowerCase(argomento) indica la conversione in minuscolo dell’argomento

UpperCase(argomento) indica la conversione in maiuscolo dell’argomento

argomento1 + argomento2 indica la concatenazione dei due argomenti

La conversione in minuscole è richiesta perché nelle versioni attuali di KnoS sia il nome utente che la password sono Case Insensitive.

Per il calcolo dello SHA1 è inoltre richiesto l’utilizzo dell’encoding "ISO-8859-1".

Una volta ottenuto il Digest il client può invocare l’operazione di DigestAuthentication passando come parametri della richiesta:


DigestAuthentication oggetto Contenitore per UserName, Ticket e Digest.

UserName stringa Nome utente (non importa se LowerCase oppure no).

Ticket stringa Ticket fornito dall’operazione GetTicket.

Digest stringa Calcolato con la formula indicata sopra.

e ottenendo in risposta:





19


UserIdentity oggetto Contenitore per SecurityToken.

SecurityToken stringa Token di sicurezza utilizzato per l’autenticazione dell’utente.


20


4.3 Servizio: FileTransferÈ il servizio che gestisce le operazioni di upload e download via MTOM.Supporta le seguenti operazioni:

UploadPdI DownloadFile

È possibile inviare una solo pacchetto di indicizzazione alla volta tramite l’operazione UploadPdI che restituisce, in caso di pacchetto accettato, l’identificativo della pacchetto: IdPdI.L’upload dei pacchetti è consentito solo agli utenti degli Enti di Caricamento abilitati.

Con l’operazione DownloadFile è possibile scaricare i file del PdI o delle notifiche associate.Per poter scaricare un file è necessario passare la coppia IdObject, IdDoc restituita dalle operazioni di ServizioCS.

Il download è un operazione disponibile a tutti gli utenti che hanno accesso al file richiesto.

4.3.1 Operazione: UploadPdIQuesta operazione consente l’invio delil PdI al Servizio CCT TeamSystem.



UserIdentity oggetto Contiene l’identità dell’utente (vedi Appendice B).

UploadPdI oggetto Contiene gli estremi per l’upload del PdI.

Canale stringa Contiene le info sul canale di trasmissione.

SoggettoProduttore oggetto Soggetto che usufruisce del servizio e che può inviare in conservazione documenti propri o di terzi (Soggetti Deleganti) (Vedi Appendicie B).

SoggettoTitolare oggetto Soggetto che deve conservare il documento: coincide col SoggettoProduttore tranne nel caso di Studi o altri che eseguono la conservazione per conto terzi (Vedi Appendice B).

SoggettoOrigine oggetto Soggetto che ha originato il documento da conservare: normalmente coincide col SoggettoTitolare per i documenti attivi (Vedi Appendice B).

SoggettoDestinazione oggetto Soggetto a cui è destinato il documento:

21


normalmente coincide con il SoggettoTitolare nel caso di documenti passivi o nel caso di documenti che non hanno una destinazione (Libri Giornali, Registri IVA, ecc.) (Vedi Appendice B).

DatiDocumento oggetto Contiene le informazioni relative al documento da conservare (Vedi Appendice B).

Se la creazione della pubblicazione ha esito positivo la risposta restituisce:





UploadPdI oggetto Contenitore per le informazioni relative alil PdI (vedi Appendice B).

IdPdI intero Identificativo univoco della del PdI.

IdDoc intero Identificativo univoco del documento allegato alla pubblicazione.

DateCreation data-ora Data e ora in cui il PdI è stato creato all’interno del Servizio CCT.

IdStatus intero Identificativo dello stato corrente del PdI.

StatusName stringa Nome dello stato corrente del PdI.

DateChangeStatus data-ora Data e ora in cui il PdI ha assunto lo stato corrente.


Il parametro IdPdI è utilizzabile come identificativo univoco in tutte le operazioni che lo richiedono.

22


4.3.2 Operazione: DownloadFileQuesta operazione consente il download del file precedentemente inviato al Servizio CCT TeamSystem.




DownloadFile oggetto Contenitore per le informazioni relative al file da scaricare (vedi Appendice B).

IdObject intero Id della pubblicazione (fattura, messaggio o altro che contiene il file).

IdDoc intero Identificativo del file all’interno della pubblicazione.

Se l’utente ha accesso al file richiesto la risposta restituisce:





FileInfo oggetto Oggetto contenente i metadati del file richiesto ed il file stesso (vedi Appendice B).


23


4.4 Servizio: ServizioCSÈ il Web Service offerto agli utenti per monitorare lo stato dei propri PdI. Offre le seguenti operazioni:

GetPdI SearchPdI

Tramite l’operazione GetPdI è possibile monitorare lo stato di un PdI di cui si conosce l’identificativo ed ottenere l’elenco dei file conservati.

In assenza dell’IdPdI è comunque sempre possibile ottenere l’elenco dei PdI presenti sul sistema tramite l’operazione SearchPdI che restituisce un elenco paginato dei PdI caricati dall’utente. L’operazione accetta alcuni parametri di ricerca per ottenere un elenco mirato.

4.4.1 Operazione: GetPdIConsente di recuperare le informazioni relative ad un PdI inviato dall’utente.



IdPdI intero Identificativo del PdI di cui si vuole recuperare lo stato.

DownloadFile booleano

Flag che indica se scaricare o meno il file mandato in conservazione.

Se il PdI risulta valida la risposta restituisce l’oggetto GetPdIOutputDC:





InfoPdI oggetto Contenitore per i dati del PdI indicato.


24


L’oggetto InfoPdI è costituito dal seguente insieme di campi:

InfoPdI: Tipo Descrizione

IdPdI intero Identificativo da utilizzare per referenziare il PdI nelle operazioni che lo richiedono.

DateCreation data-ora Data e ora in cui la pubblicazione che contiene il PdI è stata creata all’interno del Servizio CCT


StatusName stringa Nome dello stato corrente del PdI.


SoggettoProduttore oggetto Soggetto che usufruisce del servizio e che può inviare in conservazione documenti propri o di terzi (Soggetti Deleganti) (Vedi Appendicie B).

SoggettoTitolare oggetto Soggetto che deve conservare il documento: coincide col SoggettoProduttore tranne nel caso di Studi o altri che eseguono la conservazione per conto terzi (Vedi Appendice B).

SoggettoOrigine oggetto Soggetto che ha originato il documento da conservare: normalmente coincide col SoggettoTitolare per i documenti attivi (Vedi Appendice B).

SoggettoDestinazione oggetto Soggetto a cui è destinato il documento: normalmente coincide con il SoggettoTitolare nel caso di documenti passivi o nel caso di documenti che non hanno una destinazione (Libri Giornali, Registri IVA, ecc.) (Vedi Appendice B).

IdTipoDocumento intero Identificativo del tipo di documento da conservare.

Canale stringa Contiene le info sul canale di trasmissione.

Esercizio intero Anno chiusura dell’esercizio.

AdditionalStringParameters elenco chiave-valore

Attributi specifici (obbligatori o meno) relativi allo specifico tipo di documento da conservare.

AdditionalIntParameters elenco chiave-valore


25


AdditionalDateTimeParameters elenco chiave-valore


AdditionalDecimalParameters elenco chiave-valore


FileInfo oggetto File inviato per la conservazione. (Vedi Appendice B)

IdStatus e StatusName sono rispettivamente l’identificativo interno e il nome dello stato del Workflow della Conservazione Sostitutiva in Cloud (vedi appendice A). TeamSystem si riserva di applicare eventuali variazioni al Workflow (aggiunta o rimozione di stati), tuttavia IdStatus è da considerarsi un valore fisso che identifica con certezza uno stato. StatusName è va invece considerato come una stringa mnemonica associata allo stato ed eventualmente oggetto di modifiche.

26


4.4.2 Operazione: SearchPdIConsente di recuperare le informazioni relative ad un PdI inviato dall’utente.

Parametri di input Tipo Descrizione


SearchExpression oggetto Contenitore per le clausole di ricerca (vedi appendice D).

OrderBy oggetto Contenitore per le clausole di ordinamento (vedi appendice D).

PageSize intero Dimensione della pagina di dati richiesta

PageNumber intero Numero della pagina di dati richiesta

Per avere la massima flessibilità nelle ricerche sono previsti un oggetto di ricerca e un oggetto di ordinamento generici (vedasi appendice D).

I filtri di ricerca che utilizzano SearchExpression e OrderBy specificano di volta in volta i nomi dei campi (FieldName) utilizzabili nella ricerca o nell’ordinamento.

Questo approccio sacrifica la possibilità dell’utente di utilizzare l’intellisense per i parametri di ricerca ma riduce al minimo le modifiche necessarie ad introdurre nuovi campi. L’operazione controlla sempre che i campi specificati siano validi e la richiesta è rifiutata se in SearchExpression o OrderBy compaiono campi diversi da quelli elencati.

I campi di ricerca accettati dall’operazione RicercaPdI sono:

Nome Tipo del campo

Descrizione

IdPdI intero Identificativo univoco della pubblicazione che contiene il messaggio restituito da SdI.

DateCreation DateTime È la data di creazione del PdI



Titolare.CodiceFiscale stringa Codice fiscale del soggetto titolare.

Titolare.PartitaIVA stringa Partita IVA del soggetto titolare.

Destinazione.CodiceFiscale stringa Codice fiscale del soggetto destinazione.

Destinazione.PartitaIVA stringa Partita IVA del soggetto destinazione.

27


Origine.CodiceFiscale stringa Codice fiscale del soggetto origine.

Origine.PartitaIVA stringa Partita IVA del soggetto origine.

CodiceDestinatarioIPA stringa Riferimento univoco dell'ente pubblico a cui è destinata la fatturaPA.

DataDocumento data-ora Data in cui è stato emesso il documento dal soggetto emittente.

DataEmissioneOrigine data-ora Data in cui il origine ha emesso il documento.

DataFine data-ora Data di fine del periodo di competenza di un registro o libro contabile.

DataInizio data-ora Data di inizio del periodo di competenza di un registro o libro contabile.

DataRegistrazione data-ora Data in cui è stata effettuata la registrazione contabile del documento.

DataProtocollo data-ora Data di protocollo informatico attribuito dall’ente pubblico.

Descrizione stringa Descrizione relativa al documento da conservare.

Esercizio numero Anno chiusura dell’esercizio.

FileName stringa Nome del file inviato in conservazione.

HashValue stringa Valore calcolato dell’hash del file.

IdentificativoSdI stringa Codice attribuito dallo SdI alla fattura PA.

IdTipoDocumento numero Identificativo del tipo di documento da conservare.

NumeroProtocollo stringa Numero di protocollo informatico attribuito dall’ente pubblico.

NumeroAnniConservazione numero Numero di anni di conservazione del documento.

ChiaveAssociazione stringa Permette di creare un legame tra diversi PdI.Attualmente serve per correlare una notifica alla sua fattura/lotto.

NumeroFatturaOrigine stringa Numero con cui il origine ha emesso il documento.

NumeroDocumento stringa Numero con cui è stato emesso il documento dal soggetto emittente.

NumeroRegistrazione stringa Numero attribuito alla registrazione contabile del

28


documento.

PaginaIniziale numero Numero della prima pagina di un registro o libro contabile.

PaginaFinale numero Numero dell'ultima pagina di un registro o libro contabile.

Sezionale stringa Numero, codice o descrizione del registro sezionale di appartenenza di un documento o di un registro IVA.

Tipo stringa Tipo di registro o libro contabile (per es. per i registri iva: acquisti o vendite o corrispettivi).

DataOra1.Name stringa Etichetta del campo custom definito dall’utente.

DataOra1.Value data-ora Valore del campo custom definito dall’utente.





Decimale1.Name stringa Etichetta del campo custom definito dall’utente.

Decimale1.Value numero Valore del campo custom definito dall’utente.





Intero1.Name stringa Etichetta del campo custom definito dall’utente.

Intero1.Value numero Valore del campo custom definito dall’utente.



29




Testo1.Name stringa Etichetta del campo custom definito dall’utente.

Testo1.Value stringa Valore del campo custom definito dall’utente.





Per tutti i parametri di ricerca elencati è possibile specificare condizioni di ricerca in termini di valore del campo, campo compreso in intervalli specificati, ecc. Il tipo del campo indica il prefisso per gli operatori nelle clausole di ricerca.

Sarà possibile formulare espressioni di ricerca arbitrarie ma limitate ai soli campi di ricerca ammessi utilizzando i seguenti operatori:

IsNull IsNotNull AND OR NOTLessThan LessEqual Equal NotEqual GreaterEqualGreaterThan StringLike StringStartWith StringEndWith StringContains

Per i dettagli logici sul funzionamento e le modalità di composizione della stringa di ricerca si rimanda all’appendice D.

Per i dettagli implementativi si rimanda invece al codice dei progetti di esempio.

30


I campi di ordinamento accettati:

Nome Descrizione

IdPdI Identificativo univoco della pubblicazione che contiene il messaggio restituito da SdI.

DateCreation È la data di creazione del PdI

IdStatus Identificativo dello stato corrente del PdI.

DateChangeStatus Data e ora in cui il PdI ha assunto lo stato corrente.

Si noti che non sono riportati i tipi dei campi accettati perché l’ordinamento è sempre formulato indicando se ascendente ASC o discendente DESC, è possibile specificare più campi di ordinamento nell’ordine desiderato con le stesse regole previste dall’SQL.

All’atto della richiesta viene verificato che l’utente abbia specificato nelle clausole di ricerca e ordinamento solo campi accettati dall’operazione invocata. Se la richiesta è valida viene restituita una risposta con l’elenco dei PdI trovate nel formato:





SearchResultPdI oggetto Contenitore per i dati restituiti dalla ricerca.

ElencoInfoPdI elenco Elenco di oggetti InfoPdI (vedi sopra o in Appendice B)

PageNumber intero Numero della pagina di dati restituita.

PageSize intero Dimensione della pagina di dati restituita.

PageCount intero Numero di pagine totali recuperate dalla ricerca.

RecordCount intero Numero di record totali recuperati dalla ricerca.


31


5 Workflow del PdIWorkflow interno delle Fatture Elettroniche inviate alle PA

Il workflow attuale per la conservazione sostitutiva gestita dal servizio CCT è descritto dal seguente schema:

Si tratta di uno schema semplificato che per maggiore chiarezza non riporta alcune transizioni di stato che vengono eseguite assegnando al PdI uno stato specifico a fronte di eventi.

La tabella degli stati del workflow dei file da mandare in conservazione è il seguente:

Stati del workflow del PdI

IdStatus

StatusName Tipo Descrizione

4740 Redazione Persistente Editing manuale da parte dell’utente.

4741 Ricezione Transitorio

4742 Ricevuto. Transitorio

32

Appendice A


4743 Annullato Persistente

4744 Scartato Persistente

4745 Acquisito Transitorio

4746 Accodato su PdA Transitorio

4747 Conservato in PdA Persistente

4748 Decorrenza termini

Finale

Gli stati indicati come transitori sono quelli in cui il PdI può cambiare di stato a seguito di elaborazioni da parte del Servizio CCT senza l’intervento di utenti od operatori.

Gli stati persistenti sono quelli in cui il PdI permane a tempo indeterminato fino a che non intervengono un operatore o un utente.

Gli stati finali sono quelli in cui il PdI non può cambiare di stato.

33


6 Parametri di tipo oggettoRaccolta completa dei parametri di tipo oggetto

Questa appendice raccoglie le tabelle di tutti i parametri di tipo oggetto utilizzati nelle operazioni esposte dai servizi. Gli oggetti sono elencati nell’ordine in cui sono stati presentati nella documentazione.

6.1 ServiceInfoÈ la classe base utilizzata da tutti i metodi dei servizi per restituire informazioni sul servizio stesso ed eventuali info aggiuntive.

ServiceInfo: Tipo Descrizione


Info elenco Elenco di oggetti di tipo NameValue contenente eventuali informazioni aggiuntive a fronte di richieste opzionali dell’utente.

6.2 NameValueÈ la classe contenente le info aggiuntive che l’utente può inviare o ricevere ai/dai servizi: essendo in ServiceInfo è presente in tutte le risposte dei Web Services mentre per le richieste a è presente nella classe UserIdentity.

NameValue: Tipo Descrizione

Name stringa Nome dell’informazione aggiuntiva inviata/richiesta.

Value stringa Valore dell’informazione aggiuntiva inviata/richiesta.

34

Appendice B


6.3 BaseUserIdentityÈ la classe base contenente le informazioni legate all’identità dell’utente necessarie a tutte le richieste effettuate ai Web Services.

BaseUserIdentity: Tipo Descrizione

Username stringa nome utente (non importa se LowerCase oppure no).

Options elenco Elenco di oggetti di tipo NameValue contenente eventuali richieste opzionali dell’utente.

6.4 UserIdentityÈ la classe che aggiunge informazioni a BaseUserIdentity legate all’identità dell’utente necessarie a tutte le richieste effettuate ai Web Services.

Attualmente contiene solamente il valore del SecurityToken in più a BaseUserIdenty.

UserIdentity: Tipo Descrizione

SecurityToken stringa Nome utente (non importa se LowerCase oppure no).

6.5 BasicAuthenticationÈ il contenitore utilizzato per le informazioni richieste dall’autenticazione di base.

BasicAuthentication: Tipo Descrizione

UserName stringa nome utente (non importa se LowerCase oppure no)

Password stringa password

6.6 DigestAuthenticationÈ il contenitore utilizzato per le informazioni richieste dall’autenticazione fatta con l’algoritmo di hashing SHA1 come descritta nel capitolo dedicato.

DigestAuthentication: Tipo Descrizione

UserName stringa Nome utente (non importa se LowerCase oppure no).

Ticket stringa Ticket fornito dall’operazione GetTicket.

Digest stringa Calcolato con la formula indicata nel capitolo dedicato.

35


6.7 SoggettoProduttore, SoggettoTitolare, SoggettoOrigine, SoggettoDestinazione

È il contenitore per i dati relativi ai vari soggetti.

UploadPdI: Tipo Descrizione

IdPaese stringa(2) Codice del Paese nello standard ISO 3166 alpha-2.Parametro obbligatorio.

PartitaIVA stringa(50) Partita IVA del soggetto (lunghezza massima 50 caratteri).

CodiceFiscale stringa Codice fiscale del soggetto.Parametro obbligatorio.

Denominazione stringa Parametro obbligatorio se mancano Nome e Cognome.

Nome stringa Parametro obbligatorio se mancano Denominazione e Cognome.

Cognome stringa Parametro obbligatorio se mancano Denominazione e Nome.

36


6.8 DatiDocumentoÈ il contenitore dei dati relativi al documento da conservare


IdTipoDocumento intero Tipo di documento da conservare.Parametro obbligatorio.

FileType enumeratore Tipo del file (valori elencati nell’Appendice C).Parametro obbligatorio.

HashType enumeratore Tipo del di hash del file (valori elencati nell’Appendice C).Parametro obbligatorio.

HashValue stringa Valore dell’hash del file.Parametro obbligatorio.

FileName stringa Nome del file.Parametro obbligatorio.

FileSize stringa Dimensione del file.Parametro obbligatorio.

FileContent file File del PdI.Parametro obbligatorio.

Esercizio intero Esercizio del file da conservare.Parametro obbligatorio nel caso in cui il file inviato non sia una notifica (IdTipoDocumento 1005).

DataOra1 oggetto Oggetto contenente valori opzionali da conservare.

Name stringa Etichetta del valore opzionale da conservare.

Value data-ora Valore opzionale da conservare.

DataOra2 oggetto Etichetta del valore opzionale da conservare.



DataOra3 oggetto Etichetta del valore opzionale da conservare.



37


Testo1 oggetto Etichetta del valore opzionale da conservare.


Value stringa Valore opzionale da conservare.







Intero1 oggetto Etichetta del valore opzionale da conservare.


Value intero Valore opzionale da conservare.







Decimale1 oggetto Etichetta del valore opzionale da conservare.


Value decimale Valore opzionale da conservare.







AdditionalStringParameters elenco Attributi specifici (obbligatori o meno) relativi

38


chiave-valore

allo specifico tipo di documento da conservare.

AdditionalIntParameters elenco chiave-valore


AdditionalDateTimeParameters elenco chiave-valore


AdditionalDecimalParameters elenco chiave-valore


Di seguito gli IdTipoDocumenti ammessi e i relativi valori addizionali consentiti.

1001: FatturaPA emessa Tipo Descrizione



ChiaveAssociazione stringa Nome originario del file di fatturaPA inviato allo SDI.Parametro obbligatorio.

NumeroDocumento stringa Numero con cui è stato emesso il documento dal soggetto emittente.Parametro obbligatorio.


DataDocumento data-ora Data in cui è stato emesso il documento dal soggetto emittente.Parametro obbligatorio.

1002: FatturaPA rivetuta Tipo Descrizione




NumeroRegistrazione stringa Numero attribuito alla registrazione contabile del

39


documento.Parametro obbligatorio.

DataRegistrazione data-ora Data in cui è stata effettuata la registrazione contabile del documento.Parametro obbligatorio.






1003: Lotto FatturaPA emesso

Tipo Descrizione




1004: Lotto FatturaPA ricevuto

Tipo Descrizione

DataRegistrazione data-ora Data in cui è stata effettuata la registrazione contabile del documento.





40


1005: Notifica FatturaPA Tipo Descrizione



2001: Fattura emessa Tipo Descrizione




2002: Nota di variazione emessa

Tipo Descrizione


Sezionale stringa umero, codice o descrizione del registro sezionale di appartenenza di un documento o di un registro IVA.


2003: Fattura ricevuta Tipo Descrizione

NumeroRegistrazione stringa Numero attribuito alla registrazione contabile del documento.Parametro obbligatorio.

DataRegistrazione data-ora Data in cui è stata effettuata la registrazione contabile del documentoParametro obbligatorio.


41




2004: Nota di variazione rivetuta

Tipo Descrizione






2005: DDT emesso Tipo Descrizione




2006: DTT ricevuto Tipo Descrizione




42




2007: Bolla emessa Tipo Descrizione




2008: Bolla ricevuta Tipo Descrizione


DataRegistrazione data-ora Data in cui è stata effettuata la registrazione contabile del documento.Parametro obbligatorio.




2009: Libro giornale Tipo Descrizione





43


2010: Registro IVA Tipo Descrizione






Tipo stringa Tipo di registro o libro contabile (per es. per i registri iva: acquisti o vendite o corrispettivi).Parametro obbligatorio.

2011: Libro Mastro Tipo Descrizione






2012: Libro cespiti Tipo Descrizione






44


2013: Giornale di magazzino

Tipo Descrizione






45


6.9 InfoPdIÈ il contenitore per tutti i dati informativi relativi ad una fattura restituiti all’utente.


IdPdI intero Identificativo univoco della pubblicazione che contiene il PdI.

IdDoc intero Identificativo del documento da conservare allegato alla pubblicazione.

DateCreation data-ora Data e ora in cui la pubblicazione che contiene il PdI è stata creata all’interno del Servizio CCT

IdStatus intero Identificativo dello stato corrente delil PdI.

StatusName stringa Nome dello stato corrente delil PdI.


FileInfo oggetto File del PdI.

6.10FileInfoFileInfo contiene i seguenti dati:

FileInfo: Tipo Descrizione

IdObject intero Identificativo univoco della pubblicazione che contiene il file.

IdDoc intero Identificativo univoco del file all’interno della pubblicazione.

FileType enumerato

Tipo del file (valori elencati nell’Appendice C).

FileName stringa Nome del file

FileDescr stringa Eventuale descrizione del file

FileSize intero Dimensione del file in byte

FileMD5 stringa Hashing MD5 del file

FileContent file Contenuto del file

46


6.11SearchFilterPdIContenitore per i parametri di ricerca dei PdI.

SearchFilterFatturePA: Tipo Descrizione

SearchExpression oggetto Contenitore per le clausole di ricerca (vedi appendice D).

OrderBy oggetto Contenitore per le clausole di ordinamento (vedi appendice D).

PageSize intero Dimensione della pagina di dati richiesta

PageNumber intero Numero della pagina di dati richiesta

Per avere la massima flessibilità nelle ricerche sono previsti un oggetto di ricerca e uno di ordinamento generici (vedasi appendice D).

I filtri di ricerca che utilizzano SearchExpression e OrderBy specificano di volta in volta i campi (Field) utilizzabili nella ricerca o nell’ordinamento; non specificare una SearchExpression equivale a fare una ricerca completa senza parametri di filtro.

Questo approccio sacrifica la possibilità dell’utente di utilizzare l’intellisense per i parametri di ricerca ma riduce al minimo le modifiche necessarie ad introdurre nuovi campi. L’operazione controlla sempre che i campi specificati siano validi.

6.12 SearchResultPdIContenitore per il risultato di ricerca restituito dall’operazione RicercaFatture:

SearchResultFatturePA: Tipo Descrizione

ElencoInfoPdI elenco Elenco di oggetti InfoPdI.

PageNumber intero Numero della pagina di dati restituita.

PageSize intero Dimensione della pagina di dati restituita.

PageCount intero Numero di pagine totali recuperate dalla ricerca.

RecordCount intero Numero di record totali recuperati dalla ricerca.

47


7 Valori enumeratiTabelle dei parametri che assumono valori enumerati

Questa appendice elenca i parametri che assumono valori enumerati la cui codifica è stabilita dal Servizio CCT.

7.1 PdIFileTypeIl parametro PdIFileType (restituito all’interno di FileInfo e DatiDocumento) indica l’estensione del file contenuto nelle pubblicazioni:

FileType: Descrizione

pdf Estensione .pdf

pdf_p7m Estensione .pdf.p7m

pdf_m7m Estensione .pdf.m7m

tiff Estensione .tiff

tiff_p7m Estensione .tiff.p7m

tiff_m7m Estensione .tiff.m7m

jpg Estensione .jpg

jpg_p7m Estensione .jpg.p7m

jpg_m7m Estensione .jpg.m7m

xml Estensione .xml

xml_p7m Estensione .xml.p7m

48

Appendice C


xml_m7m Estensione .xml.m7m

txt Estensione .txt

txt_p7m Estensione .txt.p7m

txt_m7m Estensione .txt.m7m

eml Estensione .eml

eml_p7m Estensione .eml.p7m

eml_m7m Estensione .eml.m7m

7.2 HashTypeIl parametro HashType (contenuto all’interno di DatiDocumento) indica l’algoritmo di calcolo dell’hash di un array di byte

Tipo documento PdI: Descrizione

SHA-256 Algoritmo di crittografazione SHA-256

7.3 OperatorIl parametro Operator indica l’operatore da applicare all’espressione di ricerca:

Operator: Descrizione

IsNull Verifica che l’operando sia null

IsNotNull Verifica che l’operando non sia null

AND Concatena gli operatori specificati con un operatore AND

OR Concatena gli operatori specificati con un operatore OR

NOT Verifica che l’operando non rispetti la condizione specificata

LessThan Verifica che il primo operando abbia valore inferiore del secondo

LessEqual Verifica che il primo operando abbia valore inferiore od uguale del secondo

Equal Verifica che il primo operando abbia valore uguale del secondo

NotEqual Verifica che il primo operando abbia valore diverso dal secondo

GreaterEqual Verifica che il primo operando abbia valore maggiore od uguale del secondo

49


GreaterThan Verifica che il primo operando abbia valore maggiore del secondo

StringLike Verifica che il primo operando (di tipo stringa) abbia valore uguale del secondo

StringStartWith Verifica che il primo operando (di tipo stringa) abbia valore che coincide con l’inizio della stringa specificata come secondo operando

StringEndWith Verifica che il primo operando (di tipo stringa) abbia valore che coincide con la fine della stringa specificata come secondo operando

StringContains Verifica che il primo operando (di tipo stringa) abbia valore contenuto nella stringa specificata come secondo operando

7.4 ArgTypeIl parametro ArgType indica il tipo di dato utilizzato nell’espressione di ricerca e può valere:

ArgType: Descrizione

InnerSearchClause Il valore del parametro di ricerca è un ulteriore clausola di ricerca nidificata

FieldName Il valore del parametro è una stringa contenente il nome del campo sul quale effettuare la ricerca

IntValue Il valore del parametro è di tipo intero

StringValue Il valore del parametro è di tipo stringa

BooleanValue Il valore del parametro è di tipo booleano

DoubleValue Il valore del parametro è di tipo double

DateTimeValue Il valore del parametro è di tipo data

7.5 DirectionIl parametro Direction indica il tipo di ordinamento da effettuare sul campo specificato:

50

Direction: Descrizione

ASC Ordinamento crescente

DESC Ordinamento decrescente


8 Parametri di ricercaFormulazione delle ricerche con SearchExpression e OrderBy

Questa appendice descrive l’utilizzo del parametri SearchExpression e OrderBy utilizzati nella ricerca delle fatture.

8.1 SearchExpressionTramite la valorizzazione dell’entità SearchExpression è possibile definire una filtro di ricerca per le fatture; SearchExpression è così definita:

SearchExpression: Tipo Descrizione

SearchClause oggetto Contenitore della clausola di ricerca: viene utilizzata la notazione prefissa per la definizione di operatore ed operandi

SearchClause: Tipo Descrizione

Operator enumerato Operatore dell’espressione di ricerca (vedi appendice C)

Arguments elenco Elenco degli argomenti dell’espressione di ricerca.Vedi tabella sotto per la definizione.

Argument: Tipo Descrizione

ArgType enumerato

Tipo del valore dell’operando (vedi appendice C)

51

Appendice D


ArgValue oggetto Valore dell’operando

8.2 OrderByTramite la valorizzazione dell’entità OrderBy è possibile definire il tipo di ordinamento applicabile alla clausola di ricerca:

OrderBy: Tipo Descrizione

OrderByClauses elenco Elenco di contenitori di tipo OrderByClause contenenti le clausole di ordinamento

OrderByClause: Tipo Descrizione

FieldName stringa Nome del campo sul quale effettuare l’ordinamento

Direction enumerato

Tipo del valore di ordinamento (vedi appendice C)

52


9 Elenco erroriElenco completo degli errori restituiti dai Web Services

In questo capitolo vengono riepilogati tutti gli errori che possono essere restituiti dai Web Services del Servizio di Fatturazione Elettronica alla PA di TeamSystem.

In caso di errore il servizio invia al client una risposta del tipo:

<s:Envelope xmlns:s=http://www.w3.org/2003/05/soap-envelope xmlns:a="http://www.w3.org/2005/08/addressing"> <s:Header> <a:Action s:mustUnderstand="1">http://www.w3.org/2005/08/addressing/soap/fault</a:Action> <a:RelatesTo>urn:uuid:0d6ce642-c65e-4c5b-9933-2e5f7d23ccd3</a:RelatesTo> </s:Header> <s:Body> <s:Fault> <s:Code> <s:Value>s:Sender</s:Value>

<s:SubCode> <s:Value>s:1</s:Value> </s:SubCode>

</s:Code> <s:Reason> <s:Text xml:lang="it-IT">Id errore: [Guid dell’eccezione] - Parametro obbligatorio: UserName</s:Text> </s:Reason> </s:Fault> </s:Body></s:Envelope>dove il nodo <s:Code> contiene il FaultCode standard SOAP 1.2 Sender o Receiver a seconda che l’errore sia stato causato dai dati inviati dall’utente oppure da un errore del server ed il sottonodo <s:SubCode> contiene il codice di errore specifico; il nodo <s:Reason> invece contiene la FaultReason, un messaggio composto dall’id univoco dell’eccezione (un guid) e la descrizione testuale dell’errore.

53

Appendice E

http://www.w3.org/2003/05/soap-envelope


Nel caso in cui dal FaultCode e dalla descrizione della FaultReason non si capisca la causa dell’errore è possibile contattare il gestore del servizio facendo riferimento all’id dell’eccezione.

È possibile che in alcuni casi la risposta contenga anche ulteriori informazioni di dettaglio relative all’errore ma queste sono da considerarsi opzionali e non garantite per cui il client può limitarsi alla sola decodifica di FaultCode e FaultReason.

Gli errori sono suddivisi per categoria e la FaultReason indicata potrebbe essere oggetto di modifiche nel testo ma che non alterano il significato logico legato al FaultCode.

9.1 Errori nei dati della richiestaFaultCode FaultReason

401 Il parametro { nome parametro } è di tipo { tipo parametro } invece che { tipo parametro }

402 Il parametro { nome parametro } supera la lunghezza massima di { max valore } caratteri

403 Il parametro { nome parametro } deve avere lunghezza compresa tra { min valore }-{ max valore } caratteri

404 Il parametro { nome parametro } è obbligatorio

405 Il parametro { nome parametro } è obbligatorio e non può essere vuoto

406 Il parametro { nome parametro } è obbligatorio quando il parametro { altro parametro } è valorizzato

407 Il parametro { nome parametro } è obbligatorio quando il parametro { altro parametro } è valorizzato e vale { valore parametro }

408 Il parametro { nome parametro } è obbligatorio quando il parametro { altro parametro } è valorizzato e non vale { valore parametro }

409 Il parametro { nome parametro } è obbligatorio quando i parametri { altri parametri } non sono valorizzati

410 Il parametro { nome parametro } ha valore non compreso nel range { min valore }-{ max valore }

411 Il parametro { nome parametro } ha un valore di hash che non corrisponde a quando settato nel parametro { altro parametro }

412 Il parametro { nome parametro } dichiara un'estensione file che non corrisponde al parametro { altro parametro }

413 Il parametro { nome parametro } ha una dimensione che non corrisponde a quanto settato nel parametro { altro parametro }

54


414 Il nome campo { nome parametro } non è tra quelli consentiti nell'espressione di ricerca

415 Il parametro { nome parametro } per la clausola con operatore {1} e argomenti {2} ha un numero di argomenti non valido in quanto {3}

416 Il parametro { nome parametro } per la clausola con operatore { nome operatore } ha un argomento che vale { valore parametro } ma è stato dichiarato di tipo { tipo parametro }

417 Il parametro { nome parametro } per la clausola con operatore { nome parametro } ha l'argomento di valore { valore parametro } di tipo { tipo parametro } che ammette solo una singola parola

418 Il parametro { nome parametro } non è tra quelli consentiti nell'espressione di ordinamento

419 Il parametro { nome parametro } per la clausola con ordinamento { tipo di ordinamento } ha il nome del campo che vale { valore parametro } ma che ammette solo una singola parola

420 Il parametro { nome parametro } è obbligatorio quando il parametro { altro parametro } vale { valore parametro }

421 Il parametro { nome parametro } deve essere nullo quando il parametro { altro parametro } vale { valore parametro }

422 Il parametro { nome parametro } contiene i valori { valori parametri } non validi quando il parametro { altro parametro } vale { valore altro parametro }

423 Il parametro FileName { valore parametro } non è valido per IdTipoDocumento { valore parametro }: deve essere nella forma { forma corretta nome file }

424 Il parametro ChiaveAssociazione { valore parametro } non è valido per IdTipoDocumento { valore parametro }: deve essere nella forma { valore parametro 2} e devono coincidere coi valori settati nel parametro FieldName { valore parametro 3}.

9.2 Errori di sicurezzaFaultCode FaultReason

501 Accesso negatoErrore restituito quando la richiesta non presenta un SecurityToken valido.

502 Operazione non autorizzataErrore restituito quando l’utente, pur avendo fornito un SecurityToken valido non ha i permessi per eseguire l’operazione richiesta.

55


9.3 Errori in fase di elaborazioneFaultCode FaultReason

500 Errore inaspettato

503 Il parametro { nome parametro } non è valido

504 Il file con nome { nome file } ha dimesione pari a { valore parametro } bytes che supera la soglia massima di { max valore }

505 Tipo di hash non supportato: { valore parametro }

506 Tipo di file non supportato: { valore parametro }

507 File corrotto: { valore parametro }

508 Nessuna fattura o lotto associato alla notifica inviata: occorre prima inviare in conservazione la fattura/lotto

56

Versioni del documentocs-test.teamsystem.com/knos/wcf/cs/doc/CS-WebServices... · Web viewLa...

Documents

Transcript of Versioni del documentocs-test.teamsystem.com/knos/wcf/cs/doc/CS-WebServices... · Web viewLa...