Gateway SMS Premium Idioma: Español - España
←
→
Transcripción del contenido de la página
Si su navegador no muestra la página correctamente, lea el contenido de la página a continuación
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
MobiAdvanced.comes
MobiAdvanced.com esun
unproducto
productode
deSponsorocio,
Sponsorocio,S.L.
S.L.CIF:
CIF:B97844807
B97844807Madrid
Madrid--España
EspañaGuía integración SMS Premium Gateway - v 1.1 / MobiAdvanced.com Última Revisión. 15/07/2010
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.
MobiAdvanced.com es un producto de Sponsorocio, S.L. CIF: B97844807 Madrid - EspañaGuía integración SMS Premium Gateway - v 1.1 / MobiAdvanced.com Última Revisión. 15/07/2010
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.
MobiAdvanced.com es un producto de Sponsorocio, S.L. CIF: B97844807 Madrid - EspañaGuía integración SMS Premium Gateway - v 1.1 / MobiAdvanced.com Última Revisión. 15/07/2010
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.
MobiAdvanced.com es un producto de Sponsorocio, S.L. CIF: B97844807 Madrid - EspañaGuía integración SMS Premium Gateway - v 1.1 / MobiAdvanced.com Última Revisión. 15/07/2010
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.
MobiAdvanced.com es un producto de Sponsorocio, S.L. CIF: B97844807 Madrid - EspañaGuía integración SMS Premium Gateway - v 1.1 / MobiAdvanced.com Última Revisión. 15/07/2010
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 3.38.
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.
MobiAdvanced.com es un producto de Sponsorocio, S.L. CIF: B97844807 Madrid - EspañaGuía integración SMS Premium Gateway - v 1.1 / MobiAdvanced.com Última Revisión. 15/07/2010
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.
MobiAdvanced.com es un producto de Sponsorocio, S.L. CIF: B97844807 Madrid - EspañaGuía integración SMS Premium Gateway - v 1.1 / MobiAdvanced.com Última Revisión. 15/07/2010
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.
MobiAdvanced.com es un producto de Sponsorocio, S.L. CIF: B97844807 Madrid - EspañaGuía integración SMS Premium Gateway - v 1.1 / MobiAdvanced.com Última Revisión. 15/07/2010
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
Referencia única por SMS EJ: MO1-28728792 es
id_psms_sale_transaction Varchar(32)
recomendable que guarde este valor para evitar duplicidades
ID de la transacción “no único” puede ser el mismo para un
id_psms_sale Varchar(32) MO de servicio y para un MO Opt-in que pertenecen a la
misma venta.
id_psms_cmp int(9) ID interno de la campaña en MobiAdvanced
psms_cmp_title varchar(128) Título que definió en su campaña.
operator_mcc int(3) Código MCC del operador
Código MNC del operador se usa como identificador único
operator_mnc int(3)
para conocer el operador. ( ver lista de operadores )
Código de texto indica el nombre del operador ( puede no ser
operator_code varchar(16)
único ) para determinar el operador usar MCC+MCN
operator_title varchar(64) Nombre descriptivo del operador.
psms_method_sc_number int(10) Número corto del método de pago donde se envía el MO
psms_method_sc_price float(6,3) Importe del método de pago en la moneda local del país.
psms_method_sc_currency ISO Moneda del método de pago.
psms_method_sc_price_vat float(4,2) Porcentaje de impuesto que se aplica en el país de la venta.
psms_method_billing_mode String(mt, mo) tipo de facturación que se aplica ( ver definiciones ) billing-xx
psms_method_lang ISO Lenguaje por defecto para el método - Alpha 2 Letras.
psms_method_country ISO País del método de pago Alpha 2 letras
psms_sale_mo_number varchar(16) Número del cliente que envía el SMS-MO.
Indica si es un MO de servicio o MO de confirmación Opt-in
psms_sale_mo_type MO1 o MO2
MO1 = MO de servicio MO 2 = MO Opt-in.
psms_sale_mo_time timestamp inicio de la transacción, Formato: YYYY-mm-dd hh:ii:ss
psms_sale_mo_data varchar(160) Contenido completo del mensaje que se envió, incluye ALIAS
psms_sale_alias varchar(32) Palabra clave principal, por la que se determina la campaña
psms_sale_alias_sub varchar(32) Sub palabra clave (opcional)
psms_sale_track varchar(32) Parámetro adicional para seguimiento de la venta (opcional)
Indica el tipo de ciclo necesario para completar la
psms_sale_cicle_type int(2)
transacción. (ver tipos de ciclo de venta documento)
psms_sale_cicle_time int(3) Tiempo máximo del ciclo en minutos.
psms_sale_simulated Enum(Y , N) 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,
psms_sale_redirected Enum(Y , N)
y ha definido que los SMS que no se reconozca su alias se
re-dirijan a otro alias.
psms_cmp_alias_product_value int(11) Valor virtual que definió al producto de al alias (opcional)
psms_cmp_alias_product_name varchar(64) Nombre virtual que definió a el producto del alias (opcional)
MobiAdvanced.com es un producto de Sponsorocio, S.L. CIF: B97844807 Madrid - EspañaGuía integración SMS Premium Gateway - v 1.1 / MobiAdvanced.com Última Revisión. 15/07/2010
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 Email de la incidencia al contacto técnico definido en MobiAdvanced.
MobiAdvanced.com es un producto de Sponsorocio, S.L. CIF: B97844807 Madrid - EspañaGuía integración SMS Premium Gateway - v 1.1 / MobiAdvanced.com Última Revisión. 15/07/2010
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 3.38
3. Algunos caracteres se han tenido que eliminar.
Este tipo de alertas no son notificadas vía email, 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 email, con el fin de que
solucione el problema.
MobiAdvanced.com es un producto de Sponsorocio, S.L. CIF: B97844807 Madrid - EspañaGuía integración SMS Premium Gateway - v 1.1 / MobiAdvanced.com Última Revisión. 15/07/2010
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.
MobiAdvanced.com es un producto de Sponsorocio, S.L. CIF: B97844807 Madrid - EspañaGuía integración SMS Premium Gateway - v 1.1 / MobiAdvanced.com Última Revisión. 15/07/2010
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
MobiAdvanced.com es un producto de Sponsorocio, S.L. CIF: B97844807 Madrid - EspañaGuía integración SMS Premium Gateway - v 1.1 / MobiAdvanced.com Última Revisión. 15/07/2010
Ejemplo: Respuesta de control de “STATUS”.
Donde 1279098293 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;
1279098293
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;
http://wap.dominio.com/url_contenido?id=2982982;
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}
MobiAdvanced.com es un producto de Sponsorocio, S.L. CIF: B97844807 Madrid - EspañaGuía integración SMS Premium Gateway - v 1.1 / MobiAdvanced.com Última Revisión. 15/07/2010
Ejemplo: Respuesta Múltiples MTs en la misma petición.
mt_service;
SMS_TEXT;
Su clave de acceso es K397389
---
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;
http://wap.dominio.com/url_contenido?id=2982982;
Su clave de acceso es K397389
---
mt_extra;
SMS_TEXT;
Servicio ofrecido por MobiAdvanced, recuerde que por cada 5 descargas recibe 1 gratis.
MobiAdvanced.com es un producto de Sponsorocio, S.L. CIF: B97844807 Madrid - EspañaGuía integración SMS Premium Gateway - v 1.1 / MobiAdvanced.com Última Revisión. 15/07/2010
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"
}
}
MobiAdvanced.com es un producto de Sponsorocio, S.L. CIF: B97844807 Madrid - EspañaGuía integración SMS Premium Gateway - v 1.1 / MobiAdvanced.com Última Revisión. 15/07/2010
Ejemplo: Respuesta de control de “STATUS”.
Donde 1279098293 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":"1279098293"
}
}
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":"http://wap.dominio.com/url_contenido?id=2982982"
}
}
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"
}
}
MobiAdvanced.com es un producto de Sponsorocio, S.L. CIF: B97844807 Madrid - EspañaGuía integración SMS Premium Gateway - v 1.1 / MobiAdvanced.com Última Revisión. 15/07/2010
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 K397389."
},
"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":"http://wap.dominio.com/url_contenido?id=2982982."
},
"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."
}
}
MobiAdvanced.com es un producto de Sponsorocio, S.L. CIF: B97844807 Madrid - EspañaGuía integración SMS Premium Gateway - v 1.1 / MobiAdvanced.com Última Revisión. 15/07/2010
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 ( 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.
{MODO_DE_SMS}
{DATOS UDH *si es UDH}
{DATOS DSC *si es UDH}
{UNIX TIME STAMP} *si es STATUS
{MENSAJE ERROR *si es ERROR}
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
ERROR
Mensaje de error …
MobiAdvanced.com es un producto de Sponsorocio, S.L. CIF: B97844807 Madrid - EspañaGuía integración SMS Premium Gateway - v 1.1 / MobiAdvanced.com Última Revisión. 15/07/2010
Ejemplo: Respuesta de control de “STATUS”
Donde 1279098293 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.
STATUS
1279098293
Ejemplo: Respuesta MT Servicio - SMS_TEXT
SMS_TEXT
Ejemplo: Respuesta MT Servicio - SMS_WAP.
SMS_WAP
Ejemplo: Respuesta MT Servicio - SMS_UCS2.
SMS_UCS2
MobiAdvanced.com es un producto de Sponsorocio, S.L. CIF: B97844807 Madrid - EspañaGuía integración SMS Premium Gateway - v 1.1 / MobiAdvanced.com Última Revisión. 15/07/2010
Ejemplo: Respuesta MT Servicio - SMS_FLASH.
SMS_FLASH
Ejemplo: Respuesta Múltiples MTs en la misma petición.
SMS_TEXT
SMS_TEXT
SMS_TEXT
Ejemplo 2: Respuesta Múltiples MTs en la misma petición.
SMS_WAP
SMS_TEXT
MobiAdvanced.com es un producto de Sponsorocio, S.L. CIF: B97844807 Madrid - EspañaGuía integración SMS Premium Gateway - v 1.1 / MobiAdvanced.com Última Revisión. 15/07/2010
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.
http://api.mobiadvanced.com/{tipo}/?__method={class.method}&__lang={lg}&__version={ver}
Ejemplo URL petición con respuesta JSON
http://api.mobiadvanced.com/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 char(40) API key del usuario , obligatorio.
id_psms_sale Varchar(32) ID de la transacción de la que se responderán los MTs ( obg )
1 = MT-service , 2 = MT-optin , 3 = MT-extra Según el tipo
psms_sale_mt_type int(1)
elegido deberá hacer uso de unos u otros argumentos.
psms_sale_mt_service_type vchar(128) Título que definió en su campaña. ( obligatorio )
psms_sale_mt_service_data text Contenido del mensaje
psms_sale_mt_service_url vchar(255) URL, solo para mensajes tipo WAP_URL
psms_sale_mt_service_udh vchar(127) Hex Definición headers solo usado en mensajes tipo UDH
psms_sale_mt_service_dsc int(1) 1= 7bit 2=8bit 3=16bit. solo usado en Mensajes de tipo UDH
psms_sale_mt_optin_type vchar(128) Título que definió en su campaña. ( obligatorio )
psms_sale_mt_optin_data text Contenido del mensaje
psms_sale_mt_optin_url vchar(255) URL, solo para mensajes tipo WAP_URL
psms_sale_mt_optin_udh vchar(127) Hex Definición headers solo usado en mensajes tipo UDH
psms_sale_mt_optin_dsc int(1) 1= 7bit 2=8bit 3=16bit. solo usado en Mensajes de tipo UDH
psms_sale_mt_extra_type vchar(128) Título que definió en su campaña. ( obligatorio )
psms_sale_mt_extra_data text Contenido del mensaje
psms_sale_mt_extra_url vchar(255) URL, solo para mensajes tipo WAP_URL
psms_sale_mt_extra_udh vchar(127) Hex Definición headers solo usado en mensajes tipo UDH
psms_sale_mt_extra_dsc int(1) 1= 7bit 2=8bit 3=16bit. solo usado en Mensajes de tipo UDH
MobiAdvanced.com es un producto de Sponsorocio, S.L. CIF: B97844807 Madrid - EspañaGuía integración SMS Premium Gateway - v 1.1 / MobiAdvanced.com Última Revisión. 15/07/2010
Ejemplo de respuesta de MT_service SMS_TEXT
Recuerde reemplazar el API KEY por la perteneciente a su usuario.
POST http://api.mobiadvanced.com/json/?__method=psms_set.mt
'user_api_key' => '4b2f64874972bbacdfc49686bc182ea915041b312,
'id_psms_sale' => '356361234',
'psms_sale_mt_type' => '1',
'psms_sale_mt_service_type' => 'SMS_TEXT',
'psms_sale_mt_service_data' => 'Su clave de acceso es K39G3'
{
"status":"ok",
"code":true,
"args":false,
"value":null,
"message":
{
"public":"psms_set_mt_service_ok",
"private":"ok"
}
}
Ejemplo de respuesta de MT_service WAP
Recuerde reemplazar el API KEY por la perteneciente a su usuario.
POST http://api.mobiadvanced.com/json/?__method=psms_set.mt
'user_api_key' => '4b2f64874972bbacdfc49686bc182ea915041b312',
'id_psms_sale' => '156361234',
'psms_sale_mt_type' => '1',
'psms_sale_mt_service_type' => 'SMS_WAP',
'psms_sale_mt_service_data' => 'Siga este enlace para descarga su producto'
'psms_sale_mt_service_url' => 'http://wap.example.com?wap_product=29822'
{
"status":"ok",
"code":true,
"args":false,
"value":null,
"message":
{
"public":"psms_set_mt_service_ok",
"private":"ok"
}
}
MobiAdvanced.com es un producto de Sponsorocio, S.L. CIF: B97844807 Madrid - EspañaGuía integración SMS Premium Gateway - v 1.1 / MobiAdvanced.com Última Revisión. 15/07/2010
Ejemplo 2 respuesta de MT_optin
Recuerde reemplazar el API KEY por la perteneciente a su usuario.
POST http://api.mobiadvanced.com/json/?__method=psms_set.mt
'user_api_key' => '4b2f64874972bbacdfc49686bc182ea915041b312',
'id_psms_sale' => '356361234',
'psms_sale_mt_type' => '2',
'psms_sale_mt_service_type' => 'SMS_TEXT',
'psms_sale_mt_service_data' => 'Responda con OK este SMS para confirmar…'
{
"status":"ok",
"code":true,
"args":false,
"value":null,
"message":
{
"public":"psms_set_mt_optin_ok",
"private":"ok"
}
}
MobiAdvanced.com es un producto de Sponsorocio, S.L. CIF: B97844807 Madrid - EspañaGuía integración SMS Premium Gateway - v 1.1 / MobiAdvanced.com Última Revisión. 15/07/2010
Algunos ejemplos de respuesta con Error.
Podrá controlar el estado de la operación, mediante el valor status, el cual podrá ser “ok” o “error”.
1. Ejemplo , la venta no espera ningún MT-service. ya ha sido definido…
{"status":"error",
"message":
{
"public":"No se esperaba ningún MT de servicio para esta transacción",
"private":"error"
}
}
2. Ejemplo , la llamada al método fue incorrecta, fallo en el argumento id_psms_sale…
{"status":"error",
"message":{"public":"Algunos datos contienen errores","private":"Algunos datos
contienen errores : privado"},
"args":{
"id_psms_sale":{
"status":"error",
"public":"Este dato no puede ser vacío.",},
"psms_sale_mt_type":{
"status":"ok",
"public":"Correcto"},
"psms_sale_mt_service_type":{
"status":"ok",
"public":"Correcto"}
"psms_sale_mt_service_data":{
"status":"ok",
"public":"Correcto",}
}
}
}
MobiAdvanced.com es un producto de Sponsorocio, S.L. CIF: B97844807 Madrid - EspañaGuía integración SMS Premium Gateway - v 1.1 / MobiAdvanced.com Última Revisión. 15/07/2010
Protección IP
SI dispone de un firewall activado en el servidor donde recibe las peticiones, deberá permitir el
acceso a las siguientes IPs
94.23.50.192
94.23.50.193
94.23.50.194
94.23.81.108
94.23.87.35
Es posibles que por motivos de mejoras en la plataforma de MobiAdvanced las IPs puedan ser
modificadas. en caso de ser cliente, será informado vía email con algunas semanas de antelación.
Mas Información
Si tiene dudas acerca de este documento o quiere informar de un error en el mismo, por favor no
dude en contactarnos.
MobiAdvanced ( información general )
E-mail: soporte@mobiadvanced.com
Luis Muñoz - CTO ( información técnica )
E-mail: luis.munoz.hdez@mobiadvanced.com
MobiAdvanced.com
MobiAdvanced.com es un producto de Sponsorocio, S.L. CIF: B97844807 Madrid - EspañaTambién puede leer
