Sei sulla pagina 1di 12
DropAPI Application Programming Interface Guida rapida all’integrazione Versione 1.0 – ITA – 15 ottobre 2010
DropAPI Application Programming Interface Guida rapida all’integrazione Versione 1.0 – ITA – 15 ottobre 2010

DropAPI

Application Programming Interface

Guida rapida all’integrazione

Versione 1.0 – ITA – 15 ottobre 2010

A-Tono s.r.l.

Headquarter: Corso Buenos Aires, 77 - 20124 Milano - Tel. +39 02 32069100 - Fax +39 02 32069101 Branch Offices: Via del Chiesino, 10 - 56025 Pontedera (PI) Largo Paisiello, 5 - 95124 Catania

a-tono.com

info@a-tono.com

Sommario

Sommario Avvertenze 4 Requisiti 4 Introduzione 5 DropAPI 6 API: getUserProfile 6

Avvertenze

4

Requisiti

4

Introduzione

5

DropAPI

6

API: getUserProfile

6

Request

6

Response

6

DropOut

8

API: SendSMS

8

Request

8

Response

10

3
Avvertenze Le informazioni contenute in questo documento non adempiono a garanzia di alcuna sorta e

Avvertenze

Le informazioni contenute in questo documento non adempiono a garanzia di alcuna sorta e non possono essere utilizzate quali elementi probanti di eventuali inefficienze o malfunzionamenti nell’erogazione del servizio.

Le informazioni contenute in questo documento possono subire modifiche in qualunque momento senza preavviso.

Si declina ogni responsabilità relativa a un utilizzo del servizio che contravvenga alle leggi vigenti.

L’origine, la destinazione d’uso e il contenuto delle informazioni trasmesse attraverso il servizio in oggetto sono entità di cui l’utilizzatore è consapevole assumersi piena responsabilità.

Marchi di terze parti eventualmente citati sono proprietà dei rispettivi titolari, siano esse persone fisiche o giuridiche.

Requisiti

Per utilizzare il servizio http è necessario disporre di un collegamento alla rete Internet e di hardware e software in grado di funzionare da client HTTP e di inoltrare le richieste il cui contenuto sia XML well- formed.

Introduzione geodrop è un sistema in grado di inoltrare messaggi SMS verso le reti dei

Introduzione

geodrop è un sistema in grado di inoltrare messaggi SMS verso le reti dei gestori italiani ed esteri di telefonia mobile. Avendo un orientamento business to business è stato dotato di una interfaccia XML di comunicazione attraverso la quale è possibile accedere alle sue funzionalità.

Nella versione 3.0 (cui si riferisce il presente documento) è stato abbandonato il supporto ai contenuti binari (presente invece nelle versioni 2.x). Contemporaneamente è stato introdotto il concetto di droplet:

applicazioni che raccolgono tra loro coerentemente le funzionalità di specifici servizi.

Attualmente in geodrop 3.0 sono disponibili 2 droplet:

la DropOut fornisce gli strumenti per gestire una campagna di invio di messaggi;

la DropAPI è la droplet che implementa l’interfaccia XML e permette agli sviluppatori di sfruttare le funzionalità delle altre droplet, integrandole con le proprie applicazioni.

DropAPI Le droplet sono applicazioni che raccolgono tra loro coerentemente le funzionalità di specifici servizi.

DropAPI

Le droplet sono applicazioni che raccolgono tra loro coerentemente le funzionalità di specifici servizi. Le

droplet espongono delle API (application programming interface) per l’accesso alle funzionalità. Quando l’utente accede a tali API, l’autenticazione e l’autorizzazione per l’accesso alle API viene gestito in modo trasparente dalla DropAPI. Se l’autenticazione e l’autorizzazione hanno esito positivo, la chiamata all’API potrà continuare ed essere eseguita dalla droplet competente, diversamente la DropAPI impedirà l’accesso

e restituirà il codice di errore appropriato.

La DropAPI espone anche un’API proprietaria, getUserProfile, per l’accesso al proprio credito

API: getUserProfile

Prima di utilizzare per la prima volta la API getUserProfile della DropAPI è obbligatorio accedere al proprio profilo sul sito web, creare dei sub-account prestando attenzione a fornire tutti i dati richiesti e infine trasferire il necessario credito in drop dal proprio account principale a quello del sub-account.

Request

La chiamata alla API getUserProfile della DropAPI è possibile solo con le credenziali del sub-account (UserID

e password).

La

chiamata

deve

fare

parte

di

una

richiesta

HTTP

autenticata

con

il

paradigma

Basic

