Envío de SMS vía HTTP. HTTP XML API

Transcripción

1 Envío de SMS vía HTTP. HTTP XML API LleidaNetworks Serveis Telemàtics, S.L. 13 de abril de 2012

2 ÍNDICE 2 Índice 1. Introducción 4 2. Aspectos generales Códigos de error Envío de SMS Elemento src Elemento dst Elemento txt Elemento data coding Elemento delivery receipt Elemento allow answer Elemento mt id Elemento schedule Subelementos del elemento <result> para la operación de envío de SMS Envío de Enlaces Web por WAP Consulta de estado de un mensaje Formato de la consulta Subelementos del elemento <result> para la operación de consulta de estado Consulta de nuevos mensajes entrantes Formato de la consulta Subelementos del elemento <result> para la operación de consulta de nuevos mensajes entrantes Consulta la información del usuario Formato de la consulta Subelementos del elemento <result> para la operación de consulta de la información del usuario

3 Copyright (c) - LleidaNetworks Serveis Telematics, S.L. Todos los derechos reservados Este documento contiene información propietaria y confidencial. Queda totalmente prohibido distribuir sus contenidos total o parcialmente por cualquier medio, sea físico o electrónico, sin la autorización expresa de su titular.

4 1 INTRODUCCIÓN 4 1. Introducción La API XML/HTTP permite enviar SMS mediante consultas HTTP, permitiendo acceder a los servicios de mensajería de Lleida Networks desde redes securizadas mediante firewalls que sólo permiten el tráfico saliente de navegación web estándard. Además, al utilizar el protocolo HTTP y el formato XML para la representación de los datos, se asegura una rápida integración con la aplicación del cliente, puesto que la mayor parte de lenguajes de programacion disponen de un excelente soporte para ambos.

5 2 ASPECTOS GENERALES 5 2. Aspectos generales La operación de envío de mensajes cortos se invoca mediante la ejecución del CGI situado en La llamada al CGI debe hacerse con el método POST del protocolo HTTP. La llamada al CGI debe incluir la variable xml, donde se encontrarán los datos de la operación codificados según el formato XML que se describe en las secciones posteriores. Todas las operaciones reciben como respuesta otro documento XML, cuyo nodo raíz es el elemento <result>. Este elemento se compone de varios elementos comunes a todas las operaciones y que siempre están presentes, seguidos de otros elementos específicos para la operación que se ha invocado. Los elementos comunes del tag <result> son los siguientes: action: Contiene un nombre identificativo de la operación que se ha invocado. status: Contiene un código de estado informativo del éxito o error operación. msg: Contiene un texto informativo del éxito o error de la operación Además de estos campos comunes, el elemento <result> incorpora otros elementos específicos según la operación, que se encuentran detallados en las secciones correspondientes a éstas.

6 2 ASPECTOS GENERALES Códigos de error Los códigos de estado que admite el parámetro status son los siguientes: Código Significado 100 Correcto 0 Error desconocido -1 XML inválido -2 Usuario inválido -3 Crédito insuficiente -4 No hay destinatarios -5 Texto inválido -6 Error temporal. Reintentar -7 Sesión duplicada -8 Correo inválido -9 MT ID no encontrado -10 Destinatario inválido

7 3 ENVÍO DE SMS 7 3. Envío de SMS El DTD que describe el formato XML a utilizar para el envío de SMS se puede encontrar en El root element del XML debe ser obligatoriamente el tag sms. Este tag debe contener, al menos, los elementos siguientes: user: Login del usuario en la plataforma de envíos de SMS de LleidaNet password: Contraseña del usuario en la plataforma de envíos de SMS de LleidaNet dst: Contiene uno o más elementos num, con los números destino del SMS txt: El texto del SMS A continuación sigue un ejemplo del formato XML más simple posible para el envío de un SMS: <?xml version="1.0" encoding="iso "?> <sms> <user>miusuario</user> <password>micontrase~na</password> <dst> <num> </num> <num> </num> </dst> <txt>el texto del mensaje</txt> </sms> La tabla siguiente enumera todos los elementos que admite el tag sms: Elemento Opcional Descripción user N Login del usuario password N Contraseña del usuario src S Contiene el remitente del mensaje (ver 3.1)

