Especificaciones de la Interfaz Web Services para env´ıo de SMS

Especificaciones de la Interfaz Web Services para env´ıo de SMS Altiria TIC, S.L.L. Versi´ on: 1.2

c Altiria TIC 2016 Copyright Este documento s´ olo puede ser reproducido por completo o en parte, almacenado, recuperado o transmitido por medios electr´ onicos, mec´ anicos, fotocopiado o cualquier otro medio con el consentimiento previo de los autores de acuerdo con los t´ erminos que estos indiquen.

Especificaciones de la Interfaz Web Services para env´ıo de SMS Historial de cambios

Versi´ on

Cambios

1.2

Se a˜ nade dos nuevos estados de confirmaci´on de entrega: “ERROR 114” y “ERROR 115” (cuadro 2.13). Se actualiza los ejemplos de programaci´on (secci´on 2.8).

1.1

Se modifica la lista de caracteres v´alidos para el remitente de los mensajes as´ı como la gesti´on de los caracteres inv´alidos en el par´ ametro “senderId” (secci´on 2.3.1).

1.0

Primera versi´ on del documento.

1

Especificaciones de la Interfaz Web Services para env´ıo de SMS

´Indice general 1. Introducci´ on

3

2. Descripci´ on de la API

4

2.1. Acceso al servicio web . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4

2.2. Respuesta del servicio web . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4

2.3. Operaciones del servicio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5

2.3.1. Env´ıo de un mensaje de texto . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5

2.3.2. Env´ıo de un mensaje multimedia WAP-PUSH . . . . . . . . . . . . . . . . . . . .

9

2.3.3. Consulta del cr´edito disponible . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 2.4. Mensajes de texto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 2.4.1. Codificaci´ on por defecto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 2.4.2. Unicode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 2.4.3. Longitud del mensaje . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 2.5. Mensajes WAP-PUSH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 2.5.1. Caracteres permitidos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 2.5.2. Especificaci´ on de la URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 2.5.3. Tipos de contenido . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 2.5.4. Formato del contenido . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 2.5.5. Direcci´ on del contenido . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 2.5.6. Env´ıo del contenido . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 2.5.7. Control de acceso al contenido . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 2.6. Confirmaci´ on de entrega . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 2.7. C´ odigos de estado . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 2.8. Ejemplos

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

2.8.1. Env´ıo de un mensaje en PHP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 2.8.2. Env´ıo de un mensaje en JAVA . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 2.8.3. Env´ıo de un mensaje en .NET . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

2

Especificaciones de la Interfaz Web Services para env´ıo de SMS

Cap´ıtulo 1

Introducci´ on En este documento se presenta la API disponible para el env´ıo de mensajes cortos sobre la interfaz de Altiria a trav´es de servicios web. El servicio de env´ıo de mensajes cortos est´a disponible en muchos paises. Para conocer los paises permitidos, las operadoras v´ alidas en cada pa´ıs y las posibles restricciones geogr´aficas (salvedades al funcionamiento general detallado en este documento que pudieran aplicar en cada caso) se puede enviar un correo electr´ onico a [email protected]. El servicio opcional de confirmaci´ on de entrega requiere que el cliente exponga un servicio web para recibir la informaci´ on de confirmaci´ on (ver la secci´on 2.6).

3

Especificaciones de la Interfaz Web Services para env´ıo de SMS

Cap´ıtulo 2

Descripci´ on de la API 2.1.

Acceso al servicio web

La URL de acceso al servicio web debe ser suministrada por Altiria. En los datos de acceso se proporciona la URL del fichero WSDL 1.1 que describe las operaciones del servicio web. El servicio web est´ a disponible a trav´es de SOAP 1.1 y de SOAP 1.2 Se recomienda el uso de la codificaci´on UTF-8 en la comunicaci´on con el servidor. En cualquier caso los caracteres de la tabla 2.1 deben ser representados de manera especial al comunicarlos al servidor: Car´ acter Retorno de carro Nueva l´ınea ” ’ & < >

Representaci´ on o o " ' & < >

Cuadro 2.1: Caracteres especiales Como norma general no se deben usar los caracteres prohibidos por la especificaci´on XML para evitar errores de comunicaci´ on con el servidor.

2.2.

Respuesta del servicio web

Cada operaci´ on del servicio web lleva asociada una respuesta desde el servidor de Altiria. La respuesta a cada operaci´ on se remite codificada con el juego de caracteres usado por el cliente al acceder al servicio web. En los siguientes apartados se detalla la respuesta para cada operaci´on siempre que resulte exitosa. En esos casos el c´ odigo de estado HTTP ser´a 200. Si se produjese alg´ un error en el servidor se emitir´a una respuesta de tipo “Fault” detallando las causas. En estos casos el c´ odigo de estado HTTP no ser´a 200 sino 500 y la respuesta no se ajustar´ aa lo especificado en el fichero WSDL. 4

Especificaciones de la Interfaz Web Services para env´ıo de SMS

Un ejemplo de respuesta “Fault” en SOAP 1.1 debido a un error en la petici´on del cliente (falta el par´ ametro obligatorio “domainId”) es el siguiente: soap:Client Unmarshalling Error: cvc-complex-type.2.4.a: Invalid content was found starting with element ’login’. One of ’{domainId}’ is expected. El mismo ejemplo de respuesta “Fault” en SOAP 1.2 es el siguiente: soap:Sender Unmarshalling Error: cvc-complex-type.2.4.a: Invalid content was found starting with element ’login’. One of ’{domainId}’ is expected.

2.3.

Operaciones del servicio

A continuaci´ on se detallan las operaciones disponibles en el servicio web y los par´ametros que las componen seg´ un la definici´ on del fichero WSDL. Cada par´ametro puede ser obligatorio u opcional y en algunos casos puede aparecer m´ ultiples veces.

2.3.1.

Env´ıo de un mensaje de texto

Permite enviar un mensaje corto de texto a uno o a varios tel´efonos destinatarios. Se trata de la operaci´ on sendSms definida en el fichero WSDL del servicio. Esta compuesta por los par´ ametros obligatorios de entrada detallados en el cuadro 2.2. Para enviar el mensaje a varios destinatarios basta repetir el par´ametro “destination” tantas veces como sea preciso sin sobrepasar el l´ımite m´aximo permitido de 100, asign´andole cada vez el valor de un n´ umero de tel´efono distinto (los tel´efonos repetidos son descartados). En el cuadro 2.3 se detallan los par´ ametros constituyentes de los tipos de datos complejos Credentials y TextMessage as´ı como el par´ ametro simple “destination”.

5

Especificaciones de la Interfaz Web Services para env´ıo de SMS

Nombre credentials destination message

