Gestión de acciones vía HTTP Action XML API

Gestión de acciones vía HTTP Action XML API LleidaNetworks Serveis Telemàtics, S.L. devel@lleida.net 5 de enero de 2012

ÍNDICE 2 Índice 1. Introducción 4 2. Aspectos generales 4 3. Eventos y Acciones 5 3.1. Eventos.............................. 5 3.2. Acciones.............................. 5 3.3. Parámetros............................ 6 4. DTD s 7 5. Variables del CGI 8 5.1. Variable request.......................... 8 5.2. Elementos comunes........................ 9 5.2.1. Elemento num...................... 9 5.2.2. Elemento lang...................... 10 6. Peticiones 10 6.1. Obtener los números asignados................. 10 6.2. Obtener las acciones configuradas................ 11 6.3. Añadir una acción........................ 12 6.4. Editar una acción......................... 14 6.5. Quitar una acción......................... 14 7. Respuesta del CGI 14 7.1. Elemento request id....................... 15 7.2. Códigos de estado......................... 16 8. Notas de uso 17

Copyright (c) 2012 - LleidaNetworks Serveis Telemàtics, 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.

1 INTRODUCCIÓN 4 1. Introducción La API XML/Action permite acceder a los servicios de configuración de acciones de Lleida Networks mediante consultas HTTP. 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 programación disponen de un excelente soporte para ambos. El uso 2. Aspectos generales El CGI esta situado en http://xml.lleida.net/api/action.cgi. La llamada al CGI debe hacerse preferentemente con el método POST o alternativamente con el método GET 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. O bien, incluir las variables por separado que más adelante se especificaran. 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 elemento <result> son los siguientes: request: 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 que se encuentran detallados en las secciones correspondientes a éstas.

3 EVENTOS Y ACCIONES 5 3. Eventos y Acciones 3.1. Eventos Los eventos se agrupan por MO (Mobile Originated) o por DR (Delivery Report). Estos eventos son los responsables de lanzar la acción o acciones que tenga configurado el usuario. MO SMS: Al recibir un SMS a un numero de Lleida.net MO MMS: Al recibir un MMS a un numero de Lleida.net DR SMS: Al actualizar el estado de un acuse de recibo de un SMS. DR MMS: Al actualizar el estado de un acuse de recibo de un MMS. PDF SMS: Al finalizar de generar el PDF certificado de un SMS tanto enviado como recibido. PDF MMS: Al finalizar de generar el PDF certificado de un MMS tanto enviado como recibido. 3.2. Acciones Existen siete acciones diferentes. Mas adelante se especifica con detalle los campos que se enviaran en cada acción. Cada acción tiene un solo parámetro obligatorio. La accion MAIL CERT es la única acción con el parámetro opcional lang. El valor por defecto es el Español - ES. CGI tiene como parámetro una URL MAIL tiene como parámetro una dirección de correo electrónico MAIL CERT tiene como parámetro una dirección de correo electrónico valida y opcionalmente el idioma del certificado. RESP AUTO SMS tiene como parámetro un texto RESP AUTO MMS tiene como parámetro el nombre de un objeto multimedia MULTIMEDIA OBJECT tiene como parámetro un texto REDIRECT tiene como parámetro un numero de teléfono

3 EVENTOS Y ACCIONES 6 3.3. Parámetros Los tipos de parámetros son: url Debe comenzar con http(s):// email Dirección de correo electrónico valida lang Idioma del certificado. text Texto del SMS como máximo 160 caracteres (un solo SMS). name obj Nombre de un objeto multimedia. number Numero donde se reenviara el SMS. En la siguiente tabla puede observar la relación entre las diferentes acciones y los eventos, junto con el tipo de parámetro que se debe configurar. DR SMS DR MMS MO SMS MO MMS CGI url url url url MAIL email email MAIL CERT email, lang email, lang RESP AUTO SMS text text RESP AUTO MMS name obj name obj MULTIMEDIA OBJECT text text REDIRECT number Actualmente los eventos PDF solo admiten acciones a CGI. Mas adelante se detallan las variables que se enviaran por POST (ver 8). PDF SMS PDF MMS CGI url url

