SMS API. Documentazione Tecnica YouSMS HTTP API. YouSMS Evet Limited

Transcript

1 SMS API Documentazione Tecnica YouSMS HTTP API YouSMS Evet Limited

2 INDICE DEI CONTENUTI Introduzione... 2 Autenticazione & Sicurezza... 2 Username e Password... 2 Connessione sicura SSL... 2 Filtro IP... 3 Interfaccia HTTP... 3 Invio di un messaggio SMS... 3 Specifiche... 3 URL... 3 Parametri di invio... 4 Risposta... 4 Codici Errore... 5 Esempio di invio messaggio... 5 Ricevute di consegna... 6 Interfaccia Cliente... 6 Parametri inviati all Interfaccia Cliente... 6 Ricezione messaggi... 7 Interfaccia Cliente... 7 Parametri inviati all interfaccia cliente... 7 Ricezione messaggi su numerazione condivisa con Keyword... 7 Ricezione messaggi su numerazione dedicata... 8 Evet Limited 2015 Per supporto tecnico scrivere ad supporto@yousms.it 1

3 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 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

4 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 Il Cliente potrà filtrare questo indirizzo IP al fine di assicurare l autenticità dei callbacks effettuati da YouSMS. INTERFACCIA HTTP Questo documento descrive l interfaccia HTTP offerta da YouSMS. L invio e la ricezione di messaggi SMS tramite questa interfaccia risulta particolarmente semplice e flessibile. L integrazione può essere effettuata mediante l uso dei maggiori linguaggi di programmazione in quanto essi supportano nativamente richieste HTTP. Le richieste di invio di messaggi SMS vengono inviate nello stesso modo utilizzato da un form web (POST o GET) o digitando una URL in un browser internet (GET). INVIO DI UN MESSAGGIO SMS SPECIFICHE L interfaccia supporta sia richieste HTTP GET che HTTP POST. Connessioni persistenti possono essere utilizzate per aumentare la capacità di invio. URL L interfaccia disponibile presso l indirizzo Evet Limited 2015 Per supporto tecnico scrivere ad supporto@yousms.it 3

5 PARAMETRI DI INVIO La tabella seguente specifica i parametri che dovranno essere inviati all interfaccia HTTP. Parametro Descrizione Note Esempio Obbligatorio Username Username del Cliente Password API password del Cliente SenderID Mittente del messaggio To Message Date Destinatario del messaggio Testo del messaggio Data ed ora di invio del messaggio Max 11 caratteri alfanumerici info@nomedominio.com 098f6bcd4621d373cade4e832627b4f6 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 04/09/ :30 NO SI SI RISPOSTA Per ciascuna richiesta inviata all interfaccia si riceverà una risposta contenente l esito della richiesta. In caso di esito positivo si riceverà una risposta contenente la parola OK, seguita dall identificativo univoco (ID) assegnato al messaggio. L identificativo univoco (ID) potrà essere utilizzato per tracciare il messaggio SMS e per gestire la relativa ricevuta di consegna. Esempio OK <ID> In caso di esito negativo, a seguito di un errore, si riceverà esclusivamente il codice errore verificatosi. Esempio <Codice Errore> La lista dei codici errore possibili è rappresentata nella tabella seguente. Evet Limited 2015 Per supporto tecnico scrivere ad supporto@yousms.it 4

6 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 ESEMPIO DI INVIO MESSAGGIO Di seguito un esempio di invio messaggio utilizzando il metodo HTTP GET Disponendo delle seguenti credenziali di accesso API: Username: info@nomedominio.com Password API: 098f6bcd4621d373cade4e832627b4f6 Supponendo di voler inviare il seguente messaggio SMS: Mittente: NomeAzienda Destinatario: 39338XXXXXXX Testo del Messaggio: Test La richiesta da effettuare sarà: b4f6&SenderID=NomeAzienda&Message=Test&To=39338XXXXXXX Per programmare l invio futuro dello stesso messaggio occorrerà semplicemente aggiungere il parametro Date. Quindi supponendo di voler programmare l invio del messaggio per il giorno 04/09/2012 alle ore 8:30am La richiesta da effettuare sarà: b4f6&SenderID=NomeAzienda&Message=Test&To=39338XXXXXXX&Date=04%2F09%2F %3A30 A fronte di questa richiesta il sistema restituirà l esito: OK a7aeed f3b292a982238f83d2 Evet Limited 2015 Per supporto tecnico scrivere ad supporto@yousms.it 5