Valor Datos de identificaci´ on del usuario suministrados por Altiria N´ umero de tel´efono m´ ovil del destinatario del mensaje. Datos propios del mensaje a enviar

Tipo de datos Credentials String TextMessage

Cuadro 2.2: Par´ ametros de entrada de la operaci´on sendSms

Nombre domainId login passwd destination

msg

senderId

ack

idAck

dPort

Valor Identificador suministrado por Altiria al cliente. Identificador de usuario suministrado por Altiria al cliente. Clave del usuario suministrada por Altiria al cliente. N´ umero de tel´efono m´ ovil del destinatario del mensaje. Se especificar´a en formato de numeraci´ on internacional sin prefijo ’00’ ni el signo ’+’. Ej: 34645852126. Es fundamental incluir el prefijo del pa´ıs (34 para Espa˜ na) para que el mensaje llegue al destino esperado. No debe superar los 16 d´ıgitos. Mensaje a enviar. La lista de caracteres v´alidos y la longitud m´axima permitida se detalla en la secci´on 2.4. No puede estar vac´ıo (cadena vac´ıa). Remitente del mensaje a enviar, autorizado por Altiria . La posibilidad de personalizar el remitente depende del pa´ıs destinatario del mensaje. Puede tomar dos posibles valores: 1) valor alfanum´erico de hasta 11 caracteres (n´ umeros y letras de la “a” a la “z” tanto may´ usculas como ˜ y la “˜ min´ usculas excluyendo la “N” n”); 2) valor num´erico de hasta 15 d´ıgitos decimales comenzando por el car´acter “+”. Los caracteres inv´ alidos ser´ an suprimidos autom´ aticamente. Si se pretende que el receptor pueda responder al mensaje corto recibido se deber´ıa usar un remitente num´erico (opci´on 2) incluyendo el prefijo de pa´ıs. Si no se incluye, el mensaje se enviar´a con el remitente por defecto seleccionado por Altiria. Solicitud de confirmaci´ on de entrega de los mensajes enviados (ver secci´ on 2.6). Si vale ”true” solicita confirmaci´on de entrega de los SMS enviados. En su ausencia o si tiene otro valor no se solicita confirmaci´on de entrega. C´ odigo identificativo para la confirmaci´on de entrega (ver secci´on 2.6). Valor alfanum´erico de hasta 20 caracteres (n´ umeros y letras de la “a” a ˜ ni “˜ la “z” tanto may´ usculas como min´ usculas sin incluir ni “N” n”). De rebasar la longitud m´ axima permitida ser´a truncado. Los caracteres no permitidos ser´ an eliminados. Solo ser´a considerado si el par´ametro ack se env´ıa con valor ”true”. Si se incluye expl´ıcitamente este par´ametro y toma como valor cadena vac´ıa, anula la solicitud de confirmaci´on de entrega. Puerto destino del SMS a enviar. Valor num´erico entre 1 y 65535 (solo d´ıgitos decimales). Solo necesario si se desea cambiar el valor habitual de esta propiedad. Si se define, la longitud m´axima del mensaje a enviar (par´ ametro “msg”) se ver´a reducida (ver la secci´on 2.4.3) y se invalidar´ a la posibilidad de enviar mensajes concatenados (ver par´ametro “concat”). Si solo se define “sPort”, este tomar´a el valor 0.

6

Obligatorio s´ı s´ı s´ı s´ı

s´ı

no

no

no

no

Especificaciones de la Interfaz Web Services para env´ıo de SMS

sPort

encoding

concat

Puerto origen del SMS a enviar. Valor num´erico entre 1 y 65535 (solo d´ıgitos decimales). Solo necesario si se desea cambiar el valor habitual de esta propiedad. Si se define, la longitud m´axima del mensaje a enviar (par´ ametro “msg”) se ver´a reducida (ver la secci´on 2.4.3) y se invalidar´ a la posibilidad de enviar mensajes concatenados (ver par´ametro “concat”). Si solo se define “dPort”, este tomar´a el valor 0. El u ´nico valor permitido es “unicode” para cambiar la codificaci´on del SMS a Unicode (ver la secci´on 2.4.2). En su ausencia o si tiene otro valor el SMS tomar´ a la codificaci´on por defecto. Si vale “true” permite concatenar mensajes para enviar un mensaje corto de longitud mayor que la habitual (ver la secci´on 2.4.3). En su ausencia, si tiene otro valor o si se define el par´ametro “sPort” o “dPort” se deshabilita la concatenaci´on de mensajes. Cuadro 2.3: Lista de par´ametros para sendsms

no

no

no

De acuerdo al fichero WSDL, un ejemplo de mensaje SOAP correspondiente a la operaci´ on sendSms, solicitando el env´ıo de un mensaje concatenado a dos destinatarios ser´ıa este: XXXXX YYYYY ZZZZZ 346XXXXXXXX 346YYYYYYYY Ejemplo de mensaje concatenado enviado a m´ as de un destinatario con la codificaci´ on UNICODE para admitir las vocales acentuadas y solicitud de confirmaci´ on de entrega. altiria.net true 123456789 unicode true Seg´ un el fichero WSDL, la respuesta de la operaci´ on sendSms est´a compuesta por un c´odigo de estado general de los descritos en apartado 2.7 Si la operaci´ on ha resultado exitosa (c´odigo de estado “000”) la respuesta contendr´a adicionalmente para cada destinatario del env´ıo (par´ ametros “destination” de entrada) los siguientes datos: destination: se corresponde con el n´ umero de tel´efono del destinatario. Si se hubiese enviado un mensaje concatenado (ver el par´ametro “concat”) a un u ´nico destinatario le corresponder´ an varios mensajes, tantos como fragmentos compongan el mensaje concatenado. En ese caso aparecer´ an datos independientes para cada fragmento siendo cualificado el valor de “destination” 7

Especificaciones de la Interfaz Web Services para env´ıo de SMS

con un sufijo que diferencie cada fragmento con un ´ındice num´erico comenzando por 0. Por ejemplo para un mensaje concatenado de tres fragmentos enviado al n´ umero “xxxxxxxxxxx” se recibir´ an datos para destination=xxxxxxxxxxx(0), destination=xxxxxxxxxxx(1) y destination=xxxxxxxxxxx(2). status: se corresponde con uno de los c´odigos de estado del apartado 2.7. idAck: se corresponde con el c´ odigo de identificaci´on asociado a la solicitud de confirmaci´on de entrega (ver secci´ on 2.6). Solo aparecer´a si se solicita la confirmaci´on de entrega y es aceptada. Un ejemplo de respuesta exitosa correspondiente a la operaci´on sendSms del ejemplo anterior ser´ıa el mostrado a continuaci´ on. Al tratarse de un mensaje concatenado aparecen datos para cada uno de los tres fragmentos que lo componen para cada destinatario del env´ıo: 000 346XXXXXXXX(0) 000 123456789 346XXXXXXXX(1) 000 123456789 346XXXXXXXX(2) 000 123456789 346YYYYYYYY(0) 000 123456789 346YYYYYYYY(1) 000 123456789 346YYYYYYYY(2) 000 123456789

