Guía integración SMS Premium Gateway - v 1.1 / MobiAdvanced.com Última Revisión. 15/07/2010. Gateway SMS Premium. Idioma: Español - España

Transcripción

1 Gateway SMS Premium Idioma: Español - España MobiAdvanced.com es es un un producto de de Sponsorocio, S.L. CIF: B Madrid -- España

2 Información general Introducción MobiAdvanced es una plataforma que permite ofrecer medios de pago vía teléfono móvil a través de SMS Premium, los cuales pueden ser integrados y automatizados con otras aplicaciones, webs u otros medios. MobiAdvanced también ofrece herramientas de uso útil, relacionadas con los pagos mediante SMS Premium y diferentes servicios relacionados con sistemas de pago y marketing móvil. Descripción de responsabilidad MobiAdvanced no ofrece garantía de ningún tipo, ya sea expresa, implícita o legal sobre el contenido declarado en este documento, MobiAdvanced no asume ninguna responsabilidad por los daños directos o indirectos que pueda ocasionar el uso del documento o los ejemplos de código indicados en el mismo. MobiAdvanced se reserva el derecho a realizar cambios y correcciones del documento sin previo aviso. MobiAdvanced no garantiza que este documento siga siendo válido en el futuro. Antes del uso de este documento, se recomienda revisar si este documento es la última versión del mismo. Documento Este documento describe como realizar una integración de la herramienta Gateway ofrecida por MobiAdvanced. Pese a que la integración de esta herramienta ofrece métodos sencillos de implementación para el uso del mismo es necesario tener un mínimo de conocimiento en desarrollo web, estándares de comunicación HTTP y lenguajes estándares de comunicación web. Este documento está enfocado al detalle técnico de la integración y no al funcionamiento de cada tipo de servicio o método de pago que pueda ser integrado. Cuando se vaya a realizar la integración, debe tener en cuenta los detalles técnicos y legales de cada método de pago integrado. Es de alta importancia que conozca estos detalles referentes a cada método. *Solicite información en caso de no disponer de ella. Audiencia Este documento está dirigido a desarrolladores y comerciantes clientes de MobiAdvanced que requieren integrar sus servicios de pago antes de ponerlos en producción.

3 Definiciones e información básica necesaria. A continuación se describen una serie de conceptos y definiciones las cuales son necesarias conocer antes de realizar cualquier tipo de integración con MobiAdvanced. SMS Premium Se definen como SMS Premium, los SMS que tienen un coste adicional a cambio de recibir un servicio extra. El proceso básico de un pago mediante SMS Premium se podría resumir de la siguiente forma: El usuario envía un SMS a un número corto, este SMS es entregado a la operadora de telefonía, posteriormente la operadora entrega el SMS al proveedor del servicio y este responde al usuario un SMS indicando el servicio contratado. Al usuario se le aplica una tarifa especial en su factura telefónica, pasado un periodo de tiempo definido, al prestador del servicio se le pagará un porcentaje del total de ese SMS cobrado al usuario en su factura telefónica. SMS MO Un SMS MO es aquel que se origina en el terminal del usuario ( Mobile Originated ), por ejemplo cuando el usuario escribe un SMS para solicitar un servicio. SMS MT Un SMS MT es aquel que se entrega en el terminal del usuario ( Mobile Terminated ), por ejemplo cuando el usuario recibe un SMS de respuesta de un servicio. SMS Premium con opt-in simple Este tipo de SMS Premium es el más común. El usuario envía un SMS-MO, y recibe un SMS-MT con la información del servicio solicitado, opt-in podría ser entendido como confirmación, en este tipo de SMS Premium, se entiende como opt-in simple, ya que el usuario al enviar el primer SMS- MO ya estaría realizando una confirmación.

