Descrizione e caratteristiche tecniche del servizio

Transcript

1 Network Iunet Italian Technology Powered by SMS Service Descrizione e caratteristiche tecniche del servizio Novembre 2003 (Ver 11.03) Iunet S.r.l. via Vittime Civili Foggia Italy Linkas Srl, Via Cartesio Milano Italy -

2 CLIENTI ESISTENTI...3 TRASMISSIONE VIA HTTP E HTTPS...3 Indirizzo a cui trasmettere... 3 Variabili da trasmettere... 3 Note sui tipi di messaggi inviabili... 4 Conferme di trasmissione... 4 Esempi... 5 SPEDIZIONE MULTIPLA DI SMS...5 Descrizione... 5 Elementi del file MXL... 6 Tag per ogni messaggio... 6 Esempio di file XML... 7 Messaggi sempre uguali compressione... 7 Note tecniche: Trasmissione del file XML... 8 Esempio di script Perl per la trasmissione XML via socket... 8 Esempio di script Php per la trasmissione XML via socket TO SMS...9 Trasmissione del file XML via WEB SERVICES...9 SERVIZI DISPONIBILI... 9 send...9 getcredit...9 PHP... 9 ALTRI LINGUAGGI RICEZIONE SMS...10 Su SIM dedicata Su SIM condivisa Specifiche di ricezione messaggi specifica comune REPORTISTICA...11 Report giornaliero Sistema XML e Sistema HTTP Sistema HTTP report Report HTTP Sistema XML report Report HTTP IL SITO CHANGES...13 Modifiche rispetto alla versione precedente Novembre 2003 Pag. 2

3 Clienti esistenti Il cliente che ha già implementato tali specifiche è tenuto a leggere innanzitutto la sezione Changes per verificare eventuali modifiche alle specifiche o per conoscere le differenze con la versione precedente di questo documento. Il cliente sarà tenuto a controllare i contenuti del sito al fine di controllare nuovi ed eventuali aggiornamenti. TRASMISSIONE VIA HTTP e HTTPS Per inviare SMS via col protocollo http è necessario effttuare una chiamata HTTP con metodo POST o GET. Sono a disposizione le medesime URL in modalità HTTPS con certificati non siglati. Indirizzo a cui trasmettere L indirizzo http a cui trasmettere le richieste è: (In alternativa, è possibile trasmettere alla pagina splitter.php aggiungendo le due variabili username e password nel formato accodando successivamente le sottostanti variabili). Variabili da trasmettere?? body -> Contenuto del messaggio ( max 160 char se testo) Si noti che tale campo dovrà essere encoded. Per esempio il carattere [SPAZIO] dovrà essere convertito nel suo corrispondente %20 (non in + o nell effettivo carattere [SPAZIO]). In Php, ad esempio, esiste la funzione urlencode che effettua tali conversioni. E superfluo dire che solo il valore della variabile è encode?? dest -> indica il destinatario del messaggio, CON prefisso internazionale Si noti che il carattere + deve essere codificato poiché questo è considerato, nel protocollo http, quale uno spazio e non quale il simbolo +?? orig -> indica il numero del mittente che invia il messaggio (max 13 caratteri per il numero telefonico del mittente in formato internazionale oppure max 11 caratteri per una stringa di testo) Si prega di voler verificare la corretta trasmissione del mittente prima di effettuare invii numerosi poiché il set di caratteri disponibili nel mittente non è così esteso quanto quello del testo dei messaggi.?? Submit=1 -> Costante di invio. Senza questa variabile l'sms non sarà preso in considerazione. Esiste la possibilità di vedere le variabili affinchè siano Novembre 2003 Pag. 3