8 3 ENVÍO DE SMS 8 dst N Contiene los destinatarios del mensaje (ver 3.2) txt N Texto del mensaje (ver 3.3) data coding S Especifica la codificación del SMS (ver 3.4) delivery receipt S Activa la notificación de entrega (ver 3.5) allow answer S Activa el envío con remitente numérico largo (ver 3.6) mt id S Especifica un identificador único para el mensaje. (ver 3.7) schedule S Especifica la hora en que se desea entregar el mensaje en destino. (ver 3.8) 3.1. Elemento src Este elemento contiene el remitente del SMS, el remitente puede ser numérico o alfanumérico. Si el remitente es alfanumérico, éste no puede superar los 11 carácteres de longitud, si es numérico, no puede superar los 12 carácteres. Ejemplo: <sms> <user>miusuario</user> <password>micontrase~na</password> <src>miremitente</src> Elemento dst Este elemento debe contener uno o más sub-elementos <num>, cada uno de los cuales contiene un número de teléfono destinatario del SMS: <dst>

9 3 ENVÍO DE SMS 9 <num> </num> <num> </num> <num> </num> </dst> Los números de teléfono deben indicarse en formato internacional (es decir, con el signo + al principio seguido del código de país). No hay un límite definido para la cantidad de destinatarios de un SMS, pero se recomienda no sobrepasar los Elemento txt El elemento <txt> contiene el texto del SMS que se enviará. En el caso que la longitud del texto sea mayor que el límite de caracteres por SMS (160 en caso de mensajes de texto con codificación ASCII, y 70 en el caso de mensajes en codificación Unicode), el SMSC de Lleida Networks dividirá el mensaje en varios SMS encadenados. Este elemento dispone de dos parámetros opcionales, encoding y charset, para el caso que el texto del mensaje esté en una codificación diferente de la especificada en la cabecera del XML. Un ejemplo sería el caso que el XML esté codificado en ISO (latin) y se quiera enviar un SMS en Unicode. Si el texto del mensaje está en una codificación diferente de la del XML, el parámetro encoding debe tener el valor base64, y el contenido del elemento <txt> debe estar codificado en base 64. De este modo se evita el problema de que el XML no sea válido por encontrar caracteres no permitidos en la codificación utilizada. Además, el parámetro charset debe contener el código de caracteres utilizado (por ejemplo, utf-16 para codificación Unicode). Cuando el servidor de la API XML/HTTP se encuentra con estos parámetros, primero descodifica el texto de base 64, y posteriormente lo importa según el charset especificado. Debe remarcarse que los parámetros encoding y charset no afectan a la codificación del SMS resultante: su única función es poder incluir texto en cualquier charset dentro del XML. La codificación que tendrá el SMS cuando se envíe depende del contenido del elemento data_coding (ver sección 3.4). El siguiente ejemplo especifica como texto del SMS la frase Hello world, pero utilizando la codificación utf-16:

10 3 ENVÍO DE SMS 10 <txt encoding="base64" charset="utf-16"> /v8asablagwababvacaadwbvahiababk </txt> 3.4. Elemento data coding Este elemento opcional controla la codificación en que se enviará el SMS (ver la especificación de la 3GPP número TS ). Los dos valores permitidos son: text (valor por defecto), y unicode. Si se especifica el valor text, sólo se permiten en el texto del mensaje los caracteres del alfabeto GSM (la mayor parte de los caracteres ASCII). En cambio, con el valor unicode se puede utilizar caracteres de cualquier alfabeto del mundo (siempre y cuando el teléfono receptor lo permita), ya que el SMS es enviado en utf-16. Si se mandan SMS Unicode, probablemente deberá combinar este elemento junto con los parámetros encoding y charset del elemento <txt>. El siguiente ejemplo envía un SMS que contiene las letras griegas alfa y beta: <?xml version="1.0" encoding="iso "?> <sms> <user>miusuario</user> <password>micontrase~na</password> <dst> <num> </num> </dst> <txt encoding="base64" charset="utf-16"> /v8dsqoy </txt> <data_coding>unicode</data_coding> </sms> 3.5. Elemento delivery receipt Este elemento activa la petición de notificación de entrega para el SMS. El elemento puede estar vacío, o contener una dirección de correo electrónico. Si contiene una dirección de correo electrónico, se enviará un mail a esta dirección cuando la operadora notifique algún cambio de estado del SMS, que

