Subdirección General de Aplicaciones

Transcripción

1 Especificación Servicio Web de Obtención domicilio fiscal. Código certificado: Fecha: Estándar: SCSP V3 Plataforma: Adujava-CICS Departamento de Informática Tributaria C/ Sta. María Magdalena, Madrid Subdirección General de Aplicaciones Agencia Tributaria

2 Control Documental Versión Documento Fecha 0.1 Especificación inicial Cambios nombre del servicio y descripción de errores Especificación de formato del campo NombreCompletoFuncionario Insertado nuevo código de error Cambiado el apartado de Códigos de estado y de error genéricos. 1.2 Añadidas ULs para el nuevo entorno de integración 1.3 Añadidos nuevos NIFs de prueba para el entorno de integración Página 2 de 24

3 Tabla de contenidos Control Documental... 2 Tabla de contenidos... 3 ESPECIFICACIONES DEL SEVICIO WEB PAA LA OBTENCIÓN DEL DOMICILIO FISCAL DE UN CONTIBUYENTE... 4 DESCIPCIÓN... 4 ENTADA:... 4 SALIDA:... 4 INFOMACIÓN ADICIONAL... 4 CAACTEÍSTICAS... 5 MEDIO DE ENVÍO:... 5 SEVICIOS DISPONIBLES... 6 ENTONOS... 6 EQUISITOS... 7 COMPOSICIÓN DE LOS MENSAJES DE PETICIÓN Y DE ESPUESTA MENSAJE DE LOS DATOS DE LA PETICIÓN... 8 MENSAJE DE LOS DATOS DE ESPUESTA (PATE COMÚN) DESCIPCIÓN DE LOS DATOS DE LA ESPUESTA (PATE COMÚN) MENSAJE DE LOS DATOS DE LA ESPUESTA (PATE ESPECÍFICA) SOAP FAULT DESCIPCIÓN DE LOS CAMPOS FIMA ESTUCTUA DE LOS MENSAJES EJEMPLOS WSDL S CÓDIGOS DE ESTADO Y DE EO CONTACTOS Página 3 de 24

4 ESPECIFICACIONES DEL SEVICIO WEB PAA LA OBTENCIÓN DEL DOMICILIO FISCAL DE UN CONTIBUYENTE DESCIPCIÓ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. ENTADA: Para llamar al servicio hay que facilitar el NIF del contribuyente. SALIDA: Este servicio devuelve al organismo público solicitante los datos del domicilio fiscal referente al titular solicitado. INFOMACIÓN ADICIONAL Para más información sobre el Servicio Web se pueden consultar los ficheros: Protocolo o guía de procedimientos (POTGEN) (protgen.pdf) y Formulario para solicitar certificados a través de servicios web (Formsweb_mi_MI.pdf) en la Sede electrónica de la AEAT, dirección: a/modelos_y_formularios/administraciones_publicas/indice_serv_web_sum_aapp.pdf El documento protgen.pdf contiene, a su vez, una referencia ( CICA ) de donde se puede encontrar toda la información técnica. Página 4 de 24

5 CAACTEÍSTICAS Entorno: Intranet Administrativa (ed SAA). Protocolo: HTTPS. Mensajes: Web Service con SOAP 1.1 modo Document. En el índice de Servicios Web en el apartado de Domicilio Fiscal, se encuentran los siguientes ficheros para establecer la comunicación con el servicio web: WSDL: wsdl_jav3_.wsdl. Esquema entrada: schema_jav3 peticion.xsd Esquema salida: schema_jav3 respuesta.xsd schema_jav3 datos-especificos.xsd El mensaje contendrá el NIF del organismo peticionario en el tag <IdentificadorSolicitante> y debe estar autorizado en la AEAT 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: 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. El NIF de persona jurídica incluido en el mismo debe coincidir con el incluido en el tag <IdentificadorSolicitante>. Firma: en XMLDSig. Se deberá enviar obligatoriamente el tag X509Certificate para poder autenticar el mensaje. Nodo de firma: todo el BODY del SOAP. Encoding: preferentemente UTF-8 y, si no, ISO Página 5 de 24