4 completamente passate (alcuni browser hanno limiti nella scrittura di caratteri nel campo URL) inserendo come valore il numero 2. Si noti la S maiuscola. o 1 Trasmette l sms o 2 Visualizza le variabili passate?? op -> Indica il tipo di messaggio che si vuole inviare, secondo questo schema:?? 0 test 1 - sms normale 2 - Logo GIF (72x14) 3 - Logo JPG (72x14) 4 - Logo BMP (72x14) 5 - Logo NOL (Nokia) 6 - Suoneria RTTTL 7 - Suoneria MID Non più attivo* 8 - Flash Sms 9 - Suoneria MIDI Non più attivo* 10 - Picture Message Non più attivo 11 - Immagine HexDump Non più attivo In mancanza del campo op o nel caso assuma un valore diverso da quelli previsti, il messaggio viene inviato come SMS normale ed addebitato al mittente. Note sui tipi di messaggi inviabili?? *gli screen saver sono GIF,JPG,BMP di dimensioni pari a 72 x 28 pixels?? gli standard logo sono GIF,JPG,BMP di 72 x 14 pixels?? L ordine nel quale le variabili appaiono non è importante Conferme di trasmissione La pagina post.php darà conferma dell avvenuto trasferimento del messaggio inviando il seguente testo: MESSAGGIO INVIATO MESSAGGIO NON SPEDITO Tale testo deve essere ricercato all interno della risposta del server che può trasmettere anche altri caratteri e/o tag HTML (parola necessaria e sufficiente SPEDITO/INVIATO minuscoli o maiuscoli) Tutta la pagina potrà subire cambiamenti senza preavviso, unica condizione di lettura sarà legata alle parole inviato e spedito che dovranno essere utilizzate per distinguere lo stato di invio del messaggio. Tali parole saranno da cercare in tutto il testo ritornato dal server. Si noti che tale conferma non è una conferma di ricezione del messaggio da parte del terminale GSM ricevente, ma è la conferma di avvenuto traferimento del messaggio all operatore che si occuperà della consegna al terminale GSM Novembre 2003 Pag. 4

5 Esempi Esempio di invio messaggio sms testo: Submit=1&op=1 per i test: ubmit=2&op=1 Esempio di invio logo operatore: C2C2C FFFFFF EEEEEE080808D8D8D83E3E3E F8F8F8A7A7A7FE010221F F002C E000004FF10C841A5BD 386BCB0ED920D87D193584E AAE437B19B46B4B097B8779AC C2B0C B C D544B CE241C074E09A F7CA5AC296DE97B109F0FC B3A7E157E B1F8A278C C260A3D0B056C05759B679E14A054A378A D00AD4 C76040B140E723AA6B5B7BB6ABABCBE3E95837F65B3B286857B643D3242CE3488CBD 31A8297CC86DD99850D09E409A5DAA69867E2E5E6C7D413B103B53D9AEA8630BD461 6DADDE067F98AB44007EB44AA799CFE194260A2D50005C70208F0678D B48 4C06009B3D6F062A0038D893C761008ACB C E9AA53C23E E F24009B1470BAA B00&dest= &orig=Smspoint&Submit= 1&op=4 SPEDIZIONE MULTIPLA DI SMS Descrizione Per trasmettere in massa un numero notevole di messaggi, Smspoint mette a disposizione un apposito sistema di ricezione. Tale sistema riceve via socket (si veda le note tecniche descritte più avanti) un file di testo formattato secondo descrizione e trasmette gli sms in esso contenuti. Di norma, al fine di non creare disfunzioni e rallentamenti, si consiglia di implementare il sistema di trasmissione XML solo nel caso in cui il numero di messaggi da inviare sia maggiore di 10. Tutto il blocco di dati si trova all interno del nodo <SMS>. La prima parte contiene le informazioni di login, mentre la successiva include la lista dei messaggi da inviare. Si noti che il formato XML non prevede l uso di alcuni caratteri speciali che devono quindi essere convertiti, in particolare: Carattere Descrizione Da sostituire con & e commerciale & < minore < Novembre 2003 Pag. 5

6 > maggiore > " doppio apice " apice singolo &apos; Segue la descrizione degli elementi indispensabili per considerare un file ben formattato. Elementi del file MXL <LOGIN> Username utente </LOGIN> <PWD> Passoword dell utente </PWD> <DESC> Campo libero </DESC> <MSGLST> Una lista è composta da una serie di messaggi, ciascuno descritto da alcune informazioni, contenute nel nodo <MSG>. <MSG> Tag per ogni messaggio Nodo Obbligatorio Descrizione <TEXT> S Testo del messaggio (in formato esadecimale per la spedizione di loghi e suonerie). <OP> S Tipo di messaggio richiesto. I valori possibili sono: 0 - test (messaggio inviato all smsc ma non trasmesso) 1 - sms normale 2 - Logo GIF (72x14) 3 - Logo JPG (72x14) 4 - Logo BMP (72x14) 5 - Logo NOL (Nokia) 6 - Suoneria RTTTL 7 - Suoneria MID Non più attivo* 8 - Flash Sms 9 - Suoneria MIDI Non più attivo* 10 - Picture Message Non più attivo 11 - Immagine HexDump Non più attivo <RCV> S Numero del terminale/telefono a cui spedire il messaggio, espresso in formato internazionale con + (es. +39YYYXXXXX). Nel caso non venisse inserito il + verrà aggiunto il prefisso +39. Novembre 2003 Pag. 6