(http://www.ietf.org/rfc/rfc2617.txt),

inoltrata

tramite

metodo

POST

(senza

body)

alla

URL

http://api.geodrop.net/dropapi/messaging/users/profile.

Di seguito è riportato un esempio:

POST /dropapi/messaging/users/profile HTTP/1.1 HOST: api.geodrop.net Authorization: BASIC SHRT438Msgber== Content-type: application/x-www-form-urlencoded

La

stringa che segue la parola chiave BASIC deve essere la codifica Base64 della giustapposizione di UserID

e

password, relative al sub-account di cui si desidera avere informazioni, separati da “:”

(< UserIDSubAccount>:< PasswordSubAccount>).

Response

La risposta restituita sarà conforme alla seguente XML Data Type Definition (d’ora in poi DTD):

<?xml version="1.0" ?> <!DOCTYPE GEORESPONSE [ <!ELEMENT GEORESPONSE <!ELEMENT USER <!ATTLIST USER <!ATTLIST USER <!ATTLIST USER <!ATTLIST USER <!ATTLIST USER

]>

(USER)> EMPTY> userid CDATA #REQUIRED> sent CDATA #REQUIRED> account CDATA #REQUIRED> expire CDATA #REQUIRED> credit CDATA #REQUIRED>

L’elemento USER riassume lo stato del sub-account e contiene gli attributi seguenti: • userid :

L’elemento USER riassume lo stato del sub-account e contiene gli attributi seguenti:

userid: identificativo del sub-account;

sent: numero di sms inviati dal sub-account;

account: tipo di account sottoscritto (al momento solo prepaid, ovvero ricaricabile);

credit: indica il credito ancora disponibile per il sub-account.

Utilizzando l’utility curl (per informazioni: http://curl.haxx.se) è possibile testare rapidamente il servizio con una chiamata del tipo:

curl --basic --user "< UserIDSubAccount>:< PasswordSubAccount>" --data "" --url "http://api.geodrop.net/dropapi/messaging/users/profile"

In caso di successo la risposta sarà simile alla seguente:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <GEORESPONSE> <USER userid="<UserIDSubAccount>" sent="0" credit="12.00" account="Prepaid"

expire="2025-09-30"/>

</GEORESPONSE>

DropOut La DropOUT è la droplet nata per inviare SMS. L’invio può avvenire sia tramite

DropOut

La DropOUT è la droplet nata per inviare SMS. L’invio può avvenire sia tramite un’interfaccia grafica accessibile direttamente dal proprio profilo sul sito web, sia tramite API. Prima di utilizzare per la prima volta le API della DropOUT è obbligatorio accedere al proprio profilo sul sito web, creare dei sub-account prestando attenzione a fornire tutti i dati richiesti e infine trasferire il necessario credito in drop dal proprio account principale a quello del sub-account. La chiamata alle API della DropOUT è possibile solo con le credenziali del sub-account.

API: SendSMS

Le funzionalitàdi DropOut disponibili tramite API sono attualmente le seguenti:

Invio di SMS con lunghezza massima 160 caratteri a destinatari multipli (con un limite di 500 destinatari per richiesta);

Invio differito con possibilità di specificare data e ora di spedizione del SMSì;

Impostazione del mittente personalizzato.

Request La chiamata deve fare parte di una richiesta HTTP autenticata con il paradigma Basic, inoltrata tramite

metodo POST alla URL http://api.geodrop.net/dropapi/messaging/sms/send.

POST /dropapi/messaging/sms/send HTTP/1.1 HOST: api.geodrop.net

Authorization: BASIC SHRT438Msgber== Content-type: application/x-www-form-urlencoded

La

stringa che segue la parola chiave BASIC deve essere la codifica Base64 della giustapposizione di UserID

e

password, relative al sub-account che si desidera utilizzare per l’invio dei messaggi, separati da “:”

(< UserIDSubAccount>:< PasswordSubAccount>).

Il body della richiesta (al posto dei ““) deve contenere un XML conforme alla seguente DTD:

<?xml version="1.0" ?> <!DOCTYPE GEOSMS [ <!ELEMENT GEOSMS <!ELEMENT MESSAGE <!ELEMENT TEXT <!ELEMENT TPOA <!ELEMENT LIST <!ELEMENT DEST <!ELEMENT DEFFEREDTIME <!ATTLIST MESSAGE <!ATTLIST DEST

]>

(MESSAGE,LIST,TPOA?,DEFERRED?)> (TEXT)> (#PCDATA)> (#PCDATA)> (DEST+)> EMPTY> (#PCDATA)> content (text) #REQUIRED> msisdn CDATA #REQUIRED >

L’elemento MESSAGE, che deve essere presente, raccoglie le informazioni relative al contenuto del messaggio. L’attributo content indica a geodrop quale classe di contenuti dovrà aspettarsi nell’elemento TEXT (contenuto all’interno dell’elemento MESSAGE. Attualmente è supportato il solo contenuto di tipo testuale, per il quale l’attributo deve essere valorizzato con la stringa “text”).

L’elemento TEXT consiste di una stringa lunga al massimo 160 caratteri. I caratteri ammessi sono

L’elemento TEXT consiste di una stringa lunga al massimo 160 caratteri. I caratteri ammessi sono quelli dello standard GSM 03.38, riportati nella tabella sottostante (fonte:

http://en.wikipedia.org/wiki/GSM_03.38). I simboli individuati dal codice esadecimale 1Bxx occupano 2 caratteri.

dal codice esadecimale 1Bxx occupano 2 caratteri. L’elemento LIST deve contenere tanti elementi DEST

L’elemento LIST deve contenere tanti elementi DEST quanti sono i destinatari del messaggio.

un telefonica nazionale o internazionale valida nei possibili formati:

L’elemento

DEST

individua

destinatario

tramite

l’attributo

347123456

+39347123456

msisdn

che

deve

indicare

un’utenza

L’elemento TPOA, il cui uso è opzionale, consente di personalizzare il mittente del messaggio con una stringa alfanumerica qualunque della lunghezza massima di 11 caratteri (o, in alternativa, fino a 16 cifre numeriche). Se non viene utilizzato questo elemento il mittente utilizzato sarà quello associato al sub- account, indicato al momento della creazione del sub-account sul sito web di geodrop.

ATTENZIONE! Se utilizzato, l’elemento TPOA deve essere posizionato dopo l’elemento TEXT e prima dell’elemento DEFERREDTIME (descritto nel paragrafo seguente).

L’elemento DEFERREDTIME, il cui utilizzo è opzionale, consente di programmare la trasmissione del messaggio in un istante nel futuro. Il deferimento massimo è un parametro della DropOut ed è aumentabile acquistando appositi estensioni.

Un esempio di XML valido, per inviare un SMS a due destinatari, è il seguente:

Un esempio di XML valido, per inviare un SMS a due destinatari, è il seguente:

<?xml version="1.0" standalone="yes"?> <GEOSMS> <MESSAGE content="text"> <TEXT><![CDATA[Con geodrop 3 metti il turbo ai tuoi SMS]]></TEXT> </MESSAGE> <LIST> <DEST msisdn="+393471234567" /> <DEST msisdn="+393351234568" /> </LIST> </GEOSMS>

Per chi utilizza il programma curl per effettuare l’invio riportiamo, a titolo di esempio, il comando relativo all’invio di cui sopra (prima di provare il comando ricordarsi di modificare le credenziali di accesso con quelle del proprio sub-account e i numeri delle utenze destinatarie).

curl --basic --user "< UserIDSubAccount>:< PasswordSubAccount>" --data "<?xml version=\"1.0\" standalone=\"yes\"?><GEOSMS><MESSAGE content=\"text\"><TEXT><![CDATA[Con geodrop 3 metti il turbo ai tuoi SMS]]></TEXT></MESSAGE><LIST><DEST msisdn=\"+393471234567\" /><DEST msisdn=\"+393351234568\" /></LIST></GEOSMS>" --url "http://api.geodrop.net/dropapi/messaging/sms/send"

Response Dopo aver processato la richiesta, geodrop invia una risposta HTTP il cui contenuto è un documento XML conforme alla seguente DTD:

<?xml version="1.0" ?> <!DOCTYPE GEORESPONSE [ <!ELEMENT GEORESPONSE <!ELEMENT USER <!ELEMENT BAD <!ELEMENT REPORT <!ELEMENT OK <!ELEMENT ERROR <!ATTLIST USER <!ATTLIST USER <!ATTLIST USER <!ATTLIST USER <!ATTLIST USER <!ATTLIST REPORT <!ATTLIST REPORT <!ATTLIST BAD <!ATTLIST BAD <!ATTLIST OK <!ATTLIST OK <!ATTLIST ERROR <!ATTLIST ERROR

]>

((USER,REPORT)|(USER,BAD))> EMPTY> EMPTY> (OK+|ERR+|(OK+,ERR+))> EMPTY> EMPTY> userid CDATA #REQUIRED> sent CDATA #REQUIRED> account CDATA #REQUIRED> expire CDATA #REQUIRED> credit CDATA #REQUIRED> requested CDATA #REQUIRED> posted CDATA #REQUIRED> code CDATA #REQUIRED> description CDATA #REQUIRED> msisdn CDATA #REQUIRED> orderid CDATA #REQUIRED> msisdn CDATA #REQUIRED> reason CDATA #REQUIRED>

La risposta contiene:

La risposta contiene: • elemento USER : sempre; • elemento BAD : unicamente nel caso di

elemento USER: sempre;

elemento BAD: unicamente nel caso di errori per i quali non è stato possibile inoltrare il messaggio;

elemento REPORT: se non ci sono stati errori.

geodrop tratta eventuali errori nella richiesta separando gli errori nella formattazione del messaggio o della richiesta stessa da quelli, eventuali, riscontrati nella lista dei destinatari.

Questo perché, se il messaggio è ritenuto valido, geodrop lo inoltrerà a tutti quei destinatari per cui è possibile farlo, accettando di fatto la richiesta, se pur soltando parzialmente.

Tutti i destinatari per i quali l’operazione ha avuto successo saranno elencati in elementi OK, quelli invece per cui non è stato possibile completare la richiesta verranno collocati in elementi ERR.

L’elemento USER è analogo all’omonimo elemento della response descritta per l’API getUserProfile.

L’elemento BAD è presente se si è verificata una condizione di errore tale per cui non è stato possibile esaudire la richiesta dell’utente. Due gli attributi, sempre presenti:

code: codice dell’errore

description: breve descrizione dell’errore indicato

La tabella seguente riporta i possibili codici di errore e le relative descrizioni:

Codice

Descrizione

101

Errore interno al server. La responsabilità non è dell’utente

102

La richiesta http è pervenuta vuota

103

Il documento XML della richiesta non è ben formattato (verificare i tag)

104

Errori nella sintassi dell’elemento MESSAGE

201

L’account dell’utente non soddisfa le condizioni necessarie

301

La lista dei destinatari è vuota

401

Il messaggio di contenuto testuale presenta l’elemento TEXT vuoto

402

Il testo del messaggio eccede la lunghezza massima consentita

403

Il testo del messaggio contiene almeno un carattere non valido

501

Non è stato indicato il contenuto e/o il tipo del messaggio

502

Il tipo indicato è sconosciuto

601

La sintassi dell’elemento DEFERREDTIME è errata

602

La data programmata è una data già passata

603

La data programmata non appartiene all’intervallo consentito

L’elemento REPORT fornisce l’esito dettagliato della transazione ed è presente solo se geodrop è stata in grado di soddisfare, anche solo in parte, la richiesta dell’utente. Contiene sempre 3 attributi:

requested: numero di destinatari richiesto dall’utente

posted: numero di destinatari verso i quali è stato possibile inoltrare il messaggio

drop: numero di crediti necessari per l’invio del messaggio ad ogni singolo destinatario

Il numero di SMS inviati viene conteggiato moltiplicando il numero dei destinatari per i quali

Il numero di SMS inviati viene conteggiato moltiplicando il numero dei destinatari per i quali la trasmissione ha avuto successo per il numero degli SMS necessari alla singola trasmissione (al momento il limite è 1 SMS per messaggio). L’eventuale credito dell’utente verrà decrementato di conseguenza.

L’elemento OK indica il successo dell’acquisizione del messaggio per il singolo destinatario. Contiene sempre 2 attributi:

orderid: codice di identificazione della transazione

msisdn: numero telefonico del destinatario

L’attributo orderid identifica univocamente la transazione nell’ambito della quale è stato trasmesso un messaggio. Può essere utile per eventuali segnalazioni o richieste di supporto.

L’elemento ERROR indica uno di questi 2 possibili errori:

il numero telefonico non ha il formato corretto

il destinatario appartiene all’eventuale sottolista eccedente la massima capacità di invio multiplo di geodrop

e contiene sempre 2 attributi:

msisdn: numero telefonico del destinatario

reason: un numero intero che indica la ragione del fallimento (vedi tabellina sotto)

Reason

Descrizione

1

msisdn nel formato errato

3

Destinatario appartenente alla sottolista in eccesso

5

Errore interno a geodrop (richiedere supporto)

In caso di successo, la risposta ottenuta alla richiesta d’esempio riportata nel paragrafo precedente è simile alla seguente:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <GEORESPONSE> <REPORT requested="2" posted="2"> <OK orderid="63032064-20101011-041135-00001339" msisdn="+393471234567"/> <OK orderid="63032064-20101011-041135-00001339" msisdn="+393351234568"/> </REPORT> <USER userid=" < UserIDSubAccount>" sent="2" credit="93.00" account="Prepaid"/> </GEORESPONSE>