API.NET. Lleida.net 15 de julio de 2013

Transcripción

1 API.NET Lleida.net 15 de julio de 2013

2 Copyright (c) Lleida.net 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.

3 3 Resumen Este documento especifica la configuración y las funcionalidades construidas para el consumo de los servicios de Lleida.net La finalidad es que los perfiles técnicos dispongan de una interfaz de comunicación compatible con el Framework 4.0 o superior de.net.

4 ÍNDICE 4 Índice Resumen 3 1. Descripción de la API.NET 6 2. Requerimientos e instalación Recomendaciones Configuración 7 4. Descripción de la librería Connect Descripción Evento de respuesta Quit Descripción Evento de respuesta AllowAnswerCommand Descripción Evento de respuesta SendScheduledSMSText Descripción Evento de respuesta SendSMSText Descripción Evento de respuesta GetBalance Descripción Evento de respuesta GetFare Descripción Evento de respuesta SendWapLink Descripción Evento de respuesta SendWapLink Descripción Evento de respuesta SendMMS SMILMessage Descripción

5 ÍNDICE Evento de respuesta SendFileMsg Descripción Evento de respuesta EnableAcknowledgment Descripción Evento de respuesta DisableAcknowledgment Descripción Evento de respuesta CheckAll Descripción Evento de respuesta CheckNetwork Descripción Evento de respuesta Eventos de Servidor OnPingReceived OnDisconnected OnIncomingReceived OnAcuseReceived Anexos Anexo

6 1 DESCRIPCIÓN DE LA API.NET 6 1. Descripción de la API.NET Es una librería para la creación de aplicaciones basadas en el framework 4 o superior de.net con funciones de mensajería SMS/MMS a través de la Pasarela Avanzada de Mensajería (PAM) de Lleida.net Incluye la implementación del protocolo de comunicaciones de SMS MA- SIVO, para el envío masivo de mensajes de texto SMS y MMS, así como enlaces WAP y contenidos WAP-PUSH. Esta API está disponible gratuitamente en la página web oficial del servicio: 2. Requerimientos e instalación La API funciona correctamente con la versión Framework 4 o superior. Requiere el uso de SOCKETS y conexión a la pasarela de mensajería de Lleida.net (normalmente el host es sms.lleida.net y el puerto tcp 2048) por lo que deberemos consultar al administrador del servidor Web o proveedor de servicios de Hosting en caso de que la conexión está limitada por algún tipo de cortafuegos. Es imprescindible disponer de una cuenta con saldo para el envío de mensajes. Puede obtener una cuenta de usuario de forma totalmente gratuita a través de la página web de Lleida.net o llamando al teléfono de atención al cliente Recomendaciones Si desea establecer conexiones seguras SSL, deberá seguir los pasos detallados en 6

7 3 CONFIGURACIÓN 7 La API requiere de los siguientes ficheros: net.lleida.sms.dll: Librería.NET con la funcionalidad descrita en la sección 4. App.config: Archivo de configuración cliente. Debe contener las características log4net descritas en la sección de Configuración (ver 3) sms.cer: Debe instalarse como certificado de raiz de confianza. ipscaglobal.crt: Debe instalarse como certificado de raiz de confianza. 3. Configuración <configsections> <section name="log4net" type="log4net.config.log4netconfigurationsectionhandler, log4net" /> </configsections> <log4net debug="false"> <appender name="logfileappender" type="log4net.appender.fileappender,log4net" > <file value="[localpath]\log-file.txt" /> <appendtofile value="true" /> <layout type="log4net.layout.patternlayout"> <conversionpattern value=" %date [ %thread] %-5level %logger [ %property{ndc}] - %message %newline" /> </layout> </appender> <root> <priority value="error" /> <appender-ref ref="logfileappender" /> </root> <category name="net.lleida.sms.protocol"> <priority value="all" /> </category> </log4net> El archivo de configuración debe contener la sección log4net y que ésta sea definida en las secciones de configuración. Se trata de la utilidad de logging de la librería y sus parámetros mas relevantes son:

8 4 DESCRIPCIÓN DE LA LIBRERÍA 8 <file>: Su valor indica el fichero (ruta completa) de log. <conversionpattern>: Indica el formato en que se escribirán cada una de las líneas del fichero de log. <priority>: Indica que tipo de mensajes se registrarán en el log. La librería.net solo registrará mensajes de ERROR. <category>: Indica la instancia de log que escribirá en el fichero de log. Si se desea registrar el log de la librería, este valor no debe modificarse. 4. Descripción de la librería 4.1. Connect Descripción Conecta con los servicios de Lleida.net mediante un usuario y contraseãśa de cliente. Es obligatorio establecer si se desea conectar mediante SSL o no Evento de respuesta OnConnected Devuelve por parámetro un boleano que indica si está o no conectado y un mensaje errormessage si conectado es falso, indicando el motivo Quit Descripción Cierra la conexión con los servicios PAM de Lleida.net Evento de respuesta OnQuit 4.3. AllowAnswerCommand Descripción Habilita o deshabilita el comando allowanswer. El parámetro turnonoff, debe informarse mediante:

9 4 DESCRIPCIÓN DE LA LIBRERÍA 9 Y Para indicar que se desea activar el comando. N Para indicar que se desea desactivar el comando Evento de respuesta OnAllowAnswer 4.4. SendScheduledSMSText Descripción Método sobrecargado que envía SMSs de texto planificados. Existen dos sobrecargas para poder enviar SMSs con remitente personalizado o sin él. Los parámetros pueden ser: allowanswer Indica si la repuesta al SMS de texto enviado está habilitada. mode Indica si el mensaje se envía en formato binario, unicode o normal. mtid Id que ayuda al usuario a identificar la respuesta del servidor. customizedsender Valor utilizado para mostrar como remitente personalizado del SMS de texto. recipient Destinatario del SMS. text Texto del mensaje. scheduled Fecha en la que se desea que el mensaje sea enviado. El formato debe ser YYYYMMDDhhmm[+-]ZZzz.

10 4 DESCRIPCIÓN DE LA LIBRERÍA Evento de respuesta OnSentScheduledSMSText Devuelve por parámetro el id informado en el Método (mtid) y un mensaje errormessage en caso de haberse producido SendSMSText Descripción Método sobrecargado que envía SMSs de texto. Al igual que SendScheduledSMSText, existen dos sobrecargas para poder enviar SMSs con remitente personalizado o sin él. Los parámetros pueden ser: allowanswer Indica si la repuesta al SMS de texto enviado está habilitada. mode Indica si el mensaje se envía en formato binario, unicode o normal. mtid Id que ayuda al usuario a identificar la respuesta del servidor. customizedsender Valor utilizado para mostrar como remitente personalizado del SMS de texto. recipient Destinatario del SMS. text Texto del mensaje Evento de respuesta OnSentSMSText Devuelve por parámetro el id informado en el Método (mtid) y un mensaje errormessage en caso de haberse producido GetBalance Descripción Obtiene el saldo de un usuario conectado.

11 4 DESCRIPCIÓN DE LA LIBRERÍA Evento de respuesta OnBalanceReceived Devuelve por parámetro el saldo y un mensaje errormessage en caso de haberse producido GetFare Descripción Recupera la tarifa asociada al número de teléfono pasado por parámetro Evento de respuesta OnFareReceived Devuelve por parámetro: sendednumber número de teléfono del que se ha realizado la consulta. farecode Código de la tarifa. mtprice Precio del MT. acknowledgment Acuse de recivo. sender Remitente errormessage Mensaje de error en caso de haberse producido SendWapLink Descripción Evento de respuesta

12 4 DESCRIPCIÓN DE LA LIBRERÍA SendWapLink Descripción Envia un mensaje con un link. Los parámetros son: recipient Inúmero de teléfono al que va dirijido el mensaje. url Url del link que se va a enviar. comment Comentarios adicionales que apareceran en el mensaje Evento de respuesta OnWapLinkSent Devuelve por parámetro: errormessage Mensaje de error en caso de haberse producido SendMMS SMILMessage Descripción envía un MMS o un mensaje en formato SMIL. Los parámetro son: mmstype Enumerador para indicar si el mensaje es MMS o SMIL. recipient Inúmero de teléfono al que va dirijido el mensaje. mimetype Formato del contenido del mensaje. data Datos del mensaje en codificado en formato Base64. text Texto que aparecerá en el mensaje.