4 SMS Premium con doble opt-in Este tipo de SMS Premium es usado en rangos de precio más altos de lo común, o algunos tipos suscripciones premium. El usuario envía un primer SMS-MO solicitando el servicio, se responde un SMS-MT el cual indica el servicio que se va contratar y solicita un SMS-MO de confirmación como respuesta, una vez el usuario responde ese SMS-MT, se responde un SMS-MO informando del servicio contratado. Se entiende como doble opt-in por el hecho en el cual el usuario hace una primera confirmación con un SMS-MO solicitando el servicio y luego se le solicita un segundo SMS-MO de confirmación. MO Servicio Se entiende como el SMS-MO en el cual el usuario solicita el servicio. También definidos como MO1 MO Optin SMS-MO en el cual envía su confirmación del servicio en el caso de los SMS Premium de doble opt-in. También definidos como MO2 MT Servicio SMS-MT en el cual se indica el servicio contratado. También definidos como MT1 MT Optin SMS-MT en el que se envía la información del servicio que se va contratar y/o se solicita una confirmación para completar el servicio. En algunos métodos de pago y/o excepciones de operadores, se requiere de el envío de un MT-optin con información del servicio a contratar. También definidos como MT2 MT Extra en algunos casos por la naturaleza del servicio contratado, es requerido enviar más de un MT, por ejemplo en el caso que se responde un texto superior al número de caracteres y se requiere de un MT-extra para completar el texto. también definidos como MT3 Modelo de facturación El modelo de facturación varía según el método de pago, indica en que momento de la transacción, se aplica el cargo al usuario.

5 Modelo de facturación Billing-MO El cargo se aplica cuando el usuario realiza el envío del primer MO de servicio. Por ejemplo si el usuario es prepago y no dispone de crédito, no podrá realizar el envío para solicitar el servicio. Modelo de facturación Billing-MT El cargo se aplica una vez que el usuario recibe el MT de servicio. Ciclo de venta El cliclo de venta define el el proceso y tipo de SMS requeridos para completar una transacción y que está pueda ser retribuida. El ciclo de venta puede variar según el método de pago y/o operadora de telefonía. 1 - Ejemplo: Un método de pago puede requerir un ciclo de venta de MO-servicio + MT-servicio, si el usuario no recibe el MT de servicio, la transacción no será completada, con lo que ese SMS no será retribuido. Puede darse el caso en el que un mismo método de pago se apliquen diferentes ciclos de venta según el operador de telefonía. 2 - Ejemplo: En el operador A, se requiere MO-Servicio + MT-Servicio y en el operador B se requiere MO-Servicio + MT-servicio + MT-optin (como se indicaba anteriormente un MT-Optin puede ser usado como método informativo en SMS Premium de opt-in simple). Tiempo de ciclo de venta Según el método de pago y/o operador, existe un tiempo máximo para completar un ciclo de venta una vez concluido ese tiempo, la transacción se marcará como incompleta y no será retribuida.

6 Tipos de SMS El tipo de mensaje puede variar según el tipo de contenido y su formato, la plataforma MobiAdvanced admite los siguientes tipos de mensajes, ( El tipo de mensajes admitidos varía según le método de pago ) si planea usar tipos de mensaje diferentes a SMS-TEXT consulte su disponibilidad en el método de pago, antes de realizar su integración. SMS-TEXT Mensajes de texto común, admite hasta 160 caracteres y el juego de caracteres GSM 3.38 juego de caracteres de 7bit. (la longitud admitida puede variar, según el método de pago debido a las condiciones legales y la necesidad de incluir información informativa obligatoriamente). SMS-FLASH Mensajes de texto mostrado en pantalla, admite hasta 160 caracteres y el juego de caracteres GSM 3.38 juego de caracteres de 7bit. (la longitud admitida puede variar, según el método de pago debido a las condiciones legales y la necesidad de incluir información informativa obligatoriamente). SMS-WAP Mensajes en formato WAP, estos pueden incluir una URL que será incluida en el mensaje WAP de hasta 255 caracteres y un texto que será incluido como anchor de esa URL, de hasta 55 caracteres usando el juego de caracteres GSM SMS-UCS2 Mensajes con codificación UCS2, admite hasta 70 caracteres, este tipo de mensajes soportan la mayoría de caracteres internacionales (la longitud admitida puede variar, según el método de pago debido a las condiciones legales y la necesidad de incluir información informativa obligatoriamente). SMS-UDH Mensajes de tipo user-defined-header, permite definir el header de codificación del SMS y el contenido, suelen ser usados para enviar contenidos especiales como pueden ser Logos de operador, Ringtones de fabricante etc.

