Manuale Gateway SMS. (Versione Documento 2.1) pagina 1 di 5

Transcript

1 Manuale Gateway SMS (Versione Documento 2.1) pagina 1 di 5

2 1. Introduzione Questo documento descrive i diversi metodi e l'uso dell'sms center per trasmettere messaggi SMS con metodo HTTP POST o GET. Il nostro servizio si basa su degli script di richiesta che vengono costruiti con i metodi descritti di seguito negli esempi riportati. I dati per le richieste devono essere trasmessi al nostro gateway attraverso richieste GET o POST via URL. 2. Abilitazione del servizio Per abilitare il servizio API il cliente, deve richiedere l'attivazione, telefonicamente. Nella richiesta dovrà essere specificato il o gli indirizzi IP da attivare sull'account. L'indirizzo IP deve essere di tipo statico. I tempi di abilitazione del servizio sono brevi, solitamente lo stesso giorno in cui la richiesta ci è pervenuta. 3. Composizione dell'url di invio L'URL da richiamare per inviare gli sms è Per utilizzarla bisogna però completarlo con diversi parametri (variabili). Tutte le variabili devono essere urlencoded prima di essere inoltrate al nostro sistema. I parametri base da impostare nell'url di invio sono I seguenti: PARAMETRO DESCRIZIONE TIPO username Nome utente dell'account Obbligatorio - Set type: string password Password dell'account type_user Tipo di account : user route Tipologia gateway di invio, può essere: GW1 per invii senza personalizzazione del mittente GW2 per invii con mittente personalizzato NB: in base al gateway scelto verranno scalati i crediti relativi message Il testo del messaggio da inviare. E' possibile inviare SMS fino a 160 caratteri. to time from flash Il numero/numeri del/dei destinatari. In caso di più destinatari i numeri devono essere separati dalla virgola senza spazi Il numero deve essere riportato con il prefisso internazionale. In caso di più destinatari consigliamo di non eccedere i 100 numeri per richiesta. Specifica data e ora di invio del messaggio. Se viene impostato un valore il messaggio verrà consegnato all'ora specificata. Il formato della data accettato è: Specifica il mittente del messaggio. La personalizzazione del mittente sarà tuttavia possibile solo utilizzando il gateway GW2. E' possibile inserire fino a 11 caratteri per un mittente alfanumerico o fino a 16 caratteri per un mittente solo numerico. Manda un messaggio di tipo Flash. Questo tipo di messaggio appare direttamente sul terminale mobile del destinatario senza che venga aperto. Viene cancellato dalla memoria della SIM alla chiusura se non viene salvato esplicitamente. NB: non tutti i cellulari possono risultare compatibili con questo tipo di messaggi xxxxxxx, aaaa-mm-gg hh:mm:01 /int NomeAzienda 39347xxxxxx Di seguito l'url di esempio completa: username=xxxxx&password=xxxxx&type_user=user&route=xxxxx&message=hello+world&to= %2b39348XXXXX&from=Pippo&time=xxxx-xx-xx+xx:xx:01 pagina 2 di 5

