MANUALE DI INTEGRAZIONE API DMM (v 2.5)

Transcript

1 MANUALE DI INTEGRAZIONE API DMM (v 2.5) Questo documento contiene le informazioni necessarie per l interfacciamento con il gateway SMS di DMM. Il suo utilizzo è riservato ai clienti che abbiano attivato un account di DMM. Come utilizzare le API 1) HTTP Il gateway SMS della piattaforma DMM 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 DMM 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 (utilizza crediti Top) e sendsmslow (utilizza crediti Low Cost) 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 ID alfanumerico Il nome utente del proprio account DMM. psw 40 caratteri, alfanumerico L hash MD5 della password dell account DMM. 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 UTF-8. I caratteri ammessi sono riportati nell allegato The 7 bit default DESCRIZIONE Il numero, o i numeri (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 DMM. Il testo del messaggio da inviare. alphabet (pag.3) from max 11 caratteri, alfanumerico Opzionale. Il mittente del messaggio. Viene visualizzato sul telefono del destinatario. La stringa specificata deve essere tra quelle autorizzate da AGCOM per l account DMM. 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 DMM. Il mittente non può contenere caratteri accentati. Il parametro viene ignorato se si sta effettuando un invio con crediti Low Cost. 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.

3 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. low booleano, valori ammessi: 1 o true Opzionale (SOLO PER RICHIESTE HTTP). Se indicato e valorizzato, l invio sarà di tipo Low Cost. Esempio: Nome Utente Account DMM: user Password Account DMM: password L hash della password è: md5( password ) = 5f4dcc3b5aa765d61d8327deb882cf99 Richiesta HTTP (metodo GET): &text=sms%20di%20test&from=TheBox Invio Low Cost: &text=sms%20di%20test&low=1 Invio programmato: &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 Invio Low Cost: $risposta = $client->sendsmslow( user, 5f4dcc3b5aa765d61d8327deb882cf99, , sms di test,, , );

5 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 ID alfanumerico Il nome utente del proprio account DMM. psw 40 caratteri, alfanumerico L hash MD5 della password dell account DMM. Può essere facilmente calcolato nella maggior parte dei linguaggi di programmazione usati. Parametri SMS 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, , );

6 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 DMM. Parametri addcontact Di seguito sono elencati i parametri da inserire nelle richieste: Parametri Autenticazione ID alfanumerico Il nome utente del proprio account DMM. psw 40 caratteri, alfanumerico L hash MD5 della password dell account DMM. Può essere facilmente calcolato nella maggior parte dei linguaggi di programmazione usati. Parametri contatti 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 DMM. 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 DMM); custom2: campo custom2 (vedi piattaforma DMM); custom3: campo custom3 (vedi piattaforma DMM); custom4: campo custom4 (vedi piattaforma DMM);

7 customdate1: campo customdate1 (vedi piattaforma DMM; formati dd.mm.yyyy dd/mm/yyyy dd-mm-yyyy); customdate2: campo customdate2 (vedi piattaforma DMM; formati dd.mm.yyyy dd/mm/yyyy dd-mm-yyyy); customdate3: campo customdate3 (vedi piattaforma DMM; 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);

8 $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);

9 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 DMM ( Invia SMS e Crea DB ). Parametri checkcoupon Di seguito sono elencati i parametri da inserire nelle richieste: Parametri Autenticazione ID alfanumerico Il nome utente del proprio account DMM. psw 40 caratteri, alfanumerico L hash MD5 della password dell account DMM. Può essere facilmente calcolato nella maggior parte dei linguaggi di programmazione usati. Parametri SMS coupon 8-11 caratteri, 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);

