Integración de Servicios Web en Organismos y Sedes Electrónicas. Incluye Versión 2 del Servicio Web para Organismos

Transcripción

1 Servicio compartido de Gestión de Notificaciones Integración de Servicios Web en Organismos y Sedes Electrónicas Incluye Versión 2 del Servicio Web para Organismos ATENCIÓN: Para la comprensión de este documento, debe consultarse el Glosario de Términos y Especificaciones Notific@" que dispone de todos los términos y abreviaturas utilizados, así como su definición y en algunos casos, las especificaciones técnico-funcionales asociadas a los mismos. Manual Notific@ Versión 3.00 Fecha de revisión 28/07/2017 Realizado por 1

2 Tabla de contenido PLATAFORMA 1 INTEGRACIÓN DE SERVICIOS WEB EN ORGANISMOS Y SEDES ELECTRÓNICAS... 1 INCLUYE VERSIÓN 2 DEL SERVICIO WEB PARA ORGANISMOS REGISTRO DE CAMBIOS OBJETIVO INFORMACIÓN GENERAL DE APLICACIÓN A LA INTEGRACIÓN CON NOTIFIC@ MEDIANTE SERVICIO WEB CONDICIONES ESPECIALES EN EL PROCEDIMIENTO DE INTEGRACIÓN CON NOTIFIC@ A TRAVÉS DE LOS SERVICIOS WEB REQUISITOS DE LOS ENVÍOS SERVICIOS WEB PARA ORGANISMOS VERSIÓN 2.0 DE LOS SERVICIOS WEB PARA ORGANISMOS (EN DESARROLLO) Descripción de entornos para Organismos Servicio web de Notific@ para Organismos Método infoenvio2() Método getcies() VERSIÓN 1.0 DE LOS SERVICIOS WEB PARA ORGANISMOS (DEPRECIADA, A EXTINGUIR) Descripción de entornos para Organismos Servicio web de Notific@, como parte servidora, para Organismos Método altaenvio() Método infoenvio() Método consultaestado() Método consultadatadoenvio() Método consultacertificacionenvio() Método consultaorganismosactivos() Método consultacies() SERVICIO ADVISER EN ORGANISMOS PARA NOTIFIC@ MÉTODO DATADOORGANISMO() MÉTODO CERTIFICACIONORGANISMO() SERVICIOS WEB PARA SEDES ELECTRÓNICAS DESCRIPCIÓN DE ENTORNOS PARA SEDES ELECTRÓNICAS SERVICIO WEB DE NOTIFIC@, COMO PARTE SERVIDORA, PARA SEDES ELECTRÓNICAS Método getenvios() Método getenvios2() Método getenviosagrupados() Método infoenvio() Método certificacionsede() Método getcertificacion() Método comunicacionsede()

3 ANEXO I SW PARA ORGANISMOS - PRUEBAS DE INTEGRACIÓN PRUEBAS DE EMISIÓN CORRECTAS. (A ADAPTAR POR CADA ORGANISMO EMISOR) PRUEBAS DE EMISIÓN ERRÓNEAS PRUEBA DE CONSULTA DE DATADO CORRECTAS (VERSIÓN 1) PRUEBAS DE CONSULTA DE DATADO ERRÓNEAS (VERSIÓN 1) PRUEBAS DE CONSULTA DE CERTIFICACIÓN - CORRECTAS (VERSIÓN 1) PRUEBAS DE CONSULTA DE CERTIFICACIÓN - ERRÓNEAS (VERSIÓN 1) PRUEBA DE CONSULTA INFORAMACION ENVIO CORRECTAS (VERSIÓN 2) PRUEBA DE CONSULTA INFORAMACION ENVIO ERRÓNEAS (VERSIÓN 2) ANEXO II SW PARA ORGANISMOS CÓDIGOS DE RESPUESTA ANEXO III SW PARA ORGANISMOS - EJEMPLOS PARTE SERVIDORA ANEXO IV SERVICIO ADVISER CÓDIGOS DE RESPUESTA ANEXO V SW PARA ORGANISMOS EJEMPLOS DEL ADVISER ANEXO VI - SW PARA SEDES ELECTRÓNICAS - EJEMPLOS PARTE SERVIDORA ANEXO VII ESTADOS DE UN ENVÍO ANEXO VIII CAMPOS ESPECÍFICOS PARA TIPO POSTAL

4 1. Registro de cambios Fecha Versión Descripción 29/06/ Se incluye la nueva especificación de los servicios web 2.0 para organismos, manteniéndose la definición del resto de servicios web. 4

5 2. Objetivo Este documento describe los Servicios Web que pone a disposición de los Organismos Emisores para el uso automatizado del servicio compartido y la integración de sus Sistemas de Información. Se incluyen las modificaciones en los servicios web Servicios Web para Organismos liberadas en el segundo semestre de Por tanto no se modifica la definición de los Servicios Web de Sedes Electrónicas y del Servicio Adviser, cuya especificación se puede consultar en el siguiente documento. En este está organizado en tres secciones: Servicios Web para Organismos. Se incluye la nueva especificación de los servicios, junto con la preexistente y que se considera depreciada. Servicio Adviser en Organismos Servicios Web para Sedes Electrónicas. Finalmente, se dispone de una sección de Anexos que incluye información complementaria y detallada como: definición de pruebas de integración, resumen de códigos de respuesta, ejemplos de consultas, etc 2.1. Información general de aplicación a la integración con notific@ mediante Servicio Web. La integración mediante los Servicios Web, es solo una de las maneras en que los Organismos emisores pueden establecer su comunicación con Notific@. Para la integración a través de los Servicios Web, la parte más importante que deben realizar los Organismos es la adecuación de sus Sistemas de Información para que sean capaces de comunicarse con los Servicios Web Notific@. De forma alternativa y/o adicional, los Organismos tienen a su disposición una aplicación Web que permite, la integración con Notific@ sin hacer uso de los Servicios Web, así como otra serie de funcionalidades complementarias al uso de los mismos. Para un mayor conocimiento de esta aplicación consultar el Manual de usuario sobre esta aplicación que forma parte de la documentación técnica publicada en el CTT. 5

