Protocolo de Interconexión HTTP
SMS Texto MO y MT
Celcom
Tabla de Contenidos
1. Introducción
2. Protocolo HTTP SMS MT Texto
2.1. API
2.2. Retorno
2.3 Notificaciones de recepción
2.4 Control de Tasa de Envío
2.5 Restricción por IP
2.6 Monitoreo de la plataforma
2.7 Web Service Consulta SMS disponibles (Cliente Prepago)
3. Protocolo HTTP SMS MO Texto
3.1 Servlet para recepcion de SMS
3.2 Retorno
3.3 Flujo de Mensajes MO y MT
4. Restricción de Set de Caracteres
5. Reportes CSV
6. Control de Versiones
1. Introducción
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.
2. Protocolo HTTP SMS MT Texto
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:
http://smsapi.celcom.cl/recibe?service_id=MI_APP&nro_movil=56483457&nro_corto=3
030&texto=Hola+Mundo&clave=mc.2011&tasacion=0&ext_id=CAS-04742-T1R1Q9
La API de Celcom :
1) recibe los datos, valida la identificación del Cliente a través de service_id, clave
e IP (opcional).
2) Almacena los datos del mensaje: nro_movil, nro_corto, texto, ext_id.
3) Crea un SMS y lo envía al nro_movil indicado.
Entradas:
parámetro descripción Formato Valores posibles
ID único del servicio
Tipo: Alfanumérico
service_id
(identifica la conexión) Largo: Máx. 20
Número de teléfono móvil Tipo: Numérico
nro_movil
Largo: 8 a 11
Número corto asociado al Tipo: Numérico
nro_corto
servicio Largo: 4 a 11
Texto del SMS Tipo: Alfanumérico Ver punto 4:
texto Largo: 160 (sin Restricción de Set de
encoding) Caracteres
Password de acceso a la Tipo: Alfanumérico Celcom entregará
clave
URL Largo: Máx. 30 esta clave de acceso.
Tipo de tasación Tipo: Numérico Dejar fijo en 0 (no
tasacion Largo: 1 tasado al usuario)
Opcional. Identificador para Tipo: Alfanumérico.
ext_id uso del Cliente, previo Largo maximo: 24
acuerdo comercial.
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:
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).
Estado (id_std) Descripción
010 Mensaje entregado al Operador.
011 Error. El mensaje no pudo ser entregado al
Operador.
012 Número móvil en lista negra
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).
Estado (id_std) Descripción
020 Mensaje entregado al teléfono móvil.
021 Error. El mensaje no pudo ser entregado al teléfono
móvil.
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:
http://server/app/receiveSMS
Acá el Cliente debe proporcionar a Celcom la URL definitiva del servlet.
Parámetro Descripción Formato Valores
Posibles
nro_movil Número del teléfono móvil Tipo: Numérico
(origen del SMS). Largo: 8 a 11
nro_corto Número corto (destino del Tipo: Numérico
SMS) Largo: 4 a 11
texto Texto enviado. Tipo: Encodeado en
Alfanumérico - formato http
Largo: 160 (sin (RFC 1738).
http
encoding)
idms Opcional. Identificador del Tipo:
mensaje para uso del Alfanumérico.
Cliente Largo máximo: 24
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
versión fecha autor descripción
1.0 18-12-2013 Emilio Jaque versión inicial
1.1 23-04-2015 José Andrés Alfaro Se agrega interfaz web
service
1.2 28-04-2015 José Andrés Alfaro Se agrega el manejo de
id del Cliente
1.21 15-6-2015 José Andrés Alfaro Se modifica el nombre
del id del mensaje para
uso del Cliente
1.2.2 15-01-2016 Daniel Ovalle Sch. Se agrega
documentacion WS
consulta creditos
1.2.3 18-03-2016 José Andrés Alfaro Se completa 3.1 y 4.
1.2.4 27-12-2016 Daniel Ovalle Sch. Actualiza acceso a
reportes y se completa
DLR operador Claro.