8

Especificaciones de la Interfaz Web Services para env´ıo de SMS

Un ejemplo de respuesta notificando un error en la autentificaci´on ser´ıa este: 020 La infomaci´ on de ´exito para un destinatario concreto implica que el mensaje ha sido aceptado por la pasarela, no que haya sido enviado y recibido por el destinatario. Un mensaje puede ser aceptado a´ un cuando no se disponga de cr´edito suficiente para su env´ıo (ver secci´on 2.3.3). Para asegurar el adecuado funcionamiento de esta operaci´on se recomienda probar la correcta recepci´ on de todos los caracteres permitidos en un tel´efono m´ovil antes de poner el sistema en producci´ on.

2.3.2.

Env´ıo de un mensaje multimedia WAP-PUSH

Permite enviar un mensaje multimedia a traves de WAP-PUSH a uno o a varios tel´efonos destinatarios. Para conocer en qu´e consisten los mensajes de este tipo se aconseja leer la secci´on 2.5. Para saber m´ as sobre el proceso de env´ıo de mensajes WAP-PUSH a trav´es de la pasarela se aconseja leer la secci´ on 2.5.7. Se trata de la operaci´ on sendWapPush definida en el fichero WSDL del servicio. Est´a compuesta por los par´ ametros obligatorios de entrada detallados en el cuadro 2.4. Nombre credentials destination message

Valor Datos de identificaci´ on del usuario suministrados por Altiria N´ umero de tel´efono m´ ovil del destinatario del mensaje. Datos propios del mensaje a enviar

Tipo de datos Credentials String WapPushMessage

Cuadro 2.4: Par´ ametros de entrada de la operaci´on sendWapPush Para enviar el mensaje a varios destinatarios basta repetir el par´ametro “destination” tantas veces como sea preciso sin sobrepasar el l´ımite m´aximo permitido de 100, asign´andole cada vez el valor de un n´ umero de tel´efono distinto (los tel´efonos repetidos son descartados). En el cuadro 2.5 se detallan los par´ ametros constituyentes de los tipos de datos complejos Credentials y WapPushMessage as´ı como el par´ametro simple “destination”. Nombre domainId login passwd destination

Valor Identificador suministrado por Altiria al cliente. Identificador de usuario suministrado por Altiria al cliente. Clave del usuario suministrada por Altiria al cliente. N´ umero de tel´efono m´ ovil del destinatario del mensaje. Se especificar´a en formato de numeraci´ on internacional sin prefijo ’00’ ni el signo ’+’. Ej: 34645852126. Es fundamental incluir el prefijo del pa´ıs (34 para Espa˜ na) para que el mensaje llegue al destino esperado. No debe superar los 16 d´ıgitos.

9

Obligatorio s´ı s´ı s´ı s´ı

Especificaciones de la Interfaz Web Services para env´ıo de SMS

msg

url

ack

idAck

Texto a enviar adjunto al mensaje WAP-PUSH. Representa una breve descripci´ on del contenido multimedia. Deber´ıa contener exclusivamente caracteres incluidos en la lista del apartado 2.5.1. No debe sobrepasar los 115 caracteres junto a la longitud del par´ametro “url” o bien los 88 caracteres si se opta por el env´ıo de clave en el parametro “url” (ver secci´ on 2.5.7). No puede estar vac´ıo. Direcci´ on de Internet desde donde el tel´efono m´ovil se descargar´a el contenido. Debe contener caracteres validos en una URL (ver secci´on 2.5.2). No debe sobrepasar los 115 caracteres junto a la longitud del par´ametro “msg” o bien los 88 caracteres si se opta por el env´ıo de clave en este parametro (ver secci´ on 2.5.7). No puede estar vac´ıo. No es posible seleccionar un puerto de conexi´on diferente al 80, el habitual en la navegaci´on WEB. Solicitud de confirmaci´ on de entrega de los mensajes enviados (ver secci´ on 2.6). Si vale ”true” solicita confirmaci´on de entrega de los SMS enviados. En su ausencia o si tiene otro valor no se solicita confirmaci´on de entrega. C´ odigo identificativo para la confirmaci´on de entrega (ver secci´on 2.6). Valor alfanum´erico de hasta 20 caracteres (n´ umeros y letras de la “a” a ˜ ni “˜ la “z” tanto may´ usculas como min´ usculas sin incluir ni “N” n”). De rebasar la longitud m´ axima permitida ser´a truncado. Los caracteres no permitidos ser´ an eliminados. Solo ser´a considerado si el par´ametro ack se env´ıa con valor ”true”. Si se incluye expl´ıcitamente este par´ametro y toma como valor cadena vac´ıa, anula la solicitud de confirmaci´on de entrega. Cuadro 2.5: Lista de par´ametros para sendwappush

s´ı

s´ı

no

no

De acuerdo al fichero WSDL, un ejemplo de mensaje SOAP correspondiente a la operaci´ on sendWapPush ser´ıa este: XXXXX YYYYYY ZZZZZZ 346XXXXXXXX 346YYYYYYYY Texto de alerta http://www.altiria.com?k= true 123456789

10

Especificaciones de la Interfaz Web Services para env´ıo de SMS

Seg´ un el fichero WSDL, la respuesta de la operaci´ on sendWapPush est´a compuesta por un c´ odigo de estado general de los descritos en apartado 2.7 Si la operaci´ on ha resultado exitosa (c´odigo de estado “000”) la respuesta contendr´a adicionalmente para cada destinatario del env´ıo (par´ ametros “destination” de entrada) los siguientes datos: destination: se corresponde con el n´ umero de tel´efono del destinatario. status: se corresponde con uno de los c´odigos de estado del apartado 2.7. idAck: se corresponde con el c´ odigo de identificaci´on asociado a la solicitud de confirmaci´on de entrega (ver secci´ on 2.6). Solo aparecer´a si se solicita la confirmaci´on de entrega y es aceptada. key: se corresponde con la clave u ´nica asociada al destinatario (ver secci´on 2.5.7). Solo aparecer´ a si se solicita la clave para cada destinatario Un ejemplo de respuesta exitosa correspondiente a la operaci´on sendWapPush del ejemplo anterior ser´ıa el mostrado a continuaci´ on: 000 346XXXXXXXX 000 123456789 346XXXXXXXX-22879196 346YYYYYYYY 000 123456789 346YYYYYYYY-22879196 Un ejemplo de respuesta notificando un error en la autentificaci´on ser´ıa este: 020 La infomaci´ on de ´exito para un destinatario concreto implica que el mensaje ha sido aceptado por la pasarela, no que haya sido enviado y recibido por el destinatario. Un mensaje puede ser aceptado a´ un cuando no se disponga de cr´edito suficiente para su env´ıo (ver secci´on 2.3.3). Para asegurar el adecuado funcionamiento de esta operaci´on se recomienda probar un ciclo completo de servicio, desde el env´ıo del mensaje WAP-PUSH hasta la descarga del contenido en el tel´efono m´ovil, como paso previo a poner el sistema en producci´on.