3 4. Parametri opzionali aggiuntivi Oltre ai parametri base esistono altri parametri che servono per personalizzare ulteriormente l'invio con opzioni aggiuntive. Questi parametri aggiuntivi sono disponibili unicamente utilizzando il gateway GW2 definito in route. PARAMETRO DESCRIZIONE TIPO split delivery idrefer returnurl Consente di inviare messaggi maggiori di 160 caratteri. Il sistema si occuperà di calcolare il numero di concatenamenti necessario per ricostruire sul terminale del destinatario l'sms come unico messaggio. Il numero massimo di caratteri inviabile è 816 per un totale di 6 concatenamenti. Per i long message ogni concatenamento consente al massimo 153 caratteri, I restanti servono come dati per la ricostruzione del messaggio. Per ogni concatenamento necessario verrà scalato il relativo credito. Richiesta della ricevuta di ritorno per il messaggio inviato. Permette di ricevere all'url specificata in returnurl lo stato del messaggio inviato. Per dettaglio vedere il punto 5. Indica il riferimento del messaggio. E' un valore impostato dall'utente che verrà reinviato come parametro in returnurl. E' l'url di ritorno per ricevere le ricevute di ritorno dei messaggi inviati con la richiesta di delivery (max 16 caratteri) ( 5. Delivery Report Se sono state specificate le variabili per la ricezione delle delivery all'url indicata in returnurl saranno passate 5 parametri: PARAMETRO DESCRIZIONE idrefer Indica lo stesso valore indicato dall'utente nella richiesta di invio specificato nel parametro idrefer. TIPO Set type: string number E' il numero per il quale è stata richiesta la ricevuta di ritorno Set type: string status Indica lo stato del messaggio. Per dettaglio vedere punto 5.1 Set type: int reason Indica la descrizione dello stato riportato in status Set type: string date Indica la data della ricevuta Set type: unix timestamp 5.1 Descrizione stato delivery report La variabile status contiene lo stato del messaggio per il numero specific ato in number. Questa variabile può assumere due valori 0 o 1. 0: identifica la corretta consegna al numero di cellulare 1: identifica la mancata consegna del messaggio Il mancato recapito di un messaggio a un terminale mobile può dipendere da molteplici fattori. I più comuni risultano da problemi momentanei sulla SIM in questione (memoria SIM piena) a problemi di natura tecnica/strutturale della rete dell'operatore su una particolare cella/e geografica (questo vale per tutti I gateway utilizzati). 6. Charset e caratteri Il charset da utilizzare è latin1 ISO I caratteri accettati sono: []{}^'"&!?()* #@%$ \/=+-_;,:.><A-Za-z0-9àèìòùÉ+ 7. Esempio di script PHP Il seguente esempio è scritto in HTML e PHP, il suo compito è quello di illustrare il possibile utilizzo delle API HTTP pagina 3 di 5

4 Lo script è formato da due files separati, il primo chiamato form.html che si preoccupa dell'inserimento dei dati per effettuare l'invio e un secondo invia.php che si preoccupa di ricevere i dati ed effettuare la richiesta. FILE form.html Questo file ha il compito di raccogliere tutte le variabili necessarie per l'invio del messaggio ed inviarle al file invia.php che elaborerà le variabili e procederà all'invio. <html> <head> <title> Es empio di utilizzo API </title> </head> <body> <form method="post" action="invia.php" name="form1"> <table width="300" cellpadding="0" cellspac ing="0" border="0" style="font-size:11px;"> <td width="50%"> Destinatario ( senza +39 ) <td width="50%" align="right"> <input type="tex t" name="destinatario" size="16" style="font-size:12px; color: red;"> <td width="50%"> Mittente ( max 11 caratteri ) <td width="50%" align="right"> <input type="tex t" name="mittente" size="16" s tyle="font-size:12px; color: red;"> <td colspan="2"> <textarea style="width:300; height:88; font-size:12px; color: red;" type="text" name="testo"></textarea> <td colspan="2"> <input type="submit" name="invia" value="invia sms"> </table> </form> </body> </html> FILE invia.php Questo file raccoglie tutte le variabili inviate dal form, le elabora ed invia il messaggio. <?php // Imposto le variabili per l'autenticazione $username = "Inserire il proprio username" ; $password = "Inserire la propria password" ; // imposto altri dati $type_user = "user" ; $route = "GW1" ; // GW2 se si vuole il mittente personalizzato $time = urlencode (" :20:01"); // per esempio // Recupero delle variabili del form $mittente = urlencode ( $_REQUEST [ 'mittente' ]); $destinatario = urlenc ode ("+39". $_REQUEST [ 'destinatario' ]); $messaggio = urlencode ( $_REQUEST [ 'testo' ]); // Compongo la url per l'invio del messaggio $stringa = " ; $stringa.= "&password=".$password."&type_user=".$type_user."" ; $stringa.= "&route=". $route."&message=". $messaggio."&to=". $destinatario. "" ; $stringa.= "&from=". $mittente."&time=". $time. "" ; // Leggo la URL e determino l'esito dell'invio $contents = file ($stringa ); $risposta = trim ($contents [ 0 ]); $len = strlen ($risposta ); // Invio sms e controllo della risposta if ($risposta == "OK" ){ $msg = "Invio effettuato correttamente" ; } else { $msg = "ERRORE: Invio non effettuato" ; } echo $msg. "<br>" ;?> pagina 4 di 5

