Introduzione e nota sulle connessioni sicure

Transcript

Documento: gateway.pdf
Data ultima rev.: 09/12/2010
Versione: 1.8
Organizzazione: Mobile Solution Srl
Sommario
Introduzione e nota sulle connessioni sicure .......................................................................................... 2
API base – Invio singolo / Credito ....................................................................................................................... 2
SOAP ......................................................................................................................................................................................... 2
REST ......................................................................................................................................................................................... 2
HTTP ......................................................................................................................................................................................... 4
Credito residuo ....................................................................................................................................................................... 4
API avanzate - Invio multiplo ............................................................................................................................... 5
HTTP ......................................................................................................................................................................................... 5
REST ......................................................................................................................................................................................... 5
SOAP ......................................................................................................................................................................................... 5
Charset ....................................................................................................................................................................... 7
Personalizzazione mittente .................................................................................................................................... 7
Codici di errore ........................................................................................................................................................ 7
Ricezione notifiche ........................................................................................................................................ 8
Mobile Solution s.r.l
[email protected] - www.skebby.it
Introduzione e nota sulle connessioni sicure
E’ possibile accedere al gateway attraverso l’utilizzo di un Webservice oppure effettuando delle semplici
richieste HTTP
Per il normale utilizzo del sistema è possibile utilizzare delle connessioni standard su HTTP, qualora fosse
necessario è possibile utilizzare anche il protocollo HTTPS, gli indirizzi base a cui risponde il gateway sono:


HTTP: http://gateway.skebby.it/
HTTPS: https://secure.skebby.it/gw/
Per utilizzare il protocollo HTTPS negli indirizzi va quindi l’inizio della URL da “http://gateway.skebby.it/”
a “https://secure.skebby.it/gw/“, per semplicità tutte le URL presenti di seguito in questo documento sono
state indicate solo con “http://gateway.skebby.it/”
API base – Invio singolo / Credito
I metodi e i parametri per inviare gli SMS con le API di base hanno gli stessi nomi sia per l’interfaccia
REST che per l’interfaccia SOAP, cambia solo il formato dei dati relativi allo specifico protocollo e la URL
a cui collegarsi:
SOAP
Il file wsdl con la descrizione dei metodi è disponibile a questo indirizzo:
http://gateway.skebby.it/api/send/smseasy/simple_soap.php?wsdl
REST
I parametri delle richieste REST devono essere passati con metodo GET o POST a questo indirizzo:
http://gateway.skebby.it/api/send/smseasy/simple_rest.php
Metodo (parametro
method per REST)
get_credit
Parametri
Restituisce credito e il numero di SMS residui
Parametri obbligatori:
 username (username con cui ci si è registrati)
 password (password con cui ci si è registrati)
Parametri opzionali
 charset (si veda nota sull’utilizzo del charset)
send_sms_basic
Invia un SMS Basic e restituisce il numero di SMS residui
 recipient (destinatario, in forma internazionale senza + o 00, ad
esempio: 393334455666)
 text (messaggio da spedire, lunghezza massima 1404 caratteri “9 SMS”)
Parametri opzionali
 charset (si veda nota sull’utilizzo del charset)
send_sms_classic
Invia un SMS Classic e restituisce il numero di SMS residui
esempio: 393334455666)
Parametri opzionali
 sender_number (permette di specificare un qualsiasi numero di
telefono come mittente, il numero deve essere in formato internazionale
senza + o 00, ad esempio: 393334455666)

sender_string (permette di specificare una stringa alfanumerica di
lunghezza massima 11 caratteri da utilizzare come mittente), caratteri
supportati:
[a-zA-Z0-9 .]

charset (si veda nota sull’utilizzo del charset)
Per l’utilizzo dei parametri sender_number e sender_string si veda la nota
relativa alla personalizzazione del mittente in fondo al documento.
send_sms_classic_report Invia un SMS Classic con Notifica e restituisce il numero di SMS residui e il
codice identificativo (id) dell’SMS
esempio: 393334455666)
Parametri opzionali
telefono come mittente, il numero deve essere in formato internazionale
senza + o 00, ad esempio: 393334455666)

lunghezza massima 11 caratteri da utilizzare come mittente)), caratteri
supportati:
[a-zA-Z0-9 .]

