SMS Texto MO y MT
El siguiente documento tiene el objetivo definir la API de comunicación para la inyección de mensaje de texto (SMS) a la plataforma de Celcom.
Este protocolo permite inyectar SMS de texto a la plataforma de Celcom. Se debe coordinar la habilitación en el Firewall de Celcom para los servidores que se conectan a Celcom.
IMPORTANTE: la API tiene una restricción de tasa de envío. Por defecto es de 5 SMS/seg salvo se acuerde explícitamente en el contrato o por acuerdos comerciales. Es responsabilidad del usuario de esta API no exceder esta tasa, de lo contrario la plataforma rechazará los envíos (ver códigos de retorno en sección 2.2).
2.1. API
Para invocar a esta API se usará el siguiente HTTP GET o POST (MI_APP es identificador único para esta conexión),
URL= http://smsapi.celcom.cl/recibe
método HTTP POST
service_id = MI_APP
clave = MI_CLAVE
nro_movil = CELULAR_DESTINO
nro_corto = NUMERO_CORTO
texto= TEXTO ENCODEADO
tasacion = 0
ext_id = ID del Cliente
por ejemplo:
La API de Celcom :
- recibe los datos, valida la identificación del Cliente a través de service_id, clave e IP (opcional).
- Almacena los datos del mensaje: nro_movil, nro_corto, texto, ext_id.
- Crea un SMS y lo envía al nro_movil indicado.
Entradas:
foto
2.2. Retorno
Los códigos de retorno para API anterior sigue el siguiente formato:
<status>xxx</status>
Donde xxx puede valer:
000 = transacción aceptada
001 = número de destino no es válido
002 = número corto no es válido
003 = falta el texto
004 = clave no es válida
005 = Error enviando SMS
006 = Tasación no es válida
007 = Tasa máxima de envío fue excedida
008 = IP de Origen no está habilitada
009 = Se cumplio cuota mensual SMS
010 = faltan parametros
011 = Error interno, contactar a soporte
012 = ext_id no valido
Los códigos distintos a 000 indican una condición de error y en esos casos el mensaje es rechazado y debe volverse a enviarse si corresponde (por ejemplo en el caso de status 007).
Adicionalmente, se retorna el ID del mensaje. Esto se hace en el header del response, parámetro X-SMSGW-Msg-Id. Este ID es necesario para las notificaciones que se señalan en el punto 2.3, identificando así a qué mensaje corresponden.
2.3 Notificaciones de recepción
La aplicación externa debe incluir un Servicio WEB que atenderá la actualización del estado de cada uno de los SMS en nuestro sistema, para ello desarrollará un servicio que recibirá un POST o GET HTTP. Los parámetros del REQUEST HTTP son id_msg (ID del mensaje) y id_std (estado del mensaje). El id_msg sirve para identificar a qué mensaje corresponde la notificación. La Aplicación Externa (APP) puede hacer el match usando el ID de mensaje que se retorna en el response HTTP del envío hacia la plataforma de Celcom.
Diagrama y flujos de respuesta que tenemos actualmente para notificación de despacho:
foto
1) Respuesta SÍNCRONA que recibe la Aplicación Externa (APP) para un envío de SMS mediante un REQUEST HTTP. Los parámetros a recibir se detallaron en el punto 2.2
2) Primera respuesta ASÍNCRONA que debería recibir la APP con la confirmación de la entrega del mensaje desde CELCOM al Operador. Es un REQUEST HTTP que incluye id_msg (ID del mensaje) y id_std (estado del mensaje).
foto
3) Segunda respuesta ASÍNCRONA que debería recibir la APP con la confirmación de entrega del mensaje del Operador al teléfono móvil. Es un REQUEST HTTP que incluye id_msg (ID del mensaje) y id_std (estado del mensaje).
2.4 Control de Tasa de Envío
Se permite por defecto una tasa máxima de envío de 5 SMS/seg. Nuestro Cliente debe hacer un retardo o delay (sleep) entre envíos de 0.2 segundos, para garantizar esta tasa.
Si no cumplen la tasa máxima (si envían más de 5 SMS/seg), los mensajes serán rechazados, con status 007. El sistema simplemente chequea que pasan como mínimo 0.2 segundos entre dos envíos consecutivos.
Se puede solicitar un aumento de tasa, si las proyecciones de tráfico lo justifican.
2.5 Restricción por IP
Si se desea y para mayor seguridad de las comunicaciones, se pueden habilitar una o más IPs de origen. Cualquier invocación de la API que provenga de otra IP será rechazada con error 008.
2.6 Monitoreo de la plataforma
Se realiza invocando una URL (indicada más abajo) mediante HTTP Get, que retorna un status 0 si esta todo funcionando OK o 1 si hay algún error en el sistema que no permite el envío de SMS por el momento, los posibles retornos son:
Status 0 (sistema funcionando OK):
“El servicio se encuentra Disponible”
o bien <status>0</status>
Status 1 (el sistema no permite el envío de SMS por el momento):
<status>1</status>
La URL es http://smsapi.celcom.cl/status.jsp
2.7 Web Service Consulta SMS disponibles (Cliente Prepago)
Este web Service permite conocer la cantidad de SMS disponible para enviar, en el momento que se consulta.
Protocolo: HTTP
Metodo: POST
URL: http://smsapi.celcom.cl/rest/receiver/available
Parametros:
- service_id
- clave
Ejemplo:
Service_id = Service_Gwy
Clave = 123456
$>curl -X POST -d “service_id=Service_Gwy&clave=123456” http://smsapi.celcom.cl/rest/receiver/available
Salida:
<status>000</status>
<sms>3712</sms>
Donde:
<status> indica el resultado de la consulta. El valor “000” significa que la consulta fue exitosa. Cualquier otro resultado corresponde a un error.
<sms> muestra la cantidad restante de SMS disponibles, para el ejemplo: 3712
3. Protocolo HTTP SMS MO Texto
Este protocolo permite enviar los SMS generados desde un celular a la plataforma del Cliente. Se debe coordinar la habilitación en el Firewall de Celcom para los servidores que se conectan a Celcom.
Una vez que se reciba un SMS MO (mensaje corto originado en un celular), la API Celcom buscará en sus registros el último SMS enviado a ese mismo celular, determinará el valor del ext_id y enviará los datos al servlet que el Cliente disponga.
Cada uno de estos envíos quedará registrado para el posterior conteo. Este registro consistirá de todos los datos enviados, además del timestamp de la fecha en que se envía a la API del cliente.
En caso de que no exista un SMS MT previamente enviado al celular, el parámetro ext_id no contendrá un valor. EL uso de ext_id debe habilitarse explícitamente para el Cliente que lo solicite.
En caso que llegue más de un SMS MO desde el mismo celular, no debe volver a enviarse al cliente. Es decir, para cada SMS MT puede haber máximo un SMS MO.
3.1 Servlet para recepcion de SMS
Este servicio debe implementarlo el Cliente de Celcom. Recibe los datos de un SMS enviados desde Celcom a la plataforma del Cliente. Debe implementarse con la capacidad de recibir el siguiente HTTP POST (no soporta HTTPS) , en una URL similar a:
Acá el Cliente debe proporcionar a Celcom la URL definitiva del servlet.
foto
3.2 Retorno
Los códigos de retorno para el servicio anterior sigue el siguiente formato:
<status>xxx</status>
Donde xxx puede valer:
000 = transacción aceptada
001 = error interno
3.3 Flujo de Mensajes MO y MT
Los mensajes que se intercambien entre Celcom y Cliente deben siempre mantener el mismo formato para los campos nro_movil y nro_corto. Ejemplo:
MO:
nro_movil=15691234444
nro_corto=3040
texto=T ringtone
MT:
nro_movil=15691234444
nro_corto=3040
texto=Tu contenido llegará en unos segundos
4. Restricción de Set de Caracteres
El estándar usado se basa en el GSM 03.38, el cual fue restringido aún más debido a algunos problemas de compatibilidad de equipos más viejos. La lista de caracteres permitidos es la siguiente:
@ $ ! " # % & ' ( ) * + , - . /
0 1 2 3 4 5 6 7 8 9 : ; < = > ?
A B C D E F G H I J K L M N O
P Q R S T U V W X Y Z
a b c d e f g h i j k l m n o
p q r s t u v w x y z
NOTA: estos caracteres son soportados para Movistar, Entel, Claro y VTR. Y para Virgin con la excepción de @ y $ (que aparecen como un símbolo de “tuerca”).
Recuerde que el texto a enviar a la API debe ser “http encodeado” para que sea interpretado correctamente.
5. Reportes CSV
Opcionalmente, los clientes que no desarrollen un servicio para recibir notificaciones, pueden solicitar acceso a la plataforma de reportes en línea, donde se muestra el detalle en un rango de fechas o por MSISDN individual.
6. Control de Versiones
Comentarios
0 comentarios
Inicie sesión para dejar un comentario.