7 <SND> S Numero del mittente o nome del mittente. Max 16 caratteri per il numero telefonico del mittente in formato internazionale oppure max 11 caratteri per una stringa di testo <MULTIRCV> Non implementato Esempio di file XML <SMS> <LOGIN>demo</LOGIN> <PWD>password</PWD> <DESC>Descrizione che appare nei report </DESC> <MSGLST> <MSG> <TEXT>Test message1</text> <OP>1</OP> <SND>Mittente</SND> <RCV> </RCV> </MSG> <MSG> <TEXT>Test message2</text> <SND> </SND> <RCV> </RCV> </MSG> <MSG> <OP>3</OP> <TEXT>42F E C0707C003E0E038003E0734E0072CE07C000E031DA0 05B8C FBA005DFE040001FFC1EA005783FF801F0046BE007D6200 F DA005B0E F4002F0E E0E </TEXT> <SND> </SND> <RCV> </RCV> </MSG> </MSGLST> </SMS> Messaggi sempre uguali compressione Nel caso si voglia spedire messaggi sempre identici, non è più necessario ripetere l intero tag MSG comprensivo di tutti i dati, ma potrà essere specificato solo il nuovo destinatario del messaggio: <MSG> < Novembre 2003 Pag. 7

8 Note tecniche: Trasmissione del file XML Di norma per la trasmissione del file XML è sufficiente collegarsi aprendo un canale di comunicazione socket/tcpip verso la porta 1066 dell host xml.smspoint.net e trasmettendo in chiaro il contenuto del file XML. E possibile eseguire a mano tale procedura facendo telnet all host verso la porta 1066 e digitando il testo xml a mano. Il file può essere trasmesso anche tramite l apposita classe java XMLsend.class che può essere richiesta all indirizzo sms@smspoint.net. Di tale classe sono disponibili anche i sorgenti per la personalizzazione. E possibile trasmettere il file in modalità diverse secondo le esigenze del cliente, richiedendo un contatto diretto con lo staff tecnico per i dettagli ed i consigli sull implementazione. Il sistema di trasmissione Sms in modalità XML è stato testato fino a sms per ogni file XML. Smspoint è a disposizione per effettuare test con clienti che ritenessero necessario trasmettere, in una sola sessione, un numero maggiore di messaggi. Esempio di script Perl per la trasmissione XML via socket #!/usr/bin/perl # Imposta la variabile xml_txt per fare una prova con un testo XML incompleto $xml_txt="<sms><login>mia_username</login><pwd>mia_password</pwd><desc>prov a di connessione</desc><msglst><msg><op>1</op><text>primo test di trasmissione </TEXT><SND>testo_o_numero_del_mittente</SND><RCV>numero_del_destinatario_comprens ivo_di_prefisso_internazionale</rcv></msg>\n</msglst></sms>"; # Usa le librerie di InputOutput relative ai Socket use IO::Socket; # Crea un collegamento via socket con protocollo tcp al server xml.smspoint.net sulla porta 1066 my $sock = new IO::Socket::INET ( ); PeerAddr => 'xml.smspoint.net', PeerPort => '1066', Proto => 'tcp', # Stampa un messaggio di errore nel caso in cui la connessione non riesca, altrimenti continua l'esecuzione die "Impossibile collegarsi all'host $!\n" unless $sock; # Stampa nel socket il contenuto della variabile xml_txt, ovvero trasmetti in chiaro il testo xml verso il server xml.smspoint.net print $sock $xml_txt; # Chiudi la connessione per permettere l'inizio della procedura di parse&trasmission degli sms close($sock); Esempio di script Php per la trasmissione XML via socket <?php // Imposta la variabile contenente un testo XML incompleto Novembre 2003 Pag. 8

