SmsMobile.it Principali caratteristiche piattaforma web smsmobile.it Istruzioni Backoffice Post get http VERSION 2.1 Smsmobile by Cinevision srl Via Paisiello 15/ a 70015 Noci ( Bari ) tel.080 497 30 66 fax 080 214 07 19
Principali caratteristiche della piattaforma web smsmobile.it Istruzioni per l invio di sms tramite smsmobile.it con utilizzo di vostri applicativi connessi sul gateway sms tramite chiamata post get http: Documento: Istruzioni gateway sms - Post get http - backoffice.pdf Versione: 2.1 Data ult. rev.: 30/06/2012 Indice: 1 - Principali caratteristiche tecniche della piattaforma web smsmobile.it 2 - Invio singolo SMS tramite richiesta POST/GET HTTP 3 - Invio multiplo SMS tramite richiesta POST/GET HTTP 4 - Controllo Credito SMS rimanente tramite richiesta POST/GET HTTP 5 - Controllo stato Notifica tramite richiesta POST/GET HTTP 6 - Controllo stato Notifica Multipla per data, tramite richiesta POST/GET HTTP 7 - Ricezione delle Notifiche via POST HTTP 7.1 - Specifiche per la ricezione dei POST HTTP 8 - Invio multiplo richieste MNC tramite richiesta POST/GET HTTP 8.1 - Controllo stato MNC tramite richiesta POST/GET HTTP
1 - Principali caratteristiche tecniche della piattaforma web smsmobile.it 1) Accesso tramite Username e Password dedicate su pagina web,. accessibile da qualsiasi computer collegato al web; 2) Possibilità di controllo del credito residuo in tempo reale sia in Euro che in SMS rimanenti; 3) Possibilità di utilizzo della piattaforma web contemporaneamente da più postazioni connesse al web; 4) possibilità di creare infiniti Gruppi (rubriche); 5) possibilità di inserire all' interno di ogni gruppo infiniti contatti; 6) invio Singolo sms; 7) invio multiplo sms a tutti i gruppi contemporanemente dello stesso sms; 8) invio multiplo sms solo al alcuni contatti del gruppo; 9) possibilità di differire l'invio degli sms programmando data ed ora di invio; 10) status monitor di invio sms aggiornato in tempo reale; 11) statistiche di invio aggiornate in tempo reale ed esportabili in file formato excell; 12) Creazione di infiniti modelli di invio ; 13) Invio Programmato di auguri di compleanno con personalizzazione del testo di auguri; 14) Gestione delle rubriche in formato excell e formato di testo txt (notepad); 15) Mittente dell'sms personalizzabile; 16) Gestione su cartella dedicata delle notifiche di ricezione sms; 17) Visualizzazione dello storico degli invii per data ed ora, numero destinatario, testo sms inviato; 18) Testo SMS da 160 caratteri + 11 caratteri per personalizzare il mittente. 19) Servizio MNC (Multi Number Check) per verifica dei numeri di telefono 20) SMS concatenati oltre i 160 caratteri. Gli sms concatenati sono a multipli di 134 caratteri per singolo sms. E' possibile spedire testi lunghi fino a 804 caratteri ( 6 sms concatenati ) che il destinatario riceverà sul proprio telefono cellulare sotto forma di un UNICO messaggio SMS. L invio di sms avviene tramite richieste POST/http
2 - Invio singolo SMS tramite richiesta POST/GET HTTP URL: http://sms.smsmobile-ba.com/sms/send.php Parametri autenticazione: user Login cliente pass Password cliente Parametri obbligatori: rcpt Numero destinatario nel formato internazionale %2bXXYYYZZZZZZZ data Testo del messaggio (max 160 caratteri) sender Mittente del messaggio (max 11 caratteri alfanumerici o numero %2bXXYYYZZZZZZZ) qty Qualità del messaggio: (ll, a, n bassa, automatica, notifica) Parametri opzionali: operation Tipo di messaggio che si intende spedire. I possibili valori sono: - TEXT - messaggio di testo default - WAPPUSH - messaggio WapPush - UCS2 messaggio con codifica UCS2 - MULTITEXT messaggio concatenato I messaggi UCS2 e MULTITEXT possono essere inviati solamente in qualità Notifica. Attraverso l'opzione MULTITEXT sarà possibile inviare un testo lungo fino a 804 caratteri, che verrà automaticamente suddiviso ed inviato dal sistema come più SMS i quali verranno ricevuti dal cellulare come un unico testo. url Indirizzo URL al quale si dovrà collegare il cellulare che riceve il messaggio WAPPUSH.
return_id Se impostato uguale a 1 verrà restituito l identificativo della spedizione da utilizzare nel caso si richieda lo stato della spedizione tramite post/get http (es. HTTP00000000111). Il server risponderà con OK <costo>, ove <costo> è il credito scalato per l'invio del messaggio. In caso di errore la risposta del server sarà KO <testo_errore>. Codici errore: KO Accesso non consentito (Utente non abilitato). KO Accesso non consentito (IP non abilitato). KO Parametro <nome parametro> non impostato. KO Il parametro <nome parametro> può contenere al massimo <n> numeri. KO Parametro <nome parametro> non valido. KO Operatore sconosciuto. KO Credito insufficiente. KO Impossibile accodare il/i messaggio/i. Esempi di invio sms TEXT MULTITEXT - UCS2: Un sms può essere inviato semplicemente copiando i link riportati di seguito ed incollandoli nella barra degli indirizzi di un browser dopo aver sostituito username, password e numero di telefono del destinatario con valori corretti: Messaggio TEXT (160 caratteri) http://sms.smsmobileba.com/sms/send.php?user=username&pass=password&rcpt=%2b3934 81234567&data=messaggiodiprova&sender=sms&qty=a Messaggio MULTITEXT (sms oltre i 160 caratteri messaggio concatenato) http://sms.smsmobileba.com/sms/send.php?user=username&pass=password&operation=mu
LTITEXT&rcpt=%2b393481234567&sender=sms&qty=n&data=messaggi odiprovalungopiudi160caratteri...ecc...ecc Messaggio UCS2 (messaggio con codifica UCS2 - sms con caratteri speciali) http://sms.smsmobileba.com/sms/send.php?user=username&pass=password&operation=uc S2&rcpt=%2b393487633474&sender=sms&qty=n&data= %CE%B1%CE%B2%CE%B3 (in questo esempio è stato simulato l invio di un sms con caratteri speciali dell alfabeto greco. Il cellulare riceverà i caratteri greci alfa, beta, gamma)
3 - Invio multiplo SMS tramite richiesta POST/GET HTTP URL: http://sms.smsmobile-ba.com/sms/batch.php Parametri autenticazione: user Login cliente pass Password cliente Parametri obbligatori: rcpt Elenco numeri nel formato internazionale %2bXXYYYZZZZZZ, separati da virgola data Testo del messaggio (max 160 caratteri) sender Mittente del messaggio (max 11 caratteri alfanumerici o numero %2bXXYYYZZZZZZZ) qty Qualità del messaggio: (ll, a, n bassa, automatica, notifica) Parametri opzionali: operation Tipo di messaggio che si intende spedire. I possibili valori sono: - TEXT - messaggio di testo default - WAPPUSH - messaggio WapPush - UCS2 messaggio con codifica UCS2 - MULTITEXT messaggio concatenato I messaggi UCS2 e MULTITEXT possono essere inviati solamente in qualità Notifica. Attraverso l'opzione MULTITEXT sarà possibile inviare un testo lungo fino a 804 caratteri, che verrà automaticamente suddiviso ed inviato dal sistema come più SMS i quali verranno ricevuti dal cellulare come un unico testo.
Ignore Err=true per scartare dalla lista i numeri troppo corti o troppo lunghi, senza mandare in errore tutta la spedizione multipla. Esempi: quando si invia aggiungere il parametro "ignoreerr=true" (booleano), il sistema non blocca la spedizione ma invia il messaggio a tutti i numeri corretti. Es: http://sms.smsmobileba.com/sms/batch.php?user=username&pass=password&operation=text&rcpt=%2b393 33000000,%2b39123&sender=mittente&data=testo&qty=a&ignoreErr=true Invia l'sms al numero +39333000000 e restituisce errore per il numero +39123 http://sms.smsmobileba.com/sms/batch.php?user=username&pass=password&operation=text&rcpt=%2b393 33000000,%2b39123&sender=mittente&data=testo&qty=a Senza il parametro "ignoreerr=true" nessun messaggio parte. url Indirizzo URL al quale si dovrà collegare il cellulare che riceve il messaggio WAPPUSH. return_id Se impostato uguale a 1 verrà restituito l identificativo della spedizione da utilizzare nel caso si richieda lo stato della spedizione tramite post/get http (es. HTTP00000000111). Il server risponderà con OK. In caso di errore la risposta del server sarà KO <testo_errore>.
4 - Controllo Credito SMS rimanente tramite richiesta POST/GET HTTP URL: http://sms.smsmobile-ba.com/sms/credit.php Parametri autenticazione: user Login cliente pass Password cliente Parametri opzionali: type Tipo di controllo ( credit credito residuo default -, ll messaggi bassa qualità, a messaggi alta qualità) Il server risponderà con OK <VALORE> ove <VALORE> è il numero di sms o il credito residuo in euro, a seconda del parametro type specificato. In caso di errore la risposta del server sarà KO <testo_errore>. Codici errore: KO Accesso non consentito (Utente non abilitato). KO Accesso non consentito (IP non abilitato). KO Parametro type non corretto KO Errore Interno. KO Accesso non consentito KO Parametri non corretti Esempio: http://sms.smsmobileba.com/sms/credit.php?user=username&pass=password&type=a
5 - Controllo stato Notifica tramite richiesta POST/GET HTTP Url: http://sms.smsmobile-ba.com/sms/batch-status.php Parametri autenticazione: user Login cliente pass Password cliente Parametri obbligatori: id Identificativo della spedizione (request_id specificato al momento dell invio della richiesta) type Tipo di report desiderato ( notify stato delle notifiche dei messaggi inviati) ( queue stato accodamento sms) schema Schema del report ( 1 solo codice errore) ( 2 codice di errore specifico) Il server risponderà con i dati del report richiesto on formato CVS con i campi separati da virgola, dove la prima riga conterrà i nomi delle colonne. In caso di errore la risposta del server sarà KO <testo_errore>. Codici errore: KO Accesso non consentito (Utente non abilitato). KO Accesso non consentito (IP non abilitato). KO Parametro <nome parametro> non impostato. KO Il parametro <nome parametro> non corretto KO Errore interno KO Accesso non consentito KO Parametri non corretti Esempio: http://sms.smsmobile-ba.com/sms/batchstatus.php?user=username&pass=password&id=http.&type=notify& schema=1
Stati di errore riscontrabili al momento dell'invio utilizzando il "sendstatus.php": Queue: 100 - Waiting 102 - Temporary failure 200 - Processed 300 - Permanent failure Notify: 100 - Waiting 200 - Delivered 300 - Not delivered (schema 1) - "Codice di errore specifico" (schema 2) MNC: 100 - Waiting 200 - Exist 300 Unknown subscriber Questa è una breve lista di possibili notifiche d'errore: KO - Teleservice not provisioned (Numero non abilitato in ricezione): il messaggio non può essere consegnato perchè il numero non supporta la ricezione di sms. KO - Unknown Subscriber: il numero è inesistente. KO - Absent Subscriber: numero assente. KO - Notifica non disponibile: è terminato il tempo di validità per la consegna dei messaggi. KO - Controlling MSC system failure: l'msc (Mobile Switching Centre) è un apparato dell'architettura della rete GSM che si occupa dello
smistamento dei messaggi tra operatori mobili. In particolare questo problema dipende dall'msc dell'operatore destinatario del messaggio. Spesso accade a causa di un sovraccarico dell'msc. KO - Customer is barred according to the MT HLR from receiving SMS: il numero è stato bloccato dall'operatore del destinatario. KO - Equipment protocol error: problema del protocollo dell'operatore del numero del destinatario. KO - Expired: il tempo disponibile per poter consegnare l'sms è terminato e non è stato possibile durante questo periodo recapitare l'sms. KO - MT number is unknown in the MT network's HLR: il numero è disattivato o inesistente. Tradotto letteralmente : il numero risulta sconosciuto all'interno dell'hlr (Home Location Register) della rete del numero destinatario. KO - Memory capacity exceeded (Memoria SMS esaurita): Significa che il cellulare ha terminato lo spazio per poter ricevere l'sms. KO - SS7 error. "No response from peer" : il numero è stato disattivato o è inesistente.
6 - Controllo stato Notifica Multipla per data, tramite richiesta POST/GET HTTP http://sms.smsmobile-ba.com/sms/batch-status-interval.php Parametri autenticazione: user Login cliente pass Password cliente Parametri obbligatori: from Data ora di inzio dell intervallo desiderato. La data dovrà essere nel formato gg/mm/aaaa/hh/mm (es. per richiedere lo stato degli invii effettuati a partire dalle ore 10.30 del 12/08/2008 si dovrà scrivere 12/08/2008/10/30 ). to Data/ora di fine dell intervallo desiderato. La data dovrà essere nel formato gg/mm/aaaa/hh/mm type Tipo di report desiderato ( queue stato accodamento messaggi, notify stato delle notifiche dei messaggi inviati, mnc stato delle richieste MNC) schema Schema del report (i formati sono 1 e 2 come nel caso di batchstatus.php). Il server risponderà con i dati del report richiesto in formato CSV con i campi separati da virgola, dove la prima riga conterrà i nomi delle colonne. In ogni riga verrà specificato l identificativo della spedizione cui appartiene l elemento. Questo identificativo corrisponde a quello restituito dal sistema al momento dell invio se si è impostato il parametro return_id a 1. In caso di errore la risposta del server sarà KO <testo_errore>.
Esempio report notify: id,dest,status,status_text,id_spedizione 9184,+393331111111,100,Delivered, HTTP00000000111 9185, +393331111111,Unknown subscriber, HTTP00000000111 Esempio di interrogazione: http://sms.smsmobile-ba.com/sms/batch-status-interval.php?user=xxxxxxx &pass=zzzzzzzzz&from=10/12/2008/10/00&to=20/01/2009/08/00&type=notify &schema=1 Per il momento non ci sono limitazioni riguardo la dimensione dell'intervallo temporale.
7 Ricezione delle notifiche via POST HTTP Il sistema permette di ricevere le notifiche dei messaggi inviati mediante un POST HTTP. 7.0.1 Fase di invio degli SMS Per poter abilitare la funzionalità di richiesta delle notifiche mediante POST HTTP è necessario, in fase di invio, settare il parametro qty=n e validare il parametro batch_code, settandolo con un valore a discrezione del cliente. Il parametro batch_code verrà restituito al cliente nella notifica stessa e potrà eventualmente essere utilizzato per abbinare la "mobile delivery notification" con il relativo invio. L'URL a cui il sistema posterà le notifiche lo si può settare in 2 modi: 1. direttamente dal pannello SmsMobile.it alla voce "Impostazioni > Impostazioni messaggi > URL notifiche" Questo valore verrà utilizzato come URL di default. 2. Passandolo direttamente alle api mediante il parametro notify_url Il metodo con cui il sistema seleziona l'url a cui postare le notifiche è riassunto nella seguente tabella: URL nel parametro notify_url URL settato su pannello URL a cui verrà postata la notifica non settato non settato La notifica non viene postata non settato http://miosito/notifiche-pannello.dfl http://miosito/notifiche-pannello.dfl http://miosito/notifiche-api.api non settato http://miosito/notifiche-api.api http://miosito/notifiche-api.api http://miosito/notifiche-pannello.dfl http://miosito/notifiche-api.api 7.0.2 Messaggi concatenati Con il pannello SMsMobile.it è possibile inviare attraverso un unico POST/GET HTTP un SMS con testo piu lungo di 160 caratteri utilizzando l'operation MULTITEXT. Con questa funzionalità è possibile spedire un testo lungo fino a 918 caratteri che verrà automaticamente suddiviso ed inviato dal sistema come più SMS. In questo caso l'operatore telefonico inoltra al sistema una notifica per ogni SMS parte dell'intero messaggio. Per riconoscere a quale parte dell'sms è relativa la notifica ricevuta, si può utilizzare l'udh, valore che verrà postato come parametro della notifica. Maggiori informazioni sul parametro udh sono disponibili nel paragrafo successivo.
7.1 Specifiche per la ricezione dei POST HTTP Di seguito sono riportati i parametri che verranno inviati mediante POST HTTP. I parametri sono : - rcpt - status - time - date - udh - act - return_id rcpt conterrà il numero di telefono. status conterrà lo stato del messaggio. In caso di messaggio correttamente consegnato la notifica sarà del tipo "Delivered (Consegnato)". In caso d'errore verrà restituita una notifica d'errore generica o con una breve descrizione dell'errore, a discrezione degli operatori telefonici. time conterrà l'ora di ricezione del messaggio nel seguente formato hh:mm:ss (Es.: 09:24:55) Nel caso di mancata consegna del messaggio, verrà restituita l'ora di ricezione della notifica d'errore. date conterrà la data di ricezione del messaggio nel seguente formato gg-mmaaaa (Es.: 23-01-2003) Nel caso di mancata consegna del messaggio, verrà restituita la data di ricezione della notifica d'errore.
udh il valore di questo parametro è espresso come numero esadecimale nel seguente modo: udh = aabbcc dove aa : id del messaggio dove bb : numero totale delle parti del messaggio dove cc : parte del messaggio act conterrà il batch_code impostato dal cliente al momento dell'invio. return_id conterrà l identificativo della spedizione, generato dal sistema, da utilizzare nel caso si richieda lo stato della spedizione tramite batch-status (vedi relativo capitolo alla fase di spedizione) Esempio : http://sms.smsmobileba.com/sms/send.php?user=username&pass=password&rcpt=%2b393481234567&data= messaggiodiprova&sender=sms&qty=n&batch_code=1234¬ify_url=http://www.sito. url/script In questo modo, quando il sistema riceverà la DLR la posterà all'url "http://www.sito.url/script". Questo è un esempio di parametri che si riceverà in POST per il precedente messaggio: [status] => Delivered (Consegnato) [time] => 16:45:06 [date] => 2012-06-28 [act] => 1234 [udh] => [return_id] => 36377013 [rcpt] => +393481234567
8 - Invio multiplo richieste MNC tramite richiesta POST/GET http URL: http://sms.smsmobile-ba.com/sms/mnc.php Parametri autenticazione: user Login cliente pass Password cliente Parametri obbligatori: numbers Elenco numeri nel formato internazionale +XXYYYZZZZZZ, separati da virgola. Parametri opzionali: return_id Se impostato uguale a 1 verrà restituito l identificativo della spedizione da utilizzare nel caso si richieda lo stato della spedizione tramite post/get http (es. HTTP00000000111). Il server risponderà con OK. In caso di errore la risposta del server sarà KO <testo_errore>. Codici errore: KO Accesso non consentito (Utente non abilitato). KO Accesso non consentito (IP non abilitato). KO Parametro <nome parametro> non impostato. KO Il parametro <nome parametro> può contenere al massimo <n> numeri. KO Parametro <nome parametro> non valido.
KO Impossibile accodare le richieste. KO Accesso non consentito. KO Parametri non corretti. ESEMPIO DI RICHIESTA: http://sms.smsmobileba.com/sms/mnc.php?user=username&pass=password&numbers=%2b3934 81234567,%2b393331234567&return_id=1
8.1 - Controllo stato MNC tramite richiesta POST/GET http Url: http://sms.smsmobile-ba.com/sms/batch-status.php Parametri autenticazione: user Login cliente pass Password cliente Parametri obbligatori: id Identificativo della spedizione (request_id specificato al momento dell invio della richiesta) type Tipo di report desiderato ( notify stato delle notifiche dei messaggi inviati) ( queue stato accodamento sms) ( mnc stato mnc) schema Schema del report ( 1 solo codice errore) ( 2 codice di errore specifico) Il server risponderà con i dati del report richiesto on formato CVS con i campi separati da virgola, dove la prima riga conterrà i nomi delle colonne. In caso di errore la risposta del server sarà KO <testo_errore>.
Codici errore: KO Accesso non consentito (Utente non abilitato). KO Accesso non consentito (IP non abilitato). KO Parametro <nome parametro> non impostato. KO Il parametro <nome parametro> non corretto KO Errore interno KO Accesso non consentito KO Parametri non corretti Esempio: http://sms.smsmobile-ba.com/sms/batchstatus.php?user=username&pass=password&id=http...&type=mnc&sc hema=1 Smsmobile by Cinevision srl Via Paisiello 15/ a 70015 Noci ( Bari ) tel.080 497 30 66 fax 080 214 07 19