7 Concepto básico de Gateway La herramienta de Gateway proporciona una pasarela de comunicación transparente entre la plataforma de MobiAdvanced y una aplicación externa. De este modo en el momento que se realicen transacciones SMS Premium, estás serán informadas a la aplicación externa de forma automática. a continuación se detallan los diferentes métodos de configuración y posibles opciones de uso. Todas las opciones de configuración podrán ser definidas en el panel de control de la herramienta. No todas las opciones indicadas en el documento son disponibles por defecto. Si requiere de alguna opción no definida por defecto deberá comunicarlo con los administradores. Tipos de integración La herramienta Gateway de MobiAdvanced proporciona dos métodos de integración, que difieren según el método de respuesta elegido. 1. HTTP - Respuesta directa en el contenido Los SMS-MT s de respuesta necesarios para completar la transacción, son respondidos en el contenido de la petición HTTP realizada por la plataforma de MobiAdvanced. Esta opción requiere de menor conocimiento técnico, es recomendada en la mayoría de los casos que se requiera una integración rápida y simple. Como desventaja requiere que el contenido de respuesta, sea generado en el mismo instante que se realiza la petición. 2. HTTP - Respuesta asíncrona vía API Los SMS-MT s son respondidos de forma asíncrona en un momento diferente al que se realiza la petición de notificación, la notificación de los MT s se realiza mediante el API de MobiAdvanced, es necesario que su usuario disponga de API KEY para el uso del API. En los dos modelos de integración es necesario disponer de una URL donde se notificarán las transacciones. Esta URL puede ser definida y modificada en cualquier momento por el usuario, pudiendo ser HTTP o HTTPS. En la siguiente sección encontrará información sobre las notificaciones HTTP.

8 Gestión de Opt-in La herramienta Gateway de MobiAdvanced dispone de dos opciones a la hora de tratar con métodos de pago que requieren de MT-Optin. 1. Opt-in gestionado por el sistema Opción por defecto, delega el trabajo a MobiAdvanced de responder los MT s Opt-in requeridos para completar los ciclos de venta. Es la opción recomendad por defecto ya que usted solo deberá responder el MT de servicio. 2. Opt-in gestionado por el usuario El usuario es el encargado de responder los MT-optin, pudiendo ser detallados por el usuario. está opción no está disponible por defecto, si requiere de su uso, póngase en contacto con la administración de MobiAdvanced. El contenido y nomenclaturas usados en los MT-optin varían según el método de pago, debe ser consciente de las reglas y leyes de cada método de pago y/o país de uso ya que es imperativo seguir estas normas. Notificaciones HTTP En cada transacción la plataforma de MobiAdvanced notificará con una petición HTTP a la URL indicada en la configuración de la herramienta. La notificación debe completarse con respuesta HTTP CODE 200 en caso de no responderse con HTTP CODE 200 la petición será definida marcada como error y se iniciara el proceso de control de errores. La notificación HTTP permite dos tipos de métodos para enviar los datos HTTP POST y HTT GET, los 2 métodos usan el mismo nombre de variables, puede ser elegido y modificado desde el panel de control de su herramienta.