9 $xml_txt="<sms><login>mia_username</login><pwd>mia_password</pwd><desc>prov a di connessione</desc><msglst><msg><op>1</op><text>primo test di trasmissione </TEXT><SND>testo_o_numero_del_mittente</SND><RCV>numero_del_destinatario_comprens ivo_di_prefisso_internazionale</rcv></msg>\n</msglst></sms>"; // Apri il socket verso il server $sock=fsockopen( xml.smspoint.net,1066,$errno,$errstr,10); // Se la connessione non riesce, stampa il messaggio di errore if (!$sock) exit( Impossibile collegarsi al server: $errstr ); // Trasmetti il file xml in chiaro sul socket fputs($sock,$xml_txt); // Chiudi la connessione fclose($sock);?> TO SMS Trasmissione del file XML via Il sistema di trasmissione può ricevere il file XML sopra menzionato anche via , inviandolo all indirizzo xml@xml.smspoint.net. L dovrà forzatamente essere in formato testuale, senza attachments, senza subject e dovrà contenere solo ed unicamente il file XML all interno del corpo messaggio. Tale sistema è ancora sperimentale. WEB SERVICES E attivo il Web Services per spedire gli sms. L indirizzo WSDL è Servizi disponibili Così come descritto nel WSDL sono disponibili due servizi: send ( ) Invia gli sms getcredit ( ) Restituisce il credito residuo di sms Non sono elencati altri dettagli poiché autoesplicativi nel wsdl stesso. Php E possibile scaricare la classe nusoap per utilizzare il webservices menzionato. ( Novembre 2003 Pag. 9