6 3. Condiciones especiales en el procedimiento de integración con a través de los Servicios Web Para conocer el procedimiento general de integración con se deberá consultar el documento Guía de Integración con para el responsable técnico y uso del servicio CAID. De manera adicional a lo explicado en dicho documento, se proporcionan aquí indicaciones técnicas de especial importancia: a. El API KEY facilitado durante el alta en Notific@ deberá ser incluida en la cabecera del Servicio SOAP de las peticiones. Intercambio de la parte pública de los certificados (CAs) que permitan la comunicación entre sistemas Implementación por parte del Organismo o Sede de los módulos (en modo cliente) necesarios para invocar los Servicios Web de Notific@. b. Todas las peticiones que se realizan a Notific@ deben especificar el Content- Length en su cabecera. c. Del mismo modo, todas las peticiones que se realizan a Notific@ deben añadir la cabecera Expect:100-continue. d. No se admite el envío de peticiones por fragmentos (chunks), sino que se debe mandar todo en un único bloque que incluya el tamaño. El chunking debe estar deshabilitado. e. Las comunicaciones con Notific@ (excepto para el servicio Adviser) deben realizarse utilizando el protocolo TLS 1.0. No está soportado el uso de SSLv3 o versiones inferiores. f. Si los Organismos Emisores van a implementar el Servicio Adviser deberá emplearse el puerto 443. Para el entorno de PRE se permite utilizar el puerto 80. g. La URL del servicio Adviser del Organismo Emisor no puede basarse en una dirección IP sino en un nombre de dominio. En el entorno de producción es obligatorio que la dirección DNS de las máquinas que contienen el Adviser esté PUBLICADA EN LA REDSARA. En el entorno de pruebas de integración es recomendable que también sea así, pero se admite también solicitar por incidencia la inclusión de una excepción en el archivo de hosts. h. Elaboración de pruebas en entorno de Preproducción. Antes de pasar a producción es necesario realizar pruebas que permitan acreditar el correcto funcionamiento y que se pueden basar en las pruebas definidas en el Anexo I SW para Organismos - Pruebas de Integración. Debe considerarse que mientras que las pruebas en Preproducción son gratuitas, si se realiza alguna 6

7 prueba puntual en producción puede tener asociados los costes que imputen los Agentes Colaboradores. 4. Requisitos de los envíos Para establecer la integración con los Envíos deben incorporar una cierta información y cumplir unas determinadas condiciones y requisitos técnicos-funcionales. Para conocer en detalle estas condiciones deberá consultarse el Glosario de términos y especificaciones Notific@. No obstante, se incorporan aquí algunos aspectos generales, a modo de ejemplo Requisitos funcionales de los envíos: Los envíos deberán contener cierta información que debe ser proporcionada por el Responsable Funcional y aportada a Notific@, bien en el propio cuerpo del envío, o por otros medios que, en su caso, se establezcan al efecto. Para consultar los detalles de esta información se deberá consultar la Guía para la integración con Notific@ para los Responsables Funcionales que se encuentra publicada en el CTT. Algunos requisitos funcionales, que se mencionan a modo de ejemplo, son que el Organismo Pagador haya suscrito los necesarios contratos con el/los CIEs que desee utilizar y con el correspondiente operador postal y disponga de las referencias de dichos contratos y las fechas de finalización de los mismos. Requisitos técnicos de los envíos: Los envíos deberán cumplir ciertos requisitos técnicos básicos, bien asociados a su propia condición, o bien asociados a la vía de puesta a disposición que el Organismo Emisor elija. Para conocer el detalle de esta especificación consultar el Glosario de Términos y Especificaciones y en su caso, la Guía para la integración con Notific@ para los Responsables Técnicos y el documento Notific@ flujo detallado, entre otros, que se encuentran publicados en el CTT. 5. Servicios Web para Organismos. La finalidad de los Servicios Web para Organismos es proporcionar a los Organismos Emisores herramientas para: Que puedan dar de alta sus envíos. Que puedan recabar de Notific@, bajo petición, información relativa a sus envíos (estado, metadatos, certificaciones, etc.) 7

8 En los Servicios Web para Organismos, la aplicación actúa con rol servidor y los Sistemas de Información de los Organismos Emisores como clientes. Cuando un Organismo Emisor desee integrarse con Notific@ utilizando Servicios Web deberá implementar obligatoriamente los servicios Web para Organismos y, opcionalmente, los servicios web para Sedes Electrónicas y de Adviser. A continuación se muestran dos definiciones del servicio Web. La Versión 2.0, liberada en el segundo semestre de Está en fase de desarrollo (Julio de 2017) y se espera que esté disponible en Servicios Estables en verano de La Versión 1.0, depreciada y a extinguir, que dejará de estar operativa de conformidad con el plan de compatibilidad de versiones Versión 2.0 de los Servicios Web para Organismos (En desarrollo) Descripción de entornos para Organismos. En el momento en que el servicio se encuentre desarrollado y operativo, éste se pondrá a disposición de los Organismos Emisores en el entorno de Servicios Estables (entorno Preproductivo) para acometer las correspondientes integraciones, desarrollo de pruebas y depuración en las siguientes URL: (No disponible actualmente) o Se corresponde con la IP Del mismo modo se recuerda que para determinadas funcionalidades (como es el ejemplo de la gestión de contratos del CIE o del Operador Postal) puede ser necesario acceder a la Aplicación Web de Notific@, disponible en: o Se corresponde con la IP De igual forma, el Servicio Web se pondrá a disposición de los Organismos Emisores en el entorno de Producción en: (No disponible actualmente) o Se corresponde con la IP De igual manera se recuerda que para dicho entorno la URL de acceso a la Aplicación Web de Notific@ es: 8

9 o Se corresponde con la IP Nota Antes de abrir incidencias por problemas de comunicaciones deben comprobar que su conexión con la Red SARA es correcta. Para ello deben contactar con el equipo de soporte de la Red SARA para su organismo: Para la AGE o ml Para otros organismos (CCAA, EELL ) o html Servicio web de Notific@ para Organismos. Notific@ tiene implementado un servicio web, como parte servidora, que ofrece la creación, consulta y monitorización de la entrega de una notificación, y que incluye los siguientes métodos: Método altaremesaenvios() infoenvio2() Descripción Método que permite el dar de alta una remesa, es decir, un conjunto de 1 o varios envíos que comparten las mismas características y que difieren únicamente en quiénes son los titulares y destinatarios. Método para consultar la información detallada de un envío específico. A continuación se puede consultar el detalle de cada uno de los parámetros de entrada, así como el de las respuestas generadas. Notas La especificación técnica de los Servicios Web, se podrá consultar en la siguiente url: (No disponible actualmente) Dado que el funcionamiento de los datados y certificados no siempre es trivial, 9

