Especificación Técnica de Protocolo Para el intercambio de información entre Telecom Personal y sus proveedores de servicios Página 1 de 26 09/12/2009
Página 2 de 26 09/12/2009
Índice OBJETIVOS... 5 INTRODUCCIÓN... 6 ANTECEDENTES... 7 DESCRIPCIÓN GENERAL... 8 ESPECIFICACIONES DE COMUNICACIÓN... 8 Parámetros de Soap Header de Entrada... 9 Parámetros de una Soap Exception... 9 WEB SERVICES WSSUSCRIPCIONES... 10 CONSIDERACIONES IMPORTANTES... 18 APÉNDICE... 19 WSSuscripciones.gestionarServicio() Ejemplos... 19 Ejemplo parcial de un mensaje soap de una llamada al método gestionarservicio... 19 Ejemplo parcial de un mensaje soap de respuesta con éxito de una llamada al metodo... 19 WSSuscripciones.consulta() Ejemplos... 21 Ejemplo parcial de un mensaje soap de una llamada al método consulta.... 21 Ejemplo parcial de un mensaje soap de respuesta con éxito de una llamada al método consulta... 21 WSSuscripciones.listarServicios() Ejemplos... 23 Ejemplo parcial de un mensaje soap de una llamada al método listarservicios... 23 Ejemplo parcial de un mensaje soap de respuesta con éxito de una llamada al método consulta... 23 WSSUSCRIPCIONES WSDL:... 25 GLOSARIO... 26 Página 3 de 26 09/12/2009
Historia de las revisiones Fecha de creación: 28/01/2009 Nombre del creador: WEB y VAS Marcos Javier Lamas Número de Revisión Fecha de Revisión Modificado por Resumen de los Cambios 0.1 28/01/2009 Marcos Lamas Versión inicial 0.4 02/02/2009 Betiana Cracco Revisión con proveedor 0.5 18/02/2009 Betiana Cracco Versión 5, se modifica el método de consulta de servicios. 0.6 18/03/2009 Andres Reynoso Se agregan ejemplos de XML de cómo son los Request y Responses de los métodos 0.7 11/05/2009 Andres Reynoso Se corrigen Nros de errores y se agrego el WSDL del WS. Página 4 de 26 09/12/2009
OBJETIVOS Unificar la forma en la que Telecom Personal se comunica con cada uno de los proveedores de servicios. Página 5 de 26 09/12/2009
INTRODUCCIÓN En el siguiente diagrama se muestra la arquitectura de los Web Services de Telecom Personal que pueden ser consumidos por cualquier cliente que requiera la información que éstos brindan. Arquitectura de Web Services Proveedores Suscripciones Proveedores Suscripciones Sistema de Telecom Personal Proveedor de TP 1 SOAP Proveedor de TP 2 SOAP INTERNET SOAP WSSuscripciones SOAP Gateway Service SOAP Proveedor de TP N Página 6 de 26 09/12/2009
ANTECEDENTES Los siguientes ítems fueron tomados como base para la confección de la presente especificación de Requerimientos: Documento Ubicación No Aplica No Aplica Página 7 de 26 09/12/2009
DESCRIPCIÓN GENERAL El proveedor de Servicios deberá proveer a Telecom Personal de un WS de producción y una para pruebas (Testing). En la presente sección se detalla estructura de cada uno de los métodos de los servicios web a ser desarrollados por los proveedores de servicios de Telecom Personal. Los proveedores de Servicios deberán proveer de un único servicio web que incluya tres (3) métodos: A) Método para consultar los servicios contratados por una línea. B) Método para solicitar la baja de un servicio para una determinada línea. C) Método para consultar todos los servicios disponibles. Cada uno de los métodos deberá respetar la estructura que se define a continuación: Solicitud / Request: A) Contener un HEADER B) Parámetros de Entrada al método Respuesta / Response A) Contener un HEADER B) Datos devueltos Especificaciones de Comunicación A continuación se describen los aspectos que deberán poseer cada uno de los métodos del servicio web Nombre del WS: El nombre del servicio web y los métodos de este serán definidos por Telecom Personal. Usuario y contraseña: Cada proveedor de servicios deberá proveer a Telecom Personal de un usuario y contraseña para acceder a los métodos del WS. El proveedor de servicios tiene la facultad de cambiar y/o actualizar periódicamente el usuario y/o contraseña, debiendo notificar a Telecom Personal con no menos de SIETE (7) días de antelación. URL: El proveedor de servicios deberá proveer una única URL para el WS. Página 8 de 26 09/12/2009
PUERTO: El puerto que le proveedor de servicios deberá abrir para que desde TP se consume el WS será el 8045. PROTOCOLO: El protocolo con el que Telecom Personal se comunicara con los WS de los proveedores de servicios es HTTPS SOAP 1.2 Certificado SSL: El proveedor deberá proveer a Telecom Personal de un certificado de SSL (Secure Socket Layer) para ser utilizado en las transacciones con el WS. Parámetros de Soap Header de Entrada Estos parámetros son usados para que el proveedor autentique que usuario esta invocando al método del WS. Nombre del Parámetro Tipo de Dato Descripción UserName String Nombre de Usuario. Password String Contraseña del usuario. UserName: Usuario de autenticación del web service. No puede ser vacía y la longitud máxima permitida es de 30 caracteres. El UserName y el Password son definidos por cada proveedor Password: Contraseña de autenticación del servicio. No puede ser vacía y la longitud máxima permitida es de 30 caracteres. El UserNamey y la contraseña no deben estar encriptadas. Parámetros de una Soap Exception Nombre del Parámetro Tipo de Dato Descripción Id Long Código del error. Description String Descripción del error. Id: Parámetro que identifica el código de error retornado por el Web Service. Description: Parámetro que describe el mensaje de error retornado por el Web Service. Nota: Los parámetros de salida de una Soap Exception son retornados a Telecom Personal por cualquier estado que corresponda a una operación errónea. Página 9 de 26 09/12/2009
Web Services WSSuscripciones 1) Método para la baja de servicios: WSSuscripciones.gestionarServicios() 1.1) Objetivo del método: Gestionar la baja de un servicio a una línea. En el caso de que la operación en el proveedor finalice exitosamente, este deberá enviar al usuarios final un SMS confirmado que se genero el pedido de baja. NOTA: Este método será invocado por Telecom Personal cada vez que un usuario de la pagina web de TP desee dar da baja un servicio. 1.2) Parámetros de entrada del método Alta/Baja A continuación se detallan los parámetros de entrada. Nombre del Parámetro Tipo de Dato Descripción NumeroLinea Long Numero de Línea de entrada con el siguiente formato de 10 dígitos: 35156998745, es decir sin el cero del código de área y sin el 15 del numero del celular. Acción Char(1) A o B Acción a realizar por el Web Services, pudiendo ser: A = Alta o B = Baja. Identificador del servicio del proveedor String Código con el que el proveedor identifica al servicio. Máximo contendrá 10 caracteres. Número corto Long Número corto por el que el proveedor envía o enviara el servicio. 1.3) Valores devueltos por el método de Alta/Baja Parámetros de salida exitosa del método Alta/Baja Página 10 de 26 09/12/2009
Nombre del Parámetro Tipo de Dato Descripción Estado Char(1) Confirmación del estado del Alta / Baja. 0: se realizó exitosamente 1: No correspondía Estado: Confirmación de que la operación se realizó en forma exitosa. 1.4) Excepciones Como mencionamos anteriormente el Web Services retorna una SoapException si el usuario no tiene permisos para entrar a la aplicación o bien si ocurrió algún error durante la llamada al Web Services. En esta tabla se describen los códigos el error y sus correspondientes descripciones de error. Tabla de Errores La siguiente tabla corresponde a los errores posibles de devolución hasta este momento. Id de Error Descripción del error Observaciones 2 Usuario y Password incorrectos. Las credenciales no están autorizadas para realizar esta consulta. 3 Error de TimeOut (WSSuscripciones). Timeout producido por el WS del proveedor (Tiempo máximo de espera 2 seg). 10000 Línea sin servicios adheridos La línea solicitado no tiene servicios adheridos / contratados con el proveedor 10001 Número de línea mal formado La línea puede estar: 10002 Problemas en el parámetro de entrada Acción. - Vacía (nulo o espacios). - Mal formada (se esperan 10 dígitos). - Caracteres no numéricos. El parámetro puede estar: - Vacío. Página 11 de 26 09/12/2009
10003 Problemas en el parámetro de entrada identificador de código de servicio. 10004 Problemas en el parámetro de entrada Número Corto. - Incorrecto. El parámetro puede estar: - Vacío. - Incorrecto. - Caracteres no numéricos. Tipo de dato no válido. El parámetro puede estar: - Vacío. - Incorrecto. - Caracteres no numéricos. - Tipo de dato no válido. 10005 Error consultando datos. Error con algún sistema interno del proveedor que se resolverá en un tiempo determinado. 10006 Servicio suspendido o dado de baja. Por posibles problemas de actualizaciones de TP, puede que consultemos a un servicio que ya no brinda servicio a TP. Página 12 de 26 09/12/2009
2) Método para la consulta de servicios: WSSuscripciones.consulta() 2.1) Objetivo del método: Listar los servicios contratados por la línea que se recibió por parámetro. NOTA: Este método será invocado por Telecom Personal cada vez que un usuario de la pagina web desee conocer los servicios adheridos a su línea. 2.2) Parámetros de entrada del método consulta() A continuación se detallan los parámetros de entrada. Nombre del Parámetro Tipo de Dato Descripción NumeroLinea Long Numero de Línea de entrada con el siguiente formato de 10 dígitos: 35156998745, es decir sin el cero del código de área y sin el 15 del numero del celular. 2.3) Valores devueltos por el método de consulta() Nombre del Parámetro Tipo de Dato Descripción Número corto Long - Número corto por el que el proveedor envía o enviara el servicio. Identificador del servicio del proveedor - No se aceptan valores nulos. String - Código con el que el proveedor identifica al servicio. - Máximo contendrá 10 caracteres como máximo. - No se aceptan valores nulos. NombreServicio String - Nombre con el que el proveedor promociona el servicio. - No se aceptan valores nulos. DescripcionServicion String - Texto corto (100 caracteres como máximo) describiendo el servicio. - Telecom Personal sugiere que se provea aunque sea una mínima descripción. Página 13 de 26 09/12/2009
IMPORTANTE: Este método deberá devolver una lista de servicios, ya que es posible que el cliente final tenga contratado más de un servicio para la línea; Cada uno de los elementos de la lista deberá estar formado por los campos / propiedades descriptos en la tabla de arriba. 2.4) Excepciones Como mencionamos anteriormente el Web Services retorna una SoapException si el usuario no tiene permisos para entrar a la aplicación o bien si ocurrió algún error durante la llamada al Web Services. En esta tabla se describe el código el error y la descripción del error. Tabla de Errores La siguiente tabla corresponde a los errores posibles de devolución hasta este momento. Id de Error Descripción del error Observaciones 2 Usuario y Password incorrectos. Las credenciales no están autorizadas para realizar esta consulta. 3 Error de TimeOut (WSSuscripciones). Timeout producido por el WS del proveedor (Tiempo máximo de espera 2 seg). 10000 Línea sin servicios adheridos La línea solicitado no tiene servicios adheridos / contratados con el proveedor 10001 Número de línea mal formado La línea puede estar: - Vacía (nulo o espacios). - Mal formada (se esperan 10 dígitos). - Caracteres distintos a Nros 10005 Error consultando datos. Error con algún sistema interno del proveedor que se resolverá en un tiempo determinado. Página 14 de 26 09/12/2009
3) Método para la consulta de servicios: WSSuscripciones.listarServicios() 3.1) Objetivo del método: Proveer una lista con los servicios que el proveedor de servicios agrego, modifico y/o elimino en un periodo determinado de tiempo. En caso de que el proveedor no tenga novedades para el periodo solicitado, deberá retornar una excepción (ver tabla de errores). NOTA: Este método solo será invocado por Telecom Personal una vez al día y por la noche. Aclaración: Este método solo deberá 3.2) Parámetros de entrada del método consulta() A continuación se detallan los parámetros de entrada. Nombre del Parámetro Tipo de Dato Descripción Fecha Desde Char(10) - Fecha que indica que quien invoca al método desea obtener las novedades que se produjeron desde la fecha indicada. - El formato de la fecha deberá ser DD/MM/AAAA. Fecha Hasta Char(10) - Fecha que indica que quien invoca al método desea obtener las novedades que se produjeron hasta la fecha indicada. - El formato de la fecha deberá ser DD/MM/AAAA. 3.3) Valores devueltos por el método de consulta() Nombre del Parámetro Tipo de Dato Descripción Número corto Long Número corto por el que el proveedor envía o enviara el servicio. Identificador del servicio del proveedor Long - Código con el que el proveedor identifica al servicio. - Máximo contendrá 4 dígitos Página 15 de 26 09/12/2009
NombreServicio String Nombre con el que el proveedor promociona el servicio DescripcionServicio String Texto corto (100 caracteres como máximo) describiendo el servicio. Precio Pre Pago Long Precio final del servicio (impuestos incluidos) para las líneas prepagas. Precio Post Pago Long Precio final del servicio (impuestos incluidos) para las líneas post pagas. Baja Char(1) S o N En caso que un servicio haya sido desactivado por el proveedor, este deberá enviar dicho servicio con una S en este campo, con lo que Telecom Personal realizará una baja lógica del mismo en sus bases. En caso que se debe modificar o agregar un servicio, este campo debe contener el valor N. IMPORTANTE: Este método deberá devolver una lista de servicios, Cada uno de los elementos (servicios) de la lista deberá estar formado por los campos / propiedades descriptos en la tabla de arriba. 3.4) Excepciones Como mencionamos anteriormente el Web Services retorna una SoapException si el usuario no tiene permisos para entrar a la aplicación o bien si ocurrió algún error durante la llamada al Web Services. En esta tabla se describe el código el error y la descripción del error. Tabla de Errores La siguiente tabla corresponde a los errores posibles de devolución hasta este momento. Id de Error Descripción del error Observaciones 1 Error Desconocido. Tipos de errores no definidos y no controlados por cada proveedor. 2 Usuario y Password incorrectos. Las credenciales no están autorizadas para realizar esta consulta. 3 Error de TimeOut (WSSuscripciones). Timeout producido por el WS del proveedor (Tiempo máximo de espera 2 seg). Página 16 de 26 09/12/2009
10004 No existen Novedades 10005 Error consultando datos. Error con algún sistema interno del proveedor que se resolverá en un tiempo determinado. 10007 Problemas en el parámetro de entrada 'fecha desde' 10008 Problemas en el parámetro de entrada 'fecha hasta'. 10009 La fecha 'desde' es mayor a la fecha 'hasta' El parámetro no tiene el parámetro correcto, o no se ha introducido ningún valor. El parámetro no tiene el parámetro correcto, o no se ha introducido ningún valor. Página 17 de 26 09/12/2009
CONSIDERACIONES IMPORTANTES En el siguiente apartado se detallan algunos puntos importantes de la operatoria: - Telecom Personal dejará registrada una auditoria de ejecuciones de los métodos del WS del proveedor para poder controlar la performance del mismo. - La ejecución de los métodos del WS del proveedor no puede tardar más de 3 segundos en responder por cualquiera de sus métodos. - En caso que la ejecución nocturna del WS, con el método ListarServicios de error, Telecom Personal realizará hasta 3 intentos en diferentes horarios entre las 22 hs y las 6 hs de la mañana. En caso que los 3 intentos hayan fallado, se enviará una alarma a soporte de Telecom Personal para que avise o reclame al proveedor. - Para el día 15/04/2009 se deberá disponer, en un ambiente de pruebas, el WS con todos sus métodos líneas y servicios, por cada proveedor, para tal fin. Además se deberá contar con un contacto/soporte para realizar las pruebas de Lunes a Viernes de 8 hs a 19 hs mientras duren las mismas. - A fin de Abril del 2009 se debe contar con el WS de cada proveedor en Producción y con un soporte por cada proveedor de 7x24 los primeros 3 meses de funcionamiento. - Pasado los 3 meses de la puesta en producción se debe contar con un soporte activo de Lunes a Viernes de 8 hs a 19 hs y pasivo el resto de las horas y los fines de semana y feriados. Página 18 de 26 09/12/2009
APÉNDICE WSSuscripciones.gestionarServicio() Ejemplos Ejemplo parcial de un mensaje soap de una llamada al método gestionarservicio <soap:envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns="http://personal.com.ar/services/"> <soap:header> <Authentication> <UserName>IVR</UserName> <Password> IVR</Password> </Authentication> </soap:header> <soap:body> <GestionarServicios> <numerolinea>3516130333</numerolinea> <!- - A=Alta, B=Baja --> <accion>b</accion> <servicioid>9999</servicioid> <numerocorto>1010</numerocorto> </GestionarServicios> </soap:body> </soap:envelope> Ejemplo parcial de un mensaje soap de respuesta con éxito de una llamada al metodo <soap:envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:xsi="http://www.w3.org/2001/xmlschemainstance" xmlns:xsd="http://www.w3.org/2001/xmlschema"> <soap:header> <Authentication xmlns="http://personal.com.ar/services/"> <!--Optional:--> <UserName>IVR</UserName> <!--Optional:--> <Password>IVR</Password> </Authentication> <Transaction xmlns="http://personal.com.ar/services/"> <!--Optional:--> <TransactionId>2526459</TransactionId> </Transaction> </soap:header> <soap:body> <GestionarServiciosResponse xmlns="http://personal.com.ar/services/"> <GestionarServiciosResult>0</GestionarServiciosResult> </GestionarServiciosResponse> Página 19 de 26 09/12/2009
</soap:body> Página 20 de 26 09/12/2009
WSSuscripciones.consulta() Ejemplos Ejemplo parcial de un mensaje soap de una llamada al método consulta. <soap:envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns="http://personal.com.ar/services/"> <soap:header> <Authentication> <UserName>IVR</UserName> <Password> IVR</Password> </Authentication> </soap:header> <soap:body> <ConsultarServicios> <numerolinea>3516130333</numerolinea> </ ConsultarServicios> </soap:body> </soap:envelope> Ejemplo parcial de un mensaje soap de respuesta con éxito de una llamada al método consulta. <soap:envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:xsi="http://www.w3.org/2001/xmlschemainstance" xmlns:xsd="http://www.w3.org/2001/xmlschema"> <soap:header> <Authentication xmlns="http://personal.com.ar/services/"> <!--Optional:--> <UserName>IVR</UserName> <!--Optional:--> <Password>IVR</Password> </Authentication> <Transaction xmlns="http://personal.com.ar/services/"> <!--Optional:--> <TransactionId>2526459</TransactionId> </Transaction> </soap:header> <soap:body> < ConsultarServiciosResponse xmlns="http://personal.com.ar/services/"> < ConsultarServiciosResult> <servicio> <servicioid>1111</servicioid> <numerocorto>1010</numerocorto> <servicionombre>chistes</ servicionombre> <serviciodescripcion>los mejores chistes para que compartas con tus amigos</ serviciodescripcion> <servicioprecio>0.40</servicioprecio> </servicio> <servicio> <servicioid>1112</servicioid> <numerocorto>1010</numerocorto> <servicionombre>poemas</ servicionombre> <serviciodescripcion>poemas de amor para que te luzcas</ serviciodescripcion> Página 21 de 26 09/12/2009
<servicioprecio>0.50</servicioprecio> </servicio> <servicio> <servicioid>2222</servicioid> <numerocorto>2020</numerocorto> <servicionombre>clima-cordoba-capital</ servicionombre> <serviciodescripcion>informe del clima de Cordoba Capital</ serviciodescripcion> <servicioprecio>0.33</servicioprecio> </servicio> </ ConsultarServiciosResult> </ ConsultarServiciosResponse> </soap:body> </soap:envelope> Página 22 de 26 09/12/2009
WSSuscripciones.listarServicios() Ejemplos Ejemplo parcial de un mensaje soap de una llamada al método listarservicios. <soap:envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns="http://personal.com.ar/services/"> <soap:header> <Authentication> <UserName>IVR</UserName> <Password> IVR</Password> </Authentication> </soap:header> <soap:body> <ListarServicios></ListarServicios> </soap:body> </soap:envelope> Ejemplo parcial de un mensaje soap de respuesta con éxito de una llamada al método consulta. <soap:envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:xsi="http://www.w3.org/2001/xmlschemainstance" xmlns:xsd="http://www.w3.org/2001/xmlschema"> <soap:header> <Authentication xmlns="http://personal.com.ar/services/"> <!--Optional:--> <UserName>IVR</UserName> <!--Optional:--> <Password>IVR</Password> </Authentication> <Transaction xmlns="http://personal.com.ar/services/"> <!--Optional:--> <TransactionId>2526459</TransactionId> </Transaction> </soap:header> <soap:body> < ListarServiciosResponse xmlns="http://personal.com.ar/services/"> <ListarServicios Result> <servicio> <servicioid>1111</servicioid> <numerocorto>1010</numerocorto> <servicionombre>chistes</ servicionombre> <serviciodescripcion>los mejores chistes para que compartas con tus amigos</ serviciodescripcion> <servicioprecioprepago>0.40</servicioprecioprepago> <serviciopreciopospago>0.55</serviciopreciopospago> </servicio> <servicio> <servicioid>1112</servicioid> <numerocorto>1010</numerocorto> <servicionombre>poemas</ servicionombre> <serviciodescripcion>poemas de amor para que te luzcas</ serviciodescripcion> <servicioprecioprepago>0.45</servicioprecioprepago> Página 23 de 26 09/12/2009
<serviciopreciopospago>0.59</serviciopreciopospago> </servicio> <servicio> <servicioid>2222</servicioid> <numerocorto>2020</numerocorto> <servicionombre>clima-cordoba-capital</ servicionombre> <serviciodescripcion>informe del clima de Cordoba Capital</ serviciodescripcion> <servicioprecioprepago>0.57</servicioprecioprepago> <serviciopreciopospago>0.68</serviciopreciopospago> </servicio> </ListarServicios Result> </ ListarServiciosResponse> </soap:body> </soap:envelope> Página 24 de 26 09/12/2009
WSSUSCRIPCIONES WSDL: Adjuntamos archivo WSDL correspondiente al servicio web solicitado. WSSuscripciones.wsdl Página 25 de 26 09/12/2009
GLOSARIO WS: Web Service / Servicio Web. TP: Telecom Personal Página 26 de 26 09/12/2009