Especificación Servicio Web de Obtención domicilio fiscal. Código certificado: SCPWIJ1R Fecha: 10-04-2013 Versión: 2.2 Estándar: SCSP V2 Plataforma: AsWeb Departamento de Informática Tributaria C/ Sta. María Magdalena, 16 28016 - Madrid Subdirección de Tecnologías de Análisis de la Información e Investigación del Fraude (TAIIF) AGENCIA TRIBUT RIA A www.aeat.es
Control Documental Versión Documento Fecha 0.1 Especificación inicial 21-01-2009 1.0 Revisión general y cambio de ejemplos 29-01-2009 1.1 Cambios en documentación anexa y generales 23-08-2010 2.0 Actualización de contactos 19-11-2010 2.1 Modificación de error en campos opcionales de salida 16-08-2011 2.2 Añadida dirección de internet. Cambios en el formato. 10-04-2013 Página 1
Tabla de contenidos DESCRIPCIÓN... 3 CARACTERÍSTICAS... 3 ENTORNOS... 4 REQUISITOS... 4 MENSAJE DE PETICIÓN... 5 MENSAJE DE RESPUESTA... 8 SOAP FAULT... 13 FIRMA... 15 ESTRUCTURA DE LOS MENSAJES... 16 Solicitud: Mensaje de petición... 16 Contestación: Mensaje de respuesta... 16 EJEMPLOS... 16 WSDL S... 17 MENSAJES DE ERROR... 18 FICHEROS... 19 Página 2
ESPECIFICACIONES DEL WEB SERVICE PARA LA OBTENCIÓN DEL DOMICILIO FISCAL DE UN CONTRIBUYENTE DESCRIPCIÓN Este desarrollo facilita en modo síncrono a los organismos públicos autorizados el domicilio fiscal de un contribuyente dado, siendo esta información la que figura en el momento de la solicitud en el sistema de información de la Agencia Tributaria. Para consultar más información sobre los servicios web ver el fichero Guía autorizaciones.pdf en la dirección: https://www2.agenciatributaria.gob.es/adua/internet/wscert.html CARACTERÍSTICAS Entorno: Intranet Administrativa. Protocolo: HTTPS. Mensajes: Web Service con SOAP 1.1 modo Document. En la dirección indicada en el apartado Descripción se encuentra el fichero WSDL 1.0 wsdl_scpwij1r.wsdl para la generación de clientes. MEDIO DE ENVÍO: 1. Por Intranet Administrativa: https://ws.ia.aeat.es/es13/s/scpwscpwij1r 2. Por Internet (de modo excepcional y solo a los organismos especialmente autorizados): https://www1.agenciatributaria.gob.es/es13/s/scpwscpwij1r 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. 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.2 Firma: XMLDSig. Nodo de firma: todo el BODY del SOAP. Encoding: preferentemente UTF-8 y, si no, ISO-8859-15. Página 3
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 Descripción se pueden descargar ejemplos de petición y respuesta de los tres 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 autorizar específicamente. - Conexión del organismo peticionario a la red SARA. Página 4
MENSAJE DE PETICIÓN Emisor: Organismo peticionario. Receptor: AEAT. DIAGRAMA El esquema de la solicitud consiste en: Página 5
DESCRIPCIÓN DE LOS CAMPOS. Características de los tags del mensaje: Atributos Carácter R: requerido, O: opcional Descripción Long. Tipo Car. Comentarios ATRIBUTOS IDPETICION 16 AN R Identificador de Petición. Clave única, irrepetible, para identificar la petición. Puede confeccionarse, por ejemplo, con 4 letras del organismo seguido de un secuencial NUMELEMENTOS 7 AN R Debe ser 1 por petición TIMESTAMP 29 AN R Instante de la petición ESTADO O CODIGOESTADO 4 AN O Código de estado LITERALERROR 255 AN O Descripción del error TIEMPOESTIMADORESPUESTA 4 AN O Tiempo estimado de respuesta CODIGOCERTIFICADO 64 AN R Código del certificado. Se pondrá SCPWIJ1R SOLICITUDES SOLICITUDTRANSMISION DATOSGENERICOS EMISOR NIFEMISOR 10 AN R Nif del emisor Q2826000H NOMBREEMISOR 50 AN R Nombre del emisor AEAT SOLICITANTE NIFSOLICITANTE 10 AN R Nif del Organismo que solicita la información NOMBRESOLICITANTE 50 AN R Nombre del Organismo que solicita la información 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. FUNCIONARIO O NOMBRECOMPLETOFUNCIONARIO 122 AN O Nombre completo del funcionario que realiza la petición NIFFUNCIONARIO 10 AN O Nif del funcionario que realiza la petición Página 6
TITULAR TIPODOCUMENTACION 17 AN R Tipo de documentación del contribuyente del que se va a solicitar la información (sólo se acepta NIF) DOCUMENTACION 14 AN R Documentación del contribuyente del que se va a solicitar la información NOMBRECOMPLETO 122 AN R Nombre completo 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 SCPWIJ1R IDPETICION 40 AN R Identificador de Petición. Clave única, irrepetible, para identificar la petición. Puede confeccionarse, por ejemplo, con 4 letras del organismo seguido de un secuencial. Tiene que coincidir con el campo IDPETICION rellenado anteriormente. IDTRANSMISION 26 AN O Timestamp de la petición FECHAGENERACION 29 AN O Fecha en la que se realiza la petición Página 7
MENSAJE DE RESPUESTA Emisor: AEAT. Receptor: Organismo peticionario. DIAGRAMA El esquema de la respuesta se muestra en dos partes. 1. Datos genéricos: Página 8
2. Datos específicos: Página 9
DESCRIPCIÓN DE LOS CAMPOS del mensaje de salida. Características de los tags del mensaje: Atributos Carácter R: requerido, O: opcional Descripción Long. Tipo Car. Comentarios ATRIBUTOS IDPETICION 16 AN R Identificador de Petición. Clave única, irrepetible, para identificar la petición. Puede confeccionarse, por ejemplo, con 4 letras del organismo seguido de un secuencial NUMELEMENTOS 7 AN R Debe ser 1 por petición TIMESTAMP 29 AN R Instante de la petición ESTADO O CODIGOESTADO 4 AN O Código de estado LITERALERROR 255 AN O Descripción del error TIEMPOESTIMADORESPUESTA 4 AN O Tiempo estimado de respuesta CODIGOCERTIFICADO 64 AN R Código del certificado. Se pondrá SCPWIJ1R TRANSMISIONES O TRANSMISIONDATOS DATOSGENERICOS EMISOR NIFEMISOR 10 AN R NIF del emisor Q2826000H NOMBREEMISOR 50 AN R Nombre del emisor AEAT SOLICITANTE NIFSOLICITANTE 10 AN R NIF del Organismo que solicita la información NOMBRESOLICITANTE 50 AN R Nombre del Organismo que solicita la información 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. FUNCIONARIO O NOMBRECOMPLETOFUNCIONARIO 122 AN O Nombre completo del funcionario que realiza la petición NIFFUNCIONARIO 10 AN O NIF del funcionario que realiza la petición Página 10
TITULAR TIPODOCUMENTACION 17 AN R Tipo de documentación del contribuyente del que se solicita la información (sólo se acepta NIF) DOCUMENTACION 14 AN R Documentación del contribuyente del que se solicita la información NOMBRECOMPLETO 122 AN O Nombre completo del contribuyente del que se solicita la información NOMBRE 40 AN O Nombre del contribuyente del que se solicita la información APELLIDO1 40 AN O Primer apellido del contribuyente del que se solicita la información APELLIDO2 40 AN O Segundo apellido del contribuyente del que se solicita la información TRANSMISION CODIGOCERTIFICADO 64 AN R Identificador del servicio web al que se accede IDPETICION 45 AN R Identificador de Petición. Clave única, irrepetible, para identificar la petición. Puede confeccionarse por ejemplo con 4 letras del organismo peticionario seguido de un secuencial IDTRANSMISION 26 AN O Timestamp de la petición FECHAGENERACION 29 AN O Fecha en la que se realiza la petición DATOSESPECIFICOS CABECERA CODRET_S 4 AN R Código con el resultado 1000 : correcto otros: consultar en MENSAJES DE ERROR DESCRIP_ERROR_S 100 AN R Descripción del mensaje de error recibido en CODRET_S REFERENCIA_S 11 AN R Referencia única de la respuesta FECHA_EMISIÓN_S 10 AN R Fecha de emisión de la respuesta TIPO_RESPUESTA_S 2 AN O Tipo de respuesta DIRECCION ADMÓN._FICS_S 5 AN O Administración fiscal TIPO_DOMI_S 2 AN O Tipo de domicilio 20 : domicilio fiscal en España, procede 21 : domicilio fiscal en el extranjero, no se facilita información este caso FECH_DOMI_S 8 AN O Fecha actualización último domicilio TIPO_VIA_S 5 AN O Tipo de vía CODIGO_VIA_S 5 AN O Código de vía INE VIAPBL_S 50 AN O Nombre largo de la vía pública VIAPBC_S 25 AN O Nombre corto de la vía pública TIPO_NUM_S 3 AN O Tipo número. Valores: NÚM; KM.; S/N; ETC. NUMERO_EN_S 5 AN O Número de la casa en la vía CALIF_NUM_S 3 AN O Valores: BIS; DUP; MOD; ANT; etc / metros si Tipo Numer = KM. BLOQUE_S 3 AN O Bloque (número o letras) PORTAL_S 3 AN O Portal (número o letras) Página 11
ESC_S 3 AN O Escalera (número o letras) PISO_S 3 AN O Planta o piso (número o letras) PTA_S 3 AN O Puerta (número o letras) COMPLEMENTO_S 40 AN O Datos complementarios del domicilio (si procede). Ej: Urbanización... ; Centro Comercial... ; local... ; Mercado de... puesto nº... ; Polígono Industrial..., Edificio... ; etc. POBLACIÓN_S 30 AN O Nombre localidad, población, etc (si distinta al municipio) CODPOST_S 5 AN O Código postal CODMUNI_S 5 AN O Código municipio INE MUNICIPIO_S 30 AN O Nombre del municipio CODPROV_S 2 AN O Código de provincia NOMPROV_S 20 AN O Nombre de la provincia E_MAIL_S 100 AN O Dirección electrónica TFNO_FIJO_S 9 AN O Teléfono fijo TFNO_MOVIL_S 9 AN O Teléfono móvil FAX_S 9 AN O Fax Página 12
SOAP FAULT DIAGRAMA El esquema del mensaje SOAP ante cualquier error genérico (de sistema, base de datos...) será: Página 13
DESCRIPCIÓN DE LOS CAMPOS. Características de los tags del mensaje de error: Atributos Carácter R: requerido, O: opcional 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 TimeStamp 20 an R Timestamp de petición en formato DateTime AAAA-MM-DDTHH:MM:SSZ Mensaje 20 an R Identificación del mensaje. Los valores posibles son EFICHERO-Envío de fichero RFICHERO-Recepción de fichero Estado O Estado de la transmisión. Describe el error Estado Carácter R: requerido, O: opcional Descripción Long. Tipo Car. Comentarios CodigoEstadoPrincipal 5 an O Código de estado principal que permite a la aplicación cliente la toma de decisión (reenvío...). Si se ha recibido correctamente se devolverá 00000. LiteralErrorPrincipal 150 an O Descipción del campo CodigoEstadoPrincipal si ha habido error. CodigoEstadoSecundario 5 an O Código de estado secundario. Devuelve un código de error más específico que ayuda a resolver la incidencia LiteralErrorSecundario 150 an O Descipción del campo CodigoEstadoSecundario si ha habido error. TiempoEstimadoRespuesta 4 n O Tiempo estimado en devolver respuesta en caso que el error posible se solucione Página 14
FIRMA DIAGRAMA El esquema genérico de la firma XmlDsig sería: Página 15
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 Descripción se encuentran distintos ficheros XML de ejemplos de peticiones y respuestas que se describen en el apartado Ficheros. Página 16
WSDL S El WSDL describe la interfaz del servicio web y contiene la dirección donde establecer la comunicación. En este caso contiene todos los esquemas XSD embebidos en el propio archivo. El archivo WSDL del servicio web se encuentra en la dirección indicada en el apartado Descripción. Página 17
MENSAJES DE ERROR Errores genéricos (permiten la toma de decisión). Error Descripción Solución 1001 Solicitante no autorizado Contactar con el Departamento de Informática Tributaria 1002 Titular no identificado Revisar datos identificativos del contribuyente 1003 Código de certificado desconocido Incluir SCPWIJ1R como codigo certificado 1004 Problemas técnicos Contactar con el Departamento de Informática Tributaria 1005 Entrada inconsistente Revisar datos genéricos de la solicitud 1006 No procede facilitar información Contactar con el Departamento de Informática Tributaria 1007 Solicitante no identificado Revisar datos identificativos del organismo solicitante de la información Página 18
FICHEROS FICHERO TIPO DESCRIPCIÓN xmldsig-core-schema.xsd Esquema Genérico de Firma (Signature) XMLDSig SOAP_FAULT.xsd Esquema SOAP FAULT genérico. Importa soapfaultatributos.xsd soapfaultatributos.xsd Esquema Atributos específicos para el SOAP FAULT en estos mensajes schema_copy_scpwij1r_peticion.xsd Esquema Datos específicos del Envío de fichero schema_copy_scpwij1r_respuesta.xsd Esquema Datos específicos de Recepción del fichero wsdl_scpwij1r.wsdl WSDL Petición/Respuesta de envío de fichero Peticion_SCPWIJ1R.xml XML Ejemplo de petición Respuesta_SCPIJ1R.xml XML Ejemplo de respuesta 1. Ejemplo solicitud X Ficticio.xml XML Ejemplo solicitud usuario ficticio 2. Ejemplo respuesta X Ficticio.xml XML Ejemplo respuesta usuario ficticio 3. Ejemplo solicitud Y Ficticio.xml XML Ejemplo solicitud usuario ficticio 4. Ejemplo respuesta Y Ficticio.xml XML Ejemplo respuesta usuario ficticio 5. Ejemplo solicitud Z Ficticio.xml XML Ejemplo solicitud usuario ficticio 6. Ejemplo respuesta Z Ficticio.xml XML Ejemplo respuesta usuario ficticio Página 19
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 Atención a Integradores y Desarrolladores (CAID) del Ministerio de Hacienda y Administraciones Públicas Teléfono: 902 934 405 Opción 3 Otros Servicios Correo electrónico: soporte.sustituciondecertificados@seap.minhap.es Dirección electrónica: http://administracionelectronica.gob.es/es/ctt/scsp Página 20