9 Variables notificación HTTP Nombres de variables A continuación se detalla el conjunto de variables enviadas por los métodos HTTP POST y HTT GET, el nombre de estas es idéntico para los 2 métodos. La codificación de caracteres usada es UTF-8 para todos los campos. Nombre Tipo Valor id_psms_sale_transaction id_psms_sale id_psms_cmp psms_cmp_title operator_mcc operator_mnc operator_code operator_title psms_method_sc_number psms_method_sc_price psms_method_sc_currency psms_method_sc_price_vat psms_method_billing_mode psms_method_lang psms_method_country psms_sale_mo_number psms_sale_mo_type psms_sale_mo_time psms_sale_mo_data psms_sale_alias psms_sale_alias_sub psms_sale_track psms_sale_cicle_type psms_sale_cicle_time psms_sale_simulated psms_sale_redirected psms_cmp_alias_product_value psms_cmp_alias_product_name Varchar(32) Varchar(32) int(9) varchar(128) int(3) int(3) varchar(16) varchar(64) int(10) float(6,3) ISO float(4,2) String(mt, mo) ISO ISO varchar(16) MO1 o MO2 timestamp varchar(160) varchar(32) varchar(32) varchar(32) int(2) int(3) Enum(Y, N) Enum(Y, N) int(11) varchar(64) Referencia única por SMS EJ: MO es recomendable que guarde este valor para evitar duplicidades ID de la transacción no único puede ser el mismo para un MO de servicio y para un MO Opt-in que pertenecen a la misma venta. ID interno de la campaña en MobiAdvanced Título que definió en su campaña. Código MCC del operador Código MNC del operador se usa como identificador único para conocer el operador. ( ver lista de operadores ) Código de texto indica el nombre del operador ( puede no ser único ) para determinar el operador usar MCC+MCN Nombre descriptivo del operador. Número corto del método de pago donde se envía el MO Importe del método de pago en la moneda local del país. Moneda del método de pago. Porcentaje de impuesto que se aplica en el país de la venta. tipo de facturación que se aplica ( ver definiciones ) billing-xx Lenguaje por defecto para el método - Alpha 2 Letras. País del método de pago Alpha 2 letras Número del cliente que envía el SMS-MO. Indica si es un MO de servicio o MO de confirmación Opt-in MO1 = MO de servicio MO 2 = MO Opt-in. inicio de la transacción, Formato: YYYY-mm-dd hh:ii:ss Contenido completo del mensaje que se envió, incluye ALIAS Palabra clave principal, por la que se determina la campaña Sub palabra clave (opcional) Parámetro adicional para seguimiento de la venta (opcional) Indica el tipo de ciclo necesario para completar la transacción. (ver tipos de ciclo de venta documento) Tiempo máximo del ciclo en minutos. SI el mensaje es una simulación. SI el mensaje es re-dirigido de un alias sin asignar. Por ejemplo si propietario de un número corto de forma exclusiva, y ha definido que los SMS que no se reconozca su alias se re-dirijan a otro alias. Valor virtual que definió al producto de al alias (opcional) Nombre virtual que definió a el producto del alias (opcional)

10 Control de errores La plataforma de MobiAdvanced dispone de un avanzado control de errores y un log de consulta. existen dos tipos de errores. 1. Error Indican los motivos por los cuales no se ha podido concluir una transacción correctamente. Algunas de las causas: 1. La URL indicada en la configuración, no responde o responde un código incorrecto. 2. La configuración de respuesta o el contenido es incorrecto. 3. No se respondió los MTs necesarios antes de acabar el tiempo del ciclo de venta. 4. La petición tardo más de 10 segundos en responder. Este tipo de errores son guardados en el log que podrá ver en la configuración de su herramienta. En el momento que se producen este tipo de errores, se inicia el siguiente proceso: 1. Se re-intenta la notificación pasado 1 minuto. 2. Si el problema continua se re-intenta cada minuto, hasta 1 minuto antes de completar el tiempo máximo del ciclo de venta. 3. Llegado al último intento, la transacción se responde con el MT de error por defecto configurado en el panel de la herramienta. 4. Se notifica vía de la incidencia al contacto técnico definido en MobiAdvanced.

11 2. Warning ( alertas ) Este tipo de alertas se generan cuando las respuestas no fueron correctas pero el servicio si se pudo concluir. Algunos ejemplos de causas son: 1. El texto fue demasiado largo y fue cortado. 2. Algunos caracteres se han reemplazado por su similar en el GSM Algunos caracteres se han tenido que eliminar. Este tipo de alertas no son notificadas vía , pero se guardarán en el log de la herramienta. Si se acumula una gran cantidad de este tipo de alertas será notificado vía , con el fin de que solucione el problema.