11

Especificaciones de la Interfaz Web Services para env´ıo de SMS

2.3.3.

Consulta del cr´ edito disponible

Permite conocer el cr´edito instant´ aneo disponible para enviar mensajes. Se trata de la operaci´ on getCredit definida en el fichero WSDL del servicio. Est´a compuesta por los par´ ametros obligatorios de entrada detallados en el cuadro 2.6. Nombre credentials

Valor Datos de identificaci´ on del usuario suministrados por Altiria

Tipo de datos Credentials

Cuadro 2.6: Par´ ametros de entrada de la operaci´on getCredit En el cuadro 2.7 se detallan los par´ ametros constituyentes del tipo de datos complejo Credentials. La u ´nica forma de averiguar si se tiene cr´edito suficiente para enviar los mensajes, aparte de llevar un contador propio de saldo disponible, es mediante una consulta previa a trav´es de esta operaci´on. La operaci´ on ofrece informaci´ on del cr´edito disponible en un momento dado. Puesto que el sistema decrementa el cr´edito justo al enviar el mensaje al destinatario, es necesario seguir el siguiente esquema para utilizar adecuadamente la operaci´ on de consulta de cr´edito disponible: Antes de comenzar con los env´ıos, se calcula cuantos mensajes en total se desean enviar, por ejemplo 5000. Se consulta el valor del cr´edito disponible una u ´nica vez. A partir del coste en cr´editos de cada mensaje a enviar y del saldo disponible se estima si se podr´ an enviar o no todos los mensajes. En caso positivo, se usan las operaciones de env´ıo de mensajes. En caso negativo se debe adquirir m´ as cr´edito Cuando el sistema haya finalmente enviado todos los mensajes, una nueva consulta del cr´edito disponible ofrecer´ a el valor actualizado. En cualquier caso la comprobaci´ on efectiva del saldo disponible para efectuar un env´ıo se realiza en un proceso interno justo antes de efectuar el env´ıo. En caso de que no se disponga de cr´edito suficiente, el mensaje no ser´ a enviado y el cliente ser´a informado a trav´es de correo electr´onico. Si posteriormente se adquiere m´ as cr´edito disponible, se podr´a avisar a Altiria para reintentar los env´ıos pendientes. Nombre domainId login passwd

Valor Identificador suministrado por Altiria al cliente. Identificador de usuario suministrado por Altiria al cliente. Clave del usuario suministrada por Altiria al cliente. Cuadro 2.7: Lista de par´ametros para getcredit

12

Obligatorio s´ı s´ı s´ı

Especificaciones de la Interfaz Web Services para env´ıo de SMS

De acuerdo al fichero WSDL, un ejemplo de mensaje SOAP correspondiente a la operaci´ on getCredit ser´ıa este: XXXXXX YYYYYY ZZZZZZ Seg´ un el fichero WSDL, la respuesta de la operaci´ on getCredit est´a compuesta por un c´ odigo de estado general de los descritos en apartado 2.7. Si la operaci´ on ha resultado exitosa (c´odigo de estado “000”) la respuesta contendr´a adicionalmente el valor del cr´edito disponible como un n´ umero con dos decimales. Un ejemplo de respuesta exitosa correspondiente a la operaci´on getCredit del ejemplo anterior ser´ıa el mostrado a continuaci´ on: 000 1000000.70 Un ejemplo de respuesta notificando un error en la autentificaci´on ser´ıa este: 020

13

Especificaciones de la Interfaz Web Services para env´ıo de SMS

2.4.

Mensajes de texto

Los caracteres permitidos para el texto del mensaje corto y la longitud m´ axima depender´an de la codificaci´ on de caracteres seleccionada: codificaci´on por defecto (ver secci´on 2.4.1) o la codificaci´ on UNICODE (ver secci´ on 2.4.2).

2.4.1.

Codificaci´ on por defecto

La codificaci´ on por defecto permite los caracteres de la tabla 2.8. La longitud m´ axima permitida se detalla en la secci´on 2.4.3. Las vocales con tilde o acento agudo (´a) son aceptadas pero se enviar´an al tel´efono m´ovil sin acentuar. Adicionalmente se admiten los caracteres extendidos de la tabla 2.9. Cada car´acter extendido ocupa el doble espacio que un car´ acter normal, esto debe considerarse para el c´omputo de la longitud m´ axima del mensaje. En caso de que el mensaje a enviar contenga caracteres fuera de las listas presentadas, estos ser´ an reemplazados por el car´ acter “?” antes de enviar el mensaje. @ cr1 lf2 C ¸ sp3 ! ” # $ % & ’

( ) * + , . / 0 1 2 3

4 5 6 7 8 9 : ; < = > ?

L M N ˜ N O P Q R S T U V

A B C D E F G H I J K

W X Y Z ¿ a b c d e f g

h i j k l m n n ˜ o p q r

s t u v w x y z ´ A ´ E ´I ´ O

´ U ´a ´e ´ı ´o u ´ ¨ U u ¨ `a `e `ı `o

