FTP2SMS Envío masivo de SMS por FTP Generador de informes para los DR Dpto. I+D LleidaNetworks Serveis Telemàtics S.L. Junio 2012 1
Copyright (c) 2012 - Lleida Networks Serveis Telematics, S.L. Todos los derechos reservados. Este documento contiene información propietaria y confidencial. Queda totalmente prohibido distribuir sus contenidos total o parcialmente por cualquier medio, sea físico o electrónico, sin la autorización expresa de su titular. 2
Índice de contenido Autores... 4 Novedades... 4 Introducción... 5 Descripción de la Tecnología...5 Que es el protocolo smsmassivo?...6 Como funciona?... 6 Formato del fichero...6 Nombre del fichero...7 Ejemplos de nombre de fichero...7 Notas importantes... 8 Opciones... 9 Resumen de Opciones...9 #SCHEDULED: YYYYMMDDHHMM[[+ -]HHMM]...10 Ejemplos... 10 #CUSTOMIZED_SENDER:[NUMBER TEXT]...10 #ALLOWANSWER: [ON OFF]...10 Ejemplos... 10 #TEXT:El mismo texto para todos...10 Ejemplos... 10 Acuse de recibo... 11 Ejemplos... 11 #DELIMITER: [, ;. @]...11 #UNICODE: [NO YES]...11 #RATIO_SMS:[1.. 50.. 1000]...12 #RATIO_MINUTES: [5 10 15.. 60]...12 Ejemplos... 12 #VERIFY_ONLY:[NO YES]...12 #ID:TEXT... 12 Ejemplos... 13 Fichero: promocion_easport1221.sms...13 Fichero: promocion_easport1222.sms...13 Fichero: 200902241313_100_10_SI.sms...13 Generador de informes DR...14 Formato del nombre del informe...14 Formato del fichero...14 Estado finales... 14 Enlaces de interés... 15 3
Autores Autores La tabla siguiente enumera a los autores de FTP2SMS. Departamento Autor Fecha Desarrollo David Tàpia Porcel 23.02.2009 Novedades Estas novedades están asociadas a la versión 2.0 del FTP2SMS. Esta guía fue actualizada el 14 de junio de 2012. La tabla siguiente describe los cambios mas importes desde el lanzamiento de la guía para desarrolladores del FTP2SMS. Cambios Descripción Fecha Primera versión Esta es la primera versión de la guía. 23.02.2009 Primera versión Se han añadido los comentarios del Ignasi. 24.02.2009 Primera versión Se han añadido los comentarios del D. Estopa 24.02.2009 Segunda Se ha quitado la opción COLUMNS 25.03.2009 Tercera Se modificado el texto para que pueda ser entregado a los clientes. 28.05.2009 Cuarta Se han añadido explicaciones de cada opción 01.06.2009 Quinta Se han añadido mas opcionales en los acuses y se a documentado el parámetro ID 02.06.2011 Sexta Modificación para el generador de informes DR 30.07.2011 Séptima Se ha añadido la opción de enviar SMS directamente 20.02.2012 Octava Añadidas varias aclaraciones 14.06.2012 4
Introducción Introducción Lleida.net es la primera operadora de SMS que se creó en el mercado español de las telecomunicaciones y como operadora ha desarrollado una red propia de interconexiones a nivel nacional e internacional. Dispone de clientes en más de 30 países y de una alta gama de productos y servicios para sus usuarios y distribuidores. Los productos y servicios de Lleida.net están presentes: En los tres ámbitos territoriales de la administración pública. En los partidos políticos. En los medios de comunicación. En Pymes y grandes empresas que operan dentro y fuera del estado Español. Nuestros servicios los ofrecemos mediante el protocolo propietario de Lleida.net cuyo objetivo es proporcionar un sistema para redes IP para el envío y recepción de SMS o MMS que sea fácil de implementar por parte del cliente. Para nuestros clientes tenemos disponible la SDK y la web de soporte [w3sdk]. El departamento de I+D desarrolla soluciones para nuestro protocolo como, por ejemplo: Las API XML (EAI Enterprise Application Integration), estas son HTTP XML, PDF XML y Registro. La API Java, la API PHP y el componente ActiveX OCX. Envíos de SMS mediante el correo electrónico (SMTP XML API) La administración de los distribuidores (Admin XML API) Este documento presenta las opciones mas comunes usadas en la API ftp2sms mediante el uso de pequeños ejemplos. El principal objetivo de esta guía y de la API es ayudar a desarrollar aplicaciones. La API ftp2sms requiere de una conexión sftp al puerto 22 para conexiones seguras. Esto significa que las aplicaciones clientes necesitan tener un filtro de cortafuegos correctamente configurado. Descripción de la Tecnología ftp2sms permitirá enviar SMS programados mediante la subida de un fichero de texto plano con un formato predefino. Se facilitara una URL para subir los ficheros por sftp. Se requiere de un usuario de sms de Lleida.net y de un usuario de sftp correctamente configurado para poder subir los ficheros de texto con los datos del envío. Se ha facilitado la generación de los ficheros con la web http://ftp2sms.lleida.net donde hay una explicación de todos los comandos aceptados junto con un generador de ficheros. Este sistema internamente usa el protocolo smsmassivo propietario de Lleida.net 5
Introducción Que es el protocolo smsmassivo? El objetivo del protocolo smsmassivo es proporcionar un sistema para redes IP para el envío y recepción de SMS o MMS que sea fácil de implementar por parte del cliente. Todos los mensajes que se intercambian entre cliente y servidor son líneas de texto acabadas en \n (ASCII 10), y siempre tienen la misma sintaxis: <etiqueta> <comando> [parámetros]\n La etiqueta sirve para poder enlazar fácilmente los comandos con las respuestas que generan, ya que la respuesta siempre va precedida por la misma etiqueta que el comando. La etiqueta tiene que ser una secuencia monotónica creciente de enteros. Los SMS pueden ser de tipo MO (mobile originated) o MT (mobile terminated). El envío de un MT consume créditos del saldo del cliente. El saldo para cada cliente es un numero decimal que se incrementa cuando se realizan recargas y se decrementa cuando se realizan envíos. La cantidad de créditos decrementada varía según el país de destino y las opciones activadas para el MT. Puede consultar las tarifas y países en nuestra web [w3red]. Los comandos disponibles son case insensitive. Como funciona? Cada cliente que quiera usar este método de envío deberá solicitar el alta a su comercial. Se habilitara un directorio de sftp único, de este modo los ficheros contenidos en ese directorio se enviaran con la cuenta de SMS del cliente. Una cuenta de SMS solo puede tener un usuario de sftp y viceversa. Formato del fichero El nombre del fichero y su extensión puede ser el que quieran. Recomendamos poner nombres significativos y que contengan algún identificador. La extensión puede ser *.txt, *.sms, *.s o la que se crea oportuna. Al inicio del fichero deberán estar definidos todos los parámetros opcionales descritos mas adelante en esta documentación. Los ficheros pueden contener tantos comentarios como se desee. Cada destino estará definido en una única linea y estará compuesto por tres columnas separadas con el carácter coma ',' o bien con el opcional #DELIMITER. Por orden estas columnas son: Destino Identificador único del envío para ese destino. Texto del mensaje Por ejemplo: +34656878949,ID1,Texto del mensaje Con el opcional #DELIMITER:; el mismo ejemplo seria: +34656878949;ID1;Texto del mensaje 6
Como funciona? Opcionalmente se puede obviar la columna ID, En este caso se usa un identificador autogenerado: +34656878949,Texto del mensaje Además existe este otro formato, cada destino estará definido en una única linea y estará compuesto por tres columnas separadas con el carácter coma ',' o bien con el opcional #DELIMITER. Por orden estas columnas son: Destino Remitente personalizado Texto del mensaje Por ejemplo: +34656878949,973909090,Texto del mensaje Con el opcional #DELIMITER:; el mismo ejemplo seria: +34656878949;973909090;Texto del mensaje En este caso se usa un identificador auto-generado. Los únicos opcionales validos para este formato son los referentes a los acuses. Los mensajes se envían una vez se a leído todo el fichero. Nombre del fichero El sistema acepta cualquier nombre de fichero, pero el formato que recomendamos es este: YYYYMMDDHHMM_NUMEROSMS_XTIEMPO_ACUSE.sms Donde: YYYYMMDDHHMM es la fecha para programar los SMS NUMEROSMS es el numero de SMS que se quieren enviar cada X minutos XTIEMPO son fracciones de 5 minutos, 5, 10, 15, 20, etc... ACUSE servirá para configurar los acuses. Puede tomar los valores SI, NO, LANG_TIPO. Ejemplos de nombre de fichero 200902241500_50_10_SI.sms En este ejemplo se programaran los envíos de los SMS para el día 24 de Febrero de 2009 a partir de las 15:00 y con una carencia de 50 SMS cada 10 minutos y se enviaran con acuse. 200903010000_10_5_NO.sms en este caso se envían los SMS sin acuse con una carencia de 10 SMS cada 5 minutos y se programaran para el día 1 de Marzo del 2009. 200903010000_10_5_ES_D.sms en este caso se envían los SMS con acuse certificado con una carencia de 10 SMS cada 5 minutos y se programaran para el día 1 de Marzo del 2009. 200903010000_10_5_ES_T.sms en este caso se envían los SMS mediante contrato certificado con una carencia de 10 SMS cada 5 minutos y se programaran para el día 1 de Marzo del 2009. 7
Como funciona? mifichero en este caso se leerán los opcionales del fichero y los requisitos mínimos para que funcione correctamente es tener el opcional #SCHEDULED. Sin la fecha de programación se genera un error y no se enviaran! Notas importantes Si las fechas de programación no se especifica el parámetro SCHEDULED el sistema marcara como invalido el fichero y no se realizar el envío. Si la fecha de programación del envío es anterior a la fecha actual se realizara el envío en el mismo momento que se procese todo el fichero. Por este motivo recomendamos encarecidamente que se verifiquen las fechas antes de subir el fichero. El cliente es el responsable de realizar el mantenimiento de los ficheros de su cuenta. Si se realiza un uso indebido del servicio se tomaran las medidas oportunas. Todas las lineas deben tener definido el ID. Si se decide usar el formato viejo no se pueden mezclar lineas con y sin ID. Puede mezclar ficheros con los dos formatos pero no puede mezclar los dos formatos en el mismo fichero. En caso que deseen usar el tercer formato (DST,SRC,SMS) lo deberán indicar a su comercial ya que este formato es incompatible con los dos anteriores. Los valores de las opciones no pueden contener el carácter :. Este carácter se considera un símbolo especial ya que separa la clave del valor #OPCION:VALOR 8
Opciones Opciones Resumen de Opciones. Lea el apartado Opciones para mas detalles. ACUSE: [NO* YES CERT] ACUSE_LANG: [CA ES* EN PT..] ACUSE_TYPE: [D* T] ACUSE_MAIL: [your@mailaccount.tld no-reply@lleida.net*] ACUSE_NAME: Razón social del certificado ACUSE_NAMEID: Identificador fiscal (DNI, CIF, NIF, etc.) del certificado ID: Identificador del envío. Alfanumérico UNICODE: [NO* YES] SCHEDULED: YYYYMMDDHHMM[[+ -]HHMM] [CUSTOMIZED_SENDER: [NUMBER TEXT] ALLOWANSWER: [ON* OFF]] RATIO_SMS: [1.. 50*.. 500] Numero de SMS a enviar cada RATIO_MINUTES RATIO_MINUTES: [5* 10 15...] Fracciones de 5 minutos TEXT: Es el mismo texto para todos los destinos acepta columnas %C1% DELIMITER: [,* ;. @] VERIFY_ONLY ## Dos caracteres # permiten al usuario poner comentarios unilínea El símbolo * denota la opción por defecto. 9
#SCHEDULED: YYYYMMDDHHMM[[+ -]HHMM] Esta opción le permite definir la hora y fecha de inicio del envio. YYYY Hace referencia al año MM Es el mes DD Es el día HH Es la hora MM Son los minutos [+-]HHMM - Indica el desplazamiento de su fecha local a GMT+0. Por ejemplo, en España peninsular y en horario de verano es -0200. Ejemplos #SCHEDULED:200906061808+0230 #CUSTOMIZED_SENDER:[NUMBER TEXT] #ALLOWANSWER: [ON OFF] Le permite definir el remitente personalizado o que el remitente sea su numero largo. Son mutuamente excluyentes. Esto significa que solo puede configurar uno de los dos. Si se definen los dos, el ALLOWANSWER tiene prioridad sobre el CUSTOMIZED_SENDER. Ejemplos # El remitente personalizado es un numero #CUSTOMIZED_SENDER:7777 # El remitente personalizado es un texto #CUSTOMIZED_SENDER:MYCOM # Se mostrara su numero largo como remitente #ALLOWANSWER:ON # Se mostrara un numero largo aleatorio y que no permita la respuesta #ALLOWANSWER:OFF #TEXT:El mismo texto para todos Define el mismo texto para todos los destinatarios. Se pueden definir las columnas que se deseen. El formato debe de ser #COLn donde n es una secuencia monotónica creciente. Ejemplos #TEXT:Hi #COL1 keep in mind your bonus discount of #COL2 till #COL3 #TEXT:Happy hour! Don t miss it, come to GOGODOLL 10
Acuse de recibo Las opciones para configurar el acuse de recibo son varias: #ACUSE:[NO YES CERT] Determina si se desea el acuse de recibo o no o bien si desea hacer el envío certificado. #ACUSE_MAIL:[your@mail.com no-reply@lleida.net] Es el correo electrónico donde se enviaran los acuses de recibo. #ACUSE_LANG:[CA DE EN ES FR IT NL PL PT SE] Es el idioma de los acuses de recibo. Si no se definen las opciones anteriores esta opción se ignora. #ACUSE_TYPE: [D T] Es el tipo de certificado, D certificado y T contrato. Si no se definen las opciones anteriores esta opción se ignora. Ejemplos # Sin acuse de recibo #ACUSE:NO # Acuse de recibo estándar #ACUSE:YES #ACUSE_MAIL:your@mail.com # Acuse de recibo certificado #ACUSE:CERT #ACUSE_MAIL:your@mail.com #ACUSE_LANG:EN #ACUSE_TYPE:T #DELIMITER: [, ;. @] Define el separador de columnas. En el fichero cada linea que no empiece por # se considera que es una linea con datos. La primera columna es el numero del destinatario y las siguientes o bien es el texto a enviarle o bien son las columnas definas en la opción #TEXT. #UNICODE: [NO YES] Define si desea hacer el envío en formato Unicode. Los textos deben estar codificados en Base64 sin saltos de linea. 11
#RATIO_SMS:[1.. 50.. 1000] #RATIO_MINUTES: [5 10 15.. 60] Partiendo de la fecha de programación del envío y del ratio de minutos se calcula la siguiente fecha de envío del conjunto de SMS. El ratio de SMS define el numero de mensajes del conjunto con un mínimo de 1 SMS hasta un máximo de 1000. Ejemplos # Dos SMS cada 10 minutos #RATIO_SMS:2 #RATIO_MINUTES:10 # 5 SMS cada 5 minutos #RATIO_SMS:5 #RATIO_MINUTES:5 # 500 SMS cada 35 minutos #RATIO_SMS:500 #RATIO_MINUTES:35 #VERIFY_ONLY:[NO YES] Esta opción le permite validar el formato de un fichero sin llegar a programar el envío. #ID:TEXT Esta opción le permite identificar el envío mediante su MT_ID. Este identificador le sera útil para recuperar los estados de los mensajes en las API XML. Si no define el parámetro ID todos los envíos tendrán un identificador auto-generado. 12
Ejemplos Ejemplos Fichero: promocion_easport1221.sms ---- cut here ----- #ACUSE: CERT #ACUSE_LANG: ES #ACUSE_TYPE: D #CUSTOMIZED_SENDER:34652888444 #SCHEDULED:200902241313-0200 ## Fichero de envíos del 23/02 ## Revisado por: EA Sports 34652816884,Acabamos de empezar la promo, apuntate 34652447114,Acabamos de empezar la promo, apuntate ----- cut here ----- Fichero: promocion_easport1222.sms ---- cut here ----- #ALLOWANSWER:OFF #DELIMITER:@ ## Fichero de envíos del 23/02 ## Revisado por: EA Sports #SCHEDULED:200902241313 34652816884@Acabamos de empezar la promo, apuntate 34652447114@Acabamos de empezar la promo, apuntate ----- cut here ----- Fichero: 200902241313_100_10_SI.sms ---- cut here ----- 34652816884,Acabamos de empezar la promo, apuntate ----- cut here ----- 13
Generador de informes DR Generador de informes DR Para que el sistema genera los informes DR, o acuses de recibo, debe solicitar el alta a su comercial. Los informes se generan todos los días a las 5 de la mañana hora peninsular española. Solo se generara el informe si hay datos. Formato del nombre del informe REPORT_ACUSES_FTPXXX_DDMMYYYY_FILENAME Donde: FTPXXX es el identificador único del fichero en nuestros sistemas DDMMYYYY es la fecha de generación del informe, por ejemplo: 30062011 FILENAME es el nombre de su fichero Formato del fichero Los informes contienen 5 columnas: ID es su identificador definido en cada linea para cada destino FTP_ID es nuestro identificador para que pueda usar otras de nuestras API's Estado es el estado final del acuse puede tomar varios valores Destino es el destino del SMS Texto es el texto del SMS Estado finales Los estados finales de un acuse de recibo son: D Delivered - Enviado I Invalid - Invalido C Canceled - Cancelado F Failed - Fallado E Expired - Caducado 14
Enlaces de interés Enlaces de interés [w3sdk] [w3red] [w3ftp] http://soporte.lleida.net http://www.lleida.net/red http://ftp2sms.lleida.net 15