12 HTTP respuesta en contenido Si está realizando la integración con el modelo de respuesta directa en contenido, podrá indicar el contenido y tipo de los SMS-MT s necesarios para la respuesta. podrá indicar la respuesta de varios MT s siguiendo un patrón indicado que varía según el modelo de respuesta elegido. El modelo de respuesta elegido soporta tres tipos de lenguaje y/o estándares de comunicación. Texto plano, JSON y XML. Usted puede usar cualquiera de estos métodos, seleccionándolo en la configuración de su campaña. No obstante JSON podría ser la más recomendada y menos propensa a errores de codificación y formato. Este modelo de respuesta MT en contenido, dispone de algunos sistemas de control de status y control de error. En caso de que lo requiera usted podrá forzar un error según el contenido, este será almacenado en el log y se re-intentará la petición pasado 1 minuto. Esto puede ser de utilidad si usted está realizando algún tipo de mantenimiento temporal o si tiene un problema interno, por ejemplo si su servidor de DB no funciona correctamente en ese instante, Independientemente del modelo de respuesta elegido, TEXTO PLANO, JSON o XML usted deberá responder con código HTTP Status: 503. En las notificaciones de STATUS se enviará el argumento method => check_status, según el modelo elegido POST o GET. Si usted recibe este argumento con ese valor, deberá responder el mensaje de STATUS con el ejemplo declarado abajo. Como detalle técnico, debe conocer que no es posible realizar respuestas de MT combinando el modo de respuesta directo y respuesta mediante API.

13 Modelo TEXTO PLANO El modelo de texto plano al no ser un lenguaje de marco define una serie de reglas, para separar cada elemento MT y las especificaciones de cada MT. Para separar cada elemento SMS-MT se usará \n---\n Se entiende como \n un salto de línea carácter no visible. En la última definición no es necesario añadir el separador. Para separar los valores de cada SMS-MT se usará ;\n Se entiende como \n un salto de línea carácter no visible. En la última definición no es necesario añadir el separador. En el caso de que requiera incluir ese conjunto de caracteres, podrá anular su función Escapar con una barra invertida \ antes del conjunto. Podrá definir en cada respuesta al menos hasta 3 tipos de SMS, un MT-Servicio mt_service, un MT-Optin mt_optin y un MT-Extra mt_extra. ( según el tipo de método de pago ) es posible que MT-optin o MT-extra no sean necesarios o no estén disponibles ). Es recomendable que use nuestros códigos de ejemplo y SKD donde ya se incluyen los métodos necesarios para gestionar estas respuestas. Es necesario que a la hora de realizar la respuesta HTTP se defina con header content-type: text/ plain La codificación de caracteres en el contenido debe ser UTF-8 El Esquema de respuesta para cada MT es el siguiente. tipo_de_mt; tipo_de_sms; contenido_sms A continuación se muestra una serie de ejemplos y formatos a seguir a la hora de definir MTs, en el modelo de Texto plano es necesario seguir el orden de los parámetros de cada MT, En el caso de que se definan varios MTs es una misma respuesta, el orden de estos no influirá. Ejemplo: Respuesta de ERROR. En el caso de realizar una respuesta de error forzada, deberá responder con HTTP CODE 503 none; ERROR; Mensaje de error que se guardará en el LOG de incidencias

14 Ejemplo: Respuesta de control de STATUS. Donde deberá incluir el valor unix_timestamp con la hora configurada en su servidor, esto nos ayudará a conocer las diferencias horarias a la hora de realizar una petición de control de estado. none; STATUS; Ejemplo: Respuesta MT Servicio - SMS_TEXT. mt_service; SMS_TEXT; Gracias por su compra! su clave de acceso es K97973 Ejemplo: Respuesta MT Servicio - SMS_WAP. mt_service; SMS_WAP; Siga este enlace para realizar su descarga Ejemplo: Respuesta MT Servicio - SMS_UCS2. mt_service; SMS_UCS2; K97973 Ejemplo: Respuesta MT Servicio - SMS_FLASH. mt_service; SMS_FLASH; Este mensaje se muestra en la pantalla del terminal directamente Ejemplo: Respuesta MT Servicio - SMS_UDH. En este ejemplo solo se muestra el orden, los valores serán en formato Hexadecimal. mt_service; SMS_UDH; DSC; UDH; DATA

