MANUALE DI INTEGRAZIONE API SMSSmart (v 2.2)

Transcript

1 MANUALE DI INTEGRAZIONE API SMSSmart (v 2.2) Questo documento contiene le informazioni necessarie per l interfacciamento con il gateway SMS di SMSSmart. Il suo utilizzo è riservato ai clienti che abbiano attivato un account di SMSSmart. Come utilizzare le API 1) HTTP Il gateway SMS della piattaforma SMSSmart permette l invio di messaggi di testo utilizzando il protocollo HTTP (Hyper Text Transfer Protocol). La richiesta di invio può essere effettuata attraverso entrambi i metodi GET e POST. L applicazione è disponibile a questo URL: Fare riferimento al paragrafo Parametri invio SMS per conoscere i dati necessari all invio della richiesta. Su tutti i parametri deve essere effettuato l URL Encoding (RFC 3986). 2) WEBSERVICE SOAP Utilizzando il protocollo SOAP (Simple Object Access Protocol), il gateway SMS della piattaforma SMSSmart permette sia l invio di messaggi di testo che l accesso alle funzionalità avanzate. Il webservice è disponibile a questo URL: L API è descritta dal WSDL all indirizzo: Fare riferimento ai paragrafi successivi per la descrizione dei metodi e gli esempi circa il loro utilizzo.

2 Inviare SMS (disponibile con SOAP e HTTP) Attraverso la funzione sendsms disponibile con il webservice SOAP, o direttamente con richieste HTTP, è possibile inviare uno o più SMS. Parametri invio SMS Di seguito sono elencati i parametri da inserire nelle richieste: Parametri Autenticazione NOME LUNGHEZZA e FORMATO DESCRIZIONE Id alfanumerico Il nome utente del proprio account SMSSmart. psw 40 caratteri, alfanumerico L hash MD5 della password dell account SMSSmart. Può essere facilmente calcolato nella maggior parte dei linguaggi di programmazione usati. Parametri SMS NOME LUNGHEZZA e FORMATO to 9-12 caratteri, numerico. text Es Es Es , max 160 caratteri, alfanumerico. Deve essere codificato in ISO I caratteri ammessi sono riportati nell allegato The 7 bit default alphabet (pag.3) DESCRIZIONE Il numero, o i numeri (max 50, separati da una virgola) di telefono dei destinatari. I numeri devono essere in formato internazionale senza 00 o + iniziale. Se il prefisso viene omesso, verrà inserito il prefisso di default impostato nell account SMSSmart. Il testo del messaggio da inviare from max 11 caratteri, alfanumerico Opzionale. L intestazione del mittente del messaggio. Viene visualizzato sul telefono del destinatario. Se non viene specificato o si valorizza con la stringa vuota, o nel caso in cui si sta utilizzando la programmazione dell invio (parametri date e time), il messaggio viene inviato con il mittente di default impostato nell account SMSSmart. Il mittente non può contenere caratteri accentati. date 10 caratteri, formato dd.mm.yyyy Opzionale (invio programmato). Il giorno, completo di mese ed anno, in cui si desidera programmare l invio. Se non viene specificato o si valorizza con la stringa vuota, il messaggio viene inviato immediatamente time 5 caratteri, formato hh.mm Opzionale. Obbligatorio se è stato valorizzato il parametro date (invio programmato). L ora in cui si desidera programmare l invio. Il valore delle ore (hh) è compreso nell intervallo da 00 a 23. Il valore dei minuti (mm) è compreso nell intervallo da 00 a 59.