6 SEVICIOS DISPONIBLES Para este servicio web, igual que en otros de similares características, es preciso indicar el código de certificado asociado al Servicio Web de Domicilio Fiscal () en los datos generales de petición, para lo cual en el siguente tag se consignará, por ejemplo: schema_jav3 peticion.xsd... <CodigoCertificado>... Este servicio se ofrece solo en modo síncrono (una única solicitud por petición). ENTONOS La AEAT ofrece dos entornos de desarrollo: El entorno de producción, accesible a través de la url descrita previamente. Devolverá 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). Un segundo entorno de integración, para pruebas con el exterior de la AEAT. La UL de este servicio a invocar en este entorno es: A través de ella se podrán consultar únicamente unos NIF de pruebas preparados para que se puedan validar los diferentes casos de uso relativos al servicio web. De esta manera, se permite obtener contestación simulada con los tipos de respuesta más frecuentes. Esto se consigue completando el campo NIF los datos de prueba XXXXXXXXX, YYYYYYYYY o ZZZZZZZZZZ, A , A, A (sin más datos identificativos). Para cada uno de estos 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 de Información Adicional de Descripción se pueden descargar ejemplos de petición y respuesta de los tres casos de NIF ficticios, tanto para el entorno de producción como de integración). Para poder usar el entorno de integración es necesario informar, en el formulario de autorización al WS, los campos relativos al certificado electrónico que se empleará para la autenticación y firma del servicio. Página 6 de 24

7 EQUISITOS Intercambio de datos públicos de los certificados implicados en la firma. Conexión del organismo peticionario a la red SAA (Sistema de Aplicaciones y edes para las Administraciones). El organimo 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 SEPI (comunicacion.sepri@correo.aeat.es) mediante el formulario Formulario para solicitar certificados a través de servicios web (Formsweb_mi_MI.pdf) disponible en la Sede Electrónica de la AEAT. COMPOSICIÓN DE LOS MENSAJES DE PETICIÓN Y DE ESPUESTA. Los mensajes de intercambio son de la siguiente manera: - Petición Tiene un apartado de Datos genéricos. - espuesta. Cuando el mensaje de Petición se ha recibido correctamente y se está en disposición de procesar la información solicitada, entonces se emitirá el documento XML espuesta 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 espuesta y de SOAP Fault son incompatibles entre sí, de modo que se generará uno u otro, pero no ambos a la vez. Página 7 de 24

8 MENSAJE DE LOS DATOS DE LA PETICIÓN Emisor: Organismo requiriente. eceptor: AEAT. DIAGAMA El esquema de la petición consiste en: Página 8 de 24

9 DESCIPCIÓN DE LOS CAMPOS DE LA PETICIÓN. Características de los tags del mensaje: Atributos Carácter : requerido, O: opcional Tipo AN: alfanumérico, N: numérico Descripción Long. Tipo Car. Comentarios Atributos IdPeticion 26 AN Identificador de Petición. Clave única, irrepetible, para identificar la petición del organismo requirente. Puede confeccionarse, por ejemplo, con 4 letras del organismo seguido de un secuencial Ejemplo: TGSS NumElementos 7 N Debe ser 1. Timestamp 29 AN Instante de la Formato AAAA-MM- DDThh:mm:ss.mmm hh:mm donde AAAA= año, MM= mes, DD=día, T:constante, hh:hora,mm:minutos, ss:segundos, mmm:milisegundos, :diferencia respecto a GMT, hh:horas, mm:minutos Ejemplo: T09:00: :00 Estado O 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 TiempoEstimadoespuesta 4 N O No rellenar en el mensaje de petición CodigoCertificado 64 AN Identificador del Servicio Web al que se va a acceder:. Solicitudes Id AN O Atributo opcional para agilizar las búsquedas por referencia en lugar de por Xpath en caso de cifrar el nodo Solicitudes SolicitudTransmision DatosGenericos Emisor NifEmisor 10 AN NIF del emisor. ellenar con 9 dígitos con el valor Q H NombreEmisor 50 AN Nombre del emisor. ellenar con AEAT Solicitante IdentificadorSolicitante 10 AN NIF del Organismo que solicita la información. ellenar con 9 dígitos. NombreSolicitante 50 AN Nombre del Organismo que solicita la información UnidadTramitadora 250 AN O Unidad tramitadora del Solicitante Página 9 de 24