13 4 DESCRIPCIÓN DE LA LIBRERÍA Evento de respuesta OnMMS SMILSent balance Saldo disponible después de la operación. failed Listado de destinos fallidos. errormessage Mensaje de error en caso de haberse producido SendFileMsg Descripción envía un fichero adjunto en el mensaje. Los parámetros son: recipient número de teléfono al que va dirijido el mensaje. mimetype Formato del contenido del mensaje. data Datos del mensaje en codificado en formato Base64. title Texto que aparecerá como título en el mensaje. text Texto que aparecerá en el mensaje Evento de respuesta OnFileMsgSent balance Saldo disponible después de la operación. failed Listado de destinos fallidos. errormessage Mensaje de error en caso de haberse producido.

14 4 DESCRIPCIÓN DE LA LIBRERÍA EnableAcknowledgment Descripción Activa el acuse de recibo de los mensajes para la sesión en curso. Los parámetros son: certtype Tipo de certificado. Por defecto o en forma de transacción. Es un enumerado. lang Código de dos letras del idioma en que se enviará le acuse. Es un enumerado. type Datos del mensaje en codificado en formato Base64. Es un enumerado. mail Correo electronico para el envío del acuse certificado Evento de respuesta OnAcknowledgmentEnabled errormessage Mensaje de error en caso de haberse producido DisableAcknowledgment Descripción Desactiva el acuse de recibo para la sesion en curso Evento de respuesta OnAcknowledgmentEnabled errormessage Mensaje de error en caso de haberse producido.

15 4 DESCRIPCIÓN DE LA LIBRERÍA CheckAll Descripción Solicita la resolución total de MSIDSN de un número number dado. Como resultado se obtiene el MCC, el MNC y información sobre el estado y existencia del mismo. Las consultas realizadas con este comando tienen en cuenta datos de portabilidad Evento de respuesta OnCheckallResponsed id Identificador de respuesta. timestamp Fecha en la que se recibe la respuesta del servidor. El formato debe ser YYYYMMDDhhmm[+-]ZZzz. numero número de teléfono del que se ha solicitado la información. ok Contiene 1 si la consulda MRS se ha realizado correctamente o 0 si se ha producido algun error en el proceso. rcode Contiene el Código de estado o error del número de teléfono consultado. Los posibles valores son: -2 : Invalid number to resolve. El número de teléfono especificado no es válido. -1 : Timeout while processing job or system failure. Se ha superado el tiempo máximo de espera sin obtener respuesta o se ha recibido un Fallo de sistema por parte del HLR (Home Location Register). 0 : Successful operation. La operación de consulta se ha realizado correctamente / Subscriptor válido. 1 : Invalid query format, data missing or unknown error. Se ha producido un error interno de formato, faltan datos, estan incompletos o se ha producido un error desconocido. 2 : Timeout while processing job. Se ha superado el tiempo máximo de espera sin obtener respuesta.

16 4 DESCRIPCIÓN DE LA LIBRERÍA 16 3 : Subscriber does not exist. El subscriptor no se ha identificado en el HLR (Home Location Register). 4 : Teleservice not provisioned. El subscriptor no soparta el servicio. 5 : Call barred or CUG reject. La operadora no permite enviar llamadas o mensajes al subscriptor o el subscriptor no pasa la prueba de CUG (Closed User Group) y no permite la recepción. 6 : CUG reject. El subscriptor no ha pasado la validación de CUG(Closer User Group) y ha sido rechazado para el uso de SMS. 7 : Facility not supported. El subscriptor actualmente no puede utilizar el servicio. (Ej: Roaming). 9 : Absent subscriber. El subscriptor no esta disponible actualmente.v (Ej: Apagado o fuera de cobertura). 12 : Wrong number. El número de teléfono del suscriptor es inválido. mcc Mobile Country Code. mnc Mobile Network Code. errormessage Mensaje de error en caso de haberse producido CheckNetwork Descripción Solicita la resolución parcial de MSIDSN de un número number dado. Como resultado se obtiene únicamente el MCC, el MNC. Las consultas realizadas con este comando tienen en cuenta datos de portabilidad Evento de respuesta OnCheckNetworkResponsed id Identificador de respuesta.

