Especificaciones para Integración SMS para Partners - XML sobre HTTP
Diagrama de secuencia de un flujo MO-MT completo
Introducción
La plataforma de servicios de Movilgate es de naturaleza asíncrona (store and forward). Todos los servicios que se trafican desde carriers o hacia carriers son almacenados y luego despachados hacia sus clientes. Por cada acción solicitada por un cliente de un carrier la plataforma de Movilgate genera un identificador de transacción único (IdTran) asociado a esa transacción. El objetivo de ese IdTran es garantizar que los servicios dados a los clientes correspondan con las limitaciones legales / operativas impuestas por los distintos carriers a Movilgate.
Estas limitaciones se reflejan en los servicios expuestos a los socios externos por medio del IdTran único. Esto en ambos protocolos de integración.
Para lo que son transacciones interactivas la relación de los MOs con los MTs se recomienda que sea en relación de uno a dos (1 MO por 2 MTs) para mejorar la experiencia del usuario. Esta relación se cambiara en caso de que un carrier lo requiera,y en los tiempos que el carrier exija que se realice el cambio a Movilgate.
La tendencia en los operadores es tener una relación 1 MO por 1 MT, el integrador debe tener esto presente.
Protocolo XML sobre HTTP
El protocolo XML sobre HTTP trabaja usando el método POST para el envío (con Content-Type: text/xml). A continuación se describen los casos posibles presentes en este escenario.
La implementación se basa en el uso de HTTP/XML y es totalmente asincrónico.
SMS MO
REQUEST (MORequest)
Recibido un MO que debe ser reenviado al “Integrador Externo” el GW Movilgate enviará mediante POST HTTP (con Content-Type: text/xml) la siguiente información:
<?xml version="1.0" encoding="ISO-8859-1"?>
<MORequest>
<Servicio Id="string"/>
<Telefono msisdn="string" IdTran="number"/>
<Contenido>Text</Contenido>
</MORequest>
Donde:
- Servicio ID: Es el servicio y carrier desde donde se originó el mensaje. Este servicio deberá ser devuelto en la transacción MT tal cual se envía.
- Teléfono MSISDN: Teléfono del usuario.
- Teléfono IdTran: Id de transacción, generado por Movilgate y utilizado para mantener identificadas las cadenas de eventos generadas por este MO, numérico.
- Contenido: Contenido del SMS MO.
Ejemplo :
<?xml version="1.0" encoding="ISO-8859-1"?>
<MORequest>
<Servicio Id="20500.personal.ar"/>
<Telefono msisdn="1129292929" IdTran="12345678"/>
<Contenido>ring 12944</Contenido>
</MORequest>
RESPONSE
A este request el servidor del “Integrador Externo” deberá responder con un código 200 HTTP. Cualquier otra respuesta será considerada errónea y, si el servicio contempla una notificación de error, se le enviará un MT al usuario con un texto como “Servicio no disponible por el momento”.
SMS MT
REQUEST (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:
<MTRequest>
<Proveedor Id="string" Password="string"/>
<Servicio Id="string" ContentType="number" />
<Telefono msisdn="string" IdTran="number"/>
<Contenido PushText="string" DeliveryAfter="datetime" Priority="number">string</Contenido>
</MTRequest>
Donde:
- Proveedor ID: Nombre de identificación del proveedor. Provisto por Movilgate
- Proveedor Password: Password del proveedor. Provisto por Movilgate
- Servicio ID: Código de identificación del servicio y carrier. El MT es una o varias respuestas al MO-SMS de entrada, el campo “servicio” deberá corresponder en forma exacta con este.
- Servicio ContentType: 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 |
| 3 | Envia WapPush usando PPG |
Movilgate solo convierte el binario formateado a hexadecimal solo al momento de enviar para el caso de los Content Type=1.
- Teléfono / MSISDN: Teléfono al que se le enviará el mensaje. Este teléfono debe corresponder al teléfono que genero el MO, no se deben agregar formatos de numeración o quitar ceros o modificar el número en forma alguna respecto al envío del MO.
- Teléfono IdTran: IdTran del MO que origina este MT, obligatorio. Este identificador debe ser enviado y es la característica que limita el trafico entre los clientes y los integradores externos. La cantidad de MTs que se pueden enviar en función de un MO generado es por defecto dos (2) en la plataforma. Para el caso de suscripciones se ocupa el mismo método, salvo que en estos casos el costo de la suscripción reflejara la cantidad de MTs que se podrán enviar al cliente ocupando el Identificador de Transacción del MO de entrada.
En caso de envíos Bulk o sin MO previo el IdTran debe enviarse vacío.
Para todos los otros casos extraordinarios no enmarcados en este documento se deben tratar con la Gerencia Comercial.
- Contenido PushText: Titulo del WapPush a enviar (solo Content Type = 2 , Content Type = 3)
- Contenido: Mensaje a enviar.
DeliveryAfter: en este atributo se puede especificar una fecha y hora específico desde cuando se quiere que se envíe el mensaje. El mismo debe especificarse con “AÑO-MES-DÍA HORA:MINUTOS:SEGUNDOS”, por ejemplo “2010-05-25 08:00:00”
Priority: En caso que se requiera enviar un mensaje con mayor prioridad que el resto de los envíos, por ejemplo en el caso de un Token, se debe especificar este atributo con valor 1 (uno).
Aclaraciones Importantes
Se debe especificar el "Content-type: text/xml" para el POST del XML del MTRequest.
Por cuestiones de seguridad el servicio posee la limitación de envío de 50 mensajes por día por línea telefónica. Si su servicio necesita enviar una cantidad mayor de mensajes por día a una misma línea de teléfono por favor solicítelo.
Ejemplos:
a. Para un Mensaje SMS:
<MTRequest>
<Proveedor Id="EMOBILE" Password="ps29292"/>
<Servicio Id="20500.movistar.ar" ContentType="0"/>
<Telefono msisdn="11223323334" IdTran="12345678"/>
<Contenido>La password es: 78dgydfgd6</Contenido>
</MTRequest>
b. Para un WapPush: en donde el partner genera el push y lo convierte a hexadecimal :
<MTRequest>
<Proveedor Id="EMOBILE" Password="ps29292"/>
<Servicio Id="20500.movistar.ar" ContentType="1"/>
<Telefono msisdn="11223323334" IdTran="12345678"/>
<Contenido>0605040B8423F0250601ae02056A0045C60C037761702E756E746F7175652E636F6D000103486F6C61000101</Contenido>
</MTRequest>
c. Para un WapPush en donde el partner envía un URL y Titulo: En este caso Movilgate genera el push binario al cliente:
<MTRequest>
<Proveedor Id="EMOBILE" Password="ps29292"/>
<Servicio Id="20500.movistar.ar" ContentType="2"/>
<Telefono msisdn="11223323334" IdTran="12345678"/>
<Contenido PushText="Hola">http://wap.untoque.com</Contenido>
</MTRequest>
d. Para un Mensaje SMS con Billing Asociado:
<MTRequest>
<Proveedor Id="EMOBILE" Password="ps29292"/>
<Servicio Id="20500.bill.movistar.ar" ContentType="0" IsBill="1"/>
<Telefono msisdn="11223323334" IdTran="12345678"/>
<Contenido>La password es: 78dgydfgd6</Contenido>
</MTRequest>
e. Para un Mensaje SMS con una sesión asociada en el Gateway SMS:
<MTRequest>
<Proveedor Id="EMOBILE" Password="ps29292"/>
<Servicio Id="20500.movistar.ar" ContentType="0" CreateSession="1" />
<Telefono msisdn="11223323334" IdTran="12345678"/>
<Contenido>La password es: 78dgydfgd6</Contenido>
</MTRequest>
f. Para un Mensaje SMS que genera un WapPush usando un PPG Gateway
<MTRequest>
<Proveedor Id="externo" Password="xxxxx" />
<Servicio Id="5050.movistar.ar" ContentType="3" />
<Telefono msisdn="113xxxx170" IdTran="35xxxx99" />
<Contenido PushText="Demo: Ingresa aqui">http://wap.demo.com/c.pl?m=1&id=2&x=8</Contenido>
</MTRequest>
Ejemplo:
POST /prueba HTTP/1.1
Host: 64.76.120.14:1111
Content-Type: text/xml
Cache-Control: no-cache
<MTRequest>
<Proveedor Id=”movilgate” Password=”m0v1lg4t3″/>
<Servicio Id=”22210.movistar.ar” ContentType=”0″ />
<Telefono msisdn=”1144940941″ IdTran=””/>
<Contenido>Prueba SMS</Contenido>
</MTRequest>
Ejemplo curl:
curl -X POST -H “Content-Type: text/xml” “Cache-Control: no-cache” -d ‘<MTRequest>
<Proveedor Id=”movilgate” Password=”m0v1lg4t3″/>
<Servicio Id=”22210.movistar.ar” ContentType=”0″ />
<Telefono msisdn=”1144940941″ IdTran=””/>
<Contenido>Prueba SMS</Contenido>
</MTRequest>’ http://64.76.120.14:1111/prueba
RESPONSE (MTResponse)
La respuesta de forma síncrona al posteo del MTRequest seria:
<MTResponse>
<Transaccion estado=”number” IdTran=”number” Fecha=”datetime”/>
<Texto>string</Texto>
</MTResponse>
Donde Código y Texto son códigos de respuesta según la tabla siguiente.
| Código Estado | Texto Estado |
|---|---|
| 0 | Ok |
| 1 | Usuario/Password Inválida |
| 2 | XML Inválido |
| 3 | Otro, ver texto en transacción |
Ejemplo:
<MTResponse>
<Transaccion estado=”0″ IdTran=”12345678″ Fecha=”2005-02-01 20:40:30″/>
<Texto>OK: Transaccion Exitosa</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=”5050.smsc2.personal.ar” ContentType=”0″/>
<Telefono msisdn=”117272727″ IdTran=”39″/>
<Contenido>Test de Envio de Texto Plano</Contenido>
</MTRequest>’
En este ejemplo se ve el 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 80, que también es asignado por Movilgate. El IdPartner, el UsrPassword, el PORT TCP y el URL_PARTNER son asignados por Movilgate.
Nótese que el formato de envío debe respetar el MO-SMS recibido vía XML en cuanto al Servicio Id, Telefono MSISDN y el IdTran, esos valores vienen en el MO-SMS entregado en el XML al partner y deben ser devueltos tal cual a la plataforma de Movilgate para su adecuado Ruteo.