15 Ejemplo: Respuesta Múltiples MTs en la misma petición. mt_service; SMS_TEXT; Su clave de acceso es K mt_optin; SMS_TEXT; Este servicio ha sido ofrecido por MobiAdvanced el coste total es de 1,20 Eur IVA incluido. --- mt_extra; SMS_TEXT; Recuerda si vuelves a realizar una compra antes de 10 días te regalamos un día gratis. Ejemplo 2: Respuesta Múltiples MTs en la misma petición. mt_service; SMS_WAP; Su clave de acceso es K mt_extra; SMS_TEXT; Servicio ofrecido por MobiAdvanced, recuerde que por cada 5 descargas recibe 1 gratis.

16 Modelo respuesta JSON Podrá definir en cada respuesta al menos hasta 3 tipos de SMS, un MT-Servicio mt_service, un MT-Optin mt_optin y un MT-Extra mt_extra. ( según el tipo de método de pago ) es posible que MT-optin o MT-extra no sean necesarios o no estén disponibles ). Es necesario que a la hora de realizar la respuesta HTTP se defina con header content-type: application/json Siguiendo el estándar de JSON, los caracteres no ASCII serán codificados de forma escapada UCS2. SI usted usa funciones nativas de su lenguaje de programación, no deberá preocuparse por eso. Es recomendable que use nuestros códigos de ejemplo y SKD donde ya se incluyen los métodos necesarios para gestionar estas respuestas. El Esquema de respuesta para cada MT es el siguiente. "tipo_de_mt": "psms_sale_mt_type":"tipo DE MENSAJE", "psms_sale_mt_data":"datos DE RESPUESTA", "psms_sale_mt_url":"datos DE URL *si es SMS_WAP", "psms_sale_mt_udh":"datos UDH *si es SMS_UDH", "psms_sale_mt_dsc":"datos DSC *si es SMS_UDH", "psms_sale_mt_dsc":"datos DSC *si es SMS_UDH", "status_time":"unix TIMESTAMP *si es petición STATUS", "psms_sale_error_msn":"mensaje ERROR *si es necesario", A continuación se muestra una serie de ejemplos y formatos a seguir a la hora de definir MTs, en el modelo de JSON, no es necesario seguir el orden de los parámetros de cada MT o en el orden de los MTs si son múltiples. Ejemplo: Respuesta de ERROR. En el caso de realizar una respuesta de error forzada, deberá responder con HTTP CODE 503 "none": "psms_sale_mt_type":"error", "psms_sale_error_msn":"mensaje de error que se guardará en el LOG"

17 Ejemplo: Respuesta de control de STATUS. Donde deberá incluir el valor unix_timestamp con la hora configurada en su servidor, esto nos ayudará a conocer las diferencias horarias a la hora de realizar una petición de control de estado. "none": "psms_sale_mt_type":"status", "status_time":" " Ejemplo: Respuesta MT Servicio - SMS_TEXT. "mt_service": "psms_sale_mt_type":"sms_text", "psms_sale_mt_data":"su clave de acceso es K97973" Ejemplo: Respuesta MT Servicio - SMS_WAP. "mt_service": "psms_sale_mt_type":"sms_wap", "psms_sale_mt_data":"su clave de acceso es K97973", "psms_sale_mt_url":" Ejemplo: Respuesta MT Servicio - SMS_UCS2. "mt_service": "psms_sale_mt_type":"sms_ucs2", "psms_sale_mt_data":"\u7684\u8bbf\u95ee\u4ee3\u7801\u662f K32923"

18 Ejemplo: Respuesta MT Servicio - SMS_FLASH. "mt_service": "psms_sale_mt_type":"sms_flash", "psms_sale_mt_data":"su clave de acceso es K97973" Ejemplo: Respuesta Múltiples MTs en la misma petición. "mt_service": "psms_sale_mt_type":"sms_text", "psms_sale_mt_data":"su clave de acceso es K ", "mt_optin": "psms_sale_mt_type":"sms_text", "psms_sale_mt_data":"este servicio ha sido ofrecido por MobiAdvanced el coste total es de 1,42 Eur IVA incluido.", "mt_extra": "psms_sale_mt_type":"sms_text", "psms_sale_mt_data":"recuerda si vuelves a realizar una compra antes de 10 días te regalamos un día gratis." Ejemplo 2: Respuesta Múltiples MTs en la misma petición. "mt_service": "psms_sale_mt_type":"sms_wap", "psms_sale_mt_date":"siga el enlace para descargar su producto", "psms_sale_mt_url":" "mt_extra": "psms_sale_mt_type":"sms_text", "psms_sale_mt_data":"servicio ofrecido por MobiAdvanced, recuerde que por cada 5 descargas recibe 1 gratis."