10 principalmente cuando se va a hacer uso del servicio postal, se ha publicado el siguiente documento para clarificar conceptos: Validez%20de%20notificaciones%20por%20distintos%20medios%20- %20Datados%20y%20Certificaciones.ppsx?idIniciativa=706&idElemento= Método altaremesaenvios(). El método altaremesaenvios() es un método del servicio web de Notific@ para Organismos a través se permite la incorporación a la plataforma Notific@ de un conjunto de 1 o N envíos para su gestión y puesta a disposición a través de las distintas vías de salida, conforme a las opciones que se indiquen. Todos los envíos de una misma remesa comparten los mismos datos (vías de salida, información de Organismos Emisores, documento a notificar, etc.) y únicamente difieren el Titular y/o los Destinatarios de cada envío Petición El método altaremesaenvios() debe invocarse con los siguientes parámetros: DEFINICIÓN DE OPERACIÓN altaremesaenvios() PETICIÓN CAMPO DESCRIPCIÓN TIPO Ob LON COMENTARIOS codigoorganis moemisor DIR3 del Organismo Emisor del envío S 9 tipoenvio Entero que indica si el envío es comunicación o notificación Entero S 1 Valores posibles: 1 Comunicación 2 Notificación concepto Concepto del envío S 255 En caso que se envíe a través de un CIE sólo se imprimirán los primeros 50. descripcion Descripción detallada del envío N 1000 fechaenviopro gramado Fecha en la que el envío se pondrá a disposición para su comparecencia Date N Varia ble Formato YYYY-MM-DD 10

11 procedimiento Código SIA del procedimiento de la notificación N Varia ble Es obligatorio para las notificaciones, opcional para las comunicaciones documento Información del documento que se envía Tipo complejo: Documento S Envios Envíos contenidos en la Remesa Tipo complejo: Envios S opcionesrem esa Opciones de la remesa Tipo complejo: Opciones N Opciones permitidas para el envío en modo clave:valor -retardo: número de días que el envío está a disposición de comparecencia en carpeta antes de entregarlo a otras vías (CIE o DEH) -caducidad: formato YYYY-MM- DD, fecha de expiración del envío DEFINICIÓN DE OBJETO Documento contenido Contenido del documento en base64 base64binary N Se añadirá como un adjunto, definido por el estándar Soap with Attachments (SwA). Es obligatorio si no está informado enlacedocumento. No pueden enviarse ambos elementos hash Hash del documento S Sha256 del Documento adjunto o del enlazado enlacedocum ento enlace externo donde se encuentra el documento del envío N Es obligatorio si no está informado el elemento contenido. No pueden enviarse ambos elementos. Debe ser un enlace activo desde internet, accesible por el ciudadano. metadatos metadatos extra del propio documento N Parámetros extra del propio documento en formato XML, definidos por el Organismo Emisor o conforme a algún estándar. 11

12 opcionesdocu mento Opciones que tiene el documento Tipo complejo: Opciones N Opciones válidas: -normalizado: si o no. Sólo aplica a los envíos postales, para los que es obligatorio. Ver definición de normalizado en el glosario de términos. -generarcsv: si o no. Cuando el documento aportado es un PDF con firma PADES, indicar si se desea que notific@ lo sustituya por otro en el que se inserte en el PDF un Código Seguro de Verificación. DEFINICIÓN DE OBJETO Envios envio Información del destino Tipo Complejo: Envio S Puede aparecer de 1 a 100 veces DEFINICIÓN DE OBJETO Envio referenciaemi sor Referencia que establece el Organismo Emisor para el Envío. Debe ser único para ese Organismo Emisor N 20 En esta nueva versión este campo es opcional. Si no viene relleno Notific@ generará un identificador único para el envío. titular Titular de la notificación/comunicación Tipo Complejo: Persona S destinatarios Conjunto de destinatarios de la notificación/comunicación Tipo Complejo: Destinatarios N Existirá en caso de que existan destinatarios distintos del titular entregapostal Datos para la entrega Postal Tipo Complejo: EntregaPostal N entregadeh Datos para la entrega a la DEH Tipo Complejo: EntregaDEH N DEFINICIÓN DE OBJETO Destinatarios destinatario Destinatario de la notificación/comunicación Tipo Complejo: Persona S Puede aparecer de 0 a 100 veces. Si aparece 0 veces se asume que Titular = Destinatario. Cuando un envío va por salida postal únicamente se imprime en el sobre el nombre del primer destinatario, junto con la dirección postal. DEFINICIÓN DE OBJETO Persona 12

13 nif NIF de la persona física / jurídica S 9 nombre Nombre de la persona física N Obligatorio en caso de personas físicas apellidos Apellidos de la persona física N Obligatorio en caso de personas físicas razonsocial Razón Social de la persona jurísica N Obilgatorio en caso de personas jurídicas de la persona que recibe la notificación/comunicación N Desde Notifica se recomienda la introducción de este campo para todas las notificaciones electrónicas, de esta forma se podrá avisar de la existencia de la notificación por esta vía. Adicionalmente si como resultado del envío se crea un buzón de DEH (si es obligado a DEH y no está previamente creado el buzón), la dirección de correo electrónico quedará fijada como dirección de correo de la DEH asociada. telefono Teléfono de la persona que recibe la notificación/comunicación N Actualmente no se le da uso para el envío de SMS informando de que existe una nueva notificación o comunicación. Estando en estudio su posible reimplantación en el futuro. codigodestino DIR3 o DIRe de la entidad que recibe el envío N 9 No es obligatorio en ningún caso, ni cuando el envío se dirige a personas físicas, ni a personas jurídicas del sector público (DIR3) o del sector privado (DIRe). Los códigos DIRe (relativos al sector privado) no están disponibles actualmente. DEFINICIÓN DE OBJETO EntregaPostal organismopag adorpostal Datos del organismo que asume los costes postales Tipo Complejo: OrganismoPa gadorpostal N Introducir en caso de que no haya información en la web de Notifica acerca del pagador postal. También puede introducirse para sobreescribir la información del pagador para el envío que se remite 13

