Specifica Tecnica Revisione Data Elaborato da Verificato da Note 1 21/02/13 Stefano Peruzzi Gianni Antini Mod. ST-rev002_2013-02-21 Pag. 1/11
Indice 1 Oggetto...3 2 Scopo del documento...3 3 Riferimenti...3 4 Abbreviazioni...3 5 Introduzione...3 Mod. ST-rev002_2013-02-21 Pag. 2/11
1 Oggetto Questo documento descrive i servizi web (Web Services) offerti dal sistema SMS Gateway, e fornisce una guida allo sviluppo di applicazioni per la fruizione dei servizi stessi. Il documento è indirizzato agli sviluppatori software. 1.1 Riferimenti 1.1.1 Documenti Id Documento Note [DOC 1] [DOC 2] CONSIP5 MachineToMachine Specifiche di interfaccia ver 1.5, 10/04/2011, Telecom Italia 1.1.2 Riferimenti web Specifiche dei servizi che SMS Gateway può utilizzare Id Link Note [WWW 1] [WWW 2] 1.1.3 Abbreviazioni WS WSDL Acronimo Significato Rif. Web Services Web Services Description Language Mod. ST-rev002_2013-02-21 Pag. 3/11
2 Introduzione Questo documento definisce l'interfaccia per l'utilizzo del servizio web di messaggistica SMS, offerto dal sistema SMS Gateway. Il servizio è disponibile per gli utenti autorizzati e dotati delle necessarie credenziali, ed è indirizzato agli enti della Pubblica Amministrazione. In questo documento si utilizzeranno i termini messaggio o sms riferendosi allo stesso concetto di messaggio di testo inviato ad un numero di telefono tramite un carrier telefonico. Le funzionalità offerte da SMS Gateway sono accessibili anche tramite una interfaccia Web. Gli Web Services sono invece interrogabili tramite il protocollo SOAP/XML. Attraverso queste due interfacce è possibile: Creare contatti e liste di contatti, dove un contatto è il riferimento a una entità (persona fisica, giuridica, etc) dotata di un numero di telefono che può ricevere SMS. Inviare messaggi, in particolare: ad una lista di contatti, ad uno o più contatti singoli, ad uno o piu numeri di telefono. Interrogare il sistema sullo stato dell'invio di un messaggio. Richiedere il consumo della propria quota di messaggi. In questo documento si analizza solo l'interfaccia Web Service, tralasciando l'interfaccia Web. Mod. ST-rev002_2013-02-21 Pag. 4/11
3 Gateway Web Service L'accesso al servizio viene effettuato tramite la seguente URL: http://<server>:<port>/smsgateway/services/gateway Dove <server> e <port> vanno rimpiazzati con i reali valori di hosting del servizio. Per ottenere il documento WSDL del servizio, basta utilizzare come da specifica: http://<server>:<port>/smsgateway/services/gateway?wsdl Tramite il WSDL è possibile generare le classi che compongono il modello del servizio (contatti, liste, etc). Riportiamo nei capitoli successivi la descrizione di ogni metodo offerto dal servizio. 3.1 Autenticazione Con l'autorizzazione all'utilizzo del servizio, l'utente riceverà un token di autenticazione, una stringa di testo che permetterà a SMS Gateway di verificare l'identità dell'utente. Ogni metodo del Web Service richiede tale token in ingresso, con il parametro "authtoken". 3.2 Gestione errori Ogni errore non recuperabile incontrato durante l'esecuzione dei Web Services provocherà una eccezione di tipo GatewayException. L'eccezione conterrà un messaggio in italiano con l'indicazione del problema riscontrato. In particolare, la descrizione conterrà i codici di errore eventualmente ricevuti dal carrier dei messaggi 1. 1 I codici di errore di Telecom Italia sono riportati in appendice. Mod. ST-rev002_2013-02-21 Pag. 5/11
4 Metodi del Gateway 4.1 Elenco liste di contatti (getlists) Fornisce l'elenco di tutte le liste di contatti create dall'utente attuale sul sistema SMS Gateway. List<ContactList>, lista di oggetti, obbligatorio. Collezione di tutte le liste di contatti (ContactList) presenti su SMS Gateway per l'utente. 4.2 Recupera una lista di contatti (getlistbyid) Restituisce la lista di contatti identificata dal dato id. L'id associato alla lista viene assegnato da SMS Gateway in fase di creazione (vedi saveorupdatelist). idlist, tipo numero intero, obbligatorio. Identifica la lista di contatti sul sistema SMS Gateway. ContactList. La lista di contatti con l'id specificato. 4.3 Crea o aggiorna una lista di contatti (saveorupdatelist) Crea una lista di contatti per l'invio di messaggi. Se la lista contactlist ha il dato id valorizzato, la lista del sistema verrà aggiornata. contactlist, tipo ContactList, obbligatorio. Contiene tutti i contatti della lista. Se il dato id contenuto nella lista è valorizzato, allora la lista identificata viene aggiornata sul sistema di SMS Gateway. id, tipo numero intero. Identificatore univoco della lista, creato dal sistema per la lista. In caso di aggiornamento, sarà generato un nuovo identificatore. Mod. ST-rev002_2013-02-21 Pag. 6/11
4.4 Cancella una lista di contatti (deletelist) Cancella la lista di contatti identificata dal dato id sul sistema SMS Gateway. idlist, tipo numero intero, obbligatorio. Identifica la lista di contatti sul sistema SMS Gateway. Nessuno. 4.5 Invio SMS a una lista di contatti (sendmessagetolist) Invia un messaggio a una lista di contatti (contact list). La lista deve essere stata creata sul sistema remoto (vedi saveorupdatelist), e viene indicata tramite il suo id. sender, tipo testo. Utilizzato per impostare il numero mittente dei messaggi inviati. La funzionalità è disponibile solo se il carrier utilizzato offre questa possibilità 2. text, tipo testo. Testo del messaggio 3. idlist, tipo numero intero, obbligatorio. Identifica la lista di contatti sul sistema SMS Gateway. Contiene i contatti da memorizzare sul sistema remoto. Se il dato id contenuto nella lista è valorizzato, allora la lista identificata viene aggiornata sul sistema di SMS Gateway. idinvio, tipo numero intero. Identificatore univoco dell'invio, assegnato da SMS Gateway. 4.6 Invio SMS a contatti (sendmessagetocontacts) Invia un messaggio a uno o più contatti (contact). I contatti non devono essere predentemente creati su SMS Gateway. 2 Telecom Italia attualmente non supporta la personalizzazione del mittente. 3 Telecom Italia attualmente supporta messaggi fino a 640 caratteri. Mod. ST-rev002_2013-02-21 Pag. 7/11
sender, tipo testo. Utilizzato per impostare il numero mittente dei messaggi inviati. La funzionalità è disponibile solo se il carrier utilizzato offre questa possibilità 2. text, tipo testo. Testo del messaggio 3. contacts, lista di oggetti, obbligatorio. Collezione dei contatti destinatari del messaggio. idinvio, tipo numero intero. Identificatore univoco dell'invio, assegnato da SMS Gateway. 4.7 Invio SMS a uno o più numeri di telefono (sendmessagetophones) Invia un messaggio a uno o più numeri di telefono. sender, tipo testo. Utilizzato per impostare il numero mittente dei messaggi inviati. La funzionalità è disponibile solo se il carrier utilizzato offre questa possibilità 2. text, tipo testo. Testo del messaggio 3. phones, lista di stringhe, obbligatorio. Collezione dei numeri di telefono a cui inviare il messaggio. idinvio, tipo numero intero. Identificatore univoco dell'invio, assegnato da SMS Gateway. 4.8 Stato dell'invio (getsinglemessagestatus) Recupera lo stato di un invio, inteso come un messaggio inviato a N destinatari. Il valore tornato è quindi uno stato per ogni destinatario. idinvio, tipo numero intero. Mod. ST-rev002_2013-02-21 Pag. 8/11
Identificatore univoco dell'invio, assegnato da SMS Gateway. Stato invio per singolo destinatario. Collezione di SingleMessageStatus, ogni oggetto racchiude lo stato della consegna di un messaggio a un destinatario. 4.9 Numero di messaggi inviati (getmessagesentamount) Interroga SMS Gateway per conoscere il numero di messaggi inviati in un intervallo di date specificato. from, tipo data, non obbligatorio. Data di inizio dell'intervallo di interesse. Se non specificato, ricerca senza limite iniziale. To, tipo data, non obbligatorio. Data di fine dell'intervallo di interesse. Se non specificato, ricerca senza limite finale. Numero di messaggi trovato nell'intervallo specificato. 4.10 Numero di messaggi disponibili (getmessageavailable) Interroga SMS Gateway per conoscere il numero di messaggi residui, se l'utente ha un budget di messaggi limitato. Numero di messaggi disponibili per l'utente. Mod. ST-rev002_2013-02-21 Pag. 9/11
5 Esempi di utilizzo 5.1 Utilizzo del servizio con Microsoft.NET 5.2 Utilizzo del servizio con Java Mod. ST-rev002_2013-02-21 Pag. 10/11
6 Appendici 6.1 Appendice A Codici di errore di Telecom Italia Codice Messaggio Note 3 M2M-Errore-Generico Errore generico nella chiamata. La casistica maggiore è legata agli errori di autenticazione. 112 M2M-Errore- InvioMSGContattiLiberiNOK 113 M2M-Errore- InvioMSGContattiLiberiVuota L elenco dei contatti liberi non è formalmente corretto. Verificare il formato dei numeri di telefono utilizzati. L elenco dei contatti liberi è vuoto o il parametro non è presente. 116 M2M-Errore-InvioIdNonPresente Il parametro idinvio non è presente. 120 M2M-Errore-InvioMSGTestoNOK Il parametro Testo non è corretto (non presente, lungo 0 caratteri, troppo lungo o caratteri non supportati). 123 M2M-Errore-InvioIdNOK L identificativo dell invio non è presente. Mod. ST-rev002_2013-02-21 Pag. 11/11