charset (si veda nota sull’utilizzo del charset)
Per l’utilizzo dei parametri sender_number e sender_string si veda la nota
relativa alla personalizzazione del mittente in fondo al documento.
HTTP
I parametri devono essere passati con metodo POST o GET, prima di inviare i dati al server assicurarsi che
tutti i dati rispettino lo standard urlencode, ad esempio il testo: “Ci vediamo stasera?” dovrà essere
codificato con: “Ci+vediamo+stasera%3F” inoltre il numero di telefono es: “+393334455666” dovrà essere
codificato con: “%2b393334455666”
La URL a cui inviare le richieste è:
http://gateway.skebby.it/send.php
 recipient (destinatario, nella forma internazionale +393334455666)
 text (messaggio da spedire)
Parametri opzionali per la gestione del mittente
 nosender (per inviare un SMS basic ovvero senza mittente, impostare questo valore a 1)
 senderNumber (permette di specificare un qualsiasi numero di telefono come mittente, il numero
deve essere in formato internazionale senza + o 00, ad esempio: 393334455666)
 senderString (permette di specificare una stringa alfanumerica di lunghezza massima 11 caratteri da
utilizzare come mittente)
 deliveryReport (impostando questo valore è possibile richiedere la notifica di avvenuta consegna
degli SMS, nella risposta verrà restituito l’identificativo)
Per l’utilizzo dei parametri sender_number e sender_string si veda la nota relativa alla personalizzazione
del mittente in fondo al documento.
Credito residuo
L’indirizzo per richiedere il credito è:
http://gateway.skebby.it/get_credit.php
API avanzate - Invio multiplo
I metodi e i parametri per inviare gli SMS con le API avanzate hanno gli stessi nomi sia per l’interfaccia
SOAP, REST e HTTP, cambiano solo il formato dei dati relativi allo specifico protocollo e la URL a cui
collegarsi. Il limite massimo destinatari che si possono inserire per un invio multiplo sono 50.000, per poter
effettuare invii fino a 100.000 destinatari inviare una mail a [email protected]
HTTP
I parametri devono essere passati con metodo POST, prima di inviare i dati al server assicurarsi che tutti i
dati rispettino lo standard urlencode, ad esempio il testo: “Ci vediamo stasera?” dovrà essere codificato
con: “Ci+vediamo+stasera%3F” (è stato disabilitato il metodo GET perché con tanti destinatari la richiesta
potrebbe essere troncata).
L’indirizzo per inviare un SMS è:
http://gateway.skebby.it/api/send/smseasy/advanced/http.php
REST
I parametri delle richieste REST devono essere passati con metodo POST a questo indirizzo (è stato
disabilitato il metodo GET perché con tanti destinatari la richiesta potrebbe essere troncata)
http://gateway.skebby.it/api/send/smseasy/advanced/rest.php
SOAP
Il file wsdl con la descrizione dei metodi è disponibile a questo indirizzo:
http://gateway.skebby.it/api/send/smseasy/advanced/soap.php?wsdl
Metodo (parametro method
per REST o HTTP)
send_sms_basic
Parametri
Invia un SMS Basic e restituisce il numero di SMS residui
 recipients (destinatario/i, in forma internazionale senza + o 00, ad
esempio: 393334455666, 393334455667)
 HTTP: formattazione con []
Esempio:
recipients[]=393334455666&recipients[]=393334455667
 REST: Array JSON
Esempio:
recipients = [ 393334455666 , 393271430773 ];
 SOAP: Array di Stringhe
 text (messaggio da spedire, lunghezza massima 1404 caratteri “9
SMS”)
Parametri opzionali
 charset (vedi nota sull’utilizzo del charset)
send_sms_classic
Invia un SMS Classic e restituisce il numero di SMS residui
 recipients (destinatari, in forma internazionale senza + o 00, ad
esempio: 393334455666, 393334455667)
 HTTP: formattazione con []
Esempio:
Esempio:
recipients = [ 393334455666 , 393271430773 ];
 text (messaggio da spedire, lunghezza massima 459 caratteri “3
SMS”)
Parametri opzionali
telefono come mittente, il numero deve essere in formato
internazionale senza + o 00, ad esempio: 393334455666)