14 organismopag adorcie Datos del organismo que asume los costes del CIE Tipo Complejo: OrganismoPa gadorcie N Introducir en caso de que no haya información en la web de Notifica acerca del pagador del CIE. También puede introducirse para sobreescribir la información del pagador para el envío que se remite tipodomicilio Valor numérico que define el tipo de domicilio para la entrega postal Enumerado S Valores posibles 1: Nacional Normalizado 2: Extranjero Normalizado 3: Apartado de Correos Normalizado 4: Sin Normalizar tipovia Tipo de vía para entregas postales N 5 Obligatorio si tipodomicilio = Nacional Normalizado. Ver Anexo VIII nombrevia Nombre de la vía para entregas postales N 50 Obligatorio si tipodomicilio = Nacional Normalizado o Extranjero Normalizado numerocasa Número de la casa para entregas postales N 5 Obligatorio si tipodomicilio = Nacional Normalizado a menos que se consigne puntokilometrico. puntokilometri co Punto kilométrico para entregas postales N 5 Obligatorio si tipodomicilio = Nacional Normalizado a menos que se consigne numerocasa portal Portal de la casa para entregas postales N 3 escalera Escalera de la casa para entregas postales N 3 planta Planta de la casa para entregas postales N 3 bloque Bloque de la casa para entregas postales N 3 complemento Información extra acerca de la casa para la entrega postal N 40 calificadornum ero Tipo de numeración de la dirección N 3 Campo libre para indicar información adicional sobre la numeración (por ejemplo bis, tri, etc.) 14

15 codigopostal Código Postal de la casa para entregas postales S 10 Obligatorio para cualquier valor de tipodomicilio. Para envíos internacionales en países sin código postal se puede consignar apartadocorre os Apartado de Correos para entregas postales N 10 Obligatorio cuando tipodomicilio = Apartado de Correos Normalizado municipio Código INE del municipio donde se entrega el envío N 6 Debe contener el dígito de control. Obligatorio para envíos de los tipos Nacional Normalizado y Apartado de Correos Normalizado provincia Código de provincia donde se entrega el envío N 2 Obligatorio para envíos de los tipos Nacional Normalizado, Extranjero Normalizado y Apartado de Correos Normalizado pais Código ISO3166 de 2 del país donde se entrega el envío N 2 Obligatorio cuando tipodomicilio =Extranjero Normalizado poblacion Población donde se entrega el envío N 30 Obligatorio para envíos de los tipos Nacional Normalizado, Extranjero Normalizado y Apartado de Correos Normalizado linea1 Linea 1 de la dirección de entrega del envío sin normalizar N 50 Obligatorio cuando tipodomicilio = Sin Normalizar linea2 Línea 2 de la dirección de entrega del envío sin normalizar N 50 Obligatorio cuando tipodomicilio = Sin Normalizar opcionescie Opciones de entrega postal Tipo complejo: Opciones N En formato clave:valor -cie: identificador del CIE en Notifica para seleccionarlo para el envío -formatosobre: cadena de para el formato del sobre (americano, C5 ) -formatohoja: cadena de para el formato de hoja (A4,A5 ) DEFINICIÓN DE OBJETO OrganismoPagadorPostal codigodir3po stal Código DIR3 del pagador de los costes postales S 9 15

16 numcontratop ostal Número de contrato con el operador postal S codclientefac turacionpostal Código de cliente de facturación con el operador postal S fechavigencia Postal Fecha de vigencia del contrato con el operador postal Date S DEFINICIÓN DE OBJETO OrganismoPagadorCIE codigodir3ci E Código DIR3 del pagador de los costes de impresión y ensobrado S 9 fechavigencia CIE Fecha de vigencia del contrato con el CIE Date S DEFINICIÓN DE OBJETO EntregaDEH obligado Booleano para indicar si el envío es obligado o voluntario Boolean S valores adminitos: true o false. Si no es obligado se comprueba si el Titular está suscrito voluntariamente al procedimiento, en cuyo caso se podrá notificar a través de la DEH. codigoprocedi miento Código del procedimiento en la DEH para envíos a voluntarios N El código de prodedimiento en la DEH se recomienda que coincida con el código en SIA DEFINICIÓN DE OBJETO Opciones opcion Tipo simple con la estructura Tipo complejo: opción N Puede aparecer N veces. Un ejemplo sería <alt:opcion tipo="normalizado">no</alt:opcio n> Respuesta RESPUESTA CAMPO DESCRIPCIÓN TIPO Ob LON COMENTARIOS codigorespue sta Código para indicar el OK o el ERROR S 000 para envíos correctos, para errores consultar tabla en el anexo descripcionre spuesta Descripción del código de respuesta S OK para envíos correctos, consultar tabla para el resto 16

17 codigoorganis moemisor DIR3 del organismo que realiza el envío N 9 No viene informado en caso de error fechacreacion Fecha de creación del envío DateTime N No viene informado en caso de error resultadoenvio s Array de identificadores de envío junto con el NIF del Titular ResultadoEnv ios N No viene informado en caso de error DEFINICIÓN DE OBJETO ResultadoEnvios resultadoenvio s Contendrá tantas entradas como envíos tenga la remesa ResultadoEnv io S DEFINICIÓN DE OBJETO ResultadoEnvio Identificador Identificador del envío S Identificador único del envío que deberá usarse en las sucesivas llamadas que se hagan en referencia al envío niftitular NIF del Titular N 9 Vendrá informado siempre que el Organismo Emisor lo haya indicado. NOTAS ACLARATORIAS: Envío únicamente a Carpeta / Sede electrónica Si desea que el envío esté disponible únicamente en la Carpeta Ciudadana y, en su caso, sede electrónica, se deben dejar los campos EntregaPostal y EntregaDEH sin consignar, y se deberá establecer fecha de caducidad a través del campo opcionesremesa. Envío DEH voluntario + Carpeta Ciudadana / Sede electrónica De la misma manera la caducidad también es obligatoria cuando un envío se configura como DEH no obligatoria + Carpeta Ciudadana, ya que en caso que el ciudadano no esté suscrito el envío acabará únicamente en Carpeta Ciudadana. Uso de la fecha de caducidad cuando se está integrando una sede electrónica Con respecto a la caducidad, en caso que se esté integrando una sede electrónica del organismo, y que se desee que ésta gestione la caducidad de las notificaciones en lugar de Notific@, se deberá establecer en Notific@ un periodo de caducidad superior al manejado por la sede, de modo que se produzca la caducidad primero en la sede y se informe inmediatamente a Notific@ del cambio de estado del envío, a través de los servicios web para sedes electrónicas. 17