4 DTD S 7 4. DTD s Existe una DTD para la consulta y configuración de las acciones y otra DTD para los resultados. Acciones: Esta DTD muestra como crear el XML de petición de consulta y configuración. http://xml.lleida.net/dtd/action.dtd <!-- 2010 Lleida.net - devel@lleida.net --> <!ELEMENT get_numbers (user,password,request_id?)?> <!ELEMENT get_actions (user,password,request_id?)?> <!ELEMENT set (user,password,event,num,action,value,lang?,request_id?)?> <!ELEMENT edit (user,password,id,value,lang?,request_id?)?> <!ELEMENT unset (user,password,id,request_id?)?> <!ELEMENT user (#PCDATA)> <!ELEMENT password (#PCDATA)> <!ELEMENT num (#PCDATA)> <!ELEMENT event (#PCDATA)> <!ELEMENT action (#PCDATA)> <!ELEMENT value (#PCDATA)> <!ELEMENT lang (#PCDATA)> <!ELEMENT id (#PCDATA)> <!ELEMENT request_id (#PCDATA)> Respuestas: Esta otra DTD muestra el formato de las respuestas. http://xml.lleida.net/dtd/action_result.dtd <!-- 2010 Lleida.net - devel@lleida.net --> <!ELEMENT result (request, status, msg?, user?, request_id?, id?, (numbers a <!ELEMENT request (#PCDATA)> <!ELEMENT status (#PCDATA)> <!ELEMENT msg (#PCDATA)> <!ELEMENT user (#PCDATA)> <!ELEMENT numbers (num*)> <!ELEMENT action_list (action*)> <!ELEMENT action (id, event, type, value, num)> <!ELEMENT id (#PCDATA)> <!ELEMENT event (#PCDATA)>

5 VARIABLES DEL CGI 8 <!ELEMENT type (#PCDATA)> <!ELEMENT value (#PCDATA)> <!ELEMENT num (#PCDATA)> <!ELEMENT request_id (#PCDATA)> 5. Variables del CGI La variable principal del CGI es la variable xml. Por ejemplo en PHP: var enviardatos = xml=.urlencode( <!DOCTYPE get_actions SYSTEM "action.dtd"> <get_actions> <user>usuario</user><password>clave</password> </get_actions> ); El error mas común consiste en enviar el XML sin asignarlo a la variable xml. Las etiquetas también se pueden enviar por separado. En este tipo de envío no existen los elementos raíz del documento XML por lo que deben añadir la variable request (ver 5.1). Por ejemplo y mediante GET: [..]?request=get_actions&user=usuario&password=clave Tenga en cuenta que en las URL se deben codificar correctamente los símbolos especiales. Por ejemplo, %2B que corresponde al símbolo + y %3D corresponde al =. Las URL tienen un limite máximo de caracteres y, por tanto, nosotros recomendamos el uso de POST. Enviar las variables por POST es mas seguro que por GET y no tiene esta limitación de caracteres. 5.1. Variable request La etiqueta request corresponde al elemento raíz de los xml y puede tomar los siguientes valores:

5 VARIABLES DEL CGI 9 get numbers Para obtener los números asignados (ver 6.1) get actions Para obtener las acciones configuradas (ver 6.2) set Para añadir una acción (ver 6.3) edit Para editar una acción existente (ver 6.4) unset Para quitar una acción (ver 6.5) 5.2. Elementos comunes Los elementos comunes, tanto al formato XML como al envío de variables, son: 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 event: Tipo de evento que lanzara la acción (ver 3.1) action: Tipo de acción (ver 3.2) value: Parámetro de la acción (ver 3.3) lang: El idioma de los correos certificados 5.2.1. Elemento num Este elemento debe contener un número de teléfono perteneciente al usuario, o la palabra especial all que significa que la acción se ejecutara para todos los números asignados. <num>%2b34900000000</num> O bien, <num>all</num> 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). Otro punto importante que se debe tener en cuenta es cuando se decide enviar la variable de forma no encapsulada en un documento XML. En el ejemplo anterior:

6 PETICIONES 10 [..]&num=%2b34900000000&[..] O bien, configurando la acción para todos los números asignados. [..]&num=all&[..] 5.2.2. Elemento lang Solo esta disponible para la acción MAIL_CERT y se indica el idioma en que se desea recibir el certificado. Los idiomas disponibles para el certificado son: Código ES CA EU GL EN FR DE IT NL PT SE PL Idioma Español Catalán Euskera Gallego Inglés Francés Alemán Italiano Neerlandés Portugués Sueco Polaco 6. Peticiones 6.1. Obtener los números asignados Para obtener los números de teléfono asignados a un usuario tiene el elemento get numbers. <!DOCTYPE get_numbers SYSTEM "action.dtd"> <get_numbers> <password></password> </get_numbers>

6 PETICIONES 11 Si todo es correcto obtendrá como resultado un XML de este tipo: <!DOCTYPE result SYSTEM "action_result.dtd"> <result> <request>get_numbers</request> <status>100</status> <msg>success</msg> <numbers> <num></num> <num></num>... <num></num> </numbers> </result> Si el usuario no tiene ningún numero asignado la respuesta sera del tipo: <!DOCTYPE result SYSTEM "action_result.dtd"> <result> <request>get_numbers</request> <status>100</status> <msg>success</msg> <numbers /> </result> Si se produce un error ver la sección 7.2. 6.2. Obtener las acciones configuradas Para obtener las acciones configuradas de un usuario tiene el elemento get actions. <!DOCTYPE get_actions SYSTEM "action.dtd"> <get_actions> <password></password> </get_actions>

