Interfaccia SOAP del FUSC Versione 3.10
Indice 1 Introduzione... 4 2 Descrizione... 5 2.1 Condizioni per l utilizzo del web service... 5 2.2 Il server SOAP... 5 2.3 Attivazione del web service... 5 2.3.1 Operazioni ad uso di un foglio ufficiale cantonale... 6 2.3.1.1 Operazione getactualcantonnoticelist()... 6 2.3.1.2 Operazione getactualcantonnoticelistforcategory(category)... 6 2.3.1.3 Operazione getnoticelist(publishdate)... 6 2.3.2 Operazioni ad uso degli abbonati... 7 2.3.2.1 getnoticelistforsubscriber(publishdate, subscriptionid)... 7 2.3.2.2 getnoticelistforsubscriberdaterange(publishdatefrom, publishdateto, subscriptionid)... 7 2.3.3 Operazioni di uso generale... 8 2.3.3.1 getnoticexml(documentid)... 8 2.3.3.2 getnoticehtml(documentid)... 8 2.3.3.3 getnoticepdf(documentid)... 9 2.3.4 getnoticexmls(publishdate)... 9 2.3.5 Operazione ad uso del foglio ufficiale del Cantone di Zurigo... 9 2.4 Messaggi di errore... 9 2.5 Esempio di programma in Java... 10 KPS Documents Interfaccia SOAP del FUSC Pagina 2/12
Cronologia modifiche Versione (n.) Data Modifica Pagine Autore 1.0 15.02.2012 Elaborazione Tutte J.Quapp 1.1 10.04.2012 Piccole modifiche e esempio di programma Tutte J.Quapp 1.2 24.05.2012 Modifiche di dettagli J.Quapp 2.0 01.10.2012 Ampliamento del service Tutte J.Quapp 2.01 24.10.2012 Correzioni del testo J.Quapp 3.0 22.11.2012 Correzioni del testo SECO 3.01 18.08.2013 Nuovo metodo getnoticehtml(long docid) 3.10 10.11.2013 Modifica dello metodo getnoticexml(long docid) J. Quapp J. Quapp KPS Documents Interfaccia SOAP del FUSC Pagina 3/12
1 Introduzione Il FUSC offrono un interfaccia SOAP per gestire la chiamata delle API. Il presente documento contiene tutte le informazioni necessarie per l utilizzazione dell interfaccia SOAP. Se non siete ancora registrati come utenti in FUSC, potete farlo cliccando sui link seguenti: https://www.shab.ch/ SOAP è un protocollo (basato su http) per l offerta di web service. Il web service permette di accedere alle funzioni messe a disposizione dal FUSC partendo da un altro programma e indipendentemente dal linguaggio di programmazione utilizzato per quest ultimo. KPS Documents Interfaccia SOAP del FUSC Pagina 4/12
2 Descrizione 2.1 Condizioni per l utilizzo del web service L utente del web service deve essere registrato come utente del FUSC. L accesso a funzioni speciali richiede la concessione di diritti supplementari all utente. 2.2 Il server SOAP L accesso al server SOAP avviene mediante gli URL seguenti: https://www.shab.ch/soapserver 2.3 Attivazione del web service È indispensabile effettuare l autenticazione nell header http. Se con la richiesta della funzione non viene inviata l autenticazione con l header http, in risposta si riceve un messaggio di errore. L autenticazione nell header http avviene mediante i due parametri username (nome utente) e password (password). La struttura dell header http è perciò la seguente: POST /soapserver HTTP/1.1 username: [NOME UTENTE] SOAPAction: "" Accept: text/xml, multipart/related, text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 Content-Type: text/xml; charset=utf-8 password: [PASSWORT] User-Agent: Java/1.6.0_23 Host: www.shab.ch Connection: keep-alive Content-Length: 273 Il nome utente e la password sono identici a quello utilizzato per l accesso sul FUSC. L utilizzazione del web service può avvenire soltanto dopo l autenticazione. Vi rammentiamo che in alcuni casi l attivazione del web service richiede un autorizzazione speciale. L'autenticazione può essere verificata mediante la funzione getauthentication. KPS Documents Interfaccia SOAP del FUSC Pagina 5/12
Operazioni supportate Qui di seguito sono descritte tutte le funzioni offerte dal service. Tutte le altre funzioni sono destinate ad un uso interno e pertanto non sono disponibili. 2.3.1 Operazioni ad uso di un foglio ufficiale cantonale I fogli ufficiali cantonali possono caricare nel loro sistema redazionale le nuove comunicazioni mediante le funzioni di cui sotto. Le comunicazioni possono essere caricate in formato xml. 2.3.1.1 Operazione getactualcantonnoticelist() Descrizione: Questa funzione visualizza tutti gli ID delle comunicazioni convalidate e pubblicate, con data di chiusura redazionale compresa nei 14 giorni che precedono l avvio della ricerca. Sono trasmessi soltanto i dati relativi alle comunicazioni - il cui stato è «approvato» o «pubblicato»; - selezionate nella sezione corrispondente a quella scelta al momento della registrazione dalla tipografia cantonale. Accessibilità: l accesso all operazione è consentito soltanto se lo stato di utente corrisponde a «tipografia cantonale». 2.3.1.2 Operazione getactualcantonnoticelistforcategory(category) - category si tratta della sigla di una rubrica, formata da due segni. Esempio: «KK»=fallimenti Descrizione: Questa funzione visualizza tutti gli ID delle comunicazioni convalidate e pubblicate, con data di chiusura redazionale compresa nei 14 giorni che precedono l avvio della ricerca. Sono trasmessi soltanto i dati relativi alle comunicazioni: - il cui stato è «approvato» o «pubblicato»; - selezionate nel FUSC nella rubrica [category]; [category] può assumere i seguenti valori: «AW»,«KK»,«NA»,«SB»,«HR»; - Accessibilità: l accesso all operazione è consentito soltanto se lo stato di utente corrisponde a «tipografia cantonale». 2.3.1.3 Operazione getnoticelist(publishdate) - publishdate si tratta di una data di pubblicazione. KPS Documents Interfaccia SOAP del FUSC Pagina 6/12
Descrizione: Una tipografia cantonale ottiene tutti gli ID relativi ai documenti oggetto di comunicazioni con la data di pubblicazione indicata. Sono trasmessi soltanto i dati relativi alle comunicazioni: - il cui stato è «approvato» o «pubblicato»; - selezionate nella rubrica corrispondente a quella scelta al momento della registrazione da parte della tipografia cantonale. Accessibilità: l accesso all operazione è consentito soltanto se lo stato di utente corrisponde a «tipografia cantonale». 2.3.2 Operazioni ad uso degli abbonati Gli abbonati possono ricevere comunicazioni in formato xml anche tramite questo web service se hanno scelto il formato di dati corrispondente. 2.3.2.1 getnoticelistforsubscriber(publishdate, subscriptionid) - publishdate si tratta di una data di pubblicazione; - subscriptionid si tratta dell ID del vostro abbonamento. L ID dell abbonamento si trova nell area clienti abbonamento online i miei dati nell elenco abbonati. Nel caso di abbonamenti rinnovati è sufficiente un ID qualsiasi. Descrizione: si ottiene un elenco di ID di comunicazioni. L elenco viene generato dalla ricerca avviata dall abbonato. Le comunicazioni corrispondono a quelle che l abbonato vede nella sua area clienti per la data di pubblicazione scelta. Viene generato un elenco di ID di comunicazioni pubblicate alla data specificata e rispondenti ai criteri di ricerca definiti dall abbonato. Accessibilità: l accesso all operazione è consentito soltanto se lo stato di utente corrisponde a «abbonato FUSC». 2.3.2.2 getnoticelistforsubscriberdaterange(publishdatefrom, publishdateto, subscriptionid) - publishdatefrom si tratta di una data di pubblicazione (a partire da); - publishdateto si tratta di una data di pubblicazione (fino a); - subscriptionid Si tratta dell ID del vostro abbonamento. L ID dell abbonamento si trova nell area clienti abbonamento online i miei dati nell elenco abbonati. nel caso di abbonamenti rinnovati è sufficiente un ID qualsiasi. Descrizione: viene trasmesso un elenco di ID di comunicazioni. L elenco viene generato dalla ricerca avviata dall abbonato. Le comunicazioni corrispondono a quelle che l abbonato vede nella sua area clienti per l arco di tempo scelto per la data di pubblicazione [publishdatefrom]-[ publishdateto]. Viene generato un elenco di ID di comunicazioni pubblicate nell arco di tempo specificato e rispondenti ai criteri di ricerca definiti dall abbonato. KPS Documents Interfaccia SOAP del FUSC Pagina 7/12
Accessibilità: l accesso all operazione è consentito soltanto se lo stato di utente corrisponde a «abbonato FUSC». Vi rammentiamo che occorre inserire sempre l ID dell abbonamento in corso. 2.3.3 Operazioni di uso generale Le seguenti operazioni sono accessibili a diversi gruppi di utenti. 2.3.3.1 getnoticexml(documentid) - documentid si tratta del numero di una comunicazione; Descrizione: Effettuando l operazione si ottiene un documento in formato xml della comunicazione corrispondente all ID indicato. La descrizione dell xml della comunicazione è disponibile su www.shab.ch. Indicazione: Fino alla versione 3.01 l inizio del contenuto XML era presentato così: <?xml version="1.0" encoding="utf-8"?> <FORM ACTIVE.PAGE="1" FOSC_NR="85" ID=="[ID]" LANG=="[DE,FR,IT,EN]" PUBLISH_NR="[1,2,3] USER="[USER_NUMBER]"> VERSION="[VERSION_NR] > <[SUB_CATEGORY]> A partire dalla versione 3.1 l inizio del contenuto XML viene presentato così: <?xml version="1.0" encoding="utf-8"?> <FORM ACTIVE.PAGE="1" ID=="[ID]" LANG=="[DE,FR,IT,EN]" PUBLISH_NR="[1,2,3]" USER="[USER_NUMBER]" VERSION="[VERSION_NR] > <[SUB_CATEGORY]> Accessibilità: l accesso all operazione è consentito soltanto se l utente è registrato. La comunicazione deve essere stata pubblicata. Se l utente è un amministratore cantonale vengono visualizzate anche le comunicazioni «convalidate». 2.3.3.2 getnoticehtml(documentid) - documentid si tratta del numero di una comunicazione Descrizione: Effettuando l operazione si ottiene un documento in formato HTML della comunicazione corrispondente all ID indicato come viene fornito effettuando una ricerca nel FUSC. Accessibilità: l accesso all operazione è consentito soltanto se l utente è registrato. La comunicazione deve essere stata pubblicata. Se l utente è un amministratore cantonale vengono visualizzate anche le comunicazioni «convalidate». KPS Documents Interfaccia SOAP del FUSC Pagina 8/12
2.3.3.3 getnoticepdf(documentid) - documentid si tratta del numero di una comunicazione; Descrizione: Effettuando l operazione si ottiene un documento in formato pdf della comunicazione corrispondente all ID indicato. Accessibilità: l accesso all operazione è consentito soltanto se l utente è registrato. Considerato che i documenti in pdf sono disponibili soltanto nel FUSC, anche l operazione può essere effettuata soltanto nel FUSC. 2.3.4 getnoticexmls(publishdate) - publishdate si tratta di una data di pubblicazione del FUSC; Descrizione: Effettuando l operazione si ottiene un documento in formato xml di tutto il file. Il file intero contiene tutte le comunicazioni pubblicate alla data indicata. Come argomento occorre indicare una data di pubblicazione del FUSC. Accessibilità: l accesso all operazione è consentito soltanto se l utente è registrato e può essere effettuata soltanto per i numeri pubblicati. 2.3.5 Operazione ad uso del foglio ufficiale del Cantone di Zurigo Le operazioni seguenti vengono effettuate soltanto in relazione al foglio ufficiale del Cantone di Zurigo: si tratta perciò di operazioni disponibili soltanto con la relativa installazione. getactualcantonnoticelistforcategorywithstatus getattachment getproviderfromnotice 2.4 Messaggi di errore La segnalazione di un errore può avvenire sia mediante codice di errore sia mediante messaggio di errore. Si tratta di una segnalazione generica («fault»). Ad ogni «fault» sono attribuiti due parametri: «code» e «message». Il codice di errore viene trasmesso mediante l operazione getfaultinfo.getcode(). Il messaggio che specifica il tipo di errore viene trasmesso con getfaultinfo.getmessage(). Elenco dei messaggi di errore: Codice di Descrizione del tipo di errore KPS Documents Interfaccia SOAP del FUSC Pagina 9/12
errore 0 Internal error! 1 You do not have sufficient rights to perform this operation! 2 Date out of range! 10 Internal error in getauthenticationobject! 20 Not authenticated! 21 Internal error in getnoticelist! 30 Error in service getnotice. Not authenticated! 31 Internal Error in getnoticexml! 32 Error in service getnotice. Notice not available!! 35 Internal Error in getnoticexmls! 36 Error in service getnoticexmls. Not authenticated! 37 Error in service getnoticexmls. Date not published! 40 Error in service getprovider. Not authenticated! 41 Internal error in getproviderfromnotice! 42 Internal error in getprovider! 50 Error in service getattachment. Not authenticated! 51 Internal error in getattachment! 52 No document in getattachment! 60 Error in authentication. User is not a subscriber! 61 Error in getnoticelistforsubscription. Subscription id is not valid for the subscriber! 62 Error in getnoticelistforsubscription. Error processing search list! 70 Error in service getnoticepdf. Not authenticated! 71 Internal error in getnoticepdf! 72 No document in getnoticepdf! 2.5 Esempio di programma in Java L esempio di programma è finalizzato a illustrare l esecuzione degli elementi fondamentali della programmazione per un client in relazione a questo web service. Nota: per il programma di cui sotto occorre prima di tutto generare classi di client. La generazione di queste classi avviene mediante il comando wsimport -keep -p [package Java per i dati generati] -s [percorso per i file sorgente] https://www.shab.ch/soapserver?wsdl import java.net.url; import java.text.simpledateformat; import java.util.collections; import java.util.gregoriancalendar; KPS Documents Interfaccia SOAP del FUSC Pagina 10/12
import java.util.hashmap; import java.util.list; import java.util.locale; import java.util.map; import javax.xml.datatype.datatypefactory; import javax.xml.datatype.xmlgregoriancalendar; import javax.xml.namespace.qname; import javax.xml.ws.bindingprovider; import javax.xml.ws.handler.messagecontext; import de.autinform.exchange.common.soap.client.notice.fault; import de.autinform.exchange.common.soap.client.notice.longarray; import de.autinform.exchange.common.soap.client.notice.soapserver; import de.autinform.exchange.common.soap.client.notice.soapserverservice; public class Example { private final static SimpleDateFormat dateformat = new SimpleDateFormat("dd.MM.yyyy", Locale.getDefault()); public Example() { } public void main(string username, String password) { // Erstellung einer Verbindung zum Soap Server String servername = "www.shab.ch"; int port = 9191; try { URL url = new URL("http://" + servername + ":" + port +"/soapserver?wsdl"); QName servicename = new QName("http://notice.server.soap.common.exchange.autinform.de/", "SoapServerService"); SoapServerService service = new SoapServerService(url,serviceName); SoapServer serviceport = service.getsoapserverport(); /******************* Authentication ******************************/ Map<String, Object> req_ctx = ((BindingProvider)servicePort).getRequestContext(); Map<String, List<String>> headers = new HashMap<String, List<String>>(); headers.put("username", Collections.singletonList(username)); headers.put("password", Collections.singletonList(password)); req_ctx.put(messagecontext.http_request_headers, headers); /**********************************************************************/ boolean succesfulauthentication = serviceport.getauthentication(); if (succesfulauthentication) { System.out.println("Authentication successful!"); } else { System.out.println("Authentication not successful!"); return; KPS Documents Interfaccia SOAP del FUSC Pagina 11/12
} GregorianCalendar c = new GregorianCalendar(); c.settime(dateformat.parse("26.01.2013")); XMLGregorianCalendar publishdate = DatatypeFactory.newInstance().newXMLGregorianCalendar(c); } LongArray arraylist = serviceport.getnoticelistforsubscriber(publishdate, 4711); List<Long> noticelist = arraylist.getitem(); for (int i=0; i<noticelist.size(); i++) { } long documentid = noticelist.get(i); String contentxml = serviceport.getnoticexml(documentid); System.out.println("ID: " + documentid); System.out.println("XML:" + contentxml); } catch (Fault f) { f.printstacktrace(); } catch (Exception e) { } e.printstacktrace(); KPS Documents Interfaccia SOAP del FUSC Pagina 12/12