18 Importancia de consignar el campo Estadísticamente se ha confirmado que la tasa de comparecencia de notificaciones por medios electrónicos es muy superior cuando se consigna el campo . Esto es especialmente importante cuando los destinatarios están obligados a recibir notificaciones electrónicas. Es deseable que el Organismo Emisor rellene el campo a partir de la información contenida en un registro de contactos Método infoenvio2() El método infoenvio2() es un método del servicio web de Notific@ para Organismos a través del cual se permite consultar información relativa a: Los parámetros de configuración del envío con los que éste se dio de alta. El estado actual del envío. Los datados asociados al envío. Las certificaciones, si las hubiera, asociadas al envío Petición DEFINICIÓN DE OPERACIÓN infoenviov2() PETICIÓN CAMPO DESCRIPCIÓN TIPO Ob LON COMENTARIOS identificador Identificador público del envío S Debe ser el mismo identificador que corresponde al envío y que se devolvió en el método altaremesaenvios() Respuesta RESPUESTA CAMPO DESCRIPCIÓN TIPO Ob LON COMENTARIOS identificador Identificador público del envío S Identificador que corresponde al envío y que se devolvió en el método altaremesaenvios() 18

19 estado Código de estado en el que se encuentra el envío S Valores posibles (ver anexo VII): pendiente_envio enviado_ci notificada extraviada rehusada desconocido fallecido ausente direccion_incorrecta sin_informacion error pendiente_sede enviado_deh leida envio_programado pendiente_cie pendiente_deh entregado_op expirada concepto Concepto del envío S 255 descripcion Descripción detallada del envío N 1000 codigoorgani smoemisor Datos del Organismo Emisor del envío Tipo Complejo: CodigoDIR S codigoorgani smoraiz Datos del Organismo Raíz correspondiente al Organismo Emisor del envío Tipo Complejo: CodigoDIR N No viene informado en caso de que coincida con el codigoorganismoremisor. codigodestino Datos de la entidad que recibe el envío Tipo Complejo: CodigoDIR N tipoenvio Entero que indica si el envío es comunicación o notificación Entero S 1 Valores posibles: 1 Comunicación 2 Notificación fechacreacio n Fecha de creación del envío DateTime S Varia ble Formato YYYY-MM-DDTHH:ii:ss 19

20 fechapuestad isposición Fecha en la que el envío se puso a disposición para su comparecencia Date S Varia ble Formato YYYY-MM-DD. Se corresponde con: La fecha de envío programado, si se hubiera especificado si ésta no hubiera llegado aún. La fecha de alta efectiva en Notific@ en el resto de casos. fechacaducid ad Fecha en la que el envío expira Date N Varia ble Formato YYYY-MM-DD retardo Número de días en los que el envío permanece disponible para comparecencia en CC antes de entregarlo por otras vías Integer N procedimiento Datos del procedimiento SIA Tipo Complejo: Procedimient o N Obligatorio para notificaciones documento Info del documento de la notificación / comunicación Tipo Complejo: Documento S referenciaemi sor Identificador del envío que es único para ese Organismo Emisor. S 20 En caso que se informase al hacer el alta del envío, coincidirá con el número que se estableció. En caso contrario se informará el número que haya asignado Notific@. titular Titular de la notificación/comunicación Tipo Complejo: Persona S destinatarios Conjunto de destinatarios de la notificación/comunicación Tipo Complejo: Destinatario N Existirá en caso de que existan destinatarios distintos del titular entregapostal Datos para la entrega Postal Tipo Complejo: EntregaPostal N entregadeh Datos para la entrega a la DEH Tipo Complejo: EntregaDEH N datados Información de los datados Tipo Complejo: Datados S 20

21 certificacion Información de la certificación Tipo Complejo: Certificacion N opcionesenvi o Opciones del envío Tipo complejo: Opciones N Opciones permitidas para el envío en modo clave:valor -retardo: número de días que el envío está a disposición de comparecencia en carpeta antes de entregarlo a otras vías (CIE o DEH) -caducidad: formato YYYY-MM- DD, fecha de expiración del envío DEFINICIÓN DE OBJETO Destinatarios destinatario Destinatario de la notificación/comunicación Tipo Complejo: Persona S Puede aparecer de 1 a 100 veces DEFINICIÓN DE OBJETO Persona nif NIF de la persona física / jurídica S 9 nombre Nombre de la persona física N Obligatorio en caso de personas físicas apellidos Apellidos de la persona física N Obligatorio en caso de personas físicas razonsocial Razón Social de la persona jurísica N Obilgatorio en caso de personas jurídicas de la persona que recibe la notificación/comunicación N Desde Notifica se recomienda la introducción de este campo para todas las notificaciones electrónicas, de esta forma se podrá avisar de la existencia de la notificación por esta vía. telefono Teléfono de la persona que recibe la notificación/comunicación N Actualmente no se le da uso para el envío de SMS informando de que existe una nueva notificación o comunicación. Estando en estudio su posible reimplantación en el futuro. DEFINICIÓN DE OBJETO EntregaPostal 21

22 organismopa gadorpostal Datos del organismo que asume los costes postales Tipo Complejo: OrganismoPa gadorpostal N Introducir en caso de que no haya información en la web de Notifica acerca del pagador postal. También puede introducirse para sobreescribir la información del pagador para el envío que se remite organismopa gadorcie Datos del organismo que asume los costes del CIE Tipo Complejo: OrganismoPa gadorcie N Introducir en caso de que no haya información en la web de Notifica acerca del pagador del CIE. También puede introducirse para sobreescribir la información del pagador para el envío que se remite tipodomicilio Valor numérico que define el tipo de domicilio para la entrega postal Enumerado S Valores posibles 1: Nacional Normalizado 2: Extranjero Normalizado 3: Apartado de Correos Normalizado 4: Sin Normalizar tipovia Tipo de vía para entregas postales N 5 Obligatorio si tipodomicilio = Nacional Normalizado. Consultar Anexo VIII nombrevia Nombre de la vía para entregas postales N 50 Obligatorio si tipodomicilio = Nacional Normalizado o Extranjero Normalizado numerocasa Número de la casa para entregas postales N 5 Obligatorio si tipodomicilio = Nacional Normalizado a menos que se consigne puntokilometrico. puntokilometr ico Punto kilométrico para entregas postales N 5 Obligatorio si tipodomicilio = Nacional Normalizado a menos que se consigne numerocasa portal Portal de la casa para entregas postales N 3 escalera Escalera de la casa para entregas postales N 3 planta Planta de la casa para entregas postales N 3 bloque Bloque de la casa para entregas postales N 3 complemento Información extra acerca de la casa para la entrega postal N 40 22