10 Procedimiento O CodProcedimiento 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 Texto libre que indica el motivo de la petición del certificado a la AEAT Consentimiento 3 AN Indica si el solicitante tiene el permiso del titular para recabar esta información; los valores posibles son Si y Ley. Funcionario Podrá ser usado en auditoría posteriormente NombreCompletoFuncionario 122 AN Nombre y apellidos del funcionario que realiza la petición, con el formato Apellido1 Apellido2 Nombre. Ejemplo: ESPAÑOL ESPAÑOL JUAN NifFuncionario 10 AN NIF del funcionario que realiza la petición IdExpediente 25 AN O Identificación del expediente. Titular TipoDocumentacion 17 AN Tipo de documentación del contribuyente del que se va a solicitar la información. (Solo se acepta NIF/NIE) Documentacion 14 AN Número de identificación del contribuyente del que se va a solicitar la información. (Sólo se acepta NIF/NIE y debe ser de 9 posiciones) NombreCompleto 122 AN O Campo opcional, pero se recomienda que venga relleno. 1. Si Persona fisica: Apellido1 Apellido2 Nombre del contribuyente del que se va a solicitar la información Ejemplo: ESPAÑOL ESPAÑOL JUAN 2. Si Persona Juridica: azón Social. Ejemplo: INDUSTIAS PEEZ SL Nombre 40 AN O Nombre del contribuyente del que se va a solicitar la información (Sólo si persona física) En caso de persona jurídica, dejar a blancos Apellido1 40 AN O Primer apellido del contribuyente del que se va a solicitar la información (Sólo si persona física). En caso de persona jurídica, dejar a blancos Apellido2 40 AN O Segundo apellido del contribuyente del que se va a solicitar la información (Sólo si persona física) En caso de persona jurídica, dejar a blancos Transmision CodigoCertificado 64 AN Mismo valor que el tag CodigoCertificado de Atributos IdSolicitud 40 AN Mismo valor que el tag IdPeticion de Atributos IdTransmision 29 AN O No rellenar en el mensaje de FechaGeneracion 29 AN O No rellenar en el mensaje de petición Página 10 de 24

11 MENSAJE DE LOS DATOS DE ESPUESTA (PATE COMÚN). Emisor: AEAT. eceptor: Organismo requiriente. DIAGAMA Esquema de los datos de la respuesta: Página 11 de 24

12 DESCIPCIÓN DE LOS DATOS DE LA ESPUESTA (PATE COMÚN). Características de los tags del mensaje Carácter : requerido, O: opcional Tipo AN: alfanumérico, N: numérico Atributos Descripción Long. Tipo Car. Comentarios Atributos IdPeticion 26 AN Se rellenará con lo contenido en el mensaje de NumElementos 7 N Se rellenará con lo contenido en el mensaje de Timestamp 29 AN Instante de la respuesta. Formato AAAA-MM- DDThh:mm:ss.mmm hh:mm donde AAAA= año, MM= mes, DD=día, T:constante, hh:hora,mm:minutos, ss:segundos, mmm:milisegundos, :diferencia respecto a GMT, hh:horas, mm:minutos Ejemplo: T09:00: :00 Estado O CodigoEstado 4 AN O Indica cómo se ha procesado la petición; los códigos que devuelve son: - Estado tramitado: esto estados (consultar Códigos de estado y de error) CodigoEstadoSecundario 16 AN O Consultar Códigos de estado y de error LiteralError 255 AN O Consultar Códigos de estado y de error TiempoEstimadoespuesta 4 N O Sin contenido en caso de Servicio Web sincrono, que es este caso. CodigoCertificado 64 AN Se rellenará con lo contenido en el mensaje de Transmisiones O Id AN O Atributo opcional para agilizar las búsquedas por referencia en lugar de por Xpath en caso de cifrar el nodo Transmisiones TransmisionDatos DatosGenericos Emisor NifEmisor 10 AN Se rellenará con lo contenido en el mensaje de NombreEmisor 50 AN Se rellenará con lo contenido en el mensaje de Solicitante IdentificadorSolicitante 10 AN NIF/NIE del solicitante tal como aparece registrado en la AEAT. Se da con 9 posiciones. NombreSolicitante 50 AN Nombre del solicitante registrado en la AEAT correspondiente al tag IdentificadorSolicitante UnidadTramitadora 250 AN O Se rellenará con lo contenido en el mensaje de Procedimiento O Página 12 de 24