6 PETICIONES 12 Si todo es correcto obtendrá como resultado un XML de este tipo: <!DOCTYPE result SYSTEM "action_result.dtd"> <result> <request>get_actions</request> <status>100</status> <msg>success</msg> <action_list> <action> <id></id> <event></event> <type></type> <value></value> <num></num> </action>... </action_list> </result> El elemento type es el tipo de acción (ver 3.2). Si el usuario no tiene ninguna acción configurada la respuesta sera del tipo: <!DOCTYPE result SYSTEM "action_result.dtd"> <result> <request>get_actions</request> <status>100</status> <msg>success</msg> <action_list /> </result> Si se produce un error ver la sección 7.2. 6.3. Añadir una acción Se pueden añadir tantas acciones por evento como se necesiten. Con el elemento set puede añadir una acción a un evento. Por ejemplo, añadir la acción CGI al evento MO SMS para todos mis números:

6 PETICIONES 13 <!DOCTYPE set SYSTEM "action.dtd"> <set> <user>mi_usuario</user> <password>mi_clave</password> <event>mo_sms</event> <num>all</num> <action>cgi</action> <value>http://miweb.com/micgi</value> </set> Otro ejemplo, añadir la acción MAIL CERT al evento MO SMS para el numero +34973909090 : <!DOCTYPE set SYSTEM "action.dtd"> <set> <user>mi_usuario</user> <password>mi_clave</password> <event>mo_sms</event> <num>+34973909090</num> <action>mail_cert</action> <value>micorreo@miweb.com</value> <lang>ca</lang> </set> Si se produce un error ver la sección 7.2. Se ha añadido el id de la acción en la respuesta: <!DOCTYPE result SYSTEM "action_result.dtd"> <result> <request>set</request> <status>100</status> <msg>success</msg> <id>12606</id> </result>

7 RESPUESTA DEL CGI 14 6.4. Editar una acción Para editar una acción puede usar el elemento edit. Si existe la acción sobreescribirá los valores. Si no existe la acción devolverá un error. <!DOCTYPE set SYSTEM "action.dtd"> <set> <user>mi_usuario</user> <password>mi_clave</password> <id>9999</id> <value>mi_nuevo_correo@miweb.com</value> <lang>es</lang> </set> 6.5. Quitar una acción Para quitar una acción de un evento debe usar el elemento unset. Por ejemplo para quitar el ejemplo anterior: <!DOCTYPE unset SYSTEM "action.dtd"> <unset> <user>mi_usuario</user> <password>mi_clave</password> <id>9999</id> </unset> 7. Respuesta del CGI Si la petición ha sido correcta el XML de respuesta contiene: <!DOCTYPE result SYSTEM "action_result.dtd"> <result> <request>edit</request> <status>100</status> <msg>success</msg> </result>

7 RESPUESTA DEL CGI 15 Se deben tener en cuenta los casos de error. En cuyo caso las respuestas de los resultados serian del tipo : <!DOCTYPE result SYSTEM "action_result.dtd"> <result> <request>edit</request> <status>-1</status> <msg>xml inválido</msg> </result> En este caso concreto, se ha solicitado una petición de edición de una acción mediante la variable xml pero con un formato desconocido. 7.1. Elemento request id Opcionalmente puede añadir un identificador a sus peticiones. Si añade el elemento request id el CGI añadirá ese token a las respuestas. Por ejemplo si realiza la siguiente petición: <!DOCTYPE get_actions SYSTEM "action.dtd"> <get_actions> <password></password> <request_id>mi_id_88888888</request_id> </get_actions> La respuesta contendrá el token mi id 88888888. <!DOCTYPE result SYSTEM "action_result.dtd"> <result> <request>get_actions</request> <status>100</status> <msg>success</msg> <request_id>mi_id_88888888</request_id> <action_list /> </result>

7 RESPUESTA DEL CGI 16 7.2. Códigos de estado 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 -6 Error temporal. Reintentar -15 Faltan variables -16 Acción desconocida -17 Contenido inválido

8 NOTAS DE USO 17 8. Notas de uso La acción CGI envía mediante una petición POST los siguientes campos: MO SMS: fecha origen destino texto MO MMS: fecha origen destino idmms DR SMS: idacuse estado fecha envio fecha recepcion idsms origen destino texto DR MMS: idacuse estado fecha envio fecha recepcion idmms origen destino

8 NOTAS DE USO 18 PDF SMS: event - PDF SMS src - origen del sms dst - destino del sms cert type - tipo de certificado lang - idioma del certificado ref tsa - referencia del certificado mo - id del mo mt - id del mt mt id - identificador del mensaje del usuario PDF MMS: event - PDF MMS src - origen del mms dst - destino del mms cert type - tipo de certificado lang - idioma del certificado ref tsa - referencia del certificado mmso - id del mmo mmst - id del mms mmst id - identificador del mensaje del usuario Las notificaciones a CGI son de prioridad baja y pueden existir latencias importantes con respecto al evento que las genera. Si desean tener las notificaciones en tiempo real deberán optar por alguna API que use nuestro protocolo.