10 Altri linguaggi Il supporto Web Services segue le regole standard relative ai WebServices tali da renderlo utilizzabile per ogni linguaggio di programmazione che possa sfruttare tale tecnologia. RICEZIONE SMS La nuova funzionalità di ricezione Sms permette di ricevere sms sul proprio sito internet con due tipologie di contratto:?? Su SIM dedicata?? Su SIM condivisa Su SIM dedicata Il cliente potrà ricevere Sms su una SIM telefonica di qualsiasi operatore, di proprietà del cliente ed inviata a Smspoint (secondo le indicazioni dello staff) al numero di telefono della SIM. I messaggi così ricevuti saranno trasmessi alla pagina web del cliente (URL di ricezione messaggi, sul sito secondo la specifica comune (si veda paragrafi successivi). Su SIM condivisa Il cliente potrà ricevere i messaggi su un numero di telefono comunicato dallo staff Smspoint preponendo una parola anticipatamente concordata con lo staff (non si garantisce la disponibilità di parole specifiche). Quando un messaggio arriverà al numero comunicato, avendo come prima parola quella specificata, verrà chiamata la URL del cliente (URL di ricezione messaggi, sul sito secondo la specifica comune (si veda paragrafi successivi). In modalità di Sim condivisa vengono ricevuti gli sms di più clienti, per tale motivo non si garantiscono velocità e tempi di ricezione messaggi. Specifiche di ricezione messaggi specifica comune Alla ricezone di un SMS (sia per SIM condivisa che per SIM dedicata) il sistema effettuerà una chiamata alla pagina web specificata dal cliente nel campo URL di ricezione messaggi del sito Tale URL dovrà essere inserita SENZA il prefisso Le variabili passate alla pagina del cliente saranno: Nr mitt orig body Contiene il numero di log interno per eventuali referenze interne Contiene una stringa numerica/alfa numerica indicante il mittente del messaggio Contiene una stringa numerica indicante il nr di telefono al quale è stato inviato l sms Contiene una stringa alfa numerica contenente il testo del messaggio trasmesso Novembre 2003 Pag. 10

11 ora Contiene la data di chiamata della chiamata http in formato AAAAMMGGhhmmss Es: Il 16 Gennaio 1975 alle ore 12 e 00 minuti e 2 secondi verrebbe rappresentato come: Nel caso in cui il server http del cliente non sia disponibile, il sistema tenterà la trasmissione di un di avviso all indirizzo del cliente REPORTISTICA Report giornaliero Sistema XML e Sistema HTTP Il sistema di trasmissione unificato invia giornalmente (verso le ore 4.00AM del giorno successivo) un resoconto delle trasmissioni effettuate. Tale report visualizza un dettaglio dei tipi di messaggi inviati (sms testuali, loghi,suonerie) suddivisi tra Sistema HTTP e sistema XML. Viene inoltre inviato il totale degli sms trasmessi ed il credito di sms residuo calcolato in quel preciso istante. (Nel caso in cui siano stati inviati messaggi tra la mezzanotte e l ora del report, questi verranno riportati nel report del giorno successivo). Attenzione, il sistema XML riporterà un valore numerico degli sms trasmessi pari a quelli veicolati attraverso tale sistema al sistema web che conteggerà i messaggi. La somma quindi dei messaggi web+xml non è il totale addebitato. Solo il numero di messaggi http è addebitato. Sistema HTTP report Non è previsto l invio di una per ogni sms trasmesso Report HTTP Poiché il sistema POST inoltra immediatamente l esito dell invio del messaggio, il report in questa modalità non è previsto. Sistema XML report Il sistema di trasmissione XML risponderà inviando un html di report per ogni trasmissione riportando: Il codice report (nostro riferimento interno) L ora di invio Il numero di bytes trasmessi al server Il numero di sms trasmessi nel file Il numero di messaggi effettivamente trasmessi La descrizione specificata nel campo <DESC></DESC> Novembre 2003 Pag. 11

12 Report HTTP Il sistema di trasmissione XML è in grado di eseguire una chiamata http con modalità POST verso uno script appositamente creato dal cliente passando le variabili: Nr -> Indica il codice report (nostro riferimento interno) Da -> Indirizzo ip del chiamante (normalmente contiene l'ip del vostro server) Ora -> Timestamp nel formato aaaammgghhmmss bytes -> Numero di bytes trasmessi al server numerosms -> numero di sms trasmessi nel file trasmessi -> numero di messaggi effettivamente trasmessi descrizione -> sua descrizione come da campo <DESC> - Tale campo potrebbe essere utilizzato dal cliente come suo personale codice di trasmissione interno. nontrasmessi -> un set (numeri separati da virgole) con i destinatari dei messaggi fallimentari. (esempio: +39xxxxxx,+39yyyyyy) Al fine di ricevere tale chiamata il cliente deve fornire a Smspoint l indirizzo del server web e la pagina appositamente creata al fine di ricevere tali variabili oppure potrà personalizzare tale URL dal sito Sarà cura del cliente assicurarsi che il suo stesso server web sia attivo ed in grado di gestire tali variabili. Nel caso in cui il web server del cliente non restituisca al sistema XML la stringa 200 OK (questa stringa è restituita dal webserver del cliente in modo autonomo se la chiamata alla pagina è riuscita e non deve essere trasmessa manualmente dal cliente) il cliente riceverà via il messaggio di errore contenente il testo restituito dal suo stesso webserver al fine di poter risolvere eventuali malfunzionamenti/disfunzioni. Tale viene anche inviata nel caso in cui il web server del cliente non sia raggiungibile. Le chiamate http non riuscite non vengono ritrasmesse. E quindi cura del cliente gestire manualmente eventuali non conformità e/o errori sul proprio webserver. Smspoint, per ovvi motivi legati alla connettività internet, non assicura la trasmissione del report. Per questo motivo Smspoint non sarà responsabile per eventuali perdite/danni/non conformità che il cliente riscontrerà nel caso in cui il suo sistema di controllo sms del cliente sia legato in modo univoco al sistema di reportistica. Il sito Il sito è a disposizione del cliente, e tramite questo sito il cliente potrà:?? Acquistare nuovi pacchetti Sms?? Controllare il credito residuo?? Controllare i log di trasmissione dettagliati per periodo e per tipologia di invio o Si noti che nei report Web i messaggi non trasmessi hanno sfondo giallo per aver maggior risalto. Quelli trasmessi via XML sono trasmessi una seconda volta in caso di mancata trasmissione. Al fine di controllare il reale stato di invio di un messaggio si controlli, per i messaggi trasmessi via XML sia la prima riga errata Novembre 2003 Pag. 12

13 ?? Scaricare software che la seconda. I messaggi da riaccodare, trasmessia via XML,saranno solo quelli con doppia casella gialla.?? Modificare i propri dati di contatto, le URL di ricezione e spedizione messaggi, l indirizzo di invio dei report?? Controllare news, informazioni, comunicazione, nuove funzionalità. Il cliente dovrà tenersi aggiornato sulle nuove funzionalità, nuovi aggiornamenti o modifiche alle funzionalità attuali visitando il sito che è da considerarsi come unica fonte ufficiale di reperimento informazioni Changes Modifiche rispetto alla versione precedente?? Specifica Web services?? Compressione XML destinatari diversi?? Correzione errore esempio XML (mancanza del segno + per i numeri internazionali)?? Nota aggiuntiva sui caratteri a dispos izione per il campo mittente?? Url HTTPS per la spedizione dei messaggi Sms in modalità sicura Questa versione sostituisce totalmente la versione precedente. Novembre 2003 Pag. 13