13 CodProcedimiento 20 AN O Se rellenará con lo contenido en el mensaje de NombreProcedimiento 100 AN O Se rellenará con lo contenido en el mensaje de Finalidad 250 AN Se rellenará con lo contenido en el mensaje de Consentimiento 3 AN Se rellenará con lo contenido en el mensaje de Funcionario Se rellenará con lo contenido en el mensaje de NombreCompletoFuncionario 122 AN Se rellenará con lo contenido en el mensaje de NifFuncionario 10 AN Se rellenará con lo contenido en el mensaje de IdExpediente 25 AN O Se rellenará con lo contenido en el mensaje de Titular TipoDocumentacion 17 AN Se rellenará con lo contenido en el mensaje de Documentacion 14 AN NIF/NIE del titular tal como aparece registrado en la AEAT. Se da con 9 posiciones. NombreCompleto 122 AN O 1. Si se trata de una Persona Física: a) Si identificado : Apellido1 Apellido2 Nombre del titular del que se ha solicitado la información tal como figura en las bases de datos identificativas de la AEAT. Ejemplo: PEEZ MATINEZ MANUEL b) Si no identificado: Se rellena con lo contenido en el mensaje de petición 2. Si se trata de una Persona Jurídica: a) Si identificado : azón social del titular del que se ha solicitado la información tal como figura en las bases de datos identificativas de la AEAT. Ejemplo INDUSTIAS PEEZ SL b) Si no identificado: Se rellena con lo contenido en el mensaje de petición 3. Si NIF FICTICIO se rellena con ESPAÑOL ESPAÑOL JUAN Nombre 40 AN O Si es Persona Fisica, se rellena con el contenido del mensaje de Si es Persona Jurídica no se escribe. Si es NIF ficticio se escribe texto fijo: JUAN. Apellido1 40 AN O Si es Persona Fisica, se rellena con el contenido del mensaje de Si es Persona Jurídica no se escribe. Si es NIF ficticio se escribe texto fijo: ESPAÑOL. Apellido2 40 AN O Si es Persona Fisica, se rellena con el contenido del mensaje de Si es Persona Jurídica no se escribe. Si es NIF ficticio se escribe texto fijo: ESPAÑOL. Transmision CodigoCertificado 64 AN Se rellenará con lo contenido en el mensaje de IdSolicitud 40 AN Se rellenará con lo contenido en el mensaje de IdTransmision 29 AN Incluye el mismo valor del tag eferencia de DatosEspecíficos del mensaje de respuesta FechaGeneracion 29 AN Incluye el mismo valor del tag FechaEmision de DatosEspecíficos del mensaje de respuesta. Página 13 de 24

14 MENSAJE DE LOS DATOS DE LA ESPUESTA (PATE ESPECÍFICA). Emisor: AEAT. eceptor: Organismo requirente. Mensaje donde se incluye el conjuto de datos tributarios del contribuyente en los casos que corresponda. DIAGAMAS a) El esquema de los datos específicos (cabecera). b) El esquema de los datos específicos (dirección). Página 14 de 24

15 Página 15 de 24

16 DESCIPCIÓN DE LOS DATOS DE LA ESPUESTA (PATE ESPECÍFICA). Características de los tags del mensaje Carácter : requerido, O: opcional Tipo AN: alfanumérico, N: numérico Descripción Long. Tipo Car. Comentarios DatosEspecificos Id AN O Atributo opcional para agilizar las búsquedas por referencia en lugar de por Xpath en caso de cifrar el nodo DatosEspecificos Cabecera Cabecera referida a los datos epecíficos común a todos los SW Codet 4 N Código con el resultado 1000 : correcto otros: consultar en Códigos de estado y de error DescripcionError 100 AN Descripción del mensaje de respuesta recibido en Codet. eferencia 11 AN eferencia única de la respuesta. Si error no se genera referencia. FechaEmision 10 AN Fecha de proceso. Formato aaa-mm-dd Dirección AdministracionFiscal 5 AN O Administración fiscal TipoDomicilio 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 FechaDomicilio 8 AN O Fecha actualización último domicilio TipoVia 5 AN O Tipo de vía CodigoVia 5 AN O Código de vía INE NombreViaLargo 50 AN O Nombre largo de la vía pública NombreViaCorto 25 AN O Nombre corto de la vía pública TipoNumeroVia 3 AN O Tipo número. Valores: NÚM; KM.; S/N; ETC. NumeroVia 5 AN O Número de la casa en la vía CalificativoNumeroVia 3 AN O Valores: BIS; DUP; MOD; ANT; etc / metros si Tipo Numer = KM. Bloque 3 AN O Bloque (número o letras) Portal 3 AN O Portal (número o letras) Escalera 3 AN O Escalera (número o letras) Piso 3 AN O Planta o piso (número o letras) Puerta 3 AN O Puerta (número o letras) Complemento 40 AN O Datos complementarios del domicilio (si procede). Ej: Urbanización... ; Centro Comercial... ; local... ; Mercado de... puesto nº... ; Polígono Industrial..., Edificio... ; etc. Poblacion 30 AN O Nombre localidad, población, etc (si distinta al municipio) Página 16 de 24