10 Aggiungere un nuovo account (disponibile solo con SOAP) Attraverso la funzione addaccount disponibile con il webservice SOAP, è possibile aggiungere un nuovo account utente DMM utilizzando un account reseller. Parametri addaccount Di seguito sono elencati i parametri da inserire nelle richieste: Parametri Autenticazione ID alfanumerico Il nome utente del proprio account reseller DMM. psw 40 caratteri, alfanumerico L hash MD5 della password dell account reseller DMM. Può essere facilmente calcolato nella maggior parte dei linguaggi di programmazione usati. Parametri contatti details array JSON Array associativo (chiave => valore), codificato in formato JSON, contenente i dati relativi al nuovo account che si vuole creare (vedi esempi). E possibile indicare i seguenti valori: username: nome utente (da 8 a 20 caratteri, alfanumerica); password: password (da 8 a 25 caratteri, deve contenere almeno un numero ed almeno una lettera); companyname: ragione sociale; vat: partita IVA; taxcode: codice fiscale; name: nome; surname: cognome; sex: sesso; city: città; address: indirizzo; postalcode: CAP (Codice di Avviamento Postale); cellularnumber: numero di cellulare; indirizzo ; predefinedsender: mittente predefinito per gli invii SMS (max 11 caratteri, alfanumerico).

11 Esempio (scritto in PHP5): $client = new SoapClient(" $details['username'] = "thebox"; $details['password'] = "1PassWord1"; $details['companyname'] = "The Box Company"; $details['vat'] = " "; $details['taxcode'] = "RSSMRA85T10A562S"; $details['name'] = "Nome"; $details['surname'] = "Cognome"; $details['sex'] = "M"; $details['city'] = "Milano"; $details['address'] = "via M. Pagano, 63"; $details['postalcode'] = "20145"; $details['cellularnumber'] = " "; $details[' '] = "info@theboxcompany.net"; $details['predefinedsender'] = "TheBox"; $json_details = json_encode($details); $risposta = $client-> addaccount( reseller, 5f4dcc3b5aa765d61d8327deb882cf99,$json_details);

12 Caricare crediti SMS (disponibile solo con SOAP) Attraverso la funzione chargecredits disponibile con il webservice SOAP, è possibile caricare crediti SMS ad un account utente DMM utilizzando un account reseller. Parametri chargecredits Di seguito sono elencati i parametri da inserire nelle richieste: Parametri Autenticazione ID alfanumerico Il nome utente del proprio account reseller DMM. psw 40 caratteri, alfanumerico L hash MD5 della password dell account reseller DMM. Può essere facilmente calcolato nella maggior parte dei linguaggi di programmazione usati. Parametri SMS useraccount 8-25 caratteri, alfanumerico Lo username dell account utente a cui caricare i crediti SMS. amount numerico Il numero di crediti SMS da caricare all account utente. creditstype numerico, valori ammessi: Il tipo di crediti SMS da caricare all account utente, identificati da un valore numerico. 1 = crediti SMS TOP; 2 = crediti SMS Low Cost; 4 = crediti SMS DB Nazionale; description alfanumerico La causale, o la descrizione, della ricarica crediti SMS. Esempio (scritto in PHP5): $client = new SoapClient(" $risposta = $client-> chargecredits( reseller, 5f4dcc3b5aa765d61d8327deb882cf99, user,100,1, ordine SMS N.001 );

13 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 424 Testo del messaggio lungo più di 160 caratteri ER 425 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) ER 446 Non si dispone dei permessi per effettuare l operazione ER 451 Mittente non utilizzabile (delibera AGCOM). Verificare lo stato della richiesta di approvazione nel proprio account DMM. 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 ER 446 Non si dispone dei permessi per effettuare l operazione

14 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 ER 446 addaccount (SOAP) CODICE OK 230 OK 231 ER 431 ER 432 chargecredits (SOAP) CODICE OK 240 ER 441 ER 442 ER 443 ER 444 ER 445 ER 446 ER 447 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 Non si dispone dei permessi per effettuare l operazione DESCRIZIONE Il nuovo account è stato creato correttamente Il nuovo account è stato creato, ma alcuni dati non sono stati inseriti poiché sintatticamente errati Le credenziali di accesso (username e password) indicate per il nuovo account sono sintatticamente errate L account è già esistente DESCRIZIONE La ricarica è stata effettuata correttamente Parametro useraccount non specificato Parametro amount non specificato Parametro creditstype non specificato o errato I crediti dell account reseller non sono sufficienti per effettuare la ricarica L account utente indicato non esiste Non si dispone dei permessi per effettuare l operazione L account utente non dispone dei permessi per effettuare l operazione

15

16

17

18

19

20