19 Modelo respuesta XML Podrá definir en cada respuesta al menos hasta 3 tipos de SMS, un MT-Servicio mt_service, un MT-Optin mt_optin y un MT-Extra mt_extra. ( según el tipo de método de pago ) es posible que MT-optin o MT-extra no sean necesarios o no estén disponibles ). Es necesario que a la hora de realizar la respuesta HTTP se defina con header content-type: text/ xml Siguiendo el estándar de XML, Los tags que definen el contenido del SMS deberán estar definidos con <![CDATA[ contenido ]]> ( ver ejemplos ) Es recomendable que use nuestros códigos de ejemplo y SKD donde ya se incluyen los métodos necesarios para gestionar estas respuestas. El Esquema de respuesta para cada MT es el siguiente. <?xml version="1.0" encoding="utf-8"?> <statements> <tipo_de_mt> <psms_sale_mt_type>modo_de_sms</psms_sale_mt_type> <psms_sale_mt_data><![cdata[contenido]]></psms_sale_mt_data> <psms_sale_mt_url><![cdata[url *si es SMS_WAP]]></psms_sale_mt_url> <psms_sale_mt_udh>datos UDH *si es UDH</psms_sale_mt_udh> <psms_sale_mt_dsc>datos DSC *si es UDH</psms_sale_mt_udh> <status_time>unix TIME STAMP *si es STATUS</status_time> <psms_sale_error_msn>mensaje ERROR *si es ERROR</ psms_sale_error_msn> </tipo_de_mt> </statements> A continuación se muestra una serie de ejemplos y formatos a seguir a la hora de definir MTs, en el modelo de XML, no es necesario seguir el orden de los parámetros de cada MT o en el orden de los MTs si son múltiples. Ejemplo: Respuesta de ERROR En el caso de realizar una respuesta de error forzada, deberá responder con HTTP CODE 503 <?xml version="1.0" encoding="utf-8"?> <statements> <none> <psms_sale_mt_type>error</psms_sale_mt_type> <psms_sale_mt_data>mensaje de error </psms_sale_mt_data> </none> </statements>

20 Ejemplo: Respuesta de control de STATUS Donde deberá incluir el valor unix_timestamp con la hora configurada en su servidor, esto nos ayudará a conocer las diferencias horarias a la hora de realizar una petición de control de estado. <?xml version="1.0" encoding="utf-8"?> <statements> <none> <psms_sale_mt_type>status</psms_sale_mt_type> <status_time> </status_time> </none> </statements> Ejemplo: Respuesta MT Servicio - SMS_TEXT <?xml version="1.0" encoding="utf-8"?> <statements> <mt_service> <psms_sale_mt_type>sms_text</psms_sale_mt_type> <psms_sale_mt_data><![cdata[su clave K97973]]></psms_sale_mt_data> </mt_service> </statements> Ejemplo: Respuesta MT Servicio - SMS_WAP. <?xml version="1.0" encoding="utf-8"?> <statements> <mt_service> <psms_sale_mt_type>sms_wap</psms_sale_mt_type> <psms_sale_mt_data><![cdata[siga el enlace ]]></psms_sale_mt_data> <psms_sale_mt_url><![cdata[ ]]></psms_sale_mt_url> </mt_service> </statements> Ejemplo: Respuesta MT Servicio - SMS_UCS2. <?xml version="1.0" encoding="utf-8"?> <statements> <mt_service> <psms_sale_mt_type>sms_ucs2</psms_sale_mt_type> <psms_sale_mt_data><![cdata[ KR3]]></psms_sale_mt_data> </mt_service> </statements>