23 calificadornu mero Tipo de numeración de la dirección N 3 Campo libre para indicar información adicional sobre la numeración (por ejemplo bis, tri, etc.) codigopostal Código Postal de la casa para entregas postales S 10 Obligatorio para cualquier valor de tipodomicilio. Para envíos internacionales en países sin código postal se puede consignar apartadocorr eos Apartado de Correos para entregas postales N 10 Obligatorio cuando tipodomicilio = Apartado de Correos Normalizado municipio Código INE del municipio donde se entrega el envío N 6 Debe contener el dígito de control. Obligatorio para envíos de los tipos Nacional Normalizado y Apartado de Correos Normalizado provincia Código de provincia donde se entrega el envío N 2 Obligatorio para envíos de los tipos Nacional Normalizado, Extranjero Normalizado y Apartado de Correos Normalizado pais Código ISO3166 de 2 del país donde se entrega el envío N 2 Obligatorio cuando tipodomicilio =Extranjero Normalizado poblacion Población donde se entrega el envío N 30 Obligatorio para envíos de los tipos Nacional Normalizado, Extranjero Normalizado y Apartado de Correos Normalizado linea1 Linea 1 de la dirección de entrega del envío sin normalizar N 50 Obligatorio cuando tipodomicilio = Sin Normalizar linea2 Línea 2 de la dirección de entrega del envío sin normalizar N 50 Obligatorio cuando tipodomicilio = Sin Normalizar opcionescie Opciones de entrega postal Tipo complejo: Opciones N En formato clave:valor -cie: identiicador del CIE en Notifica para seleccionarlo para el envío -formatosobre: cadena de para el formato del sobre (americano, C5 ) -formatohoja: cadena de para el formato de hoja (A4,A5 ) DEFINICIÓN DE OBJETO OrganismoPagadorPostal 23

24 codigodir3p ostal Código DIR3 del pagador de los costes postales S 9 numcontrato Postal Número de contrato con el operador postal S codclientefa cturacionpost al Código de cliente de facturación con el operador postal S fechavigencia Postal Fecha de vigencia del contrato con el operador postal Date S DEFINICIÓN DE OBJETO OrganismoPagadorCIE codigodir3ci E Código DIR3 del pagador de los costes de impresión y ensobrado S 9 fechavigencia CIE Fecha de vigencia del contrato con el CIE Date S DEFINICIÓN DE OBJETO EntregaDEH obligado Booleano para indicar si el envío es obligado o voluntario Boolean S valores adminitos: true o false codigoprocedi miento Código del procedimiento en la DEH para envíos a voluntarios N El código de prodedimiento en la DEH se recomienda que coincida con el código en SIA DEFINICIÓN DE OBJETO CodigoDIR codigo Código DIR3 o DIRe de la entidad S 9 descripcionco digodir Descripción del código DIR S DEFINICIÓN DE OBJETO Procedimiento codigosia Código SIA del procedimiento de la notificación S DescripcionSI A Descripción del procedimiento S DEFINICIÓN DE OBJETO Documento 24

25 contenido Contenido del documento en base64 base64binary N Se añadirá como un adjunto, definido por el estándar Soap with Attachments (SwA). Es obligatorio en caso de no existir enlacedocumento, no pueden enviarse ambos elementos hash Hash del documento S Sha256 del Documento adjunto o del enlazado enlacedocum ento enlace externo donde se encuentra el documento del envío N Es obligatorio en caso de no existir el elemento contenido, no pueden coexistir ambos elementos en la misma petición. Debe ser un enlace activo desde internet metadatos metadatos extra del propio documento N Parámetros extra del propio documento en formato XML csv CSV del documento mime tipo MIME del documento N N size Tamaño del documento Integer N En bytes opcionesdocu mento Opciones que tiene el documento Tipo complejo: Opciones N Opciones válidas: -normalizado: si o no DEFINICIÓN DE OBJETO Datados datado Info de un datado Tipo complejo: Datado S de 1 a 100 repeticiones DEFINICIÓN DE OBJETO Datado fecha Fecha del datado DateTime S resultado Resultado del datado origen Origen del datado S S Devolverá uno de los códigos de estado mencionados anteriormente Origen del datado: - correos_cie (Postal) - electronico (DEH) - carpeta - sede - ema - funcionario_habilitado 25

26 nombrerecep tor Nombre de la persona que origina el datado N Para estados notificada, rehusada, leida. nifreceptor NIF de la persona que origina el datado N descripcioner ror Descripción detallada cuando el datado es error N DEFINICIÓN DE OBJETO Certificacion contenido Contenido del certificación en base64 base64binary S Se añadirá como un adjunto, definido por el estándar Soap with Attachments (SwA). hash Hash del documento S Sha256 del Documento adjunto o del enlazado fechacertifica cion Fecha en la que se genera la certificación DateTime S origen Origen de la certificación S Origen de la certificación: - correos_cie (Postal) - electronico (DEH) - carpeta - sede - ema - funcionario_habilitado metadatos metadatos extra del propio documento N Parámetros extra del propio documento en formato XML csv CSV del documento mime tipo MIME del documento N S size Tamaño del documento Integer S En bytes opcionescerti ficacion Opciones que tiene el documento Tipo complejo: Opciones N DEFINICIÓN DE OBJETO Opciones opcion Tipo simple con la estructura Tipo complejo: opción N Puede aparecer N veces. Un ejemplo sería <alt:opcion tipo="normalizado">no</alt:opcio n> 26