lunghezza massima 11 caratteri da utilizzare come mittente),
caratteri supportati:
[a-zA-Z0-9 .]

charset (vedi nota sull’utilizzo del charset)
Per l’utilizzo dei parametri sender_number e sender_string si veda la
nota relativa alla personalizzazione del mittente in fondo al documento.
send_sms_classic_report
Invia un SMS Classic con Notifica e restituisce il numero di SMS residui e
il codice identificativo (id) della spedizione.
 recipients (destinatari, in forma internazionale senza + o 00, ad
esempio: 393334455666)
Esempio:
recipients = [ 393334455666 , 393271430773 ];
 HTTP: Array
Esempio:

text (messaggio da spedire, lunghezza massima 459 caratteri “3
SMS”)
Parametri opzionali
telefono come mittente, il numero deve essere in formato
internazionale senza + o 00, ad esempio: 393334455666)

lunghezza massima 11 caratteri da utilizzare come mittente)),
caratteri supportati:
[a-zA-Z0-9 .]

charset (vedi nota sull’utilizzo del charset)
Per l’utilizzo dei parametri sender_number e sender_string si veda la
nota relativa alla personalizzazione del mittente in fondo al documento.
Charset
In caso di richiesta SOAP il parametro charset NON deve essere specificato e verrà ignorato.
Per i protocolli HTTP e REST, il parametro charset può essere impostato con uno dei seguenti valori:
ISO-8859-1 (Valore di default)
UTF-8
Personalizzazione mittente
Per motivi di sicurezza l’utilizzo dei parametri (senderNumber e senderString) è abilitato solamente agli
utenti che hanno verificato il proprio numero di cellulare sul sito altrimenti questi valori sono ignorati.
Se vengono specificati contemporaneamente verrà utilizzato il valore contenuto in “senderString”.
Per verificare e modificare il proprio numero di telefono sul sito è possibile utilizzare questo indirizzo:
http://www.skebby.it/user/verified-numbers/sender-id/
Codici di errore
Codice di errore
10
11
12
20
Significato
Errore generico
Charset non valido
Qualche parametro obbligatorio non è stato specificato
Parametri non validi
21
22
23
24
25
26
27
28
30
Username o password non validi
Mittente non valido
Mittente troppo lungo (oltre gli 11 caratteri)
Testo troppo lungo
Destinatario non valido
Mittente non impostato
Troppi destinatari
Destinatari duplicati: non è possibile inserire due o più volte lo stesso
numero
Credito insufficiente per inviare il messaggio
Ricezione notifiche
E’ possibile ricevere la notifica sullo stato dell’invio dell’sms inviandoci una email a [email protected]
specificando l’url da chiamare e il tipo di richiesta che si desidera (GET/POST/REST/SOAP)
I parametri inviati all’URL specificato sono:
 String smsID (numero identificativo della spedizione)
 String messageID (numero identificativo del singolo SMS)
 String destination (numero di telefono a cui è stato inviato l’SMS)
 String smsStatus (codice della notifica)
Per le richieste SOAP/REST dovrà essere implementato un metodo chiamato “notify” con argomenti:
 String smsID (numero identificativo della spedizione)
 String messageID (numero identificativo del singolo SMS)
 String destination (numero di telefono a cui è stato inviato l’SMS)
 String smsStatus (codice della notifica)
In entrambi i casi, verranno restituiti i seguenti codici per la variabile smsStatus:
Codice
0
1
2
3
4
5
6
7
8
Significato
Errore di ricezione
Consegnato
Errore generico
Numero inesistente
Destinatario irraggiungibile
Destinatario non abilitato
Problemi di rete
Consegna Fallita
Messaggio rifiutato

Introduzione e nota sulle connessioni sicure

Transcript

Documenti analoghi

Gestione email

Inviare SMS con il mittente contraffatto

COME FUNZIONA IL SERVIZIO "SMS ALERT"?

Brochure tecnica

guida all`utilizzo

Hi-Tech Italy | blinko diventa peoplesound, il nuovo social network

2016-189 Francobollo SMS

Skebby opera nel settore dei servizi di messaggistica SMS tramite