7 RICEVUTE DI CONSEGNA YouSMS inoltra le ricevute di consegna dei messaggi SMS tramite un interfaccia web. Le ricevute di consegna sono disponibili sia quando un messaggio SMS viene consegnato al destinatario e sia quando l operatore telefonico del destinatario invia uno stato definitivo per il messaggio. Le ricevute di consegna verranno inoltrate al Cliente mediante una richiesta HTTP (callback) ad una pagina/applicazione web (Interfaccia Cliente) fornita dal Cliente. INTERFACCIA CLIENTE Il Cliente dovrà creare una pagina/applicazione web per ottenere le ricevute di consegna dei messaggi SMS inviati. L interfaccia Cliente dovrà essere implementata in modo da poter ricevere e gestire i parametri inviati da YouSMS. I parametri inviati sono elencati nella tabella seguente. L indirizzo internet (URL) dove è disponibile l Interfaccia Cliente dovrà essere specificato sul pannello di controllo MySMS, nell area Impostazioni, accedendo con le credenziali di accesso del proprio account. PARAMETRI INVIATI ALL INTERFACCIA CLIENTE I seguenti parametri saranno inviati da YouSMS all Interfaccia Cliente mediante richiesta HTTP POST. Parametro Descrizione Esempio From Mittente del messaggio SMS 39338XXXXXXX To Destinatario del messaggio SMS 39345XXXXXXX Delivered Esito di consegna del messaggio True (Messaggio consegnato) False (Messaggio non consegnato) ID Identificativo univoco del messaggio a7aeed f3b292a982238f83d2 Time Data ed ora di consegna del messaggio 14/11/201109:37:03 Il valore True per il parametro Delivered sarà restituito esclusivamente in caso di consegna positiva del messaggio SMS. Il valore False verrà restituito per tutti gli esiti negativi definitivi. Evet Limited 2015 Per supporto tecnico scrivere ad supporto@yousms.it 6

8 RICEZIONE MESSAGGI I messaggi ricevuti possono essere inoltrati da YouSMS al Cliente a mezzo API. I messaggi ricevuti verranno inoltrati al Cliente mediante una richiesta HTTP (callback) ad una pagina/applicazione web (Interfaccia Cliente) fornita dal Cliente. INTERFACCIA CLIENTE Il Cliente dovrà creare una pagina/applicazione web alla quale verranno inoltrati i messaggi ricevuti. L interfaccia Cliente dovrà essere implementata in modo da poter ricevere e gestire i parametri inviati da YouSMS. I parametri inviati sono elencati nella tabella seguente. L indirizzo internet (URL) dove è disponibile l Interfaccia Cliente dovrà essere specificato sul pannello di controllo MySMS, nell area Impostazioni, accedendo con le credenziali di accesso del proprio account. PARAMETRI INVIATI ALL INTERFACCIA CLIENTE I seguenti parametri saranno inviati da YouSMS all Interfaccia Cliente mediante richiesta HTTP POST. Parametro Descrizione Esempio From Mittente del messaggio SMS 39338XXXXXXX To Numerazione sulla quale è 39345XXXXXXX pervenuto il messaggio SMS Content Contenuto del messaggio Messaggio di test Time Data ed ora ricezione messaggio 14/11/201120:38:31 RICEZIONE MESSAGGI SU NUMERAZIONE CONDIVISA CON KEYWORD I messaggi ricevuti, sulla numerazione condivisa YouSMS, inizianti con la parola chiave (Keyword) scelta dal Cliente verranno inoltrati all Interfaccia Cliente con le stesse modalità di cui sopra. In questo caso il valore del parametro To sarà costituito dal numero telefonico condiviso YouSMS. Evet Limited 2015 Per supporto tecnico scrivere ad supporto@yousms.it 7

9 RICEZIONE MESSAGGI SU NUMERAZIONE DEDICATA I messaggi ricevuti, sulla numerazione dedicata del Cliente verranno inoltrati all Interfaccia Cliente con le stesse modalità di cui sopra. In questo caso il valore del parametro To sarà costituito dal numero telefonico dedicato del Cliente. Evet Limited 2015 Per supporto tecnico scrivere ad supporto@yousms.it 8