17 4 DESCRIPCIÓN DE LA LIBRERÍA 17 timestamp Fecha en la que se recibe la respuesta del servidor. El formato debe ser YYYYMMDDhhmm[+-]ZZzz. numero Número de teléfono del que se ha solicitado la información. ok Contiene 1 si la consulda MRS se ha realizado correctamente o 0 si se ha producido algun error en el proceso. rcode Contiene el código de estado o error del número de teléfono consultado. Los posibles valores son: -2 : Invalid number to resolve. El número de teléfono especificado no es válido. -1 : Timeout while processing job or system failure. Se ha superado el tiempo máximo de espera sin obtener respuesta o se ha recibido un Fallo de sistema por parte del HLR (Home Location Register). 0 : Successful operation. La operación de consulta se ha realizado correctamente / Subscriptor válido. 1 : Invalid query format, data missing or unknown error. Se ha producido un error interno de formato, faltan datos, estan incompletos o se ha producido un error desconocido. 2 : Timeout while processing job. Se ha superado el tiempo máximo de espera sin obtener respuesta. 3 : Subscriber does not exist. El subscriptor no se ha identificado en el HLR (Home Location Register). 4 : Teleservice not provisioned. El subscriptor no soparta el servicio. 5 : Call barred or CUG reject. La operadora no permite enviar llamadas o mensajes al subscriptor o el subscriptor no pasa la prueba de CUG (Closed User Group) y no permite la recepción. 6 : CUG reject. El subscriptor no ha pasado la validación de CUG(Closer User Group) y ha sido rechazado para el uso de SMS. 7 : Facility not supported. El subscriptor actualmente no puede utilizar el servicio. (Ej: Roaming). 9 : Absent subscriber. El subscriptor no esta disponible actualmente.v (Ej: Apagado o fuera de cobertura).

18 4 DESCRIPCIÓN DE LA LIBRERÍA : Wrong number. El número de teléfono del suscriptor es inválido. mcc Mobile Country Code. mnc Mobile Network Code. errormessage Mensaje de error en caso de haberse producido.

19 5 EVENTOS DE SERVIDOR Eventos de Servidor Los eventos de servidor son respuesta recibidas desde el servidor. El servidor puede enviar una respuesta por peticiï n o varias respuestas a causa de una peticiï n inicial. Por ejemplo, al hacer login, el servidor envia automï ticamente respuestas de PING cada cierto tiempo. Estas respuestas de servidor lanzan un evento que pueden ser recopilados. A continuaciï n se describen los eventos de respuestas periï dicas OnPingReceived Se recibe cuando el servidor realiza un PING al cliente para saber si se encuentra conectado o no OnDisconnected Se produce cuando el socket se desconecta OnIncomingReceived Se produce cuando el cliente recibe un MO. Los parï metros que se reciben son: id ID del servidor. timestamp Fecha de recepciï n del MO. sender Remitente. to Destino. text Texto del MO OnAcuseReceived Se produce cuando el MO llega al cliente. Los parï metros que se reciben son:

20 5 EVENTOS DE SERVIDOR 20 id ID del servidor. timestamp Fecha de recepciï n del MO. to Destino. state Estado. ACKED : Entregado a la operadora correctamente. BUFFERED : Teléfono apagado o fuera de cobertura. FAILED : El mensaje no se puede entregar en destino. DELIVRD : El mensaje ha sido entregado en destino. text Texto del MO.

21 6 ANEXOS Anexos 6.1. Anexo 1 Instalar el archivo *.cer y *.crt en el directorio de raíz de confianza en Windows. Los pasos son los mismos para ambos certificados. Hacer doble click sobre el archivo. Aparecerá un cuadro de dialogo como el siguiente: Pulsar sobre Instalar certificado....

22 6 ANEXOS 22 Hacer click en siguiente. Aparecerá un cuadro de dialogo para elegir dónde se alamacenará el certificado. Seleccionar la segunda opción como indica la imágen:

23 6 ANEXOS 23 Pulsar sobre Examinar... y seleccionar Entidades de certificación de raíz de confianza como indica la imagen:

24 6 ANEXOS 24 Aceptar y pulsar finalizar:

25 6 ANEXOS 25 El certificado se ha instalado con éxito: