A.P.I. - Developer Guide

Transcript

Manuale A.P.I.
application programming interface
versione 1
www.smsend.it
API application programming interface
1
INVENTA. PROGETTA. SVILUPPA. 3
CREAZIONE CLIENTI IN POST HTTP
4
ASSEGNAZIONE CREDITI IN POST HTTP
5
CONTROLLO CREDITI IN POST HTTP
6
CONTROLLO OPERAZIONI BACK-OFFICE IN POST HTTP
7
CREAZIONE E ASSEGNAZIONE RICEZIONE IN POST HTTP
8
Parametri autenticazione I Parametri obbligatori I Parametri opzionali I Codici errore
Parametri autenticazione I Parametri obbligatori I Codici errore
REVOCA SERVIZIO DI RICEZIONE IN POST HTTP
9
ATTIVAZIONE / DISATTIVAZIONE CLIENTI IN POST HTTP
INVIO SINGOLO SMS IN POST HTTP
10
11
12
13
INVIO MULTIPLO SMS IN POST HTTP
INVIO RICHIESTE MULTIPLE MNC IN POST HTTP
CONTROLLO STATO SPEDIZIONI IN POST HTTP
CONTROLLO CREDITI SMS IN POST HTTP
14
16
CONTROLLO MESSAGGI RICEVUTI TRAMITE WEB SERVICE SOAP
17
INVIO MESSAGGI MMS TRAMITE WEB SERVICE SOAP
20
Sintassi I Parametri autenticazione I Parametri obbligatori
Sintassi I Parametri I Richiesta al web service I Risposta web service
API application programming interface 2
INVENTA. PROGETTA. SVILUPPA.
Implementa le funzioni sms, mms nella tua applicazione.
Grazie alle A.P.I. (Application programming interface) di smSend è possibile integrare tutte le funzioni
del nostro software all’interno della tua applicazione, sito web o software.
Collega la tua applicazione ai nostri gateway sms e mms tramite chiamate in:
HTTP POST/GET in PHP o ASP, protocolli SMPP, HTTP, HTTPS, FTP o web service SOAP.
Rendi la tua applicazione sempre più performante ed efficace, risparmia tempo, risorse e denaro per offrire
ai tuoi clienti servizi sempre più completi e innovativi.
Utilizzando le API smSend, ad esempio, ti sarà possibile inviare sms, mms, ricevere sms o mms,
effettuare richieste mnc (mobile number check), spedire messaggi multipli, controllare o assegnare
crediti, visualizzare statistiche e report e molto altro ancora.
Per spedire sms dal tuo sito web o dal tuo applicativo software è anche disponibile una piattaforma
che supporta la tecnologia ActiveX per interfacciarti al gateway sms e mms.
Potrai contare sulla nostra assistenza tecnica e commerciale in qualsiasi momento, manualistica completa
con esempi .
N.B.
L’accesso è limitato ai soli indirizzi IP o subnet abilitati al servizio back-office.
Devi avere un account smSend.
I parametri “user”, “username” o “id” sono visibili all’interno del proprio pannello di controllo nella
scheda “Profilo account” o nella scheda “Rivenditore” (riservato ai soli rivenditori).
L’indirizzo POST URL indicato nelle varie funzioni (http://app.smsend.it/...) è valido solo per funzioni
dedicate ad account direttamente collegati ad smSend (privati, società, multiaccount, agenti e rivenditori),
mentre per utilizzare le API dedicate a clienti dei rivenditori l’indirizzo POST URL varierà a seconda del
DNS indicatoci dal rivenditore stesso.
Creazione clienti in Post HTTP
POST URL: http://app.smsend.it/backoffice/client-add.php
Parametri autenticazione:
smsusername - Login rivenditore (visibile all’interno del proprio account “rivenditore”)
smspassword - Password rivenditore
Parametri obbligatori:
name - Nome del cliente da creare
username - Username per l’accesso al pannello
password - Password per l’accesso al pannello
Parametri opzionali:
email - E-mail del cliente
tpl_id - Identificativo univoco del profilo assegnato
contact - Campo libero “Contatto”
ref_id - Campo libero “Riferimento”
reseller - Può essere impostato a 0 (cliente) o 1 (rivenditore (default)
vhost - Dominio associato al rivenditore, sul quale dovranno loggarsi gli eventuali clienti
In caso di successo il server risponderà con “OK <id>”,
ove <id> è l’identificativo numerico assegnato al nuovo cliente.
In caso di errore la risposta del server sarà “KO <testo_errore>”.
Codici errore:
KO Accesso non consentito.
KO Username o password errati.
KO Parametri non corretti.
KO Parametro name non impostato.
KO Parametro username non impostato.
KO Parametro password non impostato
KO Impossibile creare un rivenditore.
KO Profilo non corretto.
KO Username già esistente.
KO Errore nella creazione.
Assegnazione crediti in Post HTTP
POST URL: http://app.smsend.it/backoffice/credit-add.php
u_id - identificativo univoco del cliente
bill_id - identificativo univoco della tariffa
credit - credito, nel formato 12,3456 o 12.3456
In caso di successo il server risponderà con “OK <id>”,
ove <id> è l’identificativo numerico assegnato al nuovo credito.
Codici errore:
KO Parametro u_id non impostato.
KO Parametro bill_id non impostato.
KO Utente non trovato.
KO Tariffa non corretta.
KO Parametro credit non corretto.
Controllo crediti in Post HTTP
POST URL: http://app.smsend.it/backoffice/credit-get.php
u_id - identificativo univoco del cliente associato al rivenditore.
In caso di successo il server risponderà con “OK <credito>”,
ove <credito> è il corrispettivo in euro del credito disponibile per il cliente,
con 4 cifre decimali e il carattere “.” (punto) come separatore dei decimali (es: 123.4567).
Codici errore:
Controllo operazioni back-office
in Post HTTP
POST URL: http://app.smsend.it/backoffice/userlog-get.php
type - Tipologia di operazione (“credits” assegnazione credito, “recv_add” creazione/assegnazione
servizio di ricezione, “recv_del” revoca del servizio di ricezione)
from - data inizio report
to - data fine report
In caso di successo il server risponderà con un report ,
in cui la prima riga contiene l’intestazione dei campi e le successive i dati.
I campi sono a lunghezza variabile separati da tabulazione e le righe sono terminate dai caratteri <CR><LF>.
Codici errore:
KO Parametro type non impostato.
Creazione e assegnazione ricezione
in Post HTTP
POST URL: http://app.smsend.it/backoffice/recv-add.php
dest - numero di telefono di ricezione
num - numero di codici da creare (massimo 20, default 1)
In caso di successo il server risponderà con “OK <codici>”,
ove <codici> è l’elenco dei codici di condivisione creati, separati da una virgola.
Codici errore:
KO Parametro dest non impostato.
KO Numero di ricezione non corretto.
KO Parametro num non corretto.
KO Il parametro num deve essere <= 20.
KO Errore nella creazione.
Revoca del servizio di ricezione
sms in Post HTTP
POST URL: http://app.smsend.it/backoffice/recv-del.php
dest - numero di telefono di ricezione
sharecode - codice di condivisione da revocare
In caso di successo il server risponderà con “OK”.
Codici errore:
KO Parametro dest non impostato.
KO Parametro sharecode non impostato.
KO Sharecode non associato all’utente specificato.
Attivazione / Disattivazione clienti
in Post HTTP
POST URL: http://app.smsend.it/backoffice/client-status.php
u_id - identificativo univodo del cliente
active - 0 =disattivato / 1 = attivato
In caso di successo il server risponderà con “OK <stato>”,
ove <stato> è l’operazione eseguita (Attivato o Disattivato).
Codici errore:
KO Parametro active non impostato.
Invio singolo SMS in Post HTTP
POST URL: http://app.smsend.it/sms/send.php
user - Login cliente o rivenditore (visibile all’interno del proprio account “rivenditore”)
pass - Password cliente o rivenditore
rcpt - Numero destinatario nel formato internazionale +XXYYYZZZZZZZ
data - testo del messaggio (massimo 160 caratteri).
sender - Mittente del messaggio (max 11 caratteri alfanumerici o numero +XXYYYZZZZZZZ).
qty - Qualità del messaggio: (ll, l, a, h, n – bassa, media, automatica, alta, notifica).
N.B. Il carattere ‘+’ nel parametro rcpt deve essere codificato in esadecimale ‘%2b’ o in ISO
operation - Tipo di messaggio che si intende spedire:
operation - TEXT = messaggio di testo (default);
operation - WAPPUSH = messaggio WapPush;
operation - UCS2 = messaggio con codifica UCS2 (massimo 70 caratteri a 16 bit);
operation - MULTITEXT = messaggio concatenato (massimo 918 caratteri);
operation - MULTIUCS2 = messaggio concatenato con codifica UCS2;
I messaggi UCS2, MULTITEXT e MULTIUCS2 possono essere inviati solo in qualità Alta o Notifica (h o n)
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).
In caso di successo il server risponderà con “OK <costo>”,
ove <costo> è il credito scalato per l’invio del messaggio.
Codici errore:
KO Accesso non consentito (utente non abilitato).
KO Accesso non consentito (IP non abilitato).
KO Parametro <nome_parametro> non impostato.
KO Parametro <nome_parametro> non valido.
KO Il parametro <nome_parametro> può contenere al massimo <n> caratteri.
KO Operatore sconosciuto.
KO Credito insufficiente.
KO Impossibile accodare il/i messaggio/i.
Invio multiplo SMS in Post HTTP
POST URL: http://app.smsend.it/sms/batch.php
rcpt - Elenco numeri destinatarii nel formato internazionale +XXYYYZZZZZZZ separati da virgola.
data - testo del messaggio (massimo 160 caratteri).
sender - Mittente del messaggio (max 11 caratteri alfanumerici o numero +XXYYYZZZZZZZ).
qty - Qualità del messaggio: (ll, l, a, h, n – bassa, media, automatica, alta, notifica).
operation - Tipo di messaggio che si intende spedire:
operation - TEXT = messaggio di testo (default);
operation - WAPPUSH = messaggio WapPush;
operation - UCS2 = messaggio con codifica UCS2 (massimo 70 caratteri a 16 bit);
operation - MULTITEXT = messaggio concatenato (massimo 918 caratteri);
operation - MULTIUCS2 = messaggio concatenato con codifica UCS2;
I messaggi UCS2, MULTITEXT e MULTIUCS2 possono essere inviati solo in qualità Alta o Notifica (h o n)
url - Indirizzo URL al quale si dovrà collegare il cellulare che riceve il messaggio WAPPUSH.
In caso di successo il server risponderà con “OK <costo>”,
ove <costo> è il credito scalato per l’invio dei messaggi.
Codici errore:
KO Il parametro <nome_parametro> può contenere al massimo <n> caratteri.
KO Operatore sconosciuto.
KO Credito insufficiente.
KO Impossibile accodare il/i messaggio/i.
Invio richieste multiple MNC
in Post HTTP
POST URL: http://app.smsend.it/sms/mnc.php
numbers - Elenco numeri nel formato internazionale +XXYYYZZZZZZ, separati da virgola.
In caso di successo il server risponderà con “OK”.
Codici errore:
KO Parametro non corretti.
KO Il parametro <nome_parametro> può contenere al massimo <n> numeri.
KO Impossibile accodare la/e richiesta/e.
Controllo stato spedizioni SMS
in Post HTTP
POST URL: http://app.smsend.it/sms/batch-status.php
id - Identificativo della spedizione (request_id specificato al momento dell’invio della richiesta)
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 (“1” è l’unico schema attualmente supportato).
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.
Codici errore:
KO Parametro <nome_parametro> non corretto.
KO Errore interno.
Esempi risposta dati CSV per controllo stato spedizioni
Esempio di report CSV con parametro “type=queue”:
id,dest,status,status_text
9182,+393209999999,100,Queued
9183,+393339999999,200,Sent
9184,+393409999999,302,Temporary failure
Esempio di report CSV con parametro “type=notify”:
id,dest,status,status_text
9184,+393209999999,100,Waiting
9185,+393339999999,200,Delivered
9186,+393409999999,300,Unknown subscriber
Esempio di report CSV con parametro “type=mnc”:
id,dest,status,netcode,status_text
9186,+393209999999,100,Waiting
9187,+393339999999,200, TIM
9188,+393409999999,300,Unknown subscriber
Controllo crediti SMS in Post
HTTP
POST URL: http://app.smsend.it/sms/credit.php
pass - Password rivenditore
type - Tipo di controllo:
- credit = credito residuo (default)
- n = Notifica
- h o in alternativa hqs = Alta
- a = Automatica
- l = Media
- ll o in alternativa lqs = Bassa
In caso di successo il server risponderà con “OK <valore>”,
ove <valore> è il numero di sms o il credito residuo in euro a seconda del parametro type specificato.
Codici errore:
KO Errore interno.
KO Parametro type non corretto.
Controllo messaggi ricevuti tramite
Web Service SOAP
POST URL: http://(dnsservice).smsend.it/wsdl/?wsdl
Sintassi:
recvList receiveSms( string user, string pass, string rcpt, string sharecode, int messages )
rcpt - Numero di ricezione
sharecode - Codice di condivisione
messages - Numero di messaggi da mostrare
Il server ritornerà l’elenco dei messaggi ricevuti utilizzando il tipo di dati complesso recvList, ovvero un
array di strutture recvSms così composte:
int id - dentificativo univoco del messaggio
string sender - Numero mittente
string text - Testo del messaggio
dateTime date - Data e ora di ricezione
Esempi controllo messaggi ricevuti tramite web service SOAP
Richiesta SOAP
POST /wsdl/index.php HTTP/1.0
Host: (dnsservice).smsend.it
User-Agent: NuSOAP/0.7.2 (1.94)
Content-Type: text/xml; charset=ISO-8859-1
SOAPAction: “urn:receiveSmswsdl#receiveSms”
Content-Length: nnn
<?xml version=”1.0” encoding=”ISO-8859-1”?>
<SOAP-ENV:Envelope
SOAP-ENV:encodingStyle=http://schemas.xmlsoap.org/soap/encoding/
xmlns:SOAP-ENV=http://schemas.xmlsoap.org/soap/envelope/
xmlns:xsd=http://www.w3.org/2001/XMLSchema
xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
xmlns:SOAP-ENC=http://schemas.xmlsoap.org/soap/encoding/
xmlns:tns=”urn:receiveSmswsdl”>
<SOAP-ENV:Body>
<tns:receiveSms xmlns:tns=”urn:receiveSmswsdl”>
<user xsi:type=”xsd:string”>username</user>
<pass xsi:type=”xsd:string”>password</pass>
<rcpt xsi:type=”xsd:string”>+39XXXYYYYYYY</rcpt>
<sharecode xsi:type=”xsd:string”>001</sharecode>
<messages xsi:type=”xsd:string”>10</messages>
</tns:receiveSms>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Esempi controllo messaggi ricevuti tramite web service SOAP
Risposta SOAP in caso di successo:
HTTP/1.1 200 OK
Date: Tue, 22 Nov 2005 16:04:22 GMT
Content-Length: nnn
<SOAP-ENV:Envelope
SOAP-ENV:encodingStyle=http://schemas.xmlsoap.org/soap/encoding/
xmlns:SOAP-ENV=http://schemas.xmlsoap.org/soap/envelope/
xmlns:xsd=http://www.w3.org/2001/XMLSchema
xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
xmlns:SOAP-ENC=http://schemas.xmlsoap.org/soap/encoding/
xmlns:tns=”urn:receiveSmswsdl”>
<SOAP-ENV:Body>
<ns1:receiveSmsResponse xmlns:ns1=”urn:receiveSmswsdl”>
<response xsi:type=”SOAP-ENC:Array”
SOAP-ENC:arrayType=”tns:recvSms[1]”>
<item xsi:type=”tns:recvSms”>
<id xsi:type=”xsd:int”>5678</id>
<sender xsi:type=”xsd:string”>+39XXXYYYYYYY</sender>
<text xsi:type=”xsd:string”>texte du message</text>
<date xsi:type=”xsd:dateTime”>2005-11-22 11:07:02</date>
</item>
</response>
</ns1:receiveSmsResponse>
</SOAP-ENV:Body>
Invio messaggi mms tramite Web
Service SOAP
POST URL: http://(dnsservice).smsend.it/sms-gw/?wsdl
Il dnsservice verrà abilitato solo su richiesta:
richiamare il metodo sendMms con i parametri specificati alla voce “Input”
Input:
string sendMms ( string id, string password, string ticket, string subject, string text, string rcpt, [
base64Binary imagedata ], [ base64Binary sounddata ] )
Id:
è un parametro obbligatorio. l’Id verrà rilasciato dal personale tecnico smSend.
password:
è un parametro obbligatorio se l’autenticazione associata all’ account e’ di tipo plain-password. Il suo
valore deve essere la password dell’account utilizzando fornita da smSend.
ticket:
è un parametro obbligatorio se l’autenticazione associata all’ account è di tipo MD5.
Usato come token di autenticazione. Il valore del ticket deve essere ricavato applicando la funzione hash
MD5 (con output in esadecimale, lowercase) alla stringa risultante dalla concatenazione dei parametri: id,
rcpt, subject, text, password.
Il valore del parametro password viene fornito all’atto dell’attivazione dell’account.
L’autenticazione è soddisfatta se l’hash MD5 ricalcolato dal gateway sui parametri ricevuti e la copia
locale della password, è uguale al ticket ricevuto.
subject:
è un parametro obbligatorio. Contiene l’oggetto del messaggio e può avere lunghezza massima di 25
caratteri.
text
è un parametro obbligatorio. Contiene il testo del messaggio e può avere lunghezza massima di 2400
caratteri.
rcpt:
è un parametro obbligatorio. Indica il numero o i numeri del terminale mobile a cui spedire il messaggio,
secondo il formato internazionale +JJxxxyyyzzkk (Es.: +393112224455).
Nel caso di invio multiplo, i numeri devono essere separati da una virgola
(Es.: “+393112224455,+393114445566,+393229998877”).
imagedata:
è un parametro opzionale. Deve contenere i dati dell’immagine da inserire nel messaggio.
I formati supportati sono JPEG, GIF e PNG e le dimensioni del file allegato non devono superare i 100
kbyte. Attenzione, il campo è di tipo base64Binary e deve essere composto dal contenuto del file di
immagine codificato tramite l’algoritmo base64.
sounddata:
è un parametro opzionale. Deve contenere i dati del file audio da inserire nel messaggio.
I formati supportati sono MIDI e MP3 e le dimensioni del file allegato non devono superare i 100
kbyte. Attenzione, il campo è di tipo base64Binary e deve essere composto dal contenuto del file audio
codificato tramite l’algoritmo base64.
videodata:
è un parametro opzionale. Deve contenere i dati dell’video da inserire nel messaggio.
I formati supportati sono MOV e 3GP e le dimensioni del file allegato non devono superare i 100 kbyte.
Attenzione, il campo è di tipo base64Binary e deve essere composto dal contenuto del file video codificato
tramite l’algoritmo base64.
OUTPUT:
La transazione ritorna una variabile response di tipo stringa contenente il credito sottratto per la
spedizione espresso in decimillesimi di euro. Se l’inoltro non è andato a buon fine verrà ritornata una
struttura Fault contenente il codice e la descrizione dell’errore verificatosi.
Codici di errore:
KO 101 not allowed
KO 102 operation not permitted
KO 103 bad recipient
KO 104 not allowed
KO 105 not allowed
KO 106 not allowed
KO 107 no auth suitable
KO 109 carrier problem
KO 110 Msg Blocked
KO 111 banned
KO 124 text too long
KO 211 quota_abs reached (credito non disponibile)
KO 213 quota_ny reached (notifiche non disponibili)
KO 215 Image file cannot be bigger than 100kB
KO 216 Image file type not supported
KO 217 Sound file bigger than 100kB
KO 218 Sound file type not supported
KO 300 System (Internal Error)
KO 301 (Connection Problem)
KO 302 (Generic Error)
KO 303 (Connection Problem)
KO 310 type unsupported
KO 311 send error
KO 400 (Internal Error)
KO 500 ERROR (Internal Error)
KO 501 ERROR (Internal Error)
KO 555 Relay Error
Esempi invio messaggi mms tramite web service SOAP
Richiesta di invio MMS con immagine e password in chiaro
(autenticazione basata sull’IP)
POST /sms-gw/index.php HTTP/1.0
Host: (dnsservice).smsend.it
“urn:sendMmswsdl#sendMms”
Content-Length: 1377
<SOAP-ENV:Envelope
SOAP-ENV:encodingStyle=”http://schemas.xmlsoap.org/soap/encoding/”
xmlns:SOAP-ENV=”http://schemas.xmlsoap.org/soap/envelope/”
xmlns:xsd=”http://www.w3.org/2001/XMLSchema”
xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xmlns:SOAP-ENC=”http://schemas.xmlsoap.org/soap/encoding/”
xmlns:tns=”urn:sendMmswsdl”>
<SOAP-ENV:Body>
<tns:sendMms xmlns:tns=”urn:sendMmswsdl”>
<id xsi:type=”xsd:string”>C00000_001</id>
<password xsi:type=”xsd:string”>password</password>
<ticket xsi:type=”xsd:string”></ticket>
<subject xsi:type=”xsd:string”>Oggetto</subject>
<text xsi:type=”xsd:string”>Testo dell'MMS</text>
<rcpt xsi:type=”xsd:string”>+393477005440</rcpt>
<imagedata
xsi:type=”xsd:base64Binary”>R0lGODlhEAAQANUAAAA(...)</imagedata>
<sounddata xsi:nil=”true” xsi:type=”xsd:base64Binary”/>
</tns:sendMms>
</SOAP-ENV:Body>
Risposta del webservice in caso di invio con successo:
HTTP/1.1 200 OK
Content-Length: 512
<SOAP-ENV:Envelope
xmlns:SOAP-ENC=”http://schemas.xmlsoap.org/soap/encoding/”>
<SOAP-ENV:Body>
<ns1:sendMmsResponse xmlns:ns1=”urn:sendMmswsdl”>
<response xsi:type=”xsd:int”>3700</response>
</ns1:sendMmsResponse>
</SOAP-ENV:Body>
Risposta del webservice in caso di invio fallito:
HTTP/1.1 500 Internal Server Error
Status: 500 Internal Server Error
Content-Length: 663
<SOAP-ENV:Envelope
xmlns:SOAP-ENC=”http://schemas.xmlsoap.org/soap/encoding/”>
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode xsi:type=”xsd:string”>KO 211</faultcode>
<faultactor xsi:type=”xsd:string”></faultactor>
<faultstring xsi:type=”xsd:string”>quota_abs reached</faultstring>
<detail xsi:type=”xsd:string”></detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>

A.P.I. - Developer Guide

Transcript

Documenti analoghi

Esame di Sicurezza delle Architetture Orientate ai Servizi

Esposizione servizi di consultazione

Disposizioni per la sicurezza e l`utilizzo degli strumenti informatici

COMUNE CASTELVETERE SUL CALORE

procedura per il ritiro viglietta-vuemme

Configurare la casella sul proprio client mail

PINNACLE SYSTEMS - Dazzle

Winsor Harmon - Cannizzo Management

Web Semantico

comune di castiglione falletto-diano d`alba-grinzane c-roddino