Departamento de Informática Tributaria Subdirección General de Aplicaciones de Aduanas e II.EE. C/ Santa María Magdalena 16, Madrid

Transcripción

1 C/ Santa María Magdalena 16, Madrid Bandeja de Entrada Autor: S.G.A.A. Fecha: 24/03/2011 Versión: 0.4 Revisiones Edi. Rev. Fecha Descripción A(*) Páginas /02/2007 Versión inicial A Todas (*) Acción: A= Añadir; R= Reemplazar Índice: 1. Nota importante 3 2. Introducción 3 3. Control de versiones 3 4. Estándares utilizados 4 5. Infraestructura de Bandeja de Entrada Acceso con Navegador Servicios Web Recuperar las referencias de las respuestas pendientes de recoger Recuperación, de la Bandeja de Entrada, de los mensajes pendientes de leer Resumen Consideraciones de diseño Versionado Integridad Transaccional Comunicación de incidencias en el procesado de las declaraciones Anexo I: Lista de Errores 13 Impreso: 14/03/2013 C:\AEAT\manolo\ADUANAS\ADWS\Bandeja de entrada\artefactos\bandejaentrada.docpágina: 1/17

2 8. Anexo II: Definición servicio y esquemas Anexo II.1: Definición del servicio ListaDecV4.wsdl Anexo II.2: Mensaje de entrada ListaDecV4Ent.xsd Anexo II.3: Mensaje de salida ListaDecV4Sal.xsd Anexo III: Ejemplos Mensaje de entrada. Petición de lista de mensajes Mensaje de salida. Lista de mensajes pendientes de leer 17 Impreso:14/03/2013 C:\AEAT\manolo\ADUANAS\ADWS\Bandeja de entrada\artefactos\bandejaentrada.doc Pág: 2/17

3 1. Nota importante No debe pedirse a la Bandeja de entrada mensajes con una frecuencia elevada; se hará como mucho cada 10 minutos para evitar la saturación de los servidores. 2. Introducción La Bandeja de Entrada es una infraestructura destinada a proporcionar un servicio asíncrono de recogida de mensajes. Bandeja Entrada Gestor Bandeja Entrada Contribuyentes que reciben Contribuyente Bandeja Entrada Bandeja entrada Bandeja-Entrada Contribuyente 3. Control de versiones Ver. Fecha Estado Cambios 4 01/07/2010 Versión 4: adaptaciones a la URL de Sede. 4 24/03/2011 Modificación endpoints Intranet Impreso:14/03/2013 C:\AEAT\manolo\ADUANAS\ADWS\Bandeja de entrada\artefactos\bandejaentrada.doc Pág: 3/17

4 4. Estándares utilizados El uso de servicios Web constituye la base de las buenas prácticas para desplegar servicios que posibiliten la interacción máquina-máquina, es decir, la automatización integral de un proceso en el que interviene varios sistemas de información (el del ciudadano/empresa y el de la Agencia Tributaria). Se pretende utilizar los estándares de facto para el desarrollo de servicios web. La estructura de los mensajes será descrita sobre la base de la creación de esquemas XML utilizando para ello la recomendación W3C de 28-Octubre de 2004 en y referenciada por el namespace Con relación a SOAP se utilizará SOAP V1.1 disponible como NOTA W3C de 08-Mayo-2000 en : y referenciado por el namespace En SOAP-1.1 existen dos estilos para implementar servicio, modo rpc y modo document, en línea con las recomendaciones actuales se utilizará siempre el modo document (style= document ) sin ningún tipo de codificación (use= literal ). Es decir el mensaje de entrada y salida estará descrito íntegramente por su respectivo esquema XML. Con relación a la descripción de los servicios utilizaremos WSDL 1.1 disponible como NOTA W3C de 14-Marzo-2001 en: y referenciado por el namespace 5. Infraestructura de Bandeja de Entrada La Bandeja de Entrada es una infraestructura destinada a proporcionar un servicio asíncrono de recogida de mensajes. Bandeja Entrada Gestor Bandeja Entrada Contribuyentes que reciben Contribuyente Bandeja Entrada Bandeja entrada Bandeja-Entrada Contribuyente Impreso:14/03/2013 C:\AEAT\manolo\ADUANAS\ADWS\Bandeja de entrada\artefactos\bandejaentrada.doc Pág: 4/17

