SMS API Documentazione Tecnica YouSMS SOAP API YouSMS Evet Limited 2015 http://www.yousms.it
INDICE DEI CONTENUTI Introduzione... 2 Autenticazione & Sicurezza... 2 Username e Password... 2 Connessione sicura SSL... 2 Filtro IP... 3 Interfaccia SOAP... 3 Tipi speciali di dati... 3 Tipo SMS... 4 Tipo SmsResponse... 4 Codici Errore... 5 Metodi di invio... 5 Metodo SendSingleSMS... 6 Metodo SendMultipleSMS... 6 Ricevute di consegna... 7 Ricezione messaggi... 7 Evet Limited 2015 Per supporto tecnico scrivere ad supporto@yousms.it 1
INTRODUZIONE YouSMS è una piattaforma SMS di alta qualità che consente di integrare applicazioni, siti web e procedure informative con servizi avanzati di messaggistica SMS. Il vantaggio principale delle interfacce YouSMS (APIs) è rappresentato dalla loro semplicità d utilizzo che permette implementazioni particolarmente veloci. E possibile impostare il mittente dei messaggi SMS con qualsiasi valore alfanumerico fino ad un massimo di 11 caratteri o con qualsiasi numero di telefono. Ad ogni messaggio inviato viene assegnato un identificativo univoco che consente una semplice gestione dei messaggi inviati e delle ricevute di consegna. AUTENTICAZIONE & SICUREZZA USERNAME E PASSWORD Per utilizzare le APIs YouSMS è necessario disporre di un nome utente (username) e di una password. Il nome utente API è rappresentato dall indirizzo email utilizzato dal Cliente in fase di registrazione. Questo è lo stesso che viene utilizzato per accedere al proprio account sul pannello di controllo MySMS. La password API è differente dalla password di accesso al pannello di controllo MySMS. La password API è disponibile sul pannello di controllo MySMS, nella sezione Dati account. Cambiando la password si cambia anche la password API CONNESSIONE SICURA SSL Tutte le comunicazioni con le APIs YouSMS sono stabilite su connessione sicura con certificato SSL. Il Cliente dovrà connettersi alle APIs utilizzando esclusivamente il protocollo HTTPS su porta 443. Evet Limited 2015 Per supporto tecnico scrivere ad supporto@yousms.it 2
FILTRO IP Alcune APIs prevedono un callback da parte di YouSMS verso i servers del Cliente (Es. Inoltro dei messaggi ricevuti, Inoltro delle ricevute di consegna). I callbacks saranno originati dall indirizzo IP 46.37.13.47 Il Cliente potrà filtrare questo indirizzo IP al fine di assicurare l autenticità dei callbacks effettuati da YouSMS. INTERFACCIA SOAP Questo documento descrive l interfaccia SOAP offerta da YouSMS. La SOAP API utilizza il WSDL (Web Services Description Language), che è un linguaggio formale in formato XML per la descrizione di Web Services. Il Cliente, connettendosi al web service YouSMS, potrà leggere il WSDL per determinare le funzionalità disponibili. Il WSDL contiene, inoltre, la descrizione dei tipi speciali di dati utilizzati dal web service. Il WSDL per il servizio YouSMS è disponibile all indirizzo: https://services.yousms.it/soap/smsapi.asmx?wsdl TIPI SPECIALI DI DATI Il servizio utilizza due tipi speciali di dati: Il tipo SMS, che rappresenta un pacchetto SMS completo di tutte le informazioni necessarie all invio Il tipo SmsResponse, che rappresenta la risposta inviata da YouSMS contenente l esito dell invio del messaggio SMS. Evet Limited 2015 Per supporto tecnico scrivere ad supporto@yousms.it 3
TIPO SMS Il tipo SMS contiente tutte le informazioni relative all invio di un messaggio SMS. Le proprietà presenti nel tipo SMS sono elencate nella tabella seguente. Parametro Descrizione Note Esempio Obbligatorio Customer Reference Riferimento interno del cliente per il messaggio SMS SenderID Mittente del messaggio To Message Date Destinatario del messaggio Testo del messaggio Data ed ora di invio del messaggio Tutte le proprietà sono di tipo string. Max 50 caratteri alfanumerici Max 11 caratteri alfanumerici Ordine 3045 NomeAzienda Numero di telefono SI preceduto dal prefisso 39338XXXXXXX internazionale 39 I numeri stranieri devono essere inseriti 0044XXXXXXXX nel formato SI internazionale Max 160 caratteri Messaggio di test SI Utilizzare il seguente formato: dd/mm/yyyy hh:mm NO 04/09/2012 08:30 NO TIPO SMSRESPONSE Un oggetto di tipo SmsResponse viene restituito dall interfaccia YouSMS in risposta alla richiesta di invio di un messaggio SMS. L oggetto contiene le informazioni relative all esito dell invio SMS e copia dell oggetto di tipo SMS presentato dal Cliente nella richiesta di invio. Le proprietà presenti nel tipo SmsResponse sono elencate nella tabella seguente. Evet Limited 2015 Per supporto tecnico scrivere ad supporto@yousms.it 4
Proprietà Descrizione Note Tipo ErrorCode Codice Errore rappresentante l esito dell invio del messaggio SMS MessageID Identificativo univoco del messaggio SMS SMS Informazioni relative al messaggio SMS contenuto nella richiesta di invio. In caso di esito positivo la proprietà avrà valore 0 (zero) In caso di esito negativo la proprietà avrà un valore numerico corrispondente all errore verificatosi. In caso di esito positivo si riceverà l identificativo univoco (ID) assegnato al messaggio. string string L identificativo univoco (ID) potrà essere utilizzato per tracciare il messaggio SMS e per gestire la relativa ricevuta di consegna. I Codici Errore sono elencati nella tabella sottostante. SMS CODICI ERRORE Codice Errore Descrizione 1 Parametri insufficienti 2 Username e/o Password errata 3 Credito insufficiente 4 Formato Data di consegna errato 5 Data di consegna errata 6 Numero telefonico errato METODI DI INVIO L interfaccia SOAP YouSMS mette a disposizione del Cliente 2 metodi di invio: SendSingleSMS SendMultipleSMS Il metodo SendSingleSMS dovrà essere utilizzato per l invio di messaggi SMS singoli mentre per l invio di messaggi SMS multipli occorrerà utilizzare il metodo SendMultipleSMS. Entrambi i metodi sono disponibili con l oggetto SmsAPI dopo che questo sia stato istanziato. Evet Limited 2015 Per supporto tecnico scrivere ad supporto@yousms.it 5
Anche se tecnicamente possibile, è preferibile non effettuare più richieste al metodo SendSingleSMS per inviare messaggi SMS multipli e di utilizzare il metodo appropriato SendMultipleSMS. Questo permetterà di diminuire il carico di lavoro per i servers e di incrementare notevolmente la capacità di invio. METODO SENDSINGLESMS Il metodo SendSingleSMS consente di inviare un singolo messaggio SMS. I parametri di input richiesti dal metodo sono elencati nella tabella seguente. Parametro Descrizione Tipo Esempio Obbligatorio Username Username del string info@nomedominio.com SI Cliente Password API password string 098f6bcd4621d373cade4e832627b4f6 SI del Cliente SMS SMS da inviare SMS SI Il metodo restituisce un oggetto di tipo SmsResponse. METODO SENDMULTIPLESMS Il metodo SendMultipleSMS deve essere utilizzato per l invio di messaggi SMS multipli. Ciascun SMS potrà contenere dati diversi in modo da inviare, con un unica chiamata al metodo, messaggi SMS a destinatari distinti, con contenuto personalizzato ed in date/ore differenti. I parametri di input richiesti dal metodo sono elencati nella tabella seguente. Parametro Descrizione Tipo Esempio Obbligatorio Username Username del Cliente Password API password del Cliente MultipleSMS SMS da inviare string info@nomedominio.com SI string 098f6bcd4621d373cade4e832627b4f6 SI Array di oggetti di tipo SMS Il metodo restituisce un array di oggetti di tipo SmsResponse pari al numero di oggetti SMS inviati al metodo. Ciascun oggetto SmsResponse conterrà un esito di invio distinto ed un identificativo univoco associato al messaggio inviato. SI Evet Limited 2015 Per supporto tecnico scrivere ad supporto@yousms.it 6
RICEVUTE DI CONSEGNA YouSMS inoltra le ricevute di consegna dei messaggi SMS esclusivamente tramite interfaccia HTTP POST. Per la gestione delle ricevute di consegna invitiamo il Cliente a fare riferimento alla documentazione YouSMS HTTP API. RICEZIONE MESSAGGI I messaggi ricevuti possono essere inoltrati da YouSMS al Cliente a mezzo API. L inoltro dei messaggi ricevuti avviene esclusivamente tramite interfaccia HTTP POST. Per la gestione dei messaggi ricevuti invitiamo il Cliente a fare riferimento alla documentazione YouSMS HTTP API. Evet Limited 2015 Per supporto tecnico scrivere ad supporto@yousms.it 7