17 CodigoPostal 5 AN O Código postal CodigoMunicipio 5 AN O Código municipio INE Municipio 30 AN O Nombre del municipio CodigoProvincia 2 AN O Código de provincia Provincia 20 AN O Nombre de la provincia 100 AN O Dirección electrónica TfnoFijo 9 AN O Teléfono fijo TfnoMovil 9 AN O Teléfono móvil Fax 9 AN O Fax Página 17 de 24

18 SOAP FAULT DIAGAMA El esquema del mensaje SOAP ante cualquier error genérico (de sistema, base de datos...) será: Página 18 de 24

19 DESCIPCIÓN DE LOS CAMPOS. Características de los tags del mensaje de error: Atributos Carácter : requerido, O: opcional Descripción Long. Tipo Car. Comentarios Idpeticion 45 an Identificación de petición que debe ser único por transmisión. Es la clave que identificará en ambos extremos TimeStamp 20 an Timestamp de petición en formato DateTime AAAA-MM-DDTHH:MM:SSZ Mensaje 20 an Identificación del mensaje. Los valores posibles son EFICHEO-Envío de fichero FICHEO-ecepción de fichero Estado O Estado de la transmisión. Describe el error Estado Carácter : 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á 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. TiempoEstimadoespuesta 4 n O Tiempo estimado en devolver respuesta en caso que el error posible se solucione Página 19 de 24

20 FIMA DIAGAMA El esquema genérico de la firma XmlDsig sería: Página 20 de 24

21 ESTUCTUA 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 HEADE 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 HEADE SOAP Firma XMLDSig (nodo Body) BODY SOAP espuesta EJEMPLOS En la dirección indicada en el apartado de Información Adicional de Descripción se encuentran algunos ficheros XML con ejemplos de peticiones y respuestas. 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 21 de 24

22 CÓDIGOS DE ESTADO Y DE EO Genéricos (comunes a todos los servicios). Se encuentran en la siguiente dirección: at/dit/adu/suap/docu/codigos_de_estado_y_de_error.pdf Página 22 de 24

23 Ejemplos de control de errores: Una vez realizada la llamada al servicio con un NIF, pueden ocurrir, entre otros, los siguientes casos: CÓDIGO DE CETIFICADO INCOECTO Si la llamada al servicio se hace con un código de certificado incorrecto, es decir, distinto de en nuestro caso, se rellena: a. Código de Estado: b. CodigoEstadoSecundario: 1006 c. Literal Error: Código de certificado desconocido o incorrecto. d. Código de etorno: e. Descripcion de Error: Código de certificado desconocido o incorrecto. CONTIBUYENTE NO IDENTIFICADO EN BASE DE DATOS Se rellenarán los siguientes tags: a. Código de Estado: b. CodigoEstadoSecundario: <no se rellena>. c. Literal Error: Titular no identificado. d. Código de etorno: e. Descripcion de Error: Titular no identificado+<nif_buscado>. Página 23 de 24

24 CONTACTOS Para cualquier duda, incidencia o sugerencia por favor diríjase a: CAT Centro de Atención Telefónica de la AEAT Teléfono Correo electrónico: catentidades@correo.aeat.es Centro de Atención a Integradores y Desarrolladores (CAID) del Ministerio de Hacienda y Administraciones Públicas Dirección electrónica: Página 24 de 24