Hamburguer icon
Movilgate - Logotipo
Wiki | Movilgate®
  • Índice
  • Protocolos
  • Integraciones corporativas/BULK
  • Suscripciones de contenido
  • Recargas

    • Integración a Suscripciones a través del MIE

    Introducción

    En este documento se detallan los protocolos a utilizar para poder integrarse a MovilGate y brindar el servicio de suscripciones. La integración consta de dos etapas. La primera es la integración con el MIE2, el cual lo utilizaremos para poder procesar los pedidos y notificaciones de altas/bajas. La segunda etapa describe la integración con el GatewaySMS de MovilGate para poder realizar cobros y despachos de SMS.

    Etapa 1: Integración al MIE

    MovilGate proporciona un servicio propietario basado en un esquema cliente/servidor donde se utiliza una estructura XML para el intercambio de información usando POST/HTTP.

    El MIE se utiliza para gestionar las ALTAS/BAJAS de un usuario a un servicio. Para el despacho de MTs utilizamos una integración al Gateway SMS, la cual será descripta más adelante en la segunda etapa.

    El MIE posee tres funcionalidades, las cuales se identifican por el valor de la etiqueta ExtServiceId:

    Funcionalidad ExtServiceId
    Pedido de PIN 3
    Pedido de ALTA/BAJA 2
    Notificación ALTA/BAJA/ERROR 0

    Si tomamos como referencia el servicio de suscripciones WEB vamos a poder hacer un repaso del funcionamiento de cada una de las etapas anteriormente mencionadas.

    Para poder dar de alta a un usuario en un servicio se suscripciones WEB existirán dos pasos que el Integrador Externo deberá realizar.

    El primero consta de solicitar a MovilGate la generación de PIN (ExtServiceId 3), en el cual se creará un PIN y se le envía al usuario vía SMS, sin que el Integrador Externo lo conozca, indicándole al usuario que debe ingresar en la web el código recibido. Aquí es donde el Integrador Externo puede completar el segundo paso, la solicitud de alta (ExtServiceId 2), haciendo la petición con los datos del usuario/servicio y el pin ingresado. Aquí también deberá ingresar un id de referencia que MovilGate entregó en el primer paso. Más adelante detallamos éste punto.

    MovilGate verificará que el código (PIN) recibido es el mismo que generó para ése id de referencia enviado. De ser correcto, dará de alta al usuario y notificará (ExtServiceId 0) al Integrador Externo de manera asíncrona. Caso contrario, lo notifica con el detalle del error correspondiente.

    Para que éste esquema funcione es importante que el Integrador Externo respete el envío de los parámetros obligatorios que se le solicitan para poder realizar el alta. Hay que tener presente que en éste nuevo esquema las altas siempre estarán relacionadas a un pedido de PIN, por lo cual es muy importante que se guarde el Transaction id que se le devuelve en el primer paso.

    A continuación se muestra un diagrama de secuencia donde se puede observar el circuito completo de una solicitud de alta, desde el pedido de PIN hasta el envío del mensaje de bienvenida.

    Wiki Movilgate - Solicitud alta suscripción SMS

    ALTA a suscripción vía SMS:

    Wiki Movilgate - Alta suscripción SMS

    A continuación se detallan cada una de éstas funcionalidades, y como debe ser la estructura del archivo XML según el ExtServiceId.

    Estructura XML solicitud PIN

    Para solicitar un PIN el Integrador Externo debe enviar, vía POST, a la URL provista por MovilGate un XML con la siguiente estructura:

    referrer=&request=<?xml version="1.0" encoding="iso-8859-1"?>
    <Request>
    <ExtServiceId>[Number]</ExtServiceId>
    <Partner>
    <Id>[Number]</Id>
    <Name>[String]</Name>
    <Password>[String]</Password>
    <IdTranExt>[String]</IdTranExt>
    </Partner>
    <Telephone msisdn="[String]" userdomain="[String]"/>
    <Service>
    <Id>[Number]</Id>
    <Name>[String]</ Name >
    <Type>[String]</Type>
    <Channel>[String]</Channel>
    <Keyword>[String]</ Keyword >
    </Service>
    </Request>

    Detalle de campos XML Request

    ExtServiceId: Siendo [Number] el valor numérico entero del subproceso al cual se quiere realizar una petición. Para el caso de solicitud de PIN el valor correspondiente es 3.

    Partner

    • Id*: Siendo [Number] el identificador numérico del Integrador Externo
    • Name*: Siendo [String] el nombre del Integrador Externo que envía la petición
    • Password*: Siendo [String] la contraseña del Integrador Externo
    • IdTranExt: Siendo [String] un valor alfanumérico, largo máximo 32, opcional que indica un valor de transacción, cuya finalidad es para posterior seguimiento.

    Telephone

    • msisdn: Siendo [String] el número de teléfono móvil del cliente del Integrador Externo
    • userdomain: Siendo [String] el numero corto, operador y país ej (70370.cti.ar)

    Service

    • Id*: Siendo [Number] el identificador numérico del servicio
    • Name*: Siendo [String] el nombre del servicio afectado a la petición
    • Type: Siendo [String] el tipo de solicitud (Alta/Baja)
    • Channel: Siendo [String] el medio por el cual se genera la solicitud (SMS/WEB/WAP/CALLCENTER)
    • Keyword: Siendo [String] la palabra clave con la que se quiere activar/desactivar elservicio.

    *valor provisto por MovilGate

    A éste request el MIE responderá de manera síncrona un XML con el resultado de la validación de los datos enviados. El formato del XML es el siguiente:

    <?xml version="1.0" encoding=" iso-8859-1"?>
    <Response>
    <Transaction id="[Number]" date="[Datetime]" statusCode=”[Number]”
    statusMessage=”[String]” />
    </ Response >

    Detalle de campos XML Response

    Transaction

    • id: Siendo [Number] el número de transacción creada para esta petición
    • date: Siendo [Datetime] la fecha de transacción creada para esta petición
    • statusCode: Siendo [Number] el código correspondiente al estado de retorno.
    • statusMessage: Siendo [String] el texto correspondiente al estado de retorno.

    Los valores que pueden tomar los atributos statusCode y statusMessage son:

    statusCode statusMessage
    0 Ok
    1 Invalid XML
    2 Password incorrect
    3 The required service does not exist or Id not found
    4 Access denied. You not have permission for access to this service
    5 Invalid content date
    6 Invalid content. Maybe this was empty or exceed the maximun of characters
    7 Reached the maximum amount allowable
    8 Internal error. Try again in a few minutes
    9 Reached the maximum retry
    10 Invalid external service
    11 Invalid partner metadata
    12 There are not urls for dispatch
    13 Invalid msisdn
    14 Invalid userdomain
    15 Your request expired
    16 Content duplicated
    17 Incorrect Channel
    Ejemplo solicitud PIN

    El externo enviará un POST HTTP a la URL del MIE, provista por MovilGate, con la siguiente estructura:

    referrer=&request=<?xml version="1.0" encoding="iso-8859-1"?>
    <Request>
    <ExtServiceId>3</ExtServiceId>
    <Partner>
    <Id>82</Id>
    <Name>ECOMOBILE</Name>
    <Password>22yut6</Password>
    <IdTranExt>33</IdTranExt>
    </Partner>
    <Telephone msisdn="1148965523" userdomain="70370.cti.ar"/>
    <Service>
    <Id>13</Id>
    <Name>Deportes</ Name >
    <Type>ALTA</Type>
    <Channel>WEB</Channel>
    <Keyword >DEPO</ Keyword >
    </Service>
    </Request>

    El MIE recibirá éste request, validará que la información enviada sea correcta, y que el servicio esté permitido para ése partner, y de manera síncrona contestará al Integrador Externo sobre el resultado de ésta validación.

    <?xml version="1.0" encoding=" iso-8859-1"?>
    <Response>
    <Transaction id="1" date="2013-03-03 03:03:03" statusCode="0" statusMessage="OK" />
    </Response >
    Estructura XML solicitud ALTA/BAJA

    Para suscribir/desuscribir a un cliente de un determinado servicio, el Integrador Externo debe realizar un POST al MIE utilizando la siguiente estructura.

    referrer=&request=<?xml version="1.0" encoding="iso-8859-1"?>
    <Request>
    <ExtServiceId>[Number]</ExtServiceId>
    <Partner>
    <Id>[Number]</Id>
    <Name>[String]</Name>
    <Password>[String]</Password>
    <IdTranExt>[String]</IdTranExt>
    </Partner>
    <Telephone msisdn="[String]" userdomain="[String]" pin="[String]" IP="[String]" UA="[String]"/>
    <Service>
    <Id>[Number]</Id>
    <Name>[String]</ Name >
    <Type>[String]</Type>
    <Channel>[String]</Channel>
    <Keyword>[String]</ Keyword >
    </Service>
    <Transaction idRef=”[Number]”/>
    </Request>

    Detalle de campos XML Request

    ExtServiceId: Siendo [Number] el valor numérico entero del subproceso al cual se quiere realizar una petición. Para el caso de solicitud de ALTA/BAJA el valor correspondiente es 2.

    Partner:

    • Id*: Siendo [Number] el identificador numérico del Integrador Externo
    • Name*: Siendo [String] el nombre del Integrador Externo que envía la petición
    • Password*: Siendo [String] la contraseña del Integrador Externo
    • IdTranExt: Siendo [String] un valor alfanumérico, largo máximo 60, opcional que indica un valor de transacción, cuya finalidad es para posterior seguimiento.

    Telephone

    • msisdn: Siendo [String] el número de teléfono móvil del cliente del externo
    • userdomain: Siendo [String] el numero corto, operador y país ej (70370.cti.ar)
    • pin: Siendo [String] el código que el usuario ingresó en la WEB del Integrador Externo
    • IP: Siendo [String] la IP del usuario
    • UA: Siendo [String] el UserAgent del usuario.

    Service

    • Id*: Siendo [Number] el identificador numérico del servicio
    • Name*: Siendo [String] el nombre del servicio afectado a la petición
    • Type: Siendo [String] el tipo de solicitud (Alta/Baja)
    • Channel: Siendo [String] el medio por el cual se genera la solicitud (SMS/WEB/WAP/CALLCENTER)
    • Keyword*: Siendo [String] la palabra clave con la que se quiere activar/desactivar el servicio.

    Transaction

    • idRef: Siendo [Number] el valor correspondiente al Transaction id devuelto por MovilGate en el Response al pedido de PIN generado por el Integrador Externo en el paso anterior.

    *valor provisto por MovilGate

    Importante: El envío del valor Transaction→ idRef es obligatorio para suscripciones WEB, caso contrario la petición no será procesada.

    Casos especiales:

    En el caso de los carriers que poseen doble optin (ICE Costa Rica, por ejemplo) se debe realizar únicamente una solicitud de ALTA (es decir, omitir la solicitud de PIN) pero con los siguientes atributos vacíos:

    • pin=””
    • idRef=””
    <Request>
    <ExtServiceId>2</ExtServiceId>
    <Partner>
    <Id>111</Id>
    <Name>Partner name</Name>
    <Password>xxxxxx</Password>
    <IdTranExt>1234</IdTranExt>
    </Partner>
    <Telephone msisdn="595911112222" userdomain="70370.personal.py" pin="" IP="x.x.x.x" UA="xxxxxxxxxx"/>
    <Service>
    <Id>9876</Id>
    <Name>service_name</Name>
    <Channel>WEB</Channel>
    <Type>ALTA</Type>
    <Keyword>kwd</Keyword>
    </Service>
    <Transaction idRef="" />
    </Request>

    A éste request el MIE responderá de manera síncrona un XML con el resultado de la validación de los datos enviados. El formato del XML es el siguiente:

    <?xml version="1.0" encoding=" iso-8859-1"?>
    <Response>
    <Transaction id="[Number]" date="[Datetime]" statusCode=”[Number]”
    statusMessage=”[String]” />
    </Response>

    Detalle de campos XML Response

    Transaction

    • id: Siendo [Number] el número de transacción creada para esta petición
    • date: Siendo [Datetime] la fecha de transacción creada para esta petición
    • statusCode: Siendo [Number] el código correspondiente al estado de retorno.
    • statusMessage: Siendo [String] el texto correspondiente al estado de retorno.

    Los valores que pueden tomar statusCode y statusMessage fueron detallados en el subproceso de pedido de Pines.

    Ejemplo solicitud ALTA

    El externo enviará un POST HTTP a la URL del MIE, provista por MovilGate, con la siguiente estructura:

    referrer=&request=<?xml version="1.0" encoding="iso-8859-1"?>
    <Request>
    <ExtServiceId>2</ExtServiceId>
    <Partner>
    <Id>82</Id>
    <Name>ECOMOBILE</Name>
    <Password>22yut6</Password>
    <IdTranExt>34</IdTranExt>
    </Partner>
    <Telephone msisdn="1148965523" userdomain="70370.cti.ar" pin="1234" IP="123.456.789.10" UA="Google*X*Chrome*X*Desktop*X*0*X*"/>
    <Service>
    <Id>13</Id>
    <Name>Deportes</ Name >
    <Type>ALTA</Type>
    <Channel>WEB</Channel>
    <Keyword>DEPO</ Keyword >
    </Service>
    <Transaction idRef="1">
    </Request>

    El MIE recibirá éste request, validará que la información enviada sea correcta y que el servicio esté permitido para ése partner. De manera síncrona contestará al Externo sobre el resultado de dicha validación.

    <?xml version="1.0" encoding=" iso-8859-1"?>
    <Response>
    <Transaction id="2" date="2013-03-03 03:13:03" statusCode="0" statusMessage="OK" />
    </Response>
    Estructura XML Notificaciones de Altas/Bajas/Errores

    Las notificaciones de Altas y/o Bajas de los servicios de suscripciones se notifican al Integrador Externo a través del MIE, utilizando un POST XML para informar sobre cualquier evento de esta índole.

    También se enviará una notificación con la misma estructura en caso que alguno de los procesos vinculados con la generación del PIN, o el alta, fallen.

    Importante: El Integrador Externo debe tener en cuenta que el usuario puede darse de baja del servicio por algún otro medio, ejemplo por SMS, por lo cual es posible que existan notificaciones de BAJA sin que el Integrador Externo haya realizado una solicitud. Es por eso que debe tener en cuenta éste punto e implementar las funcionalidades correspondientes para procesar dicho pedido.

    Estructura XML Notificación ALTAS/BAJAS

    <?xml version="1.0" encoding="iso-8859-1"?>
    <Response>
    <Version>2.0</Version>
    <ExtServiceId>[Number]</ExtServiceId>
    <Telephone msisdn="[String]" userdomain="[String]" />
    <Service>
    <Id>[Number]</Id>
    <Name>[String] </ Name >
    <Type> [String]</Type>
    <Channel> [String] </Channel>
    <Keyword>[String] </Keyword>
    </Service>
    <Transaction idRef="[Number]" idTranExt="[String]" date="[Datetime]" statusCode="[Number]" statusMessage="[String]">
    </Response>

    Detalle de campos XML Request

    • ExtServiceId: Siendo [Number] el valor numérico entero del subproceso al cual se quiere realizar una petición. Para el caso de notificaciones el valor correspondiente es 0.

     

    Telephone

    • msisdn: Siendo [String] el número de teléfono móvil del cliente del externo
    • userdomain: Siendo [String] el numero corto, operador y país ej (70370.cti.ar)

     

    Service

    • Id*: Siendo [Number] el identificador numérico del servicio
    • Name*: Siendo [String] el nombre del servicio afectado a la petición
    • Type: Siendo [String] el tipo de solicitud (Alta/Baja)
    • Channel: Siendo [String] el medio por el cual se genera la solicitud (SMS/WEB/WAP/CALLCENTER)
    • Keyword*: Siendo [String] la palabra clave con la que se quiere activar/desactivar el servicio.

     

    Transaction

    • idRef: Siendo [Number] el valor correspondiente al Transaction id que MovilGate respondió sincrónicamente en el pedido de ALTA.
    • idTranExt: Siendo [String] el valor alfanumérico que envió el Externo en la solicitud.
    • date: Siendo [Datetime] la fecha de transacción creada para esta petición
      statusCode: Siendo [Number] el código correspondiente al estado de retorno.
      statusMessage: Siendo [String] el texto correspondiente al estado de retorno.

    Ejemplo notificación ALTA

    MovilGate enviará un POST HTTP a la URL del Integrador Externo con la siguiente estructura:

    <?xml version="1.0" encoding="iso-8859-1"?>
    <Response>
    <Version>2.0</Version>
    <ExtServiceId>0</ExtServiceId>
    <Telephone msisdn="1148965523" userdomain="70370.cti.ar" />
    <Service>
    <Id>13</Id>
    <Name>Deportes</ Name >
    <Type>ALTA</Type>
    <Channel>WEB</Channel>
    <Keyword>DEPO</ Keyword >
    </Service>
    <Transaction idRef="2" idTranExt="34" date="2013-03-03 03:23:03" statusCode="0" statusMessage="OK">
    </Response>

    A éste request iniciado por MovilGate el Integrador Externo debe contestar con un código HTTP 200, para confirmar la recepción del mismo. En caso que MovilGate no reciba respuesta, o reciba otro código, realizará los reintentos correspondientes.

    Lista de códigos de retorno posibles
    statusCode statusMessage Descripción
    0 Ok Ocurre si la suscripción fue exitosa
    1 Invalid XML Ocurre si no se recibió xml
    2 Password incorrect Ocurre si el partner no envió password
    3 The required service does not exist or Id not found Ocurre si el servicio no existe o no se envió servicio
    4 Access denied. You not have permission for access to this service Ocurre si el Service Id no es el de uno de los servicios del partner
    5 Invalid content date Ocurre si la fecha enviada es incorrecta
    6 Invalid content. Maybe this was empty or exceed the maximun of characters Ocurre si el contenido no existe
    7 Reached the maximum amount allowable Ocurre si superó la cantidad máxima de mensajes
    8 Internal error. Try again in a few minutes Ocurre si hubo un error interno
    9 Reached the maximum retry Ocurre si se superó la cantidad de reintentos
    10 Invalid external service Ocurre si el subproceso no existe
    11 Invalid partner metadata Ocurre si hay errores en los datos del partner
    12 There are not urls for dispatch Ocurre si no hay urls para despachar
    13 Invalid msisdn Ocurre si el numero de telefono es incorrecto
    14 Invalid userdomain Ocurre si el userdomain es incorrecto
    15 Your request expired Ocurre si la transaccion expiró
    16 Content duplicated Ocurre si el contenido esta duplicado
    17 Incorrect Channel Ocurre si el Channel no existe
    18 Invalid Keyword Si la keyword es inválida para el servicio
    20 Invalid Pin request Ocurre si hubo un problema en el pedido de PIN
    21 Invalid Carrier Suscription request Ocurre si hubo un problema en el pedido de ALTA
    22 Invalid MG Suscription request Ocurre si hubo un problema en el pedido de ALTA
    23 Invalid Type. It should be ALTA/BAJA Ocurre si el Type no es ALTA o BAJA
    24 Service already active Ocurre si el servicio ya está activo para el usuario
    25 PIN expired Ocurre si el PIN de la transacción informada en Transaction idRef expiró
    26 PIN used Ocurre si el PIN de la transacción informada en Transaction idRef ya se usó
    27 No PIN found for this requirement Ocurre si no existe la transacción informada en Transaction idRef
    28 PIN is waiting Ocurre si aún no terminó de procesarse el pedido de PIN
    29 PIN generation failed Ocurre si falló la generación del PIN
    30 PIN generation OK Ocurre si la generación del PIN fue exitosa
    31 PIN value incorrect Ocurre si el PIN ingresado es incorrecto
    33 TICKET value incorrect Ocurre si el TICKET ingresado es incorrecto
    34 User is not using operator network. MSISDN not detected Ocurre si el usuario entra a una página WAP navegando por una red que no es de la operadora
    35 Subscription not accepted by the User Ocurre si el usuario no acepta la suscripción en la página del carrier
    131 The required service does not exist or Id Movistar not found Ocurre si hubo un error en la configuración de Movistar. Ponerse en contacto con soporte
    132 User blacklisted Ocurre si el usuario está en la lista negra
    133 IdServicio not sent Ocurre si hubo un error en la configuración de Movistar. Ponerse en contacto con soporte
    134 There is not setup a optin message for the service Ocurre si hubo un error en la configuración de Movistar. Ponerse en contacto con soporte
    135 The required service does not exist or PY Tigo ServiceType not found Ocurre si hubo un error en la configuración de Tigo. Ponerse en contacto con soporte
    136 PIN Request denied. This service works only with double optin Ocurre si el servicio está habilitado para usar con doble optin
    137 No tariff found for this service Ocurre si hubo un error en la configuración del carrier. Ponerse en contacto con soporte
    138 Insufficient Balance Ocurre si la línea del cliente posee saldo insuficiente acceder al contenido OnDemand
    218 No Inhibition packages are available Ocurre cuando la línea del usuario no se encuentra habilitada para la compra de este servicio
    300 Wrong subscription method. Please refer to the Movistar_AR documentation Ocurre si el partner intenta seguir el flujo detallado aquí para Movistar AR en vez del de la documentación específica
    333 Error MGUNDEF. Please contact support Ocurre si ocurrió un error indeterminado. Ponerse en contacto con soporte
    334 Error MGUNDEF. Please contact support Ocurre si ocurrió un error indeterminado. Ponerse en contacto con soporte
    501 Connection timeout reached to the Operator platform Ocurre si la comunicación con el carrier dió timeout
    502 Couldnt connect to the Operator platform Ocurre si la comunicación con el carrier falló
    503 Invalid Operator platform response Ocurre si el carrier dió una respuesta inválida
    Ejemplo en Unix para enviar una solicitud de PIN o ALTA/BAJA vía un POST XML usando Curl 
    curl -H 'Content-Type: text/xml' -X 'POST' 'http://64.76.120.14:15002/default' -d 'referrer=&request=<?xml version="1.0" encoding="iso-8859-1"?>
    <Request>
    <ExtServiceId>3</ExtServiceId>
    <Partner>
    <Id>[Number]</Id>
    <Name>[String]</Name>
    <Password>[String]</Password>
    <IdTranExt>[String]</IdTranExt>
    </Partner>
    <Telephone msisdn="[String]" userdomain="[String]"/>
    <Service>
    <Id>[Number]</Id>
    <Name>[String]</Name >
    <Type>[String]</Type>
    <Channel>[String]</Channel>
    <Keyword>[String]</Keyword >
    </Service>
    </Request>'

    En este ejemplo se ve al programa curl de Unix enviando una solicitud de PIN vía un POST XML. Prestar especial atención a la URL (distinta a la de envío de MT-SMS), al referrer vacío y al XML como valor del request.

    Etapa 2: Integración al Gateway SMS

    Mediante esta integración el Integrador Externo podrá realizar despachos de mensajes asociados a una tarifa, mediante la cual se realizará el débito en el crédito del usuario para poder entregarle el contenido.

    Desde el mismo servicio que MovilGate le provee al Integrador Externo este puede usarse para tasar/despachar mensajes de diferentes servicios, en diferentes países. Para poder hacer esto se requiere parametrizar el XML de intercambio de datos, los cuales se detallan a continuación.

    Estructura XML MTRequest

    Para el envío de MT desde el servidor del “Integrador Externo” a un usuario, el “Integrador Externo” hará el siguiente request HTTP con contenido XML:

    <?xml version="1.0" encoding="iso-8859-1"?>
    <MTRequest>
    <Proveedor Id="[String]" Password="[String]"/>
    <Servicio Id="[String]" ContentType="[Number]" IsBill="[Number]" />
    <Telefono msisdn="[String]" IdTran="[Number]"/>
    <Contenido ServiceName="[String]" PushText="[String]" DeliveryAfter="[Datetime]" Priority="[Number]" ServiceType="signup">[String]</Contenido>
    </MTRequest>

    Detalle de campos XML MTRequest

    Proveedor

    • Id*: Siendo [String] el nombre del externo que envía la petición
    • Password*: Siendo [String] la contraseña del Integrador Externo

    Servicio

    • Id*: Siendo [String] el numero corto, patrón bill,operador y país ej (70370.bill.cti.ar)
    • ContentType: Siendo [Number] el descriptor del tipo de contenido en el mensaje. Los mensajes podrán consistir en texto plano, ringtones monofónicos, logo de operador, Wap Push, otros.
      El mensaje de tipo binario (Content Type=1) a enviar se deberá pasar en codificación hexadecimal.
    Content Type Descripción
    0 Texto plano
    1 Binario, formateado en hexadecimal
    2 Enviar como WapPush

    MovilGate solo convierte el binario formateado a hexadecimal al momento de enviar para el caso de los Content Type=1.

    Nota: No todos los carriers soportan envío de SMS binarios. Consultar disponibilidad a su ejecutivo de cuenta.

    • IsBill: Indica si se cobra o no, si no viene definido el default es “0”.
    • Servicio Id debe también tener el patrón ”.bill.” en el texto que lo compone, ejemplo: 70370.bill.cti.ar
    IsBill Descripción
    1 Se cobra por Hot-Billing o por MT
    0 No se cobra (default)

    Teléfono

    • msisdn: Siendo [String] el número de teléfono móvil del cliente del externo.
    • IdTran: Siendo [String] un valor alfanumérico, largo máximo 60, opcional que indica un valor de transacción, cuya finalidad es para posterior seguimiento.

     

    Contenido: Siendo [String] el mensaje a enviar.

    • ServiceName*: Siendo [String] el nombre del servicio afectado a la petición.
    • PushText: Siendo [String] el título del WapPush a enviar (solo Content Type = 2, Content Type = 3).
    • DeliveryAfter: Siendo [Datetime] el horario de despacho deseado, en el caso que se quiera despachar un mensaje en un horario diferente a la fecha de recibido el request. Por ej, cuando el cliente Externo envía los MTs a MovilGate durante la madrugada, éstos se traten de cobrar de inmediato, y en caso exitoso se deja encolado hasta que se cumpla la hora de DeliveryAfter.
    • Priority: Siendo [Number] el identificador de la cola de despacho. El Gateway SMS permite trabajar con diferentes colas de despacho, se usan dos valores. 0 para el caso de los envíos de MTs con renovaciones, es el valor por default si no se envía, y 1, que es el que se sugiere utilizar para los envíos de mensajes de cobro que se entregan cuando un usuario se suscribe a un servicio. En el caso de no venir definido, el valor default es 0.
    • ServiceType: En el caso de enviar un MT de cobro por primera vez, por ejemplo en el alta del servicio, se debe agregar el atributo ServiceType=”signup”.

    Para el caso de las renovaciones, no será necesario enviar el atributo ServiceType.

    *valor provisto por MovilGate

    Nota: Si el atributo IsBill no está presente en el XML, se establece el mismo a 0, es decir, el mensaje no será cobrado

    A éste request el Gateway SMS responderá de manera síncrona un XML con el resultado de la validación de los datos enviados. El formato del XML es el siguiente:

    <MTResponse>
    <Transaction estado=”[Number]” IdTran=”[Number]” Fecha=”[Datetime]”/>
    <Texto>[String]</Texto>
    </MTResponse>
    Detalle de campos XML MTResponse

    Transaction

    • Estado: Siendo [Number] el código correspondiente al estado de retorno.
    • IdTran: Siendo [Number] el número de transacción creada para esta petición
    • Fecha: Siendo [Datetime] la fecha de transacción creada para esta petición

     

    Texto: Siendo [String] el texto correspondiente al estado de retorno.

    Donde Código y Texto son códigos de respuesta según la tabla siguiente.

    A éste request el Gateway SMS responderá de manera síncrona un XML con el resultado de la validación de los datos enviados. El formato del XML es el siguiente:

    A éste request el Gateway SMS responderá de manera síncrona un XML con el resultado de la validación de los datos enviados. El formato del XML es el siguiente:

    Estado Texto
    0 Ok
    1 Usuario/Password Inválida
    2 XML Inválido
    3 Otro, ver texto en transacción
    Ejemplos envíos de MTRequest

    a) Para el envío de un mensaje SMS con cobro, por primera vez, en el alta del servicio:

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <MTRequest>
    <Proveedor Id="EMOBILE" Password="22yut6"/>
    <Servicio Id="70370.bill.cti.ar" ContentType="0" IsBill="1" />
    <Telefono msisdn="1148965523" IdTran="12345678"/>
    <Contenido ServiceName="Deportes" ServiceType="signup">Recuerda hidratarte antes de realizar ejercicios. </Contenido>
    </MTRequest>

    b) Para el envío de un mensaje SMS con cobro de renovación:

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <MTRequest>
    <Proveedor Id="EMOBILE" Password="22yut6"/>
    <Servicio Id="70370.bill.cti.ar" ContentType="0" IsBill="1" />
    <Telefono msisdn="1148965523" IdTran="12345678"/>
    <Contenido ServiceName="Deportes">Recuerda elongar antes y después de realizar ejercicios. </Contenido>
    </MTRequest>

    c) Para el envío de un WapPush con cobro, en donde el partner genera el push y lo convierte a hexadecimal:

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <MTRequest>
    <Proveedor Id="EMOBILE" Password="22yut6"/>
    <Servicio Id="70370.bill.cti.ar" ContentType="1" IsBill="1" />
    <Telefono msisdn="1148965523" IdTran="12345678"/>
    <Contenido ServiceName="Deportes">
    0605040B8423F0250601ae02056A0045C60C037761702E756E746F7175652E636F6D000103486F6C61000101
    </Contenido>
    </MTRequest>

    d) Para el envío de un WapPush con cobro, en donde el partner envía un URL y Título: En este caso MovilGate genera el push binario al cliente:

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <MTRequest>
    <Proveedor Id="EMOBILE" Password="22yut6"/>
    <Servicio Id="70370.bill.cti.ar" ContentType="2" IsBill="1" />
    <Telefono msisdn="1148965523" IdTran="12345678"/>
    <Contenido ServiceName="Deportes" PushText="Descarga tu contenido!">http://wap.untoque.com</Contenido>
    <MTRequest>

    A cualquiera de estos request MovilGate contestará, de manera síncrona, un XML con la siguiente estructura:

    <MTResponse>
    <Transaccion estado="0" IdTran="12345678" Fecha="2005-02-01 20:40:30"/>
    <Texto>OK</Texto>
    </MTResponse>
    Ejemplo en Unix para enviar un MT-SMS vía un POST XML usando Curl 
    curl -H 'Content-Type: text/xml' -X 'POST' 'http://64.76.120.14:PORT/URL_PARTNER' -d '<MTRequest>
    <Proveedor Id="IdPartner" Password="UsrPassword"/>
    <Servicio Id="70370.bill.cti.ar" ContentType="0" IsBill="1"/>
    <Telefono msisdn="1148965523" IdTran="39"/>
    <Contenido ServiceName=”Deportes”>Test de Envio de Texto Plano</Contenido>
    </MTRequest>'

    En este ejemplo se ve al programa curl de Unix enviando un MT-SMS vía un POST XML a la URL_PARTNER que es asignada por MovilGate y al puerto PORT, que también es asignado por MovilGate. El IdPartner, el UsrPassword, el PORT TCP y el URL_PARTNER son asignados por MovilGate.

    Notificaciones de Cobro

    Cuando se realiza un despacho de un mensaje a través del Gateway SMS y se especifica en el XML que se debe cobrar el mensaje al cliente (atributo IsBill=”1”), el Integrador Externo recibirá una notificación sobre el resultado del intento de cobro.

    La notificación recibida, será del tipo XML y tendrá el siguiente formato:

    Esta notificación será enviada a una URL provista por el partner

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <MTRequestNotify>
    <Servicio id="[String]"/>
    <Telefono msisdn="[String]" idtran="[Number]" RefId="[Number]" />
    <Estado deliverdate="[Datetime]" status="[String]" tran_status="[Number]"/>
    <Info>[String]</Info>
    <TicketId value="[Number]" idtran="[Number]" status="[String]" tran_status="[Number]" charge_date="[Datetime]" tariff="[String]"><Info></Info>
    </TicketId>
    </MTRequestNotify>

    Detalle de campos XML MTRequestNotify

    Servicio

    • Id*: Siendo [String] el numero corto, operador y país ej (70370.bill.cti.ar)

    Teléfono

    • msisdn: Siendo [String] el número de teléfono móvil del cliente del externo.
    • idtran Siendo [Number] el identificador de la transacción generada por MovilGate en la recepción del MTRequest, entregado en el MTResponse.
    • RefId Siendo [Number] el valor correspondiente al que el Integrador Externo colocó en el IdTran del MTRequest.

    Estado

    • deliverdate: Siendo [Datetime] la fecha en la cual fue despacho el mensaje hacia el carrier.
    • status:  Siendo [String] el texto que informa que ocurrió con el mensaje. Los diferentes status son:
      • MT_DELIVERED: Mensaje despachado hacia el carrier.
      • EXPIRETIME: El despacho expiró.
      • MAXRETRIES: Se alcanzó la máxima cantidad de reintentos posibles.
      • DISCARD: Mensaje descartado, esto surge por alguna falla, generalmente por problemas de cobro del mensaje.
      • LENGTHZERO: El mensaje no tiene contenido, por lo que no se despacha.
      • MT_FAIL_TIMEOUT: No se recibió respuesta del carrier sobre el despacho, por lo que no se puede garantizar si el mensaje llegará a destino Nota: Cuando se recibe este estado no se debe reintentar el envío del mensaje.
    • tran_status: Siendo [Number] el código que informa que ocurrió con el despacho del mensaje.

    Info: Siendo [String] la información proporcionada por el carrier al momento de hacer el despacho del MT.

    TicketId: (todos sus atributos son opcionales, sujetos a la información provista por la operadora).

    • value: Siendo [Number] un identificador interno de MovilGate para representar al registro dentro de la plataforma de cobro.
    • Idtran: Siendo [Number] el identificar de la transacción generado por MovilGate en la recepción del MTRequest, entregado en el MTResponse.
    • status: Siendo [String] el texto que representa lo que ocurrió con el cobro del mensaje. Puede tomar los siguientes valores:
      • BILLED: Cobrado.
      • ERROR: Hubo un error Nota: Cuando se recibe este estado no se debe reintentar el envío del mensaje.
      • FAILED: Falló el cobro.
      • BANNED: Caso atípico, poco probable.
    • De no estar disponible este atributo, se debe observar Estado→status:
      • “MT_DELIVERED”: Cobrado.
      • Cualquier otro caso: Falló el cobro.
    • tran_status: Siendo [Number] el código que da una información más detallada sobre el proceso de cobro. Sus posibles valores son:
      • 1 – El contenido no está disponible.
      • 2 – Para descargar este contenido debe tener Activo el servicio de Mensajes de Texto.
      • 3 – Servicio de Descarga de Contenidos Suspendido.
      • 4 – Su línea no tiene saldo suficiente para descargar este contenido.
      • 5 – Momentáneamente el servicio no está disponible, por favor vuelva a intentar en unos minutos.
      • 6 – Contenido autorizado.
      • 7 – Por favor, espere unos instantes y vuelva a intentar. No puede hacer más de una compra por minuto.
      • 8 – Contenido libre de cargo.
      • 9 – Servicio de Descarga de Contenidos no permitida.
      • 10 – Usuario de servicio postpago. Se le debe enviar MT de tasación (Movistar Colombia).
      • 11 – Time out en la respuesta del servidor correspondiente. No reintentar.
      • 12 – Cliente bloqueado por carrier, dar de baja.
      • 13 – Cliente No existe.
      • 14 – Cliente Suspendido.
      • 16 – Sistema en carrier no disponible.
      • Cualquier valor negativo que se reciba significa que el cliente ha sido bloqueado para seguir recibiendo mensajes/cobros. Debe darlo de baja de su plataforma.
    • charge_date: Siendo [Datetime] el valor correspondiente a la fecha en que se realizó el cobro. Tener en cuenta que el timezone es GTM-3.
    • tariff: Siendo [String] la referencia a la tarifa con la que se cobró el servicio.
    • Info: Siendo [String] la información proporcionada por el carrier al momento de hacer el cobro.
    Ejemplo envío de MTRequestNotify

    Ejemplo de una notificación exitosa de cobro y de despacho hacia el carrier.

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <MTRequestNotify>
    <Servicio id="70370.bill.cti.ar"/>
    <Telefono msisdn="1148965523" idtran="14" RefId ="12345678"/>
    <Estado deliverdate="2013-03-03 11:55:57" status="MT_DELIVERED" tran_status="6"/>
    <Info>errnum:0:errstr:Status SMPP:[Code:0]</Info>
    <TicketId value="198" idtran="14" status="BILLED" tran_status="6" charge_date="2013-03-03 11:55:53" tariff="deportes">
    <Info></Info>
    </TicketId>
    </MTRequestNotify>

    A éste request iniciado por MovilGate el Integrador Externo debe contestar con un código HTTP 200, para confirmar la recepción del mismo. En caso que MovilGate no reciba respuesta, o reciba otro código, realizará los reintentos correspondientes.

    Scroll up icon