11 3 ENVÍO DE SMS 11 pueden ser Entregado, Encolado (fuera de cobertura o apagado), Entregado a la operadora o Fallado. Si el elemento aparece vacío, se activa igualmente la petición de notificación. Cuando se reciba, el estado del mensaje se anota en las bases de datos del SMSC de Lleida Networks, y puede ser consultado mediante la intranet de usuario. Este elemento dispone de cuatro parámetros opcionales, lang, cert_type, cert_name y cert_name_id, que se utilizan para activar y configurar el servicio de SMS certificado. En el parámetro lang se indica el idioma en que se desea recibir el certificado de recepción. Si el elemento delivery_receipt no contiene el parámetro lang el certificado se enviará en Español. Los parámetros cert_name y cert_name se utilizan para indicar la Razón social y el NIF dinámico que aparecerá en la certificación del PDF, para poder configurar estos datos en cada envío. Los idiomas disponibles para el certificado son: Código ES CA EN FR DE IT NL PT Idioma Español Catalán Inglés Francés Alemán Italiano Neerlandés Portugués El parámetro cert_type debe contener el tipo de certificado que se quiere consultar. Actualmente sólo hay disponible un certificado, por este motivo, el parámetro cert_type debe conter el valor D (de certificado por defecto). Ejemplo de envío de SMS con notificación vía mail: <?xml version="1.0" encoding="iso "?>

12 3 ENVÍO DE SMS 12 <sms> <user>miusuario</user> <password>micontrase~na</password> <dst> <num> </num> <num> </num> </dst> <txt>el texto del mensaje</txt> <delivery_receipt> </delivery_receipt> </sms> Ejemplo de envío de SMS con petición de estado de entrega sin enviarla a un mail: <?xml version="1.0" encoding="iso "?> <sms> <user>miusuario</user> <password>micontrase~na</password> <dst> <num> </num> <num> </num> </dst> <txt>el texto del mensaje</txt> <delivery_receipt/> </sms> Ejemplo de envío de SMS con certificado de recepción: <?xml version="1.0" encoding="iso "?> <sms> <user>miusuario</user> <password>micontrase~na</password> <dst> <num> </num> <num> </num> </dst>

13 3 ENVÍO DE SMS 13 <txt>el texto del mensaje</txt> <delivery_receipt lang="es" cert_type="d"> </delivery_receipt> </sms> Ejemplo de envío de SMS con certificado de recepción con la Razón social y el NIF configurado: <?xml version="1.0" encoding="iso "?> <sms> <user>miusuario</user> <password>micontrase~na</password> <dst> <num> </num> <num> </num> </dst> <txt>el texto del mensaje</txt> <delivery_receipt lang="es" cert_type="d" cert_name="mi empresa" cert_name_id="a "> micorreo@electronico.es </delivery_receipt> </sms> 3.6. Elemento allow answer Este elemento permite especificar que el envío del mensaje ser realice con un remitente numérico largo para que el destinatario pueda responderlo. Si el usuario tiene un número própio asignado se utilizará éste, sino se asignará uno dinámico. Cuando se especifica este elemento no puede aparecer el elemento <src>. Ejemplo: <?xml version="1.0" encoding="iso "?> <sms> <user>miusuario</user> <password>micontrase~na</password>

14 3 ENVÍO DE SMS 14 <dst> <num> </num> <num> </num> </dst> <txt>el texto del mensaje</txt> <allow_answer/> </sms> 3.7. Elemento mt id Este elemento permite que el usuario asigne un identificador único para cada mensaje, que posteriormente se puede utilizar para consultar el estado del mensaje. El contenido del elemento debe ser una cadena alfanumérica única, a la que posteriormente el sistema añadirá el número de destino para formar el identificador. Ejemplo: <?xml version="1.0" encoding="iso "?> <sms> <user>miusuario</user> <password>micontrase~na</password> <dst> <num> </num> <num> </num> </dst> <txt>el texto del mensaje</txt> <mt_id>abcde1234</mt_id> </sms> Tal como se ha indicado, el sistema añade el teléfono de destino al identificador para poder gestionar el caso de multienvíos. En el ejemplo anterior, el identificador generado para el primer mensaje sería ABCDE1234: , y para el segundo sería ABCDE1234: IMPORTANTE: Si con el mismo mt_id se repite el destinatario, la consulta de estado (ver 5) sólo devolverá la información del último enviado.

15 3 ENVÍO DE SMS Elemento schedule Con este elemento se puede especificar la fecha y hora en que se desea que se entregue el mensaje en destino. De este modo es posible realizar un envío de mensajes programado a una fecha y hora concretas. El formato de la fecha debe ser YYYYMMDDhhmm. Ejemplo: <?xml version="1.0" encoding="iso "?> <sms> <user>miusuario</user> <password>micontrase~na</password> <dst> <num> </num> <num> </num> </dst> <txt>el texto del mensaje</txt> <schedule> </schedule> </sms> Este ejemplo programaría el mensaje de texto para ser entregado a los dos destinatarios el día 1 de Diciembre del 2007 a las 13: Subelementos del elemento <result> para la operación de envío de SMS Si una operación de envío de SMS termina con éxito, el elemento <result> contiene, además de los tres elementos comunes, el elemento <newcredit>. Este sub-elemento contiene el crédito que le queda al usuario después de realizar el envío.