27 Método getcies() El método getcies() es un método del servicio web de para Organismos a través del cual se permite obtener un listado de los CIEs disponibles para un Organismo Emisor, conforme a la configuración de Agentes Colaboradores que haya podido establecer éste a través de la Aplicación Web de Notific@ Petición DEFINICIÓN DE OPERACIÓN getcies() PETICIÓN CAMPO DESCRIPCIÓN TIPO Ob LON COMENTARIOS organismoemi sor DIR3 del Organismo Emisor para el que se hace la consulta S Respuesta RESPUESTA CAMPO DESCRIPCIÓN TIPO Ob LON COMENTARIOS cies Array de Cies disponibles Tipo complejo: Cie S codigorespu esta Código para indicar el OK o el ERROR S 000 para envíos correctos, para errores consultar tabla en el anexo descripcionre spuesta Descripción del código de respuesta S OK para envíos correctos, consultar tabla para el resto DEFINICIÓN DE OBJETO Opciones Id Identificador del CIE Entero S centroimpresi on Nombre del CIE S fechavigencia Fecha de vigencia (hasta) del contrato S Formato YYYY-MM-DDTHH:ii:ss codigounidad Relacionada Código DIR3 de la unidad relacionada con el CIE (Organismo Pagador) S 9 27

28 nombreunida drelacionada Nombre de la unidad relacionada con el CIE (Organismo Pagador) S orden Orden de preferencia de este CIE Entero S 5.2. Versión 1.0 de los Servicios Web para Organismos (Depreciada, a extinguir) Descripción de entornos para Organismos. Con el objetivo de cumplir con el Procedimiento de Integración con el Servicio Web, Notific@ pone a disposición los siguientes recursos para la integración en el entorno de Pruebas/Preproducción: o URL del Punto Final del Servicio Web (EndPoint): Se corresponde con la IP o URL de acceso a la Aplicación Web: Se corresponde con la IP De igual forma, y con el objetivo de cumplir con las pruebas previstas en el Procedimiento de Integración con el Servicio Web, Notific@ pone a disposición los siguientes recursos para la integración en el entorno de Producción: o URL del Punto Final del Servicio Web (EndPoint): Se corresponde con la IP o URL de acceso a la Aplicación Web: Se corresponde con la IP Nota Antes de abrir incidencias por problemas de comunicaciones deben comprobar que su conexión con la Red SARA es correcta. Para ello deben contactar con el equipo de soporte de la Red SARA para su organismo: Para la AGE o 28

29 ml Para otros organismos (CCAA, EELL ) o html Servicio web de Notific@, como parte servidora, para Organismos. Notific@ tiene implementado un servicio web, como parte servidora, que ofrece la creación, consulta y monitorización de la entrega de una notificación, y que incluye los siguientes métodos: altaenvio() Método Descripción Método que permite el alta de un envío. infoenvio() Método para consultar la información detallada de un envío específico. consultaestado() Método que permite la consulta del Estado de un envío. consultadatadoenvio() Método que permite la consulta del Datado de un envío. consultacertificacionenvio() Método que permite la consulta de la certificación de un envío. consultaorganismosactivos() Método que permite la consulta de los Organismos Activos. A continuación se puede consultar el detalle de cada uno de los parámetros de entrada, así como el de las respuestas generadas. Notas La especificación técnica de los Servicios Web, se puede consultar en la siguiente url: Dado que el funcionamiento de los datados y certificados no siempre es trivial, principalmente cuando se va a hacer uso del servicio postal, se ha publicado el siguiente documento para clarificar conceptos: 29

30 Validez%20de%20notificaciones%20por%20distintos%20medios%20- %20Datados%20y%20Certificaciones.ppsx?idIniciativa=706&idElemento= Método altaenvio(). El método altaenvio() es un módulo del servicio web de como parte servidora, que permite el envío de los datos necesarios para el alta de un envío: comunicación o notificación. Parámetros: El método altaenvio() debe invocarse con los siguientes parámetros: Campo Tipo Descripción organismo_emisor::codigo_dir3 string Obligatorio. Código correspondiente al DIR3. organismo_emisor::nombre string Opcional. Nombre de la Entidad Emisora. organismo_pagador_correos:: codigo_dir3 string Campo aún válido pero depreciado. Sólo aplica al envío postal a través del Operador Postal Correos. Campo Opcional. Código DIR3 del organismo que realizará el pago del servicio de entrega postal. No se recomienda su uso, y utilizar e orden de preferencia según se ha establecido en la Aplicación Web, modificable a través del campo cie de domicilio. organismo_pagador_correos:: numero_contrato_correos string Campo aún válido pero depreciado. Sólo aplica al envío postal a través del Operador Postal Correos. Campo Opcional. Número de contrato del organismo pagador con el operador postal. No se recomienda su uso, y utilizar e 30

31 organismo_pagador_correos:: codigo_cliente_facturacion_correos organismo_pagador_correos:: fecha_vigencia orden de preferencia según se ha establecido en la Aplicación Web, modificable a través del campo cie de domicilio. string Campo aún válido pero depreciado. Sólo aplica al envío postal a través del Operador Postal Correos. Campo Opcional. Código cliente del organismo pagador para la facturación con el operador postal. No se recomienda su uso, y utilizar e orden de preferencia según se ha establecido en la Aplicación Web, modificable a través del campo cie de domicilio. DateTim e Campo aún válido pero depreciado. Sólo aplica al envío postal a través del Operador Postal Correos. Campo Opcional. Fecha fin del contrato con el operador postal. Si está caducado no se puede tramitar el alta del servicio en Notific@. No se recomienda su uso, y utilizar e orden de preferencia según se ha establecido en la Aplicación Web, modificable a través del campo cie de domicilio. organismo_pagador_cie:: codigo_dir3 string Campo aún válido pero depreciado. Sólo aplica al envío postal a través del CIE de la AEAT. Campo Opcional. Código DIR3 del organismo que realizará el pago de costes de impresión y ensobrado. No se recomienda su uso, y utilizar e orden de preferencia según se ha establecido en la Aplicación Web, modificable a través del 31

32 campo cie de domicilio. organismo_pagador_cie:: fecha_vigencia DateTim Campo aún válido pero e depreciado a través del CIE de la AEAT. Sólo aplica al envío postal. Campo Opcional. Fecha del fin del contrato con el Centro de Impresión y Ensobrado. Si está caducado no se puede tramitar el alta del servicio en Notific@. No se recomienda su uso, y utilizar e orden de preferencia según se ha establecido en la Aplicación Web, modificable a través del campo cie de domicilio. documento::contenido string Obligatorio. Contenido del documento de la notificación codificado en base64. Puede ser un archivo ZIP o PDF. documento::hash_sha1 string Obligatorio. Codificación base64 del sha1 del contenido binario del documento. documento::normalizado string Obligatorio. En caso de que el documento reserve en la primera página el espacio en blanco necesario para introducir la ventanilla del sobre (NCC, titular, destinatario, domicilio) se debe rellenar con SI. En caso contrario debe rellenarse con NO y el CIE adjuntará una página adicional con la ventana para el ensobrado, incrementando el coste del servicio por la página impresa y por el peso adicional del servicio postal. documento::generar_csv string Obligatorio. En caso de que desee que Notific@ genere un CSV y que el documento esté firmado digitalmente se debe introducir SI, caso contrario 32