5 8. Codici d' errore CODE DESCRIPTION SOLUZIONE KO 501 Errore: Utente non riconosciuto o non abilitato Verificare i parametri username e password Assicurarsi di avere attivato il proprio account KO 5011 Errore: Utente non riconosciuto o non abilitato Verificare i parametri username e password. Assicurarsi di avere attivato il proprio account KO 5012 Errore: Utente non riconosciuto o non abilitato Verificare la presenza del parametro type_user Il valore accettatono è user KO 502 Errore: dati per l'invio non validi. Verificare che la richiesta provenga da un ip statico abilitato all'invio KO 503 Impossibile inviare sulla route selezionata Verificare che si disponga dei permessi per inviare con la route segnalata nel.contattare l'amministratore dell'account KO 457 Errore: Parametri non presenti Verificare la presenza di tutti I parametri per l'invio. I seguenti parametri sono obbligatori: username, password, message, to, route, type_user KO 497 Errore: tipo utente non valido Verificare la presenza del parametro type_user IL valore accettatono è user KO 498 Errore: route non abilitata all'invio o coefficiente Verificare che si disponga dei permessi per inviare con la route segnalata nel. Contattare il proprio rivenditore KO 601 Errore: non hai abbastanza crediti per effettuare su questa route Il numero dei sms da inviare è maggiore di quelli disponibili. Acquistare nuovi crediti, diminuire il numero dei destinatari o contattare l'amministratore dell'account KO 602 Errore: il sender utilizzato non è corretto. Verificare il parametro from:e' possibile inserire fino a 11 caratteri per un mittente alfanumerico o fino a 16 caratteri per un mittente solo numerico. KO 603 Errore: il messaggio del sms non è conforme. Verificare la lunghezza e il contenuto del messaggio. KO 604 Errore: non ci sono crediti sufficienti Contattare amministratore dell'account. Il numero dei sms da inviare è maggiore di quelli disponibili. Acquistare nuovi crediti, diminuire il numero dei destinatari o contattare l'amministratore dell'account KO 605 Errore: non hai abbastanza crediti per effettuare l' invio su questa route Contattare amministratore dell'account. Il numero dei sms da inviare è maggiore di quelli disponibili. Acquistare nuovi crediti, diminuire il numero dei destinatari o contattare l'amministratore dell' account KO 606 Errore: il messaggio dell'sms contiene caratteri non validi Utilizzare codifica ISO Verificare la lunghezza e il contenuto del messaggio. Vedi : 6.Charset e caratteri KO 613 Errore: data temporizzazione invio non valida. Verificare il formato del parametro time Il formato della data accettato è: aaaa-mm-gg hh:mm:ss Deve essere superiore almeno di 15 minuti rispetto al momento del' invio. Verificare di essere abilitati all' invio notturno KO 655 Errore: Ora di Invio NON CONSENTITA Verificare di essere abilitati all' invio notturno KO 701 Errore: dati invio non registrati Verificare la presenza di tutti I parametri per l'invio Verificare che si KO 702 Errore: dati invio non registrati Verificare la presenza di tutti I parametri per l'invio Verificare che si KO 799 Impossibile scalare crediti per l'invio Verificare la presenza di tutti I parametri per l'invio Verificare che si KO 802 Errore: impossibile registrare il file multimediale Verificare la presenza di tutti I parametri per l'invio Verificare che si KO 801 Conferma non avvenuta Verificare la presenza di tutti I parametri per l'invio Verificare che si pagina 5 di 5