21 Ejemplo: Respuesta MT Servicio - SMS_FLASH. <?xml version="1.0" encoding="utf-8"?> <statements> <mt_service> <psms_sale_mt_type>sms_flash</psms_sale_mt_type> <psms_sale_mt_data><![cdata[este mensaje ]]></psms_sale_mt_data> </mt_service> </statements> Ejemplo: Respuesta Múltiples MTs en la misma petición. <?xml version="1.0" encoding="utf-8"?> <statements> <mt_service> <psms_sale_mt_type>sms_text</psms_sale_mt_type> <psms_sale_mt_data><![cdata[su clave K3938]]></psms_sale_mt_data> </mt_service> <mt_optin> <psms_sale_mt_type>sms_text</psms_sale_mt_type> <psms_sale_mt_data><![cdata[este servicio ]]></psms_sale_mt_data> </mt_optin> <mt_extra> <psms_sale_mt_type>sms_text</psms_sale_mt_type> <psms_sale_mt_data><![cdata[recuerda si ]]></psms_sale_mt_data> </mt_extra> </statements> Ejemplo 2: Respuesta Múltiples MTs en la misma petición. <?xml version="1.0" encoding="utf-8"?> <statements> <mt_service> <psms_sale_mt_type>sms_wap</psms_sale_mt_type> <psms_sale_mt_data><![cdata[siga el enlace ]]></psms_sale_mt_data> <psms_sale_mt_url><![cdata[ ]]></psms_sale_mt_url> </mt_service> <mt_extra> <psms_sale_mt_type>sms_text</psms_sale_mt_type> <psms_sale_mt_data><![cdata[recuerda si ]]></psms_sale_mt_data> </mt_extra> </statements>

22 Respuesta de MT mediante API Si ha elegido respuesta asíncrona mediante API, su usuario deberá tener los permisos necesarios, también disponer de un API KEY, este podrá ser obtenido en su panel de control. El API de entrada de datos de MobiAdvanced se basa en peticiones HTTP simples. POST y GET Todos los datos enviados deben usar la codificación UTF-8, Dispone de varios métodos de respuesta: JSON json, XML xml, PHP serializado php-serialized Patrón URL solicitud de peticiones API. method=class.method& lang=lg& version=ver Ejemplo URL petición con respuesta JSON method=psms_set.mt& lang=es& version=1.1 Método psms_set.mt En este documento solo haremos uso del paquete psms_set y del método mt en su versión 1.1, dispone de más información acerca del API de la plataforma de MobiAdvanced en la documentación especifica al API. Argumentos aceptados en el método de psms_set.mt Nombre Tipo Valor user_api_key id_psms_sale psms_sale_mt_type psms_sale_mt_service_type psms_sale_mt_service_data psms_sale_mt_service_url psms_sale_mt_service_udh psms_sale_mt_service_dsc psms_sale_mt_optin_type psms_sale_mt_optin_data psms_sale_mt_optin_url psms_sale_mt_optin_udh psms_sale_mt_optin_dsc psms_sale_mt_extra_type psms_sale_mt_extra_data psms_sale_mt_extra_url psms_sale_mt_extra_udh psms_sale_mt_extra_dsc char(40) API key del usuario, obligatorio. Varchar(32) ID de la transacción de la que se responderán los MTs ( obg ) int(1) 1 = MT-service, 2 = MT-optin, 3 = MT-extra Según el tipo elegido deberá hacer uso de unos u otros argumentos. vchar(128) Título que definió en su campaña. ( obligatorio ) text vchar(255) vchar(127) Hex int(1) Contenido del mensaje URL, solo para mensajes tipo WAP_URL Definición headers solo usado en mensajes tipo UDH 1= 7bit 2=8bit 3=16bit. solo usado en Mensajes de tipo UDH vchar(128) Título que definió en su campaña. ( obligatorio ) text vchar(255) vchar(127) Hex int(1) Contenido del mensaje URL, solo para mensajes tipo WAP_URL Definición headers solo usado en mensajes tipo UDH 1= 7bit 2=8bit 3=16bit. solo usado en Mensajes de tipo UDH vchar(128) Título que definió en su campaña. ( obligatorio ) text vchar(255) vchar(127) Hex int(1) Contenido del mensaje URL, solo para mensajes tipo WAP_URL Definición headers solo usado en mensajes tipo UDH 1= 7bit 2=8bit 3=16bit. solo usado en Mensajes de tipo UDH