33 debe introducir NO. El CSV se introducirá en el pie del documento con la información de los firmantes para la consulta por parte del receptor de la notificación. tipo_envio string Obligatorio. Tipo de envío a dar de alta. Los valores válidos para el elemento pueden ser notificación o comunicación. fecha_envio_programado DateTim e Opcional. Fecha para realizar un envío programado. Concepto string Obligatorio. Concepto del envío que se realiza. Máximo 50. destinatarios::item:: referencia_emisor string Obligatorio y único dentro de cada organismo. Referencia interna del Emisor del envío. No pueden existir dos envíos con la misma referencia para un mismo organismo. Máximo 20. destinatarios::item::titular:: telefono string Número de teléfono. Se prevé que se realizarán avisos vía SMS del envío de la notificación/comunicación y de su disponibilidad en Carpeta Ciudadana. destinatarios:: ítem::titular:: string (Ver nota más abajo) para realizar el aviso vía correo electrónico del envío de la notificación/comunicación cuando se realiza un envío exclusivo a Carpeta Ciudadana. destinatarios:: ítem::titular:: nif string Obligatorio para envíos a Sedes Electrónicas y Carpeta Ciudadana. Debe ser el NIF/CIF/NIE del titular del envío. destinatarios:: ítem::titular:: nombre string Obligatorio. Debe rellenarse con el nombre o la razón social del titular del envío. La longitud 33

34 máxima de la concatenación de los campos nombre y apellidos será de 125. destinatarios:: ítem::titular:: apellidos string Opcional. Debe rellenarse con los apellidos del titular del envío. Puede no usarse y poner los apellidos en el mismo campo del nombre. destinatarios:: ítem::destinatario:: telefono string Número de teléfono. Se prevé que se realizarán avisos vía SMS del envío de la notificación/comunicación y de su disponibilidad en Carpeta Ciudadana. destinatarios:: ítem::destinatario:: string (Ver nota más abajo) para realizar el aviso vía correo electrónico del envío de la notificación/comunicación cuando se realiza un envío exclusivo a Carpeta Ciudadana. destinatarios:: ítem::destinatario:: nif string Obligatorio para envíos a Sedes Electrónicas y Carpeta Ciudadana. Debe ser el NIF/CIF/NIE del destinatario del envío. destinatarios:: ítem::destinatario::nombre string Obligatorio. Debe rellenarse con el nombre o la razón social del destinatario del envío. La longitud máxima de la concatenación de los campos nombre y apellidos será de 125. destinatarios:: ítem::destinatario::apellidos string Obligatorio si es un envío a una persona física. Debe rellenarse con los apellidos del destinatario del envío. destinatarios::tipo_domicilio string Opcional. Obligatorio para envíos postales. Tipo de domicilio del destinatario, puede ser fiscal o concreto. En caso de que sea concreto deben rellenarse los campos de 34

35 destinatarios::domicilio Compues to domicilio. Obligatorio para envíos postales. Debe rellenarse el campo tipo_domicilio_concreto, que puede ser nacional, extranjero, sin_normalizar o apartado_correos. Si no se dispone de Código Postal, como sucede en algunos países, se colocará el valor Dependiendo del tipo de domicilio cambian los campos obligatorios dentro de domicilio. Nacional: tipo_via: Se corresponde con tipos indicados en el Anexo VIII: nombre_via: Máximo 50. Tipo_numeracion: Con los siguientes valores posibles: 'num', 'pkm', 's/n', 'apc' numero_casa o punto_kilometrico (solo uno de los dos). Máximo 5 poblacion: Máximo 30 municipio::codigo_i ne codigo_postal. Máximo 10, aunque en España se usan 5. provincia::codigo_p 35

36 rovincia (código INE) pais::codigo_iso Extranjero: nombre_via: Máximo 50 pais::codigo_iso316 6 codigo_postal: Máximo 10 población Máximo 30 Apartado de Correos: apartado_correos: Máximo 10 provincia::codigo_p rovincia municipio::codigo_i ne codigo_postal. Máximo 10. población. Máximo 30 Sin Normalizar: codigo_postal pais::codigo_iso316 6 linea_1: Máximo 50. linea_2: Máximo 50. destinatarios::domicilio::cie integer Opcional. En caso que se quiera alterar el CIE al que irá dirigido, de modo que el envío que se está dando de alta no siga el orden de preferencia que se estableció en la Aplicación Web, 36

37 se puede emplear el campo CIE de domicilio estableciendo el identificador que devuelve el método consultacies. destinatarios::servicio string Obligatorio. Tipo de servicio de envío a realizar, puede ser urgente o normal. Válido para la DEH y para el CIE, otorgando prioridad en la cola de envíos. En el caso del envío postal no afecta la entrega, es decir, la entrega se realiza en los plazos normales. destinatarios::direccion_electronica ::obligado destinatarios::direccion_electronica ::nif destinatarios::direccion_electronica ::codigo_procedimiento destinatarios::opciones_emision ::retardo_postal_deh booleano Obligatorio para envíos a la DEH (Ver nota más abajo). Indica si la notificación por DEH es con obligatoriedad del titular que la recibe o no. Los valores aceptados son true o false. En caso de que sea obligado y el titular no disponga de Buzón DEH se le creará uno automáticamente. En caso de no ser obligado se debe realizar la consulta del censo de suscritos. string Obligatorio para envíos a la DEH (Ver nota más abajo). NIF del titular del buzón DEH que va a recibir la notificación. string Obligatorio para envíos a la DEH NO OBLIGADOS (Ver nota más abajo). Código de procedimiento en la DEH al que el NIF debe estar suscrito. int Indica el número de días naturales que estará disponible una notificación en la Sede Electrónica y/o Carpeta Ciudadana para que pueda ser notificada por comparecencia antes de ponerse a disposición del ciudadano por 37