3 Esempio: Nome Utente Account SMSSmart: user Password Account SMSSmart: password L hash della password è: md5( password ) = 5f4dcc3b5aa765d61d8327deb882cf99 Richiesta HTTP (metodo GET): 7&text=sms%20di%20test&from=TheBox Invio programmato: 7&text=sms%20di%20test&from=TheBox&date= &time=12.00 Richiesta SOAP (scritta in PHP5): $client = new SoapClient(" $risposta = $client->sendsms( user, 5f4dcc3b5aa765d61d8327deb882cf99, , sms di test, TheBox,, ); Invio programmato: $risposta = $client->sendsms( user, 5f4dcc3b5aa765d61d8327deb882cf99, , sms di test, TheBox, , );

4 Conoscere lo stato di un SMS inviato (disponibile solo con SOAP) Attraverso la funzione statussms disponibile con il webservice SOAP, è possibile conoscere lo stato di trasmissione di ogni singolo SMS. Parametri statussms Di seguito sono elencati i parametri da inserire nelle richieste: Parametri Autenticazione NOME LUNGHEZZA e FORMATO DESCRIZIONE Id alfanumerico Il nome utente del proprio account SMSSmart. psw 40 caratteri, alfanumerico L hash MD5 della password dell account SMSSmart. Può essere facilmente calcolato nella maggior parte dei linguaggi di programmazione usati. Parametri SMS NOME LUNGHEZZA e FORMATO DESCRIZIONE msgid alfanumerico L identificativo univoco dell invio di cui si desidera richiedere lo stato (viene restituito dal sistema come risposta della richiesta di invio). to 9-12 caratteri, numerico Es Es Il numero di telefono del destinatario. Insieme al msgid, identificano univocamente un singolo SMS. I numeri devono essere in formato internazionale senza 00 o + iniziale. Esempio (scritto in PHP5): $client = new SoapClient(" $risposta = $client->statussms( user, 5f4dcc3b5aa765d61d8327deb882cf99, , );

5 Aggiungere contatti in rubrica (disponibile solo con SOAP) Attraverso la funzione addcontact disponibile con il webservice SOAP, è possibile aggiungere contatti alla rubrica collegata al proprio account SMSSmart. Parametri addcontact Di seguito sono elencati i parametri da inserire nelle richieste: Parametri Autenticazione NOME LUNGHEZZA e FORMATO DESCRIZIONE Id alfanumerico Il nome utente del proprio account SMSSmart. psw 40 caratteri, alfanumerico L hash MD5 della password dell account SMSSmart. Può essere facilmente calcolato nella maggior parte dei linguaggi di programmazione usati. Parametri contatti NOME LUNGHEZZA e FORMATO DESCRIZIONE to 9-12 caratteri, numerico. Es Es Es , Il numero, o i numeri (separati da una virgola) di telefono dei contatti da inserire in rubrica. I numeri devono essere in formato internazionale senza 00 o + iniziale. Se il prefisso viene omesso, verrà inserito il prefisso di default impostato nell account SMSSmart. Se i contatti sono già presenti in rubrica, vengono aggiornati i dati con quelli indicati nel parametro details. details array JSON Array associativo (chiave => valore), codificato in formato JSON, contenente i dati relativi al/ai contatto/i che si vuole aggiungere (vedi esempi). E possibile indicare i seguenti valori: name: nome; surname: cognome; sex: sesso; birthdate: data di nascita (formati dd.mm.yyyy dd/mm/yyyy dd-mm-yyyy); city: città; address: indirizzo; cap: CAP (Codice di Avviamento Postale); indirizzo ; custom1: campo custom1 (vedi piattaforma SMSSmart); custom2: campo custom2 (vedi piattaforma SMSSmart); custom3: campo custom3 (vedi piattaforma SMSSmart); custom4: campo custom4 (vedi piattaforma SMSSmart); customdate1: campo customdate1 (vedi piattaforma SMSSmart; formati dd.mm.yyyy dd/mm/yyyy dd-mm-yyyy); customdate2: campo customdate2 (vedi piattaforma SMSSmart; formati dd.mm.yyyy

6 dd/mm/yyyy dd-mm-yyyy); customdate3: campo customdate3 (vedi piattaforma SMSSmart; formati dd.mm.yyyy dd/mm/yyyy dd-mm-yyyy); groups: il nome del gruppo, o i gruppi (separati da una virgola) della rubrica nel quale salvare il contatto. Se il gruppo non esiste verrà creato, altrimenti il contatto sarà aggiunto al gruppo esistente. Esempio (scritto in PHP5): $client = new SoapClient(" $details[0]['name'] = "Nome"; $details[0]['surname'] = "Cognome"; $details[0]['sex'] = "M"; $details[0]['birthdate'] = " "; $details[0]['city'] = "Milano"; $details[0]['address'] = "via M. Pagano, 63"; $details[0]['cap'] = "20145"; $details[0][' '] = "info@theboxcompany.net"; $details[0]['custom1'] = "custom1"; $details[0]['custom2'] = "custom2"; $details[0]['custom3'] = "custom3"; $details[0]['custom4'] = "custom4"; $details[0]['customdate1'] = " "; $details[0]['customdate2'] = "25/01/2010"; $details[0]['customdate3'] = " "; $details[0]['groups']="gruppo A,Gruppo B"; $json_details = json_encode($details); $risposta = $client->addcontact( user, 5f4dcc3b5aa765d61d8327deb882cf99, ,$json_details);

7 $details[0]['name'] = "Nome"; $details[0]['surname'] = "Cognome"; $details[0]['sex'] = "M"; $details[0]['birthdate'] = " "; $details[0]['city'] = "Milano"; $details[0]['address'] = "via M. Pagano, 63"; $details[0]['cap'] = "20145"; $details[0][' '] = "info@theboxcompany.net"; $details[0]['custom1'] = "custom1"; $details[0]['custom2'] = "custom2"; $details[0]['custom3'] = "custom3"; $details[0]['custom4'] = "custom4"; $details[0]['customdate1'] = " "; $details[0]['customdate2'] = "25/01/2010"; $details[0]['customdate3'] = " "; $details[0]['groups']="gruppo A"; $details[1]['name'] = "Nome2"; $details[1]['surname'] = "Cognome2"; $details[1]['sex'] = "F"; $details[1]['birthdate'] = " "; $details[1]['city'] = "Milano"; $details[1]['address'] = "via M. Pagano, 63"; $details[1]['cap'] = "20145"; $details[1][' '] = "office@theboxcompany.net"; $details[1]['custom1'] = "custom1"; $details[1]['custom2'] = "custom2"; $details[1]['custom3'] = "custom3"; $details[1]['custom4'] = "custom4"; $details[1]['customdate1'] = " "; $details[1]['customdate2'] = "25/01/2010"; $details[1]['customdate3'] = " "; $details[1]['groups']="gruppo B,Gruppo C"; $json_details = json_encode($details); $risposta = $client->addcontact( user, 5f4dcc3b5aa765d61d8327deb882cf99, , , $json_details);

8 Consultare la validità di un codice coupon (disponibile solo con SOAP) Attraverso la funzione checkcoupon disponibile con il webservice SOAP, è possibile consultare l esistenza e la validità di un codice coupon, generato ed inviato via SMS con gli strumenti della piattaforma SMSSmart ( Invia SMS e Crea DB ). Parametri checkcoupon Di seguito sono elencati i parametri da inserire nelle richieste: Parametri Autenticazione NOME LUNGHEZZA e FORMATO DESCRIZIONE Id alfanumerico Il nome utente del proprio account SMSSmart. psw 40 caratteri, alfanumerico L hash MD5 della password dell account SMSSmart. Può essere facilmente calcolato nella maggior parte dei linguaggi di programmazione usati. Parametri SMS NOME LUNGHEZZA e FORMATO DESCRIZIONE coupon 8-11 carateri, numerico, Il codice del coupon da verificare. formato nnn-nnnnnn Es Es use booleano Se impostato a true, oltre a verificare la validità del codice, si richiede l annullamento dello stesso. Nelle successive verifiche, il codice risulterà valido ma già utilizzato. Esempio (scritto in PHP5): $client = new SoapClient(" $risposta = $client->checkcoupon( user, 5f4dcc3b5aa765d61d8327deb882cf99, ,false); $risposta = $client->checkcoupon( user, 5f4dcc3b5aa765d61d8327deb882cf99, ,true);

9 Risposte e codici di errore Il gateway risponde ad ogni richiesta, sia HTTP che SOAP, indicando l esito o la presenza di eventuali errori. Invio SMS (HTTP, SOAP) CODICE DESCRIZIONE OK 200 msgid Il messaggio è stato inviato correttamente. Viene restituito l identificativo univoco dell invio (es: OK ). Questo valore è necessario per conoscere lo stato di trasmissione dell SMS, utilizzando l apposita procedura OK 201 Il messaggio è stato programmato correttamente per la data e l ora specificati ER 400 Si è verificato un errore durante l invio del messaggio ER 401 Errore di autenticazione. Nome utente o password non corretti ER 402 L utente non ha credito sufficiente per l invio del messaggio ER 403 La data e l ora indicati sono antecedenti rispetto al momento in cui si effettua la richiesta ER 411 Parametro id non specificato ER 412 Parametro psw non specificato ER 413 Parametro to non specificato ER 414 Parametro text non specificato ER 418 Parametro time non specificato ER 423 Sono stati inseriti più di 50 destinatari ER 424 Testo del messaggio lungo più di 160 caratteri ER 425 L intestazione del mittente lungo più di 11 caratteri ER 426 Caratteri non supportati dall alfabeto GSM nel testo del messaggio ER 427 Caratteri non supportati nel mittente del messaggio ER 428 Prefisso Internazionale non gestito ER 433 Errore nel formato del destinatario (to) ER 437 Errore nel formato della data di invio (date) ER 438 Errore nel formato dell ora di invio (time) statussms (SOAP) CODICE DESCRIZIONE OK yyyy-mm-dd hh:mm:ss Il messaggio è stato consegnato sul cellulare del destinatario (vengono indicate la data e l ora di consegna) KO Il messaggio non è stato consegnato (numero errato, telefono spento, assenza di copertura, ecc.) ER 401 Errore di autenticazione. Nome utente o password non corretti ER 411 Parametro id non specificato ER 412 Parametro psw non specificato ER 413 Parametro to non specificato ER 416 Parametro msgid non specificato ER 433 Errore nel formato del destinatario

10 addcontact (SOAP) CODICE OK 210 OK 211 contact1,contact2 OK 212 contact1,contact2 ER 440 checkcoupon (SOAP) CODICE OK 220 OK 221 OK 222 KO ER 415 ER 417 DESCRIZIONE Tutti i contatti sono stati aggiunti in rubrica I contatti sono stati aggiunti in rubrica parzialmente. I contatti restituiti (separati da una virgola) non sono stati aggiunti poiché sintatticamente errati Tutti i contatti sono stati aggiunti in rubrica. I contatti restituiti (separati da una virgola) hanno errori su uno o più valori indicati nel parametro details, che saranno ignorati Tutti i contatti non sono stati aggiunti poiché sintatticamente errati DESCRIZIONE Il coupon è valido e non ancora annullato Il coupon è valido ed è già stato annullato Il coupon è valido ed è stato correttamente annullato Il coupon non è valido Parametro coupon non specificato Parametro use non specificato

11

12

13

14

15

16