Especificación Web Service IAE Fecha: 12-09-2011 Versión: 2.4 Departamento de Informática Tributaria C/ Sta. María Magdalena, 16 28016 - Madrid Subdirección de Aplicaciones de Aduanas e II.EE. AGENCIA TRIBUT RIA A www.aeat.es
Control Documental Versión Documento Fecha 1.0 Especificación inicial 11-12-2009 1.0 Cambio EndPoint 29-12-2009 1.1 Actualizaciónes varias 31-08-2010 2.0 Actualización de contactos 19-11-2010 2.2 Actualizaciones 04-01-2011 2.2 Revisión de la documentación 16-03-2011 2.3 Modificación en la URL de Intranet Administrativa 06-09-011 2.4 Actualización de la documentación de SOAP Fault y explicación de los mensajes que se intercambian en las solicitudes y en las respuestas. 12-09-2011 Página 1
Tabla de contenidos ESPECIFICACIONES DEL WEB SERVICE DE INFORMACIÓN DEL IMPUESTO DE ACTIVIDADES ECONÓMICAS... 3 DESCRIPCIÓN... 3 INFORMACIÓN ADICIONAL... 3 CARACTERÍSTICAS... 3 MEDIO DE ENVÍO:... 3 ENTORNOS... 4 REQUISITOS... 4 COMPOSICIÓN DE LOS MENSAJES DE PETICIÓN Y DE RESPUESTA.... 5 MENSAJE DE PETICIÓN... 6 MENSAJE DE RESPUESTA... 9 DESCRIPCIÓN DE LOS CAMPOS. MENSAJE DE RESPUESTA.... 10 SOAP FAULT... 12 DIAGRAMA... 12 DESCRIPCIÓN DE LOS CAMPOS DEL SOAP FAULT.... 13 FIRMA... 14 DIAGRAMA... 14 ESTRUCTURA DE LOS MENSAJES... 15 Solicitud: Mensaje de petición... 15 Contestación: Mensaje de respuesta... 15 EJEMPLOS... 15 ERRORES FUNCIONALES Y OTRAS SITUACIONES... 15 CONTACTOS... 17 Página 2
ESPECIFICACIONES DEL WEB SERVICE DE INFORMACIÓN DEL IMPUESTO DE ACTIVIDADES ECONÓMICAS DESCRIPCIÓN Este servicio devuelve al solicitante (organismo público) el conjunto de epígrafes del Impuesto de Actividades Económicas en los que se encuentra matriculado un contribuyente o titular en la fecha actual. Se establece un máximo de 10 actividades facilitadas por titular. INFORMACIÓN ADICIONAL Para más información sobre el servicio web consultar los ficheros: Guía autorizaciones.pdf y Formulario autorizaciones.pdf en la dirección: https://www2.agenciatributaria.gob.es/adua/internet/wscert.html, que contiene, a su vez, una referencia ( CIRCA ) de donde se puede encontrar toda la información técnica. CARACTERÍSTICAS Entorno: Intranet Administrativa. Protocolo: HTTPS. Mensajes: Web Service con SOAP 1.1 modo Document. En la dirección indicada en el apartado Información Adicional de Descripción se encuentra el fichero wsdl_adwsiae1.wsdl junto con los esquemas de entrada y salida para establecer la comunicación con el servicio web: schema_copy_adwsiae1_peticion.xsd schema_copy_adwsiae1_respuesta.xsd El mensaje contendrá el NIF del organismo peticionario en el tag <IdentificadorSolicitante> y debe estar autorizado en la aplicación destino para solicitar ese tipo concreto de certificado. Se proveerán ficheros WSDL 1.0 para la generación de clientes. MEDIO DE ENVÍO: Por Intranet Administrativa: https://ws.ia.aeat.es/es13/s/iae1adwsiae1 Y se utilizará para el SSL un certificado de la FNMT (o de cualquier otra Autoridad de Certificación reconocida por la AEAT) tanto por parte del cliente como del servidor. Es necesaria autenticación de cliente al enviarse por la Intranet Administrativa. Los mensajes irán con protocolo seguro SSL. Página 3
Certificados a utilizar: de persona jurídica o de sello emitidos por alguna autoridad de certificación homologada por la AEAT. Formato: se seguirá el esquema del SCSP V.3 Firma: XMLDSig. Nodo de firma: todo el BODY del SOAP. Encoding: preferentemente UTF-8 y, si no, ISO-8859-15. ENTORNOS Para pruebas con el exterior en la AEAT sólo hay entorno de Producción, y estos servicios devuelven, por tanto, datos reales que, además, están sujetos a la Ley de Protección de Datos (se guarda un log que está a disposición de cualquier requerimiento judicial); por este motivo se ha implementado en el entorno de Producción un tratamiento especial de NIF FICTICIOS que permite obtener contestaciones simuladas con los tipos de respuesta más frecuentes. Esto se consigue completando el campo NIF con los datos XXXXXXXXX, YYYYYYYYY o ZZZZZZZZZZ (sin más datos identificativos). Para cada uno de estos 3 casos se obtienen datos simulados que son equivalentes a los que se hubieran obtenido al consultar un contribuyente real. (En la dirección indicada en el apartado Información Adicional de Descripción, se pueden descargar ejemplos de petición y respuesta de los casos de NIF ficticios) REQUISITOS -Intercambio de datos públicos de los certificados implicados en la firma. -Dirección IP del organismo peticionario con la que se va a acceder por Intranet Administrativa ya que en AEAT se debe de autorizar específicamente. -Conexión del organismo peticionario a la red SARA (Sistema de Aplicaciones y Redes para las Administraciones). -El organismo peticionario deberá enviar los datos públicos del certificado con el que van a hacer el handshake y, si va a ser distinto, también con el que van a firmar. -Las autorizaciones de acceso al servicio se gestionarán a través del SEPRI (comunicacion.sepri@correo.aeat.es) mediante el formulario Formulario Autorizaciones.pdf. Página 4
COMPOSICIÓN DE LOS MENSAJES DE PETICIÓN Y DE RESPUESTA. Los mensajes de intercambio son de la siguiente manera: - Petición. Tiene un apartado de Datos genéricos. Respuesta. Cuando el mensaje de Petición se ha rebibido correctamente y se está en disposición de procesar la información solicitada, entonces se emitirá el documento XML Respuesta con la información que corresponda. En este caso, estará compuesto de:. Datos genéricos.. Datos específicos SOAP Fault. Cuando el mensaje de Petición tiene algún problema (como por ejemplo, firma inválida, certificado X509 revocado, error en la comunicación, error en validación de esquema, que no sea posible acceder a la BD,etc.) entonces se generará un SOAP Fault. Los mensajes de Respuesta y de SOAP Fault son incompatibles entre sí, de modo que se generará uno u otro, pero no ambos a la vez. Página 5
MENSAJE DE PETICIÓN Emisor: Organismo requirente. Receptor: AEAT. DIAGRAMA El esquema de la solicitud consiste en: Página 6
DESCRIPCIÓN DE LOS CAMPOS. MENSAJE DE PETICIÓN. Características de los tags del mensaje: Atributos Tipo AN: alfanumérico, N: numérico Carácter R: requerido, O: opcional Descripción Long. Tipo Car. Comentarios Atributos IdPeticion 26 AN R Identificador de Petición. Clave única, irrepetible, para identificar la Puede confeccionarse, por ejemplo, con 4 letras del organismo seguido de un secuencial NumElementos 4 N R Debe ser 1. TImestamp 29 AN R Instante de la Formato AAAA-MM- DDTHH:MM:SS.ZZZ+01:00 Estado O No rellenar en el mensaje de petición CodigoEstado 4 AN O No rellenar en el mensaje de petición CodigoEstadoSecundario 16 AN O No rellenar en el mensaje de petición LiteralError 255 AN O No rellenar en el mensaje de petición TiempoEstimadoRespuesta 4 N O No rellenar en el mensaje de petición CodigoCertificado 64 AN R Código del certificado. Se pondrá AEATIAE Solicitudes SolicitudTransmision DatosGenericos Emisor NifEmisor 10 AN R NIF del emisor. Rellenar con 9 dígitos con el valor Q2826000H NombreEmisor 50 AN R Nombre del emisor. Rellenar con AEAT Solicitante IdentificadorSolicitante 10 AN R NIF del Organismo que solicita la información. Rellenar con 9 dígitos. NombreSolicitante 50 AN R Nombre del Organismo que solicita la información UnidadTramitadora 250 AN O Unidad tramitadora del Solicitante Procedimiento CodigoProcedimiento 20 AN O Código de la clasificacion de procedimientos tributarios para Web Service.(Opcional) NombreProcedimiento 100 AN O Nombre de la clasificacion de procedimientos tributarios para Web Service.(Opcional). Finalidad 250 AN R Texto libre que indica el motivo de la petición del certificado a la AEAT Consentimiento 3 AN R Indica si el solicitante tiene el permiso del titular para recabar esta información; los valores posibles son SI y LEY. Página 7
Funcionario O NombreCompletoFuncionario 122 AN O Nombre y apellidos del funcionario que realiza la petición NifFuncionario 10 AN O NIF del funcionario que realiza la petición IdExpediente 25 AN O Identificación del expediente. Titular TipoDocumentacion 17 AN R Tipo de documentación del contribuyente del que se va a solicitar la información. (Solo se acepta NIF) Documentacion 14 AN R Número de documentación del contribuyente del que se va a solicitar la información. (Sólo se acepta NIF y debe ser de 9 posiciones) NombreCompleto 122 AN O Apellido1, Apellido2, Nombres del contribuyente del que se va a solicitar la información Nombre 40 AN O Nombre del contribuyente del que se va a solicitar la información Apellido1 40 AN O Primer apellido del contribuyente del que se va a solicitar la información Apellido2 40 AN O Segundo apellido del contribuyente del que se va a solicitar la información Transmision CodigoCertificado 64 AN R Identificador del servicio web al que se va a acceder rellenar con AEATIAE IdSolicitud 40 AN R Identificador de solicitud. Clave única, irrepetible, para identificar la solicitud. Puede confeccionarse, por ejemplo, con 4 letras del organismo seguido de un secuencial. Tiene que coincidir con el campo IdPeticion rellenado anteriormente. IdTransmision 29 AN O Timestamp de transmisión. Formato AAAA-MM- DDTHH:MM:SS.ZZZ+01:00 FechaGeneracion 29 AN O Fecha en la que se realiza la Formato AAAA-MM-DDTHH:MM:SS.ZZZ+01:00 Página 8
MENSAJE DE RESPUESTA Emisor: AEAT. Receptor: Organismo requirente. DIAGRAMA Página 9
DESCRIPCIÓN DE LOS CAMPOS. MENSAJE DE RESPUESTA. Características de los tags del mensaje: Atributos Tipo AN: alfanumérico, N: numérico Carácter R: requerido, O: opcional Descripción Long. Tipo Car. Comentarios Atributos Se rellenará con lo contenido en el mensaje de IdPeticion 26 AN R NumElementos 4 N R TImestamp 29 AN R Estado O CodigoEstado 4 AN O Indica cómo se ha procesado la petición; los códigos que devuelve son: - 0003 (Tramitado correctamente). - 0004 (No tramitado correctamente). consultar en ERRORES FUNCIONALES Y OTRAS SITUACIONES CodigoEstadoSecundario 16 AN O Consultar códigos en ERRORES FUNCIONALES Y OTRAS SITUACIONES LiteralError 255 AN O - Tramitado (0003) - Error Funcional (0004) Consultar en ERRORES FUNCIONALES Y OTRAS SITUACIONES. TiempoEstimadoRespuesta 4 N O Sin contenido en caso de Servicio Web sincrono, que es este caso. CodigoCertificado 64 AN R Se rellenará con lo contenido en el mensaje de Solicitudes O SolicitudTransmision DatosGenericos Emisor NifEmisor 10 AN R Se rellenará con lo contenido en el mensaje de NombreEmisor 50 AN R Solicitante Se rellenará con lo contenido en el mensaje de IdentificadorSolicitante 10 AN R NombreSolicitante 50 AN R UnidadTramitadora 250 AN O Procedimiento Se rellenará con lo contenido en el mensaje de CodigoProcedimiento 20 AN O NombreProcedimiento 100 AN O Finalidad 250 AN R Página 10
Consentimiento 3 AN R Funcionario O Se rellenará con lo contenido en el mensaje de NombreCompletoFuncionario 122 AN O NifFuncionario 10 AN O IdExpediente 25 AN O Titular TipoDocumentacion 17 AN R Se rellenará con lo contenido en el mensaje de Documentacion 14 AN R Se rellenará con lo contenido en el mensaje de NombreCompleto 122 AN O Apellido1, Apellido2, Nombre del contribuyente del que se ha solicitado la información tal como figura en las bases de datos identificativas de la AEAT. Nombre 40 AN O Se rellenará con lo contenido en el mensaje de Apellido1 40 AN O Se rellenará con lo contenido en el mensaje de Apellido2 40 AN O Se rellenará con lo contenido en el mensaje de Transmision Se rellenará con lo contenido en el mensaje de CodigoCertificado 64 AN R IdSolicitud 40 AN R IdTransmision 29 AN O FechaGeneracion 29 AN O DatosEspecificos Datos propios informados por el servicio web de la AEAT. CodRespuesta 4 AN R Código de retorno: Es igual que CodigoEstadoSecundario. Consultar en ERRORES FUNCIONALES Y OTRAS SITUACIONES DescRespuesta 50 AN O Descripción del mensaje de respuesta recibido en CodRespuesta. FechaProceso 10 AN R Fecha a la que es válida la respuesta en formato AAAA-MM-DD ReferenciaPet 11 AN R Referencia única de la respuesta para el conjunto de todas las actividades económicas. Formato 99999999999 NroActividades 4 N R Número de actividades informadas (puede ir de 0 a 10) Actividades O Hasta un máximo de 10 ocurrencias Seccion 50 AN O Sección o tipo de actividad. Los valores posibles son 1 Empresarial 2 Profesional 3 Artista 4 Actividades económicas no sujetas al IAE Epigrafe 4 AN O Epígrafe del IAE DescActividad 40 AN O Descripción de la actividad económica FechaInicio 10 AN O Fecha de alta en la actividad en formato AAAA- MM-DD FechaFin 10 AN O Fecha de baja en la actividad en formato AAAA- MM-DD Referencia 11 AN O Referencia o clave que identifica cada actividad económica. Formato 99999999999 Página 11
SOAP FAULT Cuando el sistema detecte un error (firma inválida, certificado X509 revocado, esquema no válido, no es posible acceder a la BD, etc...) responderá con un mensaje SOAP que sigue el estandar SOAP Fault. Dicho SOAP se envia sólo cuando hay error. DIAGRAMA El esquema del mensaje SOAP ante cualquier error genérico (de sistema, base de datos...) será: Página 12
DESCRIPCIÓN DE LOS CAMPOS DEL SOAP FAULT. Características de los tags del mensaje de error: Atributos del SOAP Fault Carácter R: requerido, O: opcional Tipo AN: alfanumérico, N: numérico Descripción Long. Tipo Car. Comentarios Idpeticion 45 AN R Identificación de petición que debe ser único por transmisión. Es la clave que identificará en ambos extremos NumElementos 7 N O Debe ser 1. TimeStamp 29 AN R Timestamp de petición en formato DateTime AAAA-MM-DDTHH:MM:SSZ Estado O Estado de la transmisión. Describe código de error,principal, secundario, literales, etc. CodigoEstado 4 AN O Código de estado principal que permite a la aplicación cliente la toma de decisión (reenvío...). Para más detalles, ver la descripción del error en los campos LiteralErrorPrincipal y LiteralErrorSecundario Este código de error suele venir reflejado en la documentación de CIRCA. LiteralError 150 AN O Descipción del campo CodigoEstadoPrincipal si ha habido error. CodigoEstadoSecundario 16 AN O Código de estado secundario. Devuelve un código de error más específico que ayuda a resolver la incidencia LiteralErrorSec 255 AN O Descipción del campo CodigoEstadoSecundario si ha habido error. TiempoEstimadoResp 4 N O Se devolverá 0000 en el caso de Serviciios Web síncronos, como es este caso. CodigoCertificado 64 AN O Se rellenará con lo contenido en el mensaje de Ver más detalles en la documentación que se cita en el apartado INFORMACIÓN ADICIONAL. Notas. Los valores de las columnas CódigoEstado y CodigoEstadoSecundario, en general, se corresponden con situaciones de lógica de negocio. Los valores de la columna CódigoEstado se suelen corresponder con los que aparecen en la documentación de CIRCA (Ver Información Adicional). En concreto el valor 0003 coincide exactamente (petición tramitada). Página 13
FIRMA DIAGRAMA El esquema genérico con la firma XMLDSig sería: Página 14
ESTRUCTURA DE LOS MENSAJES Solicitud: Mensaje de petición Contendrá una capa SOAP y en el BODY estarán los datos de la transmisión, éstos se firman con XMLDSig. CAPA SOAP HEADER SOAP Firma XMLDSig (nodo Body) BODY SOAP Peticion Contestación: Mensaje de respuesta Contendrá una capa SOAP y en el BODY estarán los datos de la transmisión más los datos específicos de este mensaje. Se firman con XMLDSig los atributos de transmisión y los datos específicos. CAPA SOAP HEADER SOAP Firma XMLDSig (nodo Body) BODY SOAP Respuesta EJEMPLOS En la dirección indicada en el apartado Información Adicional de Descripción se encuentran algunos ficheros XML con ejemplos de peticiones y respuestas. ERRORES FUNCIONALES Y OTRAS SITUACIONES Si la petición y respuesta son correctas, entonces en el mensaje de Respuesta.se enviará como CodigoEstado el valor 0003 (tramitada). Si hubo algún error de lógica de negocio, entonces en el mensaje de Respuesta se enviará como CodigoEstado el valor 0004 y como CodigoEstadoSecundario uno de los valores que aparecen más abajo, en la columna del mismo nombre: Página 15
CodigoEstado 0003 1000 0003 1002 0003 1006 0003 1008 0004 212 0004 1003 0004 1004 0004 1005 0004 1007 0004 1009 0004 2001 0004 2002 0004 2003 0004 2004 0004 2005 0004 2006 0004 2007 CodigoEstado Secundario Descripción Transmisión correcta. Titular identificado y con actividades económicas. Transmisión correcta. AVISO: Titular no identificado en la AEAT. Transmisión correcta. AVISO: No procede facilitar la información solicitada. Transmisión correcta. AVISO: Titular identificado y sin actividades económicas. ERROR: Solicitante no autorizado. ERROR: Servicio web desconocido. ERROR: Problemas técnicos. ERROR: Entrada inconsistente. ERROR: Organismo solicitante no identificado en las Bases de Datos de la AEAT. ERROR: Titular con C.I. revocado. ERROR: Código de certificado solicitado incorrecto ERROR: Número de elementos distinto de 1. ERROR: Nif emisor incorrecto. ERROR: Nombre de Emisor incorrecto ERROR: Error al llamar al módulo de certificación ERROR: Abend de CICS XXXX ERROR: Error BBDD con código XXXX Solución Revisar datos identificativos del contribuyente No procede facilitar dato alguno por parte de la AEAT Contactar con el Departamento de Informática Tributaria - CAT Centro de Atención Telefónica de la AEAT Incluir AEATIAE como codigo certificado en el tag CodigoCertificado> Contactar con el Departamento de Informática Tributaria (AEAT) - Centro de Atención Telefónica (CAT) de la AEAT Revisar datos genéricos de la solicitud Revisar datos identificativos del organismo solicitante de la información Reintentarlo más tarde. En caso necesario contactar con el Departamento de Informática Tributaria (AEAT) - Centro de Atención Telefónica (CAT) de la AEAT Como CodigoCertificado AEATIAE En NumElementos un 1 En NifEmisor Q2826000H En NombreEmisor AEAT Contactar con AEAT-CAT 0004 2008 Error CICS con código XXXX Página 16
CONTACTOS Para cualquier duda, incidencia o sugerencia por favor diríjase a: CAT Centro de Atención Telefónica de la AEAT Teléfono 901 200 349 Correo electrónico: CATENTIDADES@CORREO.AEAT.ES Centro de Soporte Supresión de Certificados del Ministerio de la Presidencia Teléfono 902 93 44 05 Opción 3 Otros Servicios Correo electrónico: soporte.sustituciondecertificados@mpr.es http://www.ctt.mpr.es/web/scsp/ Página 17