Pag. 1 di 15 Specifiche tecniche di trasmissione per i Comuni versione data Modifiche principali Autore/i 0.1 Redazione specifiche tecniche Dario Piermarini 1/15
Pag. 2 di 15 1 INTRODUZIONE Un Comune che utilizza il servizio di SPF Notificate dovrà fornire settimanalmente l elenco delle multe notificate e questo per permettere il riscontro dei dati al momento del pagamento presso le ricevitorie Totobit. L elenco delle multe notificate sarà contenuto in un file inviato dai Comuni ad Ancitel e sarà quest ultima a farsi carico che Totobit, attraverso procedure telematiche, riceva i flussi provenienti da tutti i comuni abbonati al servizio. Scopo di questo documento è quello di descrivere dettagliatamente il formato del file delle notificate e la modalità con cui dovrà essere inviato ad Ancitel. Il ma seguente mostra i principali flussi telematici del servizio: 2/15
Pag. 3 di 15 2 FORMATO DEI DATI Lo scambio di dati tra comuni ed Ancitel avviene utilizzando il formato XML (acronimo di extensible Markup Language), diventato ormai uno standard per la trasmissione e condivisione di dati strutturati. Ogni documento XML comprende sia una struttura logica che una struttura fisica. La struttura logica è simile a un modello che indica quali elementi includere in un documento e in quale ordine. Il modello di un documento XML viene denominato schema. La struttura fisica, d altro canto, contiene i dati effettivi utilizzati in un documento. Nel seguito viene mostrato il ma dello schema XML da utilizzare per la trasmissione dei dati relativi ai verbali notificati. Il documento di specifica formale dello schema XML si trova in appendice; ad ogni modo è possibile ricevere lo schema xsd al momento della richiesta di attivazione del servizio. Per maggiore chiarezza viene riportato l esempio di una istanza di un file XML valido e ben formato 1 per tale schema: 1 Un documento XML si dice ben formato quando rispetta le regole sintattiche del linguaggio; un documento si dice valido quando è conforme alle regole di uno schema XML. 3/15
Pag. 4 di 15 <?xml version="1.0" encoding="utf-8"?> <!--Sample XML file generated by Dario Piermarini--> <ElencoNotificate xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xsi:nonamespaceschemalocation="c:\documents and Settings\piermarini\Documenti\SPFE\schemaCOMUNI.xsd"> <Header> <NomeComune>Poggio Moiano</NomeComune> <CodiceISTAT>057054</CodiceISTAT> <DataInvio>2005-05-05</DataInvio> <Email>municipale@miodominio.it</Email> <RecordTotali>3</RecordTotali> </Header> <DataElevazione>2005-03-21</DataElevazione> <NumeroVerbale>123564</NumeroVerbale> <Targa>CM623VA</Targa> <Importo>2000</Importo> <DataElevazione>2005-03-22</DataElevazione> <NumeroVerbale>123565</NumeroVerbale> <Targa>CM623VB</Targa> <Importo>2500</Importo> <DataElevazione>2005-03-23</DataElevazione> <NumeroVerbale>123566</NumeroVerbale> <Targa>CM623VC</Targa> <Importo>3500</Importo> </ElencoNotificate> 4/15
Pag. 5 di 15 3 FORMATO DEI FILE Il nome e l estensione del file che verrà inviato dal Comune dovrà rispettare una sintassi ben precisa. Il file dovrà avere estensione.xml, mentre il nome del file sarà costituito dalla concatenazione del codice ISTAT del comune e dalla data d invio, separati dal carattere underscore (_). A titolo d esempio consideriamo il caso in cui il Comune di Roma, che codice ISTAT 058091, invii in data 1 Giugno 2005, il file xml delle notificate. Il nome di questo file sarà: 058091_01062005.xml 5/15
Pag. 6 di 15 4 TEMPI Il file contenente l elenco delle notificate può essere inviato dal Comune una volta a settimana e conterrà, al suo interno, tutte le multe che sono state notificate nell arco della settimana precedente. L intervallo di una settimana è puramente indicativo: il Comune può inviare il file xml con la cadenza che vuole, anche giornaliera. Viene consigliata una periodicità di 7 giorni perché è ragionevole supporre che in una settimana un comune medio-piccolo abbia raccolto un numero tale di multe da giustificare l invio del file. Inviando il file con cadenza giornaliera potrebbe accadere che il file, nella maggior parte dei casi, sia completamente vuoto, in quanto nell arco della singola giornata non è stata notificata nessuna multa. E bene sottolineare che se vengono inviati più file nell arco della stessa giornata, l ultimo invio sovrascriverà il precedente. Questo meccanismo è stato introdotto per permettere, nell arco della stessa giornata, di recuperare eventuali errori sui dati dei verbali. Prima di effettuare questa operazione è bene, tuttavia, contattare il supporto tecnico di Ancitel. 6/15
Pag. 7 di 15 5 TRASFERIMENTO DEL FILE PRESSO ANCITEL La trasmissione del file xml avverrà tramite upload su server ftp. Ogni Comune avrà a disposizione una propria login di accesso che verrà comunicata al momento dell abbonamento al servizio ed avrà una propria cartella su cui fare l upload (put) del file xml. Il file verrà preso in carico dal sistema entro un ora dal completamento dell upload. Le indicazioni per la connessione al server ftp e i dati per l accesso verranno forniti al momento della sottoscrizione dell abbonamento al servizio da parte del Comune. 7/15
Pag. 8 di 15 6 VALIDAZIONE DEL FILE Una volta che il sistema ha preso in carico il file, viene effettuata la validazione del documento xml. La validazione è un operazione mirata alla verifica della correttezza sintattica del documento. In altre parole verrà verificato che il file xml inviato sia un istanza well-formed dello schema presentato in appendice. Il comune riceve l esito di questa di validazione via e-mail e l indirizzo che viene utilizzato dal sistema è quello specificato nel file xml (se questo è valido) oppure quello contenuto in una tabella di indirizzi predefiniti nel caso che il file xml inviato sia scorretto. E quindi importante che il Comune aggiorni tempestivamente Ancitel ogni volta che viene cambiato l indirizzo di posta e questa operazione può essere svolta semplicemente riportando il nuovo indirizzo nel campo Email del file xml. I file xml non validi vengono accantonati e poi eliminati dal sistema e non è possibile recuperare il loro contenuto. Il Comune, una volta ricevuta la comunicazione email della validazione non riuscita può recuperare l errore in due modi. Il primo è quello di inviare di nuovo il file xml dopo aver verificato che l errore non sia più presente. Per facilitare l individuazione dell errore nella mail inviata da Ancitel c è allegato il log con l indicazione del campo xml che ha generato l errore. Una volta inviato il file xml corretto è sufficiente attendere la comunicazione email della notifica con successo. L altra alternativa è quella di attendere il prossimo invio, inserendo quindi nel file xml le multe notificate nell arco delle due settimane (quella di competenza e quella che non era stata inviata). 8/15
Pag. 9 di 15 7 AGGIORNAMENTO IMPORTI DELLE MULTE Al termine dei 60 giorni dalla prima notifica al cittadino, il comune provvede ad inviare una seconda notifica con un ulteriore aggravio sull importo della multa. Per questo scopo ogni Comune ha la possibilità di aggiornare l importo delle multe precedentemente inviate e questo attraverso un meccanismo molto semplice. E sufficiente, infatti, che il Comune inserisca i dati della multa già inviata ad Ancitel nel consueto file XML settimanale, specificando il nuovo importo. Viene ora fornito un esempio per chiarire ulteriormente la procedura di aggiornamento. ES: Il comune invia, in una determinata settimana, il seguente file XML: <?xml version="1.0" encoding="utf-8"?> <!--Sample XML file generated by Dario Piermarini--> <ElencoNotificate xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xsi:nonamespaceschemalocation="c:\documents and Settings\piermarini\Documenti\SPFE\schemaCOMUNI.xsd"> <Header> <NomeComune>Poggio Moiano</NomeComune> <CodiceISTAT>057054</CodiceISTAT> <DataInvio>2005-05-05</DataInvio> <Email>municipale@localhost.localdomain</Email> <RecordTotali>3</RecordTotali> </Header> <DataElevazione>2005-03-21</DataElevazione> <NumeroVerbale>123564</NumeroVerbale> <Targa>CM623VA</Targa> <Importo>2000</Importo> <DataElevazione>2005-03-22</DataElevazione> <NumeroVerbale>123565</NumeroVerbale> <Targa>CM623VB</Targa> <Importo>2500</Importo> <DataElevazione>2005-03-23</DataElevazione> <NumeroVerbale>123566</NumeroVerbale> <Targa>CM623VC</Targa> <Importo>3500</Importo> </ElencoNotificate> In evidenza possiamo notare il record che si riferisce al verbale con codice 123564 e che ha un importo pari a 20 euro. Dopo 60 giorni dalla ricevuta della prima notifica, il comune invia una seconda notifica con l importo maggiorato. Nel frattempo nel file XML settimanale inviato ad Ancitel, il comune provvede ad inserire il record con il nuovo importo: 9/15
Pag. 10 di 15 <?xml version="1.0" encoding="utf-8"?> <!--Sample XML file generated by Dario Piermarini--> <ElencoNotificate xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xsi:nonamespaceschemalocation="c:\documents and Settings\piermarini\Documenti\SPFE\schemaCOMUNI.xsd"> <Header> <NomeComune>Poggio Moiano</NomeComune> <CodiceISTAT>057054</CodiceISTAT> <DataInvio>2005-07-05</DataInvio> <Email>municipale@localhost.localdomain</Email> <RecordTotali>2</RecordTotali> </Header> <DataElevazione>2005-03-21</DataElevazione> <NumeroVerbale>123564</NumeroVerbale> <Targa>CM623VA</Targa> <Importo>4000</Importo> <DataElevazione>2005-04-22</DataElevazione> <NumeroVerbale>888999</NumeroVerbale> <Targa>AB626CD</Targa> <Importo>700</Importo> </ElencoNotificate> Come si può notare nella parte evidenziata del file XML, i dati inseriti nel record sono rimasti invariati ad eccezione dell importo che è passato da 20 a 40 euro. Per ogni record presente nel file XML ricevuto dai comuni, il sistema verifica che nel database centrale non sia già presente quel numero di verbale associato al codice ISTAT del comune. Se è presente viene aggiornato l importo della multa e quindi il nuovo importo sarà pari a 40 euro. E bene sottolineare che spetta comunque al comune aggiornare l importo delle multe. Il sistema permette sempre il pagamento, da parte del cittadino, dell importo presente nel database centrale. Questa affermazione ha due implicazioni: 1. Se il comune non provvede ad aggiornare il sistema con i nuovi importi, farà fede sempre l ultimo importo trasmesso, senza alcun limite temporale. 2. Se, nel periodo che intercorre tra l invio degli aggiornamenti e l acquisizione degli stessi da parte del sistema, il cittadino provvede ad effettuare il pagamento, il database centrale non permetterà l aggiornamento dell importo in quanto la multa risulterà già pagata. 10/15
Pag. 11 di 15 8 APPENDICE Schema schemacomuni.xsd schema location: attribute form default: element form default: C:\Documents and Settings\dario\Documenti\schemaCOMUNI.xsd unqualified qualified Elements ElencoNotificate element ElencoNotificate content complex children Header Record annotation documentation Schema XML delle multe notificate source <xs:element name="elenconotificate"> <xs:annotation> <xs:documentation>schema XML delle multe notificate</xs:documentation> </xs:annotation> <xs:complextype> <xs:sequence> <xs:element name="header"> <xs:complextype> <xs:sequence> <xs:element name="nomecomune" type="xs:string"/> <xs:element name="codiceistat"> <xs:simpletype> <xs:restriction base="xs:string"> <xs:pattern value="[0-9]{6}"/> </xs:restriction> </xs:simpletype> <xs:element name="datainvio" type="xs:date"/> <xs:element name="email"> <xs:simpletype> <xs:restriction base="xs:string"> <xs:minlength value="1"/> </xs:restriction> </xs:simpletype> <xs:element name="recordtotali" type="xs:positiveinteger"/> </xs:sequence> </xs:complextype> <xs:element name="record" minoccurs="0" maxoccurs="unbounded"> <xs:complextype> <xs:sequence> <xs:element name="dataelevazione" type="xs:date"/> <xs:element name="numeroverbale" type="xs:string"/> <xs:element name="targa" type="xs:string"/> <xs:element name="importo" type="xs:positiveinteger"> <xs:annotation> <xs:documentation>importo espresso in centesimi di EURO</xs:documentation> 11/15
Pag. 12 di 15 </xs:annotation> </xs:sequence> </xs:complextype> </xs:sequence> </xs:complextype> element ElencoNotificate/Header content complex children NomeComune CodiceISTAT DataInvio Email RecordTotali source <xs:element name="header"> <xs:complextype> <xs:sequence> <xs:element name="nomecomune" type="xs:string"/> <xs:element name="codiceistat"> <xs:simpletype> <xs:restriction base="xs:string"> <xs:pattern value="[0-9]{6}"/> </xs:restriction> </xs:simpletype> <xs:element name="datainvio" type="xs:date"/> <xs:element name="email"> <xs:simpletype> <xs:restriction base="xs:string"> <xs:minlength value="1"/> </xs:restriction> </xs:simpletype> <xs:element name="recordtotali" type="xs:positiveinteger"/> </xs:sequence> </xs:complextype> element ElencoNotificate/Header/NomeComune type xs:string source <xs:element name="nomecomune" type="xs:string"/> element ElencoNotificate/Header/CodiceISTAT 12/15
Pag. 13 di 15 type restriction of xs:string facets pattern [0-9]{6} source <xs:element name="codiceistat"> <xs:simpletype> <xs:restriction base="xs:string"> <xs:pattern value="[0-9]{6}"/> </xs:restriction> </xs:simpletype> element ElencoNotificate/Header/DataInvio type xs:date source <xs:element name="datainvio" type="xs:date"/> element ElencoNotificate/Header/Email type restriction of xs:string facets minlength 1 source <xs:element name="email"> <xs:simpletype> <xs:restriction base="xs:string"> <xs:minlength value="1"/> </xs:restriction> </xs:simpletype> element ElencoNotificate/Header/RecordTotali type xs:positiveinteger source <xs:element name="recordtotali" type="xs:positiveinteger"/> 13/15
Pag. 14 di 15 element ElencoNotificate/Record content complex children DataElevazione NumeroVerbale Targa Importo source <xs:element name="record" minoccurs="0" maxoccurs="unbounded"> <xs:complextype> <xs:sequence> <xs:element name="dataelevazione" type="xs:date"/> <xs:element name="numeroverbale" type="xs:string"/> <xs:element name="targa" type="xs:string"/> <xs:element name="importo" type="xs:positiveinteger"> <xs:annotation> <xs:documentation>importo espresso in centesimi di EURO</xs:documentation> </xs:annotation> </xs:sequence> </xs:complextype> element ElencoNotificate/Record/DataElevazione type xs:date source <xs:element name="dataelevazione" type="xs:date"/> element ElencoNotificate/Record/NumeroVerbale type xs:string source <xs:element name="numeroverbale" type="xs:string"/> element ElencoNotificate/Record/Targa type xs:string source <xs:element name="targa" type="xs:string"/> 14/15
Pag. 15 di 15 element ElencoNotificate/Record/Importo annotation type xs:positiveinteger documentation Importo espresso in centesimi di EURO source <xs:element name="importo" type="xs:positiveinteger"> <xs:annotation> <xs:documentation>importo espresso in centesimi di EURO</xs:documentation> </xs:annotation> 15/15