En los ejemplos de esta documentación se usa el símbolo {:name} para tu nombre de usuario y {:pass} para tu contraseña.

Transcripción

1 HTTP XML API Aspectos generales Permite enviar SMS mediantes consultas HTTP. En los ejemplos de esta documentación se usa el símbolo {:name} para tu nombre de usuario y {:pass} para tu contraseña. La operación de envío de mensajes cortos se invoca mediante la ejecución de un CGI. La llamada debe de hacerse con el método POST del protocolo HTTP. La URL de la API es: 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. El DTD que describe el formato XML a utilizar se puede encontrar en sms.dtd ( Por ejemplo en PHP var enviardatos = 'xml='.urlencode(' <!DOCTYPE sms SYSTEM "sms.dtd"> <txt>el texto del mensaje</txt> '); Elementos comunes Elemento dst Este elemento debe contener uno o más subelementos num, cada uno de los cuales contiene un número de teléfono destinatario del mensaje:

2 de petición <num> </num> <num> </num> <num> </num> Los números de teléfono deben indicarse en formato internacional (es decir, con el signo + al principio del código de país). No hay un límite definido para la cantidad de destinatarios de un mensaje, pero se recomienda no sobrepasar los Tenga en cuenta que en las URL se deben codificar correctamente los símbolos especiales. Por ejemplo en este caso %2B que corresponde al símbolo +. Elemento src Este elemento contiene el remitente del mensaje, 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 15 carácteres. de petición <src>miremitente</src>... 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, enconding 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 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 base64. De este modo se evita el problema deque 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 se encuentra con estos parámetros, primero descodifica el texto de base64, y posteriormente lo importa según el charset especificado. Debe remarcarse que los parámetros enconding y charset no afectan a la codificación del SMS resultante: su única función

3 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. El siguiente ejemplo especifica como texto del SMS la frase "Hello world", pero utilizando la codificación utf-16. <txt encoding="base64" charset="utf-16"> /v8asab1agwababvacaadwbvahiababk </txt> 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, sólo se permiten en el texto del mensaje los caracteres del alfabeto ISO 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 enconding y charset del elemento txt. El siguiente ejemplo envía un SMS que contiene las letras griegas alfa y beta: de petición <num> </num> <txt encoding="base64" charset="utf-16"> /v8dsq0y </txt> <data_coding>unicode</data_coding> 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 mensaje, que pueden ser Delivered, Buffered (fuera de cobertura o apagado), Acknowledged (by

4 the operator SMC) o Rejected. 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 atributos opcionales que se utilizan para activar y configurar el servicio de SMS certificado. En el atributo lang se indica el idioma en que se desea recibir el certificado de recepción, cuyo valor por defecto es Español. El atributo cert_type debe contener el tipo de certificado que se quiere consultar: D para el tipo certificado y T para los contratos. Los atributos cert_name y cert_name_id se utilizan para indicar la razón social y el NIF que aparecerá en la certificación del PDF. Los idiomas disponibles para el certificado son: Código CA DE EN ES FR IT NL PT Código Idioma Catalán Alemán Inglés Español Francés Italiano Neerlandés Portugués Idioma IMPORTANTE: Si se activa el servicio de SMS certificado, el elemento delivery_receipt debe contener el correo electrónico dónde se enviará el certificado de recepción. En caso de no contener el correo electrónico aparecerá el error -8: Correo electrónico incorrecto. de envío de SMS con notificación via

5 <txt>el texto del mensaje</txt> <delivery_receipt> </delivery_receipt> de envío de SMS con petición de estado de entrega sin enviarla a un <txt>el texto del mensaje</txt> <delivery_receipt/> de envío de SMS con certificado de recepción: <txt>el texto del mensaje</txt> <delivery_receipt lang = "ES" cert_type="d"> micorreo@electronico.es </delivery_receipt> Elemento allow_answer Este elemento permite especificar que el envío del mensaje se 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

6 dinámico. Cuando se especifica este elemento no puede aparecer el elemento src. de petición <txt>el texto del mensaje</txt> <allow_answer/> 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. de petición <txt>el texto del mensaje</txt> <mt_id>abcde1234</mt_id> 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 sólo devolverá la información del último mensaje enviado.

7 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. de petición 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:50. <txt>el texto del mensaje</txt> <schedule> </schedule> Formato de respuesta 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 de la 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. Códigos de estado

8 Código Significado -14 SRC inválido -13 MT_ID inválido -12 Error de socket -11 Contacto no encontrado -10 Destinatario inválido -9 MT_ID no encontrado -8 Correo inválido -7 Sesión duplicada -6 Error temporal. Reintentar -5 Texto inválido -4 No hay destinatarios -3 Crédito insuficiente -2 Usuario Inválido -1 XML inválido 0 Error desconocido 100 Correcto Código Envío de SMS Significado El root element del XML debe ser el tag sms. Parámetros user Login del usuario en la plataforma de envíos de SMS de Lleida.net. password Contraseña del usuario en la plataforma de envíos de SMS de Lleida.net. txt El texto del SMS. dst Contiene uno o más elementos num, con los números destino del SMS. src Opcional. Contiene el remitente del mensaje. data_coding Opcional. Especifica la codificación del SMS. delivery_receipt Opcional. Activa la notificación de entrega. allow_answer Opcional. Activa el envío con remitente numérico largo. mt_id Opcional. Especifica un identificador único para el mensaje.

9 schedule Opcional. Especifica la hora en que se desea entregar el mensaje en destino. <num> </num> <num> </num> <txt>el texto del mensaje</txt> Formato de respuesta 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, cuyo valor es el crédito que le queda al usuario después de realizar el envío. Envío de Waplink 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 waplink. Con los envíos del Waplink no se puede activar la opción de SMS Certificado. En el parámetro delivery_receipt los atributos opcionales lang y cert_type no se deben introducir. Parámetros user Login del usuario en la plataforma de envíos de SMS de Lleida.net. password Contraseña del usuario en la plataforma de envíos de SMS de Lleida.net. txt Es el texto que le aparece como comentario del mensaje al destinatario antes de descargar su contenido. dst Contiene uno o más elementos num, con los números destino del SMS. url Enlace web (URL), normalmente será un link a una imagen, melodía o aplicación. delivery_receipt Opcional. Activa la notificación de entrega. <waplink>

10 <url> </url> <txt> Descripción </txt> <delivery_receipt> </delivery_receipt> </waplink> 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. El root element del XML debe ser el tag query_mt_status. Parámetros user Login del usuario en la plataforma de envíos de SMS de Lleida.net. password Contraseña del usuario en la plataforma de envíos de SMS de Lleida.net. mt_id Es el identificador único del mensaje. <query_mt_status> <mt_id>bd4fsa56: </mt_id> </query_mt_status> En este ejemplo se consulta el estado del SMS enviado al número cuyo identificador es BD4fSA56. Formato de respuesta El root element del resultado de la consulta de estado de un SMS es el elemento result, que incluye los subelementos comunes y el elemento mt_status que esta formado por: mt_id Es el identificador único del mensaje. status_code Código de estado del mensaje. status_desc Mensaje descriptivo del estado del mensaje. 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

11 <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:

12 Código Descripción Significado 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 8 Cancelled La entrega del mensaje ha sido cancelada 11 Deleted El mensaje ha sido eliminado por la operadora 4 Delivered El mensaje ha sido entregado al destinatario (se ha recibido confirmación por parte del teléfono móvil). Este estádo sólo está disponible si se activó la notificación de entrega en el envío 10 Expired El mensaje ha expirado por la operadora 6 Failed El mensaje no ha sido entregado 7 Invalid El mensaje es inválido 1 New El mensaje aún no ha sido procesado 2 Pending El mensaje aún no ha sido enviado 9 Scheduled El mensaje está programado y aún no se ha entregado 3 Sent El mensaje ha sido enviado 12 Undeliverable El mensaje no se puede entregar 13 Unknown Estado desconocido Código Descripción Significado 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. También hay disponible la notificación mediante eventos, pueden consultar la Action API ( El root element del documento XML para la consulta de estado es el tag get_new_incoming_mo. Parámetros user Login del usuario en la plataforma de envíos de SMS de Lleida.net. password Contraseña del usuario en la plataforma de envíos de SMS de Lleida.net.

13 <get_new_incoming_mo> </get_new_incoming_mo> Formato de respuesta El root element del resultado de la consulta nuevos mensajes entrantes es el elemento result, que incluye los subelementos comunes y el elemento mo_list, cuyo contenido es una lista de todos los mensajes nuevos disponibles, cada uno de ellos encapsulado dentro de un elmento mo. El elemento mo contiene los siguientes subelementos: 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. <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> <txt>texto del mensaje 1</txt> </mo> <mo> <id>fa439d93c3 </id> <tm_rec> </tm_rec> <src> </src> <txt>texto del mensaje 2</txt> </mo> </mo_list> </result> Si el SMS recibido no está en alfabeto por defecto o en ISO el texto se muestra codificado en base64 y se informa con el atributo encoding con el valor base64 y el atributo charset con el valor UTF-16.

14 <txt encoding="base64" charset="utf-16"> /v8asab1agwababvacaadwbvahiababk </txt> Información de usuario Esta operación devuelve los datos y el estado de la cuenta del usuario. El root element del documento XML para la consulta de estado es el tag userinfo. Parámetros user Login del usuario en la plataforma de envíos de SMS de Lleida.net. password Contraseña del usuario en la plataforma de envíos de SMS de Lleida.net. <userinfo> </userinfo> Formato de respuesta El root element del resultado de la consulta nuevos mensajes entrantes es el elemento result, que incluye los subelementos comunes y el elemento userinfo. <result> <action>userinfo</action> <status>100</status> <msg>success</msg> <userinfo> <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 contactos</ > <organization>nombre de la empresa</organization>

15 <cif>cif de la empresa</cif> <phone_number> <num>número de telefono asignado al usuario</num> </phone_number> </userinfo> </result>