u `

Cuadro 2.8: Lista de caracteres permitidos para mensajes de texto en la codificaci´on por defecto

[

]

\

^

{

}

|

~

B C

Cuadro 2.9: Lista de caracteres extendidos permitidos para mensajes de texto

2.4.2.

Unicode

La codificaci´ on UNICODE, forzada mediante el par´ametro “unicode” (ver el cuadro 2.3), permite todo el juego de caracteres UNICODE de 16bits. La longitud m´ axima permitida se detalla en la secci´on 2.4.3, siendo siempre menor que usando la codificaci´ on por defecto (ver la secci´ on 2.4.1). Con esta codificaci´ on ser´ıa posible por ejemplo el env´ıo de vocales con tilde. 1 Retorno

de carro l´ınea 3 Espacio blanco 2 Nueva

14

Especificaciones de la Interfaz Web Services para env´ıo de SMS

2.4.3.

Longitud del mensaje

La longitud m´ axima de un mensaje de texto es un valor variable que depende de la codificaci´ on de caracteres usada y de la posibilidad de concatenaci´on. Los mensajes que excedan la longitud m´ axima aplicable ser´ an rechazados (no enviados). La longitud m´ axima de un mensaje corto con la codificaci´ on por defecto es de 160 caracteres (ver secci´ on 2.4.1). Los caracteres extendidos (ver la tabla 2.9) ocupan el doble, por tanto la longitud m´ axima se reduce. Por ejemplo si el texto del SMS contuviera el s´ımbolo del euro “B C” y los corchetes “[ ]”, la longitud m´axima del mensaje corto se reducir´ıa a 157 caracteres. La longitud m´ axima de un mensaje corto con la codificaci´ on UNICODE es de 70 caracteres (ver secci´ on 2.4.2). En caso de definir puertos origen o destino del SMS (ver los par´ametros sPort y dPort en el cuadro 2.3) la longitud m´ axima se reduce de la siguiente forma: 152 caracteres para la codificaci´ on por defecto (ver secci´on 2.4.1). Igualmente hay que considerar que los caracteres extendidos (ver la tabla 2.9) ocupan el doble. 66 caracteres para la codificaci´ on UNICODE (ver secci´on 2.4.2). Mediante el uso de mensajes concatenados es posible ampliar esos l´ımites. Un mensaje concatenado consiste en varios mensajes en secuencia recibidos como un u ´nico mensaje en el tel´efono del destinatario. Los mensajes concatenados se posibilitan mediante el par´ametro “concat” (ver el cuadro 2.3) siempre que no se esten definiendo ni el puerto origen ni el puerto destino del SMS (ver los par´ametros sPort y dPort en el cuadro 2.3). La plataforma de Altiria permite concatenar hasta 10 mensajes, aplicando en ese caso los l´ımites siguientes a la longitud del mensaje: 1530 caracteres para la codificaci´ on por defecto (ver secci´on 2.4.1). Igualmente hay que considerar que los caracteres extendidos (ver la tabla 2.9) ocupan el doble. 670 caracteres para la codificaci´ on UNICODE (ver secci´on 2.4.2).

15

Especificaciones de la Interfaz Web Services para env´ıo de SMS

2.5.

Mensajes WAP-PUSH

La interfaz HTTP de Altiria permite el env´ıo de mensajes multimedia (im´agenes, sonidos, juegos, etc) mediante la tecnolog´ıa de los mensajes WAP-PUSH. Los mensajes WAP-PUSH incluyen informaci´on sobre la ubicaci´on de un determinado contenido multimedia, una direcci´ on de Internet. En este sentido son completamente diferentes a los mensajes de texto normales, puesto que en estos el contenido relevante es el propio texto. B´ asicamente un mensaje de este tipo se compone de un peque˜ no texto a modo de presentaci´on del contenido que se ofrece y la direcci´ on de Internet donde se ubica dicho contenido. Cuando un tel´efono m´ ovil recibe un mensaje WAP-PUSH, le presenta al usuario la breve descripci´ on mencionada junto con la posibilidad de descargarse el contenido multimedia referenciado. Si el usuario acepta, el tel´efono de manera autom´ atica accede al contenido a trav´es de HTTP, se lo descarga como si de un navegador WEB se tratara y lo almacena, mostrando adem´as otras opciones en funci´on del tipo de contenido (ver una imagen, reproducir un sonido...).

2.5.1.

Caracteres permitidos

El cuadro 2.10 detalla los caracteres admisibles para los mensajes WAP-PUSH (par´ametro “msg” del cuadro 2.5). cr1 ’ . 5 < D K R Y f m t ´ A ´ı

lf2 ( / 6 = E L S Z g n u ´ E ´o

sp3 ) 0 7 > F M T a h o v ´I u ´

! * 1 8 ? G N U b i p w ´ O

” + 2 9 A H O V c j q x ´ U

# , 3 : B I P W d k r y ´a

& 4 ; C J Q X e l s z ´e

Cuadro 2.10: Lista de caracteres permitidos para los mensajes WAP-PUSH Las vocales con tilde o acento agudo (´a) son aceptadas pero se enviar´an al tel´efono m´ovil sin acentuar. En caso de que el mensaje a enviar contenga caracteres fuera de la lista presentada, estos ser´ an reemplazados por el car´ acter “?” y el mensaje ser´a enviado.

2.5.2.

Especificaci´ on de la URL

La URL de descarga de los contenidos multimedia suministrados a trav´es de mensajes WAP-PUSH (par´ ametro “url” del cuadro 2.5) debe seguir las siguientes normas de composici´on: Los caracteres del cuadro 2.11 son seguros y se pueden incluir sin codificar. 1 Retorno

de carro l´ınea 3 Espacio blanco 2 Nueva

16

Especificaciones de la Interfaz Web Services para env´ıo de SMS

Los caracteres del cuadro 2.12 son reservados y se pueden incluir sin codificar si se emplean dentro de la URL de acuerdo a su uso reservado. Por ejemplo el car´acter “&” se usa para separar los parametros de un formulario. Si estos caracteres se emplean de otro modo se deben codificar. Otros caracteres se pueden incluir previa codificaci´on. De todos modos pueden no ser seguros y es posible que algunos presenten problemas en algunos tel´efonos. Se recomienda prescindir de ellos siempre que sea posible. a o C Q 4

b p D R 5

c q E S 6

d r F T 7

e s G U 8

f t H V 9

g u I W -

h v J X

i w K Y .

j x L Z !

k y M 0 *

l z N 1 ’

m A O 2 (

n B P 3 )

Cuadro 2.11: Lista de caracteres seguros $

&

+

,

/

:

;

=

?

@

Cuadro 2.12: Lista de caracteres reservados La codificaci´ on de un car´ acter se logra a partir de su representaci´on en hexadecimal en un determinado juego de caracteres, insertando el simbolo “ %” por cada par de d´ıgitos hexadecimales. Por ejemplo la “˜ n” en UTF-8 se codificar´ıa como “ %C3 %B1”. El juego de caracteres a escoger deber´ıa ser el del servidor que albergue el contenido a descargar mediante el mensaje WAP-PUSH. Seg´ un lo visto si se desea permitir la descarga de un contenido de la URL: http://www.miempresa.com/contenidos/imagen[1].jpg se debe enviar como (usando ISO8859-1): http://www.miempresa.com/contenidos/imagen%5B1%5D.jpg Es importante rese˜ nar que cada car´acter codificado ocupa un n´ umero mayor de caracteres en el c´ omputo de la longitud completa de la URL. En cualquier caso se recomienda probar la correcta descarga de los contenidos desde la URL seleccionada para comprobar que todo el proceso se efect´ ua correctamente.

2.5.3.

Tipos de contenido

El contenido m´ as general que se puede enviar es una p´agina “wml”. Las p´aginas “wml” son similares a las conocidas p´ aginas web, adaptadas a los requisitos de un tel´efono m´ovil. De este modo se podr´ a enviar un contenido formado por texto y otros tipos de archivos como im´ agenes (ej: jpg y gif) o sonidos (ej: midi), incluidos en la propia p´agina. Tambi´en es posible enviar directamente el archivo multimedia al tel´efono, evitando incluirlo en una p´ agina “wml”. Actualmente hay mucha diversidad de tel´efonos m´oviles, cada uno con sus propias capacidades multimedia. Es posible que determinados tel´efonos no sean capaces de manejar algunos tipos de archivos. Para esas situaciones, la posibilidad de incluir texto en una p´agina “wml”, un recurso manejado por 17

Especificaciones de la Interfaz Web Services para env´ıo de SMS

todos los terminales WAP, permite al menos que el tel´efono acceda a parte de la informaci´on. A este respecto una buena pr´ actica es incluir en el texto informaci´on para el destinatario sobre la opci´on de acceder al fichero multimedia a trav´es de un navegador web convencional, adjuntando la informaci´ on relativa a la direcci´ on de Internet. En caso de optar por la inclusi´ on de texto en una p´agina “wml” se recomienda emplear un juego de caracteres sencillo, reconocible por la mayor´ıa de los tel´efonos. Como referencia se puede usar el detallado en el cuadro 2.10, sin incluir las vocales acentuadas.

2.5.4.

Formato del contenido

Independientemente del tipo de contenido escogido, siempre se deber´ıa considerar que el medio habitual de acceso al mismo ser´ a un tel´efono m´ovil. Esto tiene importantes incidencias en cuanto al tama˜ no m´aximo de la informaci´on suministrada. Se recomienda no enviar contenidos que ocupen m´as de 10kB, sobre todo si se suministran embebidos en p´ aginas “wml”. Para optimizar el tama˜ no, se sugiere adaptar los contenidos a los requerimientos de un tel´efono m´ ovil. Por ejemplo si se trata de una imagen es conveniente ajustar su tama˜ no al habitual de la pantalla, guardando adem´ as una relaci´ on de aspecto adecuada para que al recibirla ocupe el m´aximo en todas las direcciones. Una buena medida como referencia pueden ser 240 x 240 “pixels”.

2.5.5.

Direcci´ on del contenido

El tel´efono m´ ovil conoce la ubicaci´ on del contenido multimedia mediante la informaci´on de direcci´ on que le llega en el mensaje WAP-PUSH. Es obvio que para que el tel´efono pueda descargarse la informaci´on la direcci´on debe respresentar la ubicaci´ on de un recurso accesible p´ ublicamente a trav´es de HTTP, mediante navegaci´on WEB. Un detalle importante asociado a la direcci´on del contenido es que muchos tel´efonos la emplean como identificador de los mensajes WAP-PUSH recibidos. Esto supone que si se recibe un mensaje WAP-PUSH con la misma direcci´ on del contenido asociado que un mensaje ya recibido y almacenado en el tel´efono, el nuevo mensaje reemplazar´a al antiguo. Existen sin embargo tel´efonos que no siguen este patr´on y almacenan los dos mensajes con id´entica direcci´ on del contenido de forma independiente.

2.5.6.

Env´ıo del contenido

Cuando el tel´efono m´ ovil solicita el contenido referenciado en el mensaje WAP-PUSH, env´ıa una petici´ on HTTP GET (en algunos casos se env´ıa un HTTP HEAD previamente) a la direcci´on apropiada. Es necesario entonces un servidor HTTP que atienda la petici´on y entregue el contenido apropiadamente.

2.5.7.

Control de acceso al contenido

La URL indicada en el campo “url” de la operaci´on “sendWapPush” ser´a enviada en el mensaje WAP-PUSH a cada destinatario para que los interesados se descarguen el contenido ah´ı alojado. Para poder distinguir qu´e destinatarios han accedido realmente al contenido Altiria ofrece la posibilidad de enviar un mensaje diferente a cada uno de ellos. A la URL a suministrar al tel´efono se le a˜ nadir´a un par´ ametro identificador, una clave. Este par´ametro estar´a un´ıvocamente asociado al tel´efono del destinatario mediante la respuesta generada por la pasarela a la operaci´on “sendWapPush”. Cuando se reciba una petici´ on de descarga se podr´a extraer la clave y de esta manera obtener informaci´on del destinatario. 18

Especificaciones de la Interfaz Web Services para env´ıo de SMS

Si se desea solicitar el env´ıo de clave es preciso que la URL suministrada en el par´ametro “url” termine con la subcadena “k=”. Altiria agregar´a en ese caso a la URL enviada en cada mensaje la clave u ´nica con el formato: “xxxxxxxxxxx-zzzzzzzzzz”; ‘xxxxxxxxxxx” representa el n´ umero de tel´efono del destinatario en formato internacional y “zzzzzzzzzz” representa un n´ umero asociado a cada operaci´ on “sendWapPush”, como m´ aximo de diez cifras. Es necesario resaltar que si se opta por este m´etodo la longitud total para los parametros “msg” y “url” pasar´ a de 115 caracteres a 88. Finalmente para clarificar todos los elementos del servicio de env´ıo de mensajes multimedia a trav´es de la operaci´ on “sendWapPush” se esquematizan los procesos involucrados en el env´ıo de un mensaje a dos destinatarios solicitando claves independientes: 1. El cliente accede al servicio web mediante la operaci´on “sendWapPush” de la pasarela de Altiria incluyendo los siguientes par´ ametros: destination=346xxxxxxxx. destination=346yyyyyyyy. url=www.miempresa.com/contenidos/descarga.php?k= Se observa que se desea enviar el contenido multimedia a dos destinatarios y que adem´as la URL acaba con la subcadena “k=”, solicitando entonces la generaci´on de claves identificadoras. 2. La pasarela de Altiria recibe la petici´on y remite dos mensajes WAP-PUSH individuales a los destinatarios seleccionados. Como URL de descarga, los respectivos tel´efonos m´oviles recibir´ an (la segunda parte de la clave es simplemente un ejemplo) : El m´ ovil “346xxxxxxxx”: www.miempresa.com/contenidos/descarga.php?k=346xxxxxxxx12365 El m´ ovil “346yyyyyyyy”: www.miempresa.com/contenidos/descarga.php?k=346yyyyyyyy12365 Adem´ as la pasarela de Altiria responde al cliente un status general “000” y los siguientes datos para cada destinatario: status=000; destination=346xxxxxxxx; key=346xxxxxxxx-12365 status=000; destination=346yyyyyyyy; key=346yyyyyyyy-12365 3. Ambos destinatarios reciben en su tel´efono la solicitud de aceptaci´on de descarga del contenido multimedia. Suponemos que el destinatario con el n´ umero de tel´efono “346xxxxxxxx” acepta la descarga. 4. El servidor WEB del cliente, habilitado para ofrecer los contenidos multimedia, recibe una petici´ on de descarga. La petici´ on estar´a dirigida a la URL http://www.miempresa.com/contenidos/descarga.php?k=346xxxxxxxx-12365 por lo que podr´ a asociarla directamente al destinatario con n´ umero de tel´efono “346xxxxxxxx”. 5. El servidor WEB entrega el contenido al tel´efono del destinatario. 6. El tel´efono del destinatario muestra el contenido.

19

Especificaciones de la Interfaz Web Services para env´ıo de SMS

2.6.

Confirmaci´ on de entrega

El servicio de confirmaci´ on de entrega, solicitado a trav´es del par´ametro “ack” de las operaciones de env´ıo, permite recibir notificaciones con informaci´on sobre el estado de entrega de los mensajes cortos enviados mediante la pasarela. Para tener acceso a este servicio es preciso que el cliente haya notificado a Altiria la direcci´ on de Internet a donde se enviar´ an las informaciones de confirmaci´on de entrega. En caso contrario, las solicitudes de confirmaci´ on de entrega ser´an ignoradas aunque los mensajes s´ı ser´an enviados. Para que el cliente pueda asociar la informaci´on recibida sobre el estado de entrega de un mensaje con el propio mensaje enviado previamente a trav´es de la pasarela, se usar´a el identificador devuelto en la respuesta a las operaciones de envio en la parte “idAck”. Este identificador puede albergar dos tipos de valores: Si en la propia operaci´ on de env´ıo se incluye el par´ametro “idAck” (es opcional), contendr´a ese valor truncado a veinte caracteres y formado solo por caracteres v´alidos. Es importante constatar que el identificador devuelto en este caso solo coincidir´a con el suministrado en la correspondiente operaci´ on de env´ıo si cumple los criterios de composici´on explicados en las tablas 2.3 y 2.5. Si en la propia operaci´ on de env´ıo no se incluye el par´ametro “idAck”, contendr´a un valor num´erico de diez d´ıgitos como m´ aximo generado por la pasarela autom´aticamente. Las notificaciones del estado de entrega ser´an enviadas mediante la operaci´ on sendNotification del servicio web SOAP que debe exponer el cliente de acuerdo al fichero WSDL proporcionado por Altiria para desarrollar este servicio. El cliente debe suministrar la URL donde se acceder´a al servicio web, especificando si se trata de SOAP 1.1 o SOAP 1.2 La codificaci´ on de caracteres en la comunicaci´on con el servicio web del cliente ser´a UTF-8. La operaci´ on sobre el servicio web consta de un u ´nico par´ametro de entrada (tipo Notification) que puede aparecer hasta 100 veces repetido. De este modo en una sola operaci´on se podr´ıan agrupar varias confirmaciones de entrega. Los criterios de agrupaci´on de notificaciones no responder´an a ning´ un par´ ametro fijo, de modo que nada se podr´a predecir a ese respecto. En el cuadro 2.13 se detallan los par´ametros constituyentes del tipo de datos complejo Notification definido en el fichero WSDL del servicio web. Dato destination

idAck

status

Valor N´ umero de tel´efono m´ovil al que se refiere la informaci´on de estado de entrega. Si esa informaci´on es relativa a un mensaje concatenado, el tel´efono figurar´a cualificado con un sufijo que haga referencia al fragmento particular del que se trate, por ejemplo xxxxxxxxxxx(2) (ver la respuesta al enviar un mesaje concatenado en la secci´ on 2.3.1). Identificador que coincidir´a con el suministrado por Altiria al cliente en la parte “idAck” de la respuesta a la operaci´on de env´ıo. El contenido de este campo se ha explicado en el inicio de esta secci´ on. Estado relativo a la entrega del mensaje. Podr´a tomar los valores: “ENTREGADO”, “NO ENTREGADO”, “ERROR 100”, “ERROR 101”, “ERROR 114” o “ERROR 115”.

Cuadro 2.13: Lista de datos de la confirmaci´on de entrega El estado “NO ENTREGADO” aparece cuando el mensaje no puede ser entregado al tel´efono m´ovil. Es un estado definitivo, por lo que ese mensaje particular nunca ser´a entregado. Las causas pueden ser 20

Especificaciones de la Interfaz Web Services para env´ıo de SMS

m´ ultiples, desde que el tel´efono haya estado apagado durante un tiempo superior al periodo de validez, hasta que el n´ umero no exista. En general no se puede conocer la causa. El estado “ERROR 100” indica que el mensaje por el momento no ha podido ser entregado al destinatario debido a alg´ un problema en su tel´efono m´ovil. Las causas m´as comunes son: mala cobertura, buz´ on de mensajes cortos lleno o tel´efono apagado. El mensaje se intentar´a enviar varias veces con posterioridad durante un tiempo limitado. Si el problema en el tel´efono se subsana a tiempo, el mensaje ser´ a finalmente entregado, recibi´endose la correspondiente confirmaci´on. El estado “ERROR 101” indica que el mensaje por el momento no ha podido ser entregado al destinatario debido a alg´ un problema en la red de telefon´ıa m´ovil del operador. Habitualmente, cuando el operador solvente los problemas, el mensaje ser´a entregado, recibi´endose la correspondiente confirmaci´ on. El estado “ERROR 114” indica que el mensaje ha sido enviado pero no ha podido ser entregado porque el n´ umero de tel´efono destinatario no existe. El estado “ERROR 115” indica que el mensaje ha sido enviado pero no ha podido ser entregado porque el destinatario no acepta mensajes. Un ejemplo de notificaci´ on de entrega correspondiente a uno de los fragmentos del env´ıo del SMS concatenado del ejemplo de la operaci´ on sendSms (ver secci´on 2.3.1) ser´ıa este: 346YYYYYYYY(1) 123456789 ENTREGADO Opcionalmente se podr´ıa configurar el env´ıo de las notificaciones de entrega mediante peticiones HTTP POST seg´ un la especificaci´ on relativa a la confirmaci´on de entrega de la pasarela de Altiria a trav´es de HTTP para el env´ıo de SMS. Consultar al soporte t´ecnico de Altiria ([email protected]) para conocer m´ as detalles sobre esta posibilidad. El servicio web del cliente deber´ a responder un u ´nico par´ametro de tipo “String” con un contenido simple como por ejemplo la cadena “OK”. Finalmente para clarificar todos los elementos de la funcionalidad de confirmaci´on de entrega, se esquematizan los procesos involucrados en el env´ıo de un mensaje a dos destinatarios: 1. El cliente efect´ ua un env´ıo de SMS a trav´es de la pasarela de Altiria incluyendo entre otros los siguientes par´ ametros: destination=346xxxxxxxx. destination=346yyyyyyyy. ack=true. idAck=zzzz. 2. La pasarela de Altiria recibe la petici´on y remite el mensaje a los destinatarios seleccionados. Adem´ as la pasarela responde al cliente un status general “000” y los siguientes datos para cada destinatario: status=000; destination=346xxxxxxxx; idAck=zzzz status=000; destination=346yyyyyyyy; idAck=zzzz 21

Especificaciones de la Interfaz Web Services para env´ıo de SMS

Si el cliente no hubiera incluido el par´ametro “idAck” en la operaci´on “sendSms” (punto 1 del ejemplo), la pasarela de Altiria habr´ıa autogenerado el identificador para a˜ nadirlo a la respuesta. 3. Ambos destinatarios reciben en su tel´efono el mensaje corto enviado. 4. El servicio web del cliente, habilitado para recibir las notificaciones de estado de entrega, es accedido desde la pasarela de Altiria , con el par´ametro “notification” por duplicado, conteniendo: destination=346xxxxxxxx; idAck=zzzz; status=ENTREGADO destination=346yyyyyyyy; idAck=zzzz; status=ENTREGADO 5. El servicio web del cliente responde la cadena de texto “OK”. 6. Empleando el identificador zzzz, el cliente podr´a asociar la confirmaci´on de entrega con el mensaje previamente enviado a cada uno de los destinatarios.

22

Especificaciones de la Interfaz Web Services para env´ıo de SMS

2.7.

C´ odigos de estado

El cuadro 2.14 presenta la lista de los posibles c´odigos de estado que podr´an aparecer en la respuesta a cada operaci´ on. ´ CODIGO 000 001 002 010 011 013 014 015 016 017 020 022 030 031 032 033 034

DETALLE ´ Exito Error interno. Contactar con el soporte t´ecnico Error de acceso al puerto seguro 443. Contactar con el soporte t´ecnico Error en el formato del n´ umero de tel´efono Error en el env´ıo de los par´ametros de la operaci´on o codificaci´on incorrecta. El mensaje excede la longitud m´axima permitida La petici´ on HTTP usa una codificaci´on de caracteres inv´alida No hay destinatarios v´alidos para enviar el mensaje Destinatario duplicado Mensaje vac´ıo Error en la autentificaci´on El remitente seleccionado para el env´ıo no es v´alido La url y el mensaje superan la longitud m´axima permitida La longitud de la url es incorrecta La url contiene caracteres no permitidos El puerto destino del SMS es incorrecto El puerto origen del SMS es incorrecto Cuadro 2.14: Lista de los c´odigos de estado

23

Especificaciones de la Interfaz Web Services para env´ıo de SMS

2.8.

Ejemplos

Se presentan extractos de programaci´on en varios lenguajes. Altiria no se responsabiliza del funcionamiento de los ejemplos presentados. Se deben considerar como fragmentos de c´ odigo ilustrativos del acceso a algunas funcionalidades de la pasarela documentada. Con objeto de facilitar la lectura algunas l´ıneas del c´ odigo han sido partidas con saltos de l´ınea que podr´ıan afectar al correcto funcionamiento del programa en su ejecuci´on.

2.8.1.

Env´ıo de un mensaje en PHP

Ejemplo usando NuSOAP (SOAP 1.1) como cliente de los servicios web (ver [NUSOAP]).

2.8.2.

Env´ıo de un mensaje en JAVA

Ejemplo en Java para SOAP 1.2 creando autom´aticamente las clases del servicio web mediante WsImport (ver [WSIMPORT]), herramienta integrada dentro de la propia JDK de Java. Un ejemplo de uso ser´ıa: wsimport -d src -keep http://www.altiria.net/sustituirWSDLUrl?wsdl Se suministra la URL del fichero WSDL www.altiria.net/sustituirWSDLUrl?wsdl. Se debe reemplazar la cadena /sustituirWSDLUrl por la parte correspondiente de la URL suministrada por Altiria para el fichero WSDL en SOAP 1.2 al dar de alta el servicio 25

Especificaciones de la Interfaz Web Services para env´ıo de SMS

try { //Se suministra la URL del fichero WSDL www.altiria.net/sustituirWSDLUrl?wsdl //Se debe reemplazar la cadena /sustituirWSDLUrl por la parte correspondiente //de la URL suministrada por Altiria para el fichero WSDL en SOAP 1.2 al //dar de alta el servicio URL wsdlURL = new URL("http://www.altiria.net/sustituirWSDLUrl?wsdl"); net.altiria.api.soap.SmsGatewayService service = new net.altiria.api.soap.SmsGatewayService(wsdlURL); net.altiria.api.soap.SmsGatewayPort soapApi = service.getSmsGatewayApi(); BindingProvider bp = (BindingProvider)soapApi; //Tiempo maximo de respuesta. bp.getRequestContext().put("com.sun.xml.internal.ws.request.timeout", 60000); //Se preparan los datos del servicio web net.altiria.api.soap.TextMessageRequest textMessageRequest = new net.altiria.api.soap.TextMessageRequest(); //XX, YY y ZZ se corresponden con los valores de identificaci´ on del usuario en el sistema net.altiria.api.soap.Credentials credentials = new net.altiria.api.soap.Credentials(); credentials.setDomainId("XX"); credentials.setLogin("YY"); credentials.setPasswd("ZZ"); textMessageRequest.setCredentials(credentials); net.altiria.api.soap.TextMessage message = new net.altiria.api.soap.TextMessage(); message.setMsg("Mensaje de prueba"); //Se incluye el remitente autorizado por Altiria al dar de alta el servicio. //Omitir el parametro senderId si no se cuenta con ninguno. message.setSenderId("remitente"); textMessageRequest.setMessage(message); textMessageRequest.getDestination().add("346xxxxxxxx"); textMessageRequest.getDestination().add("346yyyyyyyy"); net.altiria.api.soap.TextMessageResponse textMessageResponse = null; try { textMessageResponse = soapApi.sendSms(textMessageRequest); String status = textMessageResponse.getStatus(); if(!status.equals("000")) System.out.println("ERROR. Codigo de Altiria: " + status); else { List destinations = textMessageResponse.getDetails(); for(int i=0;i