16 4 ENVÍO DE ENLACES WEB POR WAP Envío de Enlaces Web por WAP El formato del cuerpo del mensaje para este tipo de envios es parecido al de enviar un SMS. El teléfono recibirá un mensaje de navegador (mensaje WAP) con el comentario que se envía y la URL para entrar a la página o descargarse el contenido. El root element del XML debe ser obligatoriamente el tag waplink. Este tag debe contener, al menos, los elementos siguientes: user: Login del usuario en la plataforma de envíos de SMS de LleidaNet password: Contraseña del usuario en la plataforma de envíos de SMS de LleidaNet dst: Contiene uno o más elementos num, con los números destino del WapLink url: Enlace web (URL), normalmente será un link a una imagen, melodía o aplicación txt: Es el texto que le aparece como comentario del mensaje al destinatario antes de descargar su contenido A continuación sigue un ejemplo del formato XML más simple posible para el envío de un WAPLINK: <waplink> <user>miusuario</user> <password>micontrase~na</password> <dst> <num> </num> <num> </num> </dst> <url> </url> <txt> Descripción </txt> <delivery_receipt> micorreo@electronico.es </delivery_receipt> </waplink>

17 4 ENVÍO DE ENLACES WEB POR WAP 17 La tabla siguiente enumera todos los elementos que admite el tag waplink: Elemento Opcional Descripción user N Login del usuario password N Contraseña del usuario dst N Contiene los destinatarios del mensaje (ver 3.2) url N Enlace web (URL) txt N Comentario de la URL delivery receipt S Activa la notificación de entrega (ver 3.5) Con los envíos de WapLink no se puede activar la opción de SMS Certificado. En este caso los parámetros opcionales lang y cert_type no se deben introducir.

18 5 CONSULTA DE ESTADO DE UN MENSAJE Consulta de estado de un mensaje Mediante este comando se puede consultar el estado de un MT. Esta opción sólo es posible si el envío se realizó especificando un identificador mediante el tag mt_id Formato de la consulta El root element del documento XML para la consulta de estado es el tag query_mt_status. Dentro de este elemento deben aparecer obligatoriamente los siguientes campos: user: Login del usuario en la plataforma de envíos de SMS de LleidaNet password: Contraseña del usuario en la plataforma de envíos de SMS de LleidaNet mt id: Identificador del mensaje que había proporcionado el usuario en el envío. Ejemplo: <?xml version="1.0" encoding="iso "?> <query_mt_status> <user>miusuario</user> <password>micontrase~na</password> <mt_id>bd4fsa56: </mt_id> </query_mt_status> 5.2. Subelementos del elemento <result> para la operación de consulta de estado El root element del resultado de la consulta de estado de un MT es el elemento <result>, que incluye los subelementos comunes (ver sección 2) y el elemento <mt_status>. El elemento <mt_status> contiene los siguientes subelementos: mt id: El identificador del mensaje del qual se ha pedido el estado. status code: Código de estado del mensaje. status desc: Mensaje descriptivo del estado del mensaje.

19 5 CONSULTA DE ESTADO DE UN MENSAJE 19 tm last update: Unix timestamp de la hora de la última modificación en el estado del mensaje. credits: Cantidad de créditos que ha consumido este envío. num parts: Cantidad de partes que forma este envío. Ejemplo: <?xml version="1.0" encoding="iso "?> <result> <action>query_mt_status</action> <status>100</status> <msg>success</msg> <mt_status> <mt_id>bd4fsa56: </mt_id> <status_code>3</status_code> <status_desc>sent</status_desc> <tm_last_update> </tm_last_update> <credits>3.2</credits> <num_parts>2</num_parts> </mt_status> </result> Los códigos de estado posibles son los siguientes: Código Descripción Significado 1 New El mensaje aún no ha sido procesado 2 Pending El mensaje aún no ha sido enviado 3 Sent El mensaje ha sido enviado 4 Delivered El mensaje ha sido entregado al destinatario (se ha recibido confirmación por parte del teléfono móvil). Este estado sólo está disponible si se activó la notificación de entrega en el envío 5 Buffered El mensaje ha sido entregado a la operadora pero aún no al destinatario (el teléfono móvil estaba apagado o fuera de cobertura. La operadora lo entregará en cuanto el móvil esté disponible. Este estado sólo está disponible si se activó la notificación de entrega en el envío

20 5 CONSULTA DE ESTADO DE UN MENSAJE 20 6 Failed El mensaje no ha sido entregado 7 Invalid El mensaje es inválido 8 Cancelled La entrega del mensaje ha sido cancelada 9 Scheduled El mensaje está programado y aún no se ha entregado 10 Expired El mensaje ha expirado por la operadora 11 Deleted El mensaje ha sido eliminado por la operadora 12 Undeliverable El mensaje no se puede entregar 13 Unknown Estado desconocido

21 6 CONSULTA DE NUEVOS MENSAJES ENTRANTES Consulta de nuevos mensajes entrantes La plataforma de mensajería de Lleida Networks permite tanto el envío como la recepción de mensajes. El esquema a utilizar para la recepción de mensajes es de tipo polling, en el cual el cliente interroga periódicamente al sistema y éste responde con los mensajes nuevos que han llegado desde la última petición Formato de la consulta El root element del documento XML para la consulta de estado es el tag get_new_incoming_mo. Dentro de este elemento deben aparecer obligatoriamente los siguientes campos: user: Login del usuario en la plataforma de envíos de SMS de LleidaNet password: Contraseña del usuario en la plataforma de envíos de SMS de LleidaNet 6.2. Subelementos del elemento <result> para la operación de consulta de nuevos mensajes entrantes El root element del resultado de la consulta nuevos mensajes entrantes es el elemento <result>, que incluye los subelementos comunes (ver sección 2) y el elemento <mo_list>. El elemento <mo_list> contiene una lista de todos los mensajes nuevos disponibles, cada uno de ellos encapsulado dentro de un elemento mo. El elemento mo contiene los siguientes sub-elementos: id: Identificador del mensaje entrante. tm rec: Unix timestamp de la fecha de recepción del mensaje. src: Número de origen (remitente) del mensaje. dst: Número de destino del mensaje. txt: Texto íntegro del mensaje. Ejemplo:

22 6 CONSULTA DE NUEVOS MENSAJES ENTRANTES 22 <?xml version="1.0" encoding="iso "?> <result> <action>get_new_incoming_mo</action> <status>100</status> <msg>success</msg> <mo_list> <mo> <id>fa439d93c2</id> <tm_rec> </tm_rec> <src> </src> <dst> </dst> <txt>texto del mensaje 1</txt> </mo> <mo> <id>fa439d93c3</id> <tm_rec> </tm_rec> <src> </src> <dst> </dst> <txt>texto del mensaje 2</txt> </mo> </mo_list> </result> Si el SMS recibido no está en alfabeto por defecto o en latin-1 el texto se muestra encodeado en base64 y se informa con el parámetro del tag <txt> encoding, con el valor base64. Si el SMS recibido está en unicode se informa en el parámetro del tag <txt> charset, con el valor UTF-16. <txt encoding="base64" charset="utf-16"> /v8asablagwababvacaadwbvahiababk </txt>

23 7 CONSULTA LA INFORMACIÓN DEL USUARIO Consulta la información del usuario Esta operación devuelve los datos y el estado de la cuenta del usuario Formato de la consulta El root element del documento XML para la consulta de estado es el tag userinfo. Dentro de este elemento deben aparecer obligatoriamente los siguientes campos: user: Login del usuario en la plataforma de envíos de SMS de LleidaNet password: Contraseña del usuario en la plataforma de envíos de SMS de LleidaNet 7.2. Subelementos del elemento <result> para la operación de consulta de la información del usuario El root element del resultado de la consulta nuevos mensajes entrantes es el elemento <result>, que incluye los subelementos comunes (ver sección 2) y el elemento <userinfo>. Ejemplo: <result> <action>userinfo</action> <status>100</status> <msg>success</msg> <userinfo> <user>login del usuario</user> <credit>el credito del usuario</credit> <status>estado del usuario</status> <created>timestamp de la fecha de creacion</created> <lastop>timestamp de la ultima operacion</lastop> <contact_name>persona de contacto</contact_name> <phone>telefono</phone> < >mail de contacto</ > <organization>nombre de la empresa</organization> <cif>cif de la empresa</cif> <phone_number> <num>numero de teléfono asignado al usuario</num> </phone_number>

24 7 CONSULTA LA INFORMACIÓN DEL USUARIO 24 </userinfo> </result>