5 Acceso a los mensajes almacenados en la Bandeja de Entrada El usuario puede acceder a los mensajes almacenados en la Bandeja de Entrada de dos modos diferentes: Con un Navegador Web a través de las páginas-aplicaciones correspondientes. A través de Servicios Web Acceso con Navegador Los usuarios disponen de aplicaciones Web que permiten consultar, a través de un Navegador de páginas web, los mensajes almacenados en la Bandeja de Entrada. Internet: Intranet: ( ( Servicios Web La infraestructura Bandeja de Entrada proporciona dos Servicios Web con el fin de poder consultar y recuperar los mensajes en ella almacenados. El primer servicio permitirá Recuperar las referencias de las respuestas o mensajes pendientes de recoger. El segundo servicio web permitirá Recuperar una respuesta a partir de la referencia obtenida con el primer servicio web Recuperar las referencias de las respuestas pendientes de recoger Se utilizará el servicio Lista de Respuestas descrito por ListaDecV4.wsdl Impreso:14/03/2013 C:\AEAT\manolo\ADUANAS\ADWS\Bandeja de entrada\artefactos\bandejaentrada.doc Pág: 5/17

6 ( 4.wsdl) Se trata de un servicio web que permite conocer si existen respuestas pendientes de recoger y en su caso devolverá las referencias de las mismas. Este servicio no requiere que los XML intercambiados sean firmados. Petición de Lista de Mensajes Pendientes de leer BANDEJA DE ENTRADA Lista de Mensajes Pendientes de leer Mensaje de petición El esquema ListaDecV4Ent.xsd define la estructura de los mensajes de entrada de este servicio. ( Ent.xsd) Un mensaje para solicitar a la bandeja de entrada los mensajes pendientes de leer por el usuario Juan Español tendría el aspecto que se muestra a continuación: <soapenv:envelope xmlns:soapenv=" xmlns:xsd=" xmlns:xsi=" <soapenv:body> <ListaDecV4Ent xmlns=" <declarante> <NifDeclarante> R</NifDeclarante> <NombreDeclarante>JUAN ESPAÑOL</NombreDeclarante> </declarante> </ListaDecV4Ent> </soapenv:body> </soapenv:envelope> Impreso:14/03/2013 C:\AEAT\manolo\ADUANAS\ADWS\Bandeja de entrada\artefactos\bandejaentrada.doc Pág: 6/17

7 ListaDecV4Ent: Etiqueta raíz del mensaje Namespace: xmlns=" Solo contiene el elemento declarante. declarante: Información del declarante que solicita los mensajes. Contiene dos elementos que identifican unívocamente al declarante, su Nif y su Nombre: NifDeclarante y NombreDeclarante. NifDeclarante: Nif del declarante que quiere recuperar sus mensajes. NombreDeclarante: Nombre del declarante que quiere recuperar sus mensajes Mensaje de respuesta El esquema ListaDecV4Sal.xsd define la estructura de los mensajes de salida de este servicio. ( Sal.xsd) A continuación se muestra un ejemplo que representa un mensaje de salida de este servicio en el que se informa de la disponibilidad de dos mensajes pendientes de leer: <soapenv:envelope xmlns:soapenv=" xmlns:xsd=" xmlns:xsi=" <soapenv:body> <ListaDecV4Sal xmlns=" <declaracion> <clave> </clave> <referencia>suma1072</referencia> <tiporespuesta> Respuesta> </declaracion> <declaracion> <clave> </clave> <referencia>suma1073</referencia> <tiporespuesta> Respuesta> </declaracion> </ListaDecV4Sal> </soapenv:body> </soapenv:envelope> ListaDecV4Sal: Etiqueta raíz del mensaje Namespace: xmlns=" Solo contiene el elemento declaracion. Eso sí, puede tener cero o más elementos declaracion, tantos como mensajes pendientes de leer existan en la bandeja de entrada. Impreso:14/03/2013 C:\AEAT\manolo\ADUANAS\ADWS\Bandeja de entrada\artefactos\bandejaentrada.doc Pág: 7/17

8 declaracion: Información de la declaración pendiente de leer. Contiene los elementos que identifican unívocamente a la declaración pendiente de leer y que permitirán su posterior recuperación con el otro servició que nos proporciona el bandeja de entrada. clave: Clave de recuperación, entendida como la clave interna de la Agencia que identifica unívocamente el mensaje y que será utilizada en el otro servicio de la bandeja de entrada para recuperar dicho mensaje. referencia: Referencia del mensaje de petición. Referencia de la operación. tiporespuesta: Tipo del mensaje. (identificación del servicio web de consulta) Recuperación, de la Bandeja de Entrada, de los mensajes pendientes de leer Se podrá utilizar el Servicio Web definido por cada proyecto para recuperar los mensajes de la Bandeja de Entrada que estén pendientes de leer. Cada proyecto o tipo de mensaje tendrá su propio servicio para recuperar, de la Bandeja de Entrada, los mensajes de esa tipología. Vamos a utilizar como ejemplo el Servicio de Suma. Si volvemos al apartado anterior, en el que se explicaba el Servicio Web de obtención de la lista de mensajes pendientes de leer, se puede ver que en el mensaje de salida teníamos una referencia a dos mensajes pendientes de leer. En ese momento, se puede utilizar este nuevo servicio para recuperar esos mensajes de uno en uno. En nuestro ejemplo el mencionado servicio sería el SumaV4Res.wsdl ( Petición recuperación Mensaje de de BANDEJA DE ENTRADA Mensaje (resultado de suma) Impreso:14/03/2013 C:\AEAT\manolo\ADUANAS\ADWS\Bandeja de entrada\artefactos\bandejaentrada.doc Pág: 8/17

9 Mensaje de petición El esquema DetalleV4Ent.xsd define la estructura de los mensajes de petición de este servicio. Y lo que es muy importante, será común a todos los servicios definidos para recuperar mensajes de la bandeja de entrada. ( El mensaje de petición para recuperar el mensaje referenciado por <declaracion> <clave> </clave> <referencia>suma1072</referencia> <tiporespuesta> Res.wsdl</tipoRespuesta> </declaracion> en el mensaje de salida de la lista de respuestas, sería <soapenv:envelope xmlns:soapenv=" xmlns:xsd=" xmlns:xsi=" <soapenv:body> <DetalleV4Ent xmlns= > <clave> </clave> </DetalleV4Ent> </soapenv:body> </soapenv:envelope> DetalleV4Ent: Etiqueta raíz. Namespace: xmlns=" Solo contiene el elemento clave. clave: Clave de recuperación, entendida como la clave interna de la Agencia que identifica unívocamente el mensaje y que ha sido obtenida del servicio de Lista de Respuestas Mensaje de respuesta El mensaje de respuesta sí es particular de cada proyecto. En nuestro ejemplo, el esquema SumaV4Sal.xsd define la estructura de los mensajes de salida de este servicio. ( A continuación se muestra un ejemplo que representa un mensaje de salida de este servicio: Impreso:14/03/2013 C:\AEAT\manolo\ADUANAS\ADWS\Bandeja de entrada\artefactos\bandejaentrada.doc Pág: 9/17

10 <soapenv:envelope xmlns:soapenv=" xmlns:xsd=" xmlns:xsi=" <soapenv:body> <SumaV4Sal xmlns=" <Total>1105</Total> </SumaV4Sal> </soapenv:body> </soapenv:envelope> SumaV4Sal: Etiqueta raíz. Namespace: xmlns=" Solo contiene el elemento Total. Total: Resultado de la suma Resumen Resumiendo, la infraestructura Bandeja de Entrada nos proporciona un servicio (LISTA DE RESPUESTAS, ListaDecV4.wsdl) para obtener la lista de mensajes pendientes de leer en la Bandeja de Entrada para un usuario dado. Y además, define el mensaje de petición (DetalleV4Ent.xsd) del servicio que se implemente para recuperar los mensajes de la Bandeja de Entrada. (Servicio SumaV4Res.wsdl, mensaje de petición DetalleV4Ent.xsd y mensaje de respuesta SumaV4Sal.wsdl). 6. Consideraciones de diseño 6.1. Versionado Los servicios se definirán con un convenio de versionado que facilite que las futuras actualizaciones son reconocibles y por tanto diferenciables. Para ello detrás del nombre del servicio y de todos los objetos relacionados se incluye un número de versión Integridad Transaccional Los servicios web se despliegan utilizando el protocolo de transporte https. Básicamente una petición https consiste en una petición que procesa el servidor y genera su respectiva respuesta. Impreso:14/03/2013 C:\AEAT\manolo\ADUANAS\ADWS\Bandeja de entrada\artefactos\bandejaentrada.docpág: 10/17

11 En condiciones normales el protocolo descrito anteriormente responde a las necesidades de un servicio web, pero puede ocurrir por diversos motivos (caída de red, caída del servidor,...) que el cliente no reciba la respuesta y en estas ocasiones NO podemos conocer si el servidor ha procesado la petición o no. Esta circunstancia puede no tener importancia, por ejemplo en una consulta para conocer el estado, se volverá a pedir más tarde no afectando a la integridad de los datos, sin embargo si el servicio actualizar la base de datos el resultado después de aplicar dos peticiones iguales podría alterar de forma sustancial lo esperado (imaginemos un mensaje de resto 100 unidades a una cuenta, al realizarlo dos veces por no tener confirmación de la primera petición habríamos restado 200 en vez de 100). Por lo anterior, en todo servicio web que actualice información se implementa un mecanismo que garantice un control de las peticiones duplicadas. Cada petición contiene una referencia unívoca de tal modo que caso de recibir una petición con la misma referencia que una previa actuaremos del siguiente modo: Si el contenido del mensaje es idéntico al recibido en la primera ocasión, se devolverá la respuesta que se generó para la primera petición. Si el contenido del mensaje difiere al recibido en la primera ocasión, se devolverá un error indicando el uso incorrecto de la referencia que debería ser unívoca. Con este mecanismo el cliente, en caso de error y por tanto de indeterminación de sí se ha procesado o no la petición, tiene una forma fácil de resincronizarse con garantía de integridad en el resultado final de la operación. ( Si no se recibió la primera petición se procesará como nueva en caso contrario se devolverá la respuesta generada con la petición anterior) Comunicación de incidencias en el procesado de las declaraciones. En caso de incidencias en la aplicación estás serán comunicadas tal como se describen en el protocolo SOAP V1.1, es decir utilizando el elemento FAULT. casos: A modo de resumen como respuesta a una petición se pueden producir los siguientes Resultado Recibimos una respuesta con el xml esperado Acción OK. Mensaje procesado Impreso:14/03/2013 C:\AEAT\manolo\ADUANAS\ADWS\Bandeja de entrada\artefactos\bandejaentrada.docpág: 11/17

12 Recibimos un respuesta con elemento FAULT y faultcode del tipo soapenv:server. No progresa la trasmisión o bien no recibimos un documento xml que responde a lo esperado Reenviar mensaje Reenviar mensaje Recibimos un respuesta con elemento FAULT y faultcode del tipo soapenv:client. La respuesta enviada NO es formamelmente incorrecta, o bien contiene referencia única duplicada de otra con distinto contenido. La declaración NO se debe reenviar. Impreso:14/03/2013 C:\AEAT\manolo\ADUANAS\ADWS\Bandeja de entrada\artefactos\bandejaentrada.docpág: 12/17

13 7. Anexo I: Lista de Errores Impreso:14/03/2013 C:\AEAT\manolo\ADUANAS\ADWS\Bandeja de entrada\artefactos\bandejaentrada.docpág: 13/17

14 8. Anexo II: Definición servicio y esquemas 8.1. Anexo II.1: Definición del servicio ListaDecV4.wsdl La definición de este servicio se puede consultar en la dirección wsdl <?xml version="1.0" encoding="utf-8"?> - <wsdl:definitions targetnamespace=" dl" xmlns:listadecv4=" sdl" xmlns:listadecv4ent=" Ent.xsd" xmlns:listadecv4sal=" Sal.xsd" xmlns:wsdl=" xmlns:wsdlsoap=" xmlns:xsd=" - <wsdl:types> - <schema elementformdefault="qualified" targetnamespace=" ListaDecV4.wsdl" xmlns:listadecv4ent=" nt/listadecv4ent.xsd" xmlns:listadecv4sal=" nt/listadecv4sal.xsd" xmlns=" <xsd:import namespace=" /ListaDecV4Ent.xsd" schemalocation="listadecv4ent.xsd" /> <xsd:import namespace=" /ListaDecV4Sal.xsd" schemalocation="listadecv4sal.xsd" /> </schema> </wsdl:types> - <wsdl:message name="entrada"> <wsdl:part name="listadecv4ent" element="listadecv4ent:listadecv4ent" /> </wsdl:message> - <wsdl:message name="salida"> <wsdl:part name="listadecv4sal" element="listadecv4sal:listadecv4sal" /> </wsdl:message> - <wsdl:porttype name="listadecv4"> - <wsdl:operation name="listadecv4"> <wsdl:input message="listadecv4:entrada" name="entrada" /> <wsdl:output message="listadecv4:salida" name="salida" /> </wsdl:operation> </wsdl:porttype> - <wsdl:binding name="listadecv4soapbinding" type="listadecv4:listadecv4"> <wsdlsoap:binding style="document" transport=" /> - <wsdl:operation name="listadecv4"> <wsdlsoap:operation soapaction="" /> - <wsdl:input name="entrada"> <wsdlsoap:body use="literal" /> </wsdl:input> - <wsdl:output name="salida"> <wsdlsoap:body use="literal" /> </wsdl:output> </wsdl:operation> </wsdl:binding> - <wsdl:service name="listadecv4service"> - <wsdl:port binding="listadecv4:listadecv4soapbinding" name="listadecv4"> <wsdlsoap:address location=" V4SOAP" /> </wsdl:port> - <wsdl:port binding="listadecv4:listadecv4soapbinding" name="listadecv4intranet"> <wsdlsoap:address location=" /> </wsdl:port> - <wsdl:port binding="listadecv4:listadecv4soapbinding" name="listadecv4intranet2"> <wsdlsoap:address location=" /> </wsdl:port> </wsdl:service> </wsdl:definitions> Impreso:14/03/2013 C:\AEAT\manolo\ADUANAS\ADWS\Bandeja de entrada\artefactos\bandejaentrada.docpág: 14/17

15 8.2. Anexo II.2: Mensaje de entrada ListaDecV4Ent.xsd La definición del esquema del mensaje de entrada se puede consultar en la dirección nt.xsd <?xml version="1.0" encoding="utf-8"?> - <schema targetnamespace=" xmlns=" xmlns:listadecv4ent=" Ent.xsd" elementformdefault="qualified"> - <annotation> <documentation>esquema para solicitar a la Bandeja de Entrada la LISTA DE LAS RESPUESTAS pendientes de leer.</documentation> </annotation> <element name="listadecv4ent" type="listadecv4ent:listadecv4ent" /> - <complextype name="listadecv4ent"> - <sequence> <element name="declarante" type="listadecv4ent:declarantetype" maxoccurs="1" minoccurs="1" /> </sequence> </complextype> - <complextype name="declarantetype"> - <annotation> <documentation>declarantetype: Información del declarante, de la persona en cuyo nombre se presenta la declaración. NifDeclarante: Nif del declarante NombreDeclarante: Nombre del declarante</documentation> </annotation> - <sequence> <element name="nifdeclarante" maxoccurs="1" minoccurs="1" type="string" /> <element name="nombredeclarante" type="string" maxoccurs="1" minoccurs="1" /> </sequence> </complextype> </schema> Impreso:14/03/2013 C:\AEAT\manolo\ADUANAS\ADWS\Bandeja de entrada\artefactos\bandejaentrada.docpág: 15/17

16 8.3. Anexo II.3: Mensaje de salida ListaDecV4Sal.xsd La definición del esquema del mensaje de salida se puede consultar en la dirección al.xsd <?xml version="1.0" encoding="utf-8"?> - <schema targetnamespace=" xsd" xmlns=" xmlns:listadecv4sal=" Sal.xsd" elementformdefault="qualified"> - <annotation> <documentation>esquema del mensaje de respuesta al solicitar a la Bandeja de Entrada la LISTA DE LAS RESPUESTAS pendientes de leer. Este mensaje proporciona información de cada una de las declaraciones pendientes de leer en la Bandeja de Entrada.</documentation> </annotation> <element name="listadecv4sal" type="listadecv4sal:listadecv4sal" /> - <complextype name="listadecv4sal"> - <sequence> <element name="declaracion" type="listadecv4sal:declaraciontype" maxoccurs="unbounded" minoccurs="1" /> </sequence> </complextype> - <complextype name="declaraciontype"> - <annotation> <documentation>información necesaria para recuperar una declaración pendiente de leer de la Bandeja de Entrada. clave: Clave que identifica univocamente cada respuesta. referencia: Referencia del mensaje. Coincide con el valor del campo ID del mensaje de petición. tiporespuesta: Tipo de respuesta. Está en función del tipo de Servicio Web utilizado.</documentation> </annotation> - <sequence> <element name="clave" type="string" maxoccurs="1" minoccurs="1" /> <element name="referencia" type="string" maxoccurs="1" minoccurs="1" /> <element name="tiporespuesta" type="string" maxoccurs="1" minoccurs="1" /> </sequence> </complextype> </schema> Impreso:14/03/2013 C:\AEAT\manolo\ADUANAS\ADWS\Bandeja de entrada\artefactos\bandejaentrada.docpág: 16/17

17 9. Anexo III: Ejemplos 9.1. Mensaje de entrada. Petición de lista de mensajes <?xml version="1.0" encoding="utf-8"?> - <ListaDecV4Ent xmlns=" - <declarante> <NifDeclarante> R</NifDeclarante> <NombreDeclarante>JUAN ESPAÑOL</NombreDeclarante> </declarante> </ListaDecV4Ent> 9.2. Mensaje de salida. Lista de mensajes pendientes de leer <?xml version="1.0" encoding="utf-8"?> <soapenv:envelope xmlns:soapenv=" xmlns:xsd=" xmlns:xsi=" - <soapenv:body> - <ListaDecV4Sal xmlns=" 4Sal.xsd"> - <declaracion> <clave> </clave> <referencia>suma1072</referencia> <tiporespuesta> ula/sumav4res.wsdl</tiporespuesta> </declaracion> - <declaracion> <clave> </clave> <referencia>suma1073</referencia> <tiporespuesta> mav4res.wsdl </tiporespuesta> </declaracion> </ListaDecV4Sal> </soapenv:body> </soapenv:envelope> Impreso:14/03/2013 C:\AEAT\manolo\ADUANAS\ADWS\Bandeja de entrada\artefactos\bandejaentrada.docpág: 17/17