Integración de Servicios Web en Organismos y Sedes Electrónicas

Transcripción

1 Servicio compartido de Gestión de Notificaciones Integración de Servicios Web en Organismos y Sedes Electrónicas 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 2.27 Fecha de revisión 07/07/2017 Realizado por 1

2 Tabla de contenido 1. 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 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() ANEXO I SW PARA ORGANISMOS - PRUEBAS DE INTEGRACIÓN PRUEBAS DE EMISIÓN CORRECTAS PRUEBAS DE EMISIÓN ERRÓNEAS PRUEBA DE CONSULTA DE DATADO CORRECTAS PRUEBAS DE CONSULTA DE DATADO ERRÓNEAS PRUEBAS DE CONSULTA DE CERTIFICACIÓN - CORRECTAS PRUEBAS DE CONSULTA DE CERTIFICACIÓN - ERRÓNEAS ANEXO II SW PARA ORGANISMOS CÓDIGOS DE RESPUESTA

3 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

4 1. Registro de cambios Fecha Versión Descripción 02/11/ Sustituidas mayúsculas por minúsculas en los estados de las notificaciones en el método certificacionsede() ya añadida descripción del campo fecha 29/11/ Se añade como posibilidad para el alta de notificaciones y comunicaciones el envío de un documento ZIP en lugar de PDF cuando no se vaya a usar el CIE como posible vía de salida. Se añade recomendación de lectura del documento Notific@ flujo detallado. Se añade el método getenvios2() Se aclara el concepto de fecha de caducidad 13/12/ Se remarca la importancia de la lectura del documento sobre datados y certificaciones disponible en el CTT en todo caso pero sobre todo cuando se va a hacer uso del servicio postal. Se añade el campo modo en el método datadoorganismo del servicio Adviser. 25/01/ Se añaden nuevas condiciones a cumplir por las URL donde los Organismos Emisores publican sus Advisers. Se especifica la longitud máxima de algunos campos con formato string. Las notificaciones pasan a caducar a última hora del día en lugar de a primera hora como hasta ahora. 08/02/ Se corrige en algún sitio en que no estaba corregido el cambio de criterio de la 4

5 fecha de caducidad correspondiente a la versión 2.23 de este manual. 31/03/ Aclaración de que los campos deprecated de alta envío solo aplican al CIE de la AEAT y Correos. Aclaración del modo para emitir notificaciones en la DEH con destinatario distinto del titular. 12/04/ Corregida redacción en el apartado 3 del documento 07/07/ Se añaden literales al anexo VII 2. Objetivo. Este documento describe los Servicios Web que Notific@ pone a disposición de los Consumidores del Servicio Compartido con la finalidad de que de manera automatizada se consiga que: Los Organismos emisores puedan realizar el envío de sus notificaciones y comunicaciones. Las Sedes Electrónicas, entre las que se incluye el Punto de Acceso General (PAG) con Carpeta Ciudadana (CC), puedan realizar consultas y certificaciones del estado de los envíos. El documento, además de proporcionar alguna información general, tiene su principal contenido dirigido a la especificación de los distintos Servicios Web y por consiguiente está organizado en tres secciones cuya aplicación se refleja en el gráfico: Servicios Web para Organismos. Servicio Adviser en Organismos Servicios Web para Sedes Electrónicas. 5

6 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. 6

7 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 de los servicios web implementados, siendo necesario cumplir con el protocolo de pruebas definido en el Anexo I SW para Organismos - Pruebas de Integración. Notific@ pone a disposición recursos para la integración en Preproducción los cuales pueden ser consultados en los apartados Descripción de entornos para 7

8 Organismos y Descripción de entornos para Sedes Electrónicas, de acuerdo a si es un Organismo o una Sede Electrónica respectivamente. i. Elaboración de pruebas de los servicios web implementados en el entorno de Producción, al ser un entorno de Producción no se puede cumplir con el mismo protocolo de pruebas definido en el Anexo I SW para Organismos - Pruebas de Integración, en este caso, se realizarán 2 o 3 pruebas puntuales para comprobar que todo esté en orden. 4. Requisitos de los envíos Para establecer la integración con Notific@, 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. 8

9 5. Servicios Web para Organismos. cuenta con varios Servicios Web, algunos de ellos en el rol de servidor y otros en el rol cliente. Servicio web para Organismos (rol servidor): es el encargado de recibir por parte de los Organismos la información relacionada a las funciones que se desean utilizar y en donde se emite una respuesta, Servicio web para Organismos (rol de cliente): es el encargado de llamar a los servicios implementados por los Organismos para que se les pueda enviar información de interés, como por ejemplo, el acuse de recibo. Como ya se ha mencionado anteriormente, Notific@ cuenta con un aplicativo web con el que se pueden realizar la integración, sin embargo, si se desea contar con un uso automatizado de Notific@ debe realizar la integración con el Servicio Web, lo que comprende: El desarrollo de la parte cliente, obligatoria y necesaria para poder invocar los servicios web de Notific@ y/o la creación del Servicio Adviser, necesaria solamente en el caso de desear recibir información de los servicios de Notific@ como Datados y Certificados. El uso de los métodos citados a continuación en los siguientes apartados. La evaluación de los resultados junto con las respuestas esperadas 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): 9

10 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 ml Para otros organismos (CCAA, EELL ) o html 5.2. 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. 10

11 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: 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 Notific@, 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. 11

12 organismo_pagador_correos:: numero_contrato_correos organismo_pagador_correos:: codigo_cliente_facturacion_correos organismo_pagador_correos:: fecha_vigencia 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. 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 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 12

13 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 campo cie de domicilio. organismo_pagador_cie:: fecha_vigencia DateTim e Campo aún válido pero 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) 13

14 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 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 caracteres. 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 caracteres. 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. 14

15 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 máxima de la concatenación de los campos nombre y apellidos será de 125 caracteres. 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 15

16 longitud máxima de la concatenación de los campos nombre y apellidos será de 125 caracteres. 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 domicilio. destinatarios::domicilio Compues to 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 los siguientes tipos: 'ALMDA' => 'ALAMEDA', 'CALLE' => 'CALLE', 'CAMNO' => 'CAMINO', 'CARR' => 'CARRER', 16

17 'CTRA' => 'CARRETERA', 'GTA' => 'GLORIETA', 'KALEA' => 'KALEA', 'PSJ' => 'PASAJE', 'PASEO' => 'PASEO', 'PLAÇA' => 'PLAÇA', 'PLAZA' => 'PLAZA', 'RAMBL' => 'RAMBLA', 'RONDA' => 'RONDA', 'RÚA' => 'RÚA', 'SECT' => 'SECTOR', 'TRAV' => 'TRAVESÍA', 'URB' => 'URBANIZACIÓ N', 'AVDA' => 'AVENIDA', 'AVGDA' => 'AVINGUDA', 'BAR' => 'BARRIO', 'CJA' => 'CALLEJA', 'CAMÍ' => 'CAMÍ', 'CAMPO' => 'CAMPO', 'CRA' => 'CARRERA', 'CSTA' => 'CUESTA', 17

18 'EDIF' => 'EDIFICIO', 'EPTZA' => 'ENPARANTZA', 'ESTR' => 'ESTRADA', 'JARD' => 'JARDINES', 'JARDI' => 'JARDINS', 'PRQUE' => 'PARQUE', 'PSG' => 'PASSEIG', 'PRAZA' => 'PRAZA', 'PLZA' => 'PLAZUELA', 'PLCTA' => 'PLACETA', 'POBL' => 'POBLADO', 'VIA' => 'VIA', 'TRAVS' => 'TRAVESSERA', 'PASTG' => 'PASSATGE', 'BVR' => 'BULEVAR', 'POLIG' => 'POLÍGONO', 'OTROS' => 'OTROS', nombre_via: Máximo 50 caracteres. Tipo_numeracion: Con los siguientes valores posibles: 'num', 'pkm', 's/n', 'apc' 18

19 numero_casa o punto_kilometrico (solo uno de los dos). Máximo 5 caracteres poblacion: Máximo 30 caracteres municipio::codigo_i ne codigo_postal. Máximo 10 caracteres, aunque en España se usan 5. provincia::codigo_p rovincia (código INE) pais::codigo_iso Extranjero: nombre_via: Máximo 50 caracteres pais::codigo_iso316 6 codigo_postal: Máximo 10 caracteres población Máximo 30 caracteres Apartado de Correos: apartado_correos: Máximo 10 caracteres provincia::codigo_p rovincia municipio::codigo_i ne codigo_postal. Máximo 10 caracteres. población. Máximo 30 caracteres Sin Normalizar: 19

20 codigo_postal pais::codigo_iso316 6 linea_1: Máximo 50 caracteres. linea_2: Máximo 50 caracteres. 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, 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 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. 20

21 destinatarios::direccion_electronica ::codigo_procedimiento destinatarios::opciones_emision ::retardo_postal_deh destinatarios::opciones_emision ::caducidad string int 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. 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 otras vías. Una vez pasen esos días, el envío pasará a ser realizado a través de la DEH o el CIE. En el caso de que el valor sea 0, pasa directamente a la DEH o al CIE para la posterior entrega postal, permaneciendo en todo caso disponible en la Sede Electrónica y/o Carpeta Ciudadana. Opcional (Ver nota más abajo). Fecha en la cual, a última hora del día, una notificación pasa a estado rehusado. Aplica a los envíos que se depositan en Carpeta y/o sede electrónica y a los que van a la DEH. Cuando no sea obligatorio establecer fecha de caducidad y un envío se ponga a disposición a través de la DEH, se considerará un plazo por defecto de 10 días conforme a la Ley. El formato correcto de la fecha es YYYY- MM-DD. procedimiento::codigo_sia string Opcional, pero obligatorio para las notificaciones. Para las comunicaciones no aplica. 21

22 Código de procedimiento SIA (Sistema de Información Administrativa). procedimiento::descripcion_sia string Opcional. Descripción del SIA (Sistema de Información Administrativa). 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, para evitar que el destinatario sea notificado a través de la DEH o por la Vía Postal, los valores de los campos: destinatarios::tipo_domicilio, destinatarios::domicilio y destinatarios::dirección_electrónica deben ser nulos y el campo destinatarios::opciones_emision::caducidad pasaría a ser obligatorio. Envío DEH voluntario + Carpeta Ciudadana / Sede electrónica De la misma manera el campo caducidad también es obligatorio cuando un envío se configura como DEH con el campo obligado a false + 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 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. Envíos a través de la DEH cuando el titular es distinto que el destinatario Cuando se desea enviar una notificación o comunicación a través de la DEH con titular diferente del destinatario (o, lo que es lo mismo, autorizado según el vocabulario de la DEH), se deben rellenar los campos de la siguiente manera: destinatarios::ítem::titular::nif coincidirá con destinatarios::direccion_electronica::nif destinatarios::ítem::destinatario::nif contendrá el NIF del destinatario (autorizado) Importancia de consignar el campo 22

23 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. Datos de respuesta: Se devuelve una respuesta SOAP de nombre altaenvioresponse con los campos: Variable Tipo Descripción identificadores::item:: identificador identificadores::item:: referencia_emisor string string ID que se proporciona al dar el alta y que se deberá usar posteriormente para referenciar dicho envío. Referencia interna del Emisor del envío. No pueden existir dos envíos con la misma referencia para un mismo organismo. NIF/CIF/NIE del titular del envío. identificadores::item:: string nif_titular codigo_csv string Opcional. Código de Seguridad y Verificación generado en el alta del envío. codigo_respuesta string Código de tres dígitos asociado al resultado. descripcion_respuesta string Descripción de la operación. Los valores devueltos en los campos codigo_respuesta y descripción_respuesta se pueden consultar en el Anexo II SW para Organismos Códigos de respuesta. En el Anexo III SW para Organismos - Ejemplos parte servidora podrá consultar un ejemplo de este método Método infoenvio(). El método infoenvio() es un módulo del servicio web de Notific@, como parte servidora, que permite la consulta y el detalle de un envío. Parámetros: El método infoenvio() debe invocarse con los siguientes parámetros: Variable Tipo Descripción 23

24 envio_destinatario string Obligatorio. Identificador del envío devuelto en la respuesta de altaenvio(). Datos de respuesta: Se devuelve una respuesta SOAP de nombre infoenvioresponse con los campos: 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 Sólo se muestra para envíos postales cuando el dato fue consignado en el Método altaenvio(). Código DIR3 del organismo que realizará el pago del servicio de entrega postal. organismo_pagador_correos:: numero_contrato_correos organismo_pagador_correos:: codigo_cliente_facturacion_correos organismo_pagador_correos:: fecha_vigencia string string DateTim e Sólo se muestra para envíos postales cuando el dato fue consignado en el Método altaenvio() Número de contrato del organismo pagador con el operador postal. Sólo se muestra para envíos postales cuando el dato fue consignado en el Método altaenvio(). Código cliente del organismo pagador para la facturación con el operador postal. Sólo se muestra para envíos postales cuando el dato fue consignado en el Método altaenvio(). Fecha fin del contrato con el operador postal. organismo_pagador_cie:: codigo_dir3 string Sólo se muestra para envíos postales cuando el dato fue 24

25 organismo_pagador_cie:: fecha_vigencia DateTim e consignado en el Método altaenvio(). Código DIR3 del organismo que realizará el pago de costes de impresión y ensobrado Sólo se muestra para envíos postales cuando el dato fue consignado en el Método altaenvio(). Fecha del fin del contrato con el Centro de Impresión y Ensobrado. documento::contenido string Obligatorio. Contenido del documento de la notificación codificado en base64. 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 debe introducir NO. El CSV se introducirá en el pie del documento con la 25

26 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. 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. 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 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 26

27 destinatarios:: ítem::titular::apellidos string Obligatorio si es un envío a una persona física. Debe rellenarse con los Apellidos del titular del envío. 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 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 titular del envío. destinatarios:: ítem::destinatario::nombre string Obligatorio. Debe rellenarse con el nombre o la razón social del titular del envío destinatarios:: ítem::destinatario::apellidos string Obligatorio si es un envío a una persona física. Debe rellenarse con los apellidos del titular del envío. destinatarios::tipo_domicilio string Opcional aunque 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 domicilio. destinatarios::domicilio Compues Obligatorio para envíos to postales. Mostrará información conforme se introdujo al dar de alta el envío. 27

28 destinatarios::servicio string Obligatorio. Tipo de servicio de envío a realizar, puede ser urgente o normal. destinatarios::direccion_electronica ::obligado destinatarios::direccion_electronica ::nif destinatarios::direccion_electronica ::codigo_procedimiento destinatarios::opciones_emision ::retardo_postal_deh destinatarios::opciones_emision ::caducidad booleano Obligatorio para envíos a la DEH. 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. NIF del titular del buzón DEH que va a recibir la notificación. string Obligatorio para envíos a la DEH NO OBLIGADOS. 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 otras vías, de acuerdo a la configuración que se estableció al dar de alta el envío. string Opcional. Fecha en la cual, a primera hora del día, una notificación pasa a estado rehusado a última hora del día. El formato correcto de la 28

29 fecha es YYYY-MM-DD. procedimiento::codigo_sia string Opcional. Código de procedimiento SIA (Sistema de Información Administrativa). procedimiento::descripcion_sia string Opcional. Descripción del SIA (Sistema de Información Administrativa). certificada booleano Obligatorio. Indica si la notificación ha llegado a su estado final. Los valores aceptados son true o false. Nótese que para las notificaciones un valor de true indica que hay certificación pero ésta puede ser positiva o negativa. Para las comunicaciones este valor siempre es false. codigo_respuesta string Obligatorio. Código de tres dígitos asociado al resultado. descripción_respuesta string. Obligatorio. Descripción de la operación. Los valores devueltos en los campos codigo_respuesta y descripción_respuesta se pueden consultar en el Anexo II SW para Organismos Códigos de respuesta Método consultaestado(). El método consultaestado() es un módulo del servicio web de Notific@, como parte servidora, que permite consultar el Estado de un envío. Parámetros: El método consultaestado() debe invocarse con los siguientes parámetros: Campo Tipo Descripción identificador_envio string Obligatorio. Identificador del envío devuelto en la respuesta de 29

30 altaenvio() Datos de respuesta: Se devuelve una respuesta SOAP de nombre consultaestadoresponse con los campos: Variable Tipo Descripción estado:: string Obligatorio. Identificador del envío identificador_envio devuelto en la respuesta de altaenvio() estado:: estado string Obligatorio. Estado del envío. identificador_envio:: nif_titular string Opcional. El NIF/CIF/NIE del titular del envío. estado::ncc_id_externo string Opcional. NCC. Número de seguimiento de correos. codigo_respuesta string Obligatorio. Código de tres dígitos asociado al resultado. descripcion_respuesta string Obligatorio. Descripción de la operación. Los valores devueltos en los campos codigo_respuesta y descripción_respuesta se pueden consultar en el Anexo II SW para Organismos Códigos de respuesta. En el Anexo III SW para Organismos - Ejemplos parte servidora podrá consultar un ejemplo de este método. 30

31 5.6. Método consultadatadoenvio(). El método consultadatadoenvio() es un módulo del servicio web de como parte servidora, que permite consultar el Datado de un envío. Parámetros: El método consultadatadoenvio() debe invocarse con los siguientes parámetros: Campo Tipo Descripción identificador_envio string Obligatorio. Identificador del envío devuelto en la respuesta de altaenvio() Datos de respuesta: Se devuelve una respuesta SOAP de nombre consultadatadoenvioresponse con los campos: Variable Tipo Descripción identificador_envio:: identificador identificador_envio:: referencia_emisor string string Obligatorio. Identificador del envío devuelto en la respuesta de altaenvio() Obligatorio. Referencia interna del Emisor del envío. No pueden existir dos envíos con la misma referencia para un mismo organismo. Opcional. El NIF/CIF/NIE del titular del envío. identificador_envio:: string nif_titular datado::item::estado string Opcional. Estado del Datado. Es un array o lista con todo el historial de estados. datado::item::descripción string Opcional. Descripción del estado. datado::item::fecha string Opcional. Fecha del datado. estado_actual string Estado Actual o último estado del array o lista con todo el historial de estados. descripción_estado_actua l string Obligatorio. Descripción del estado actual. 31

32 fecha_actualizacion DateTime Obligatorio. Fecha de actualización. ncc_id_externo string Opcional. NCC. codigo_respuesta string Obligatorio. Código de tres dígitos asociado al resultado. descripcion_respuesta string Obligatorio. Descripción de la operación. Los valores devueltos en los campos codigo_respuesta y descripción_respuesta se pueden consultar en el Anexo II SW para Organismos Códigos de respuesta. En el Anexo III SW para Organismos - Ejemplos parte servidora podrá consultar un ejemplo de este método Método consultacertificacionenvio(). El método consultacertificacionenvio() es un módulo del servicio web de Notific@, como parte servidora, que permite consultar la Certificación de un envío. Parámetros: El método consultacertificacionenvio() debe invocarse con los siguientes parámetros: Campo Tipo Descripción identificador_envio string Obligatorio. Identificador del envío devuelto en la respuesta de altaenvio() Datos de respuesta: Se devuelve una respuesta SOAP de nombre consultacertificacionenvioresponse con los campos: Variable Tipo Descripción certificación::identificador_envio:: identificador string Obligatorio. ID que se proporciona al dar de alta un envío. certificación::identificador_envio:: string Obligatorio. referencia_emisor Referencia interna del Emisor del envío. No pueden existir dos envíos con la misma referencia para un 32

33 mismo organismo. certificación::identificador_envio:: nif_titular string Opcional. El NIF/CIF/NIE del titular del envío. certificación::pdf_certificado string Opcional. Contenido del Certificado en PDF y en base 64. Es excluyente con el siguiente campo, si está en PDF no se devuelve en XML. certificación::xml_certificado string Opcional. Contenido del Certificado en XML. Es excluyente con el anterior campo, si está en XML no se devuelve en PDF. certificación::certificación string Obligatorio. Tipo de acuse o sobre. Nótese que para envíos postales el acuse es una notificación positiva y el sobre es una notificación negativa (por ejemplo, rehusada). Para otros medios se usa el acuse independientemente del resultado. certificación::fecha_actualizacion DateTime Obligatorio. Fecha en la que llega el acuse. certificación::ncc_id_externo string Opcional. NCC. codigo_respuesta string Obligatorio. Código de tres dígitos asociado al resultado. descripcion_respuesta string Obligatorio. Descripción de la operación. 33

34 Los valores devueltos en los campos codigo_respuesta y descripción_respuesta se pueden consultar en el Anexo II SW para Organismos Códigos de respuesta. En el Anexo III SW para Organismos - Ejemplos parte servidora podrá consultar un ejemplo de este método Método consultaorganismosactivos(). El método consultaorganismosactivos() es un módulo del servicio web de Notific@, como parte servidora, que permite consultar a los Organismos activos. Parámetros: El método consultaorganismosactivos() no recibe parámetros. Datos de respuesta: Se devuelve una respuesta SOAP de nombre consultaorganismosactivosresponse con los campos: Variable Tipo Descripción organismos::item:: codigo_dir3 string Obligatorio. Código DIR3 del Organismo. organismos::item:: nombre string Obligatorio. Nombre del Organismo. codigo_respuesta string Obligatorio. Código de tres dígitos asociado al resultado. descripcion_respuesta string Obligatorio. Descripción de la operación. Los valores devueltos en los campos codigo_respuesta y descripción_respuesta se pueden consultar en el Anexo II SW para Organismos Códigos de respuesta Método consultacies(). El método consultacies() es un módulo del servicio web de Notific@, como parte servidora, que permite consultar a los CIEs disponibles para un organismo emisor. 34

35 Parámetros: El método consultacies() recibe los siguientes parámetros. Variable Tipo Descripción organismo_emisor string Obligatorio. Código DIR3 del Organismo. Datos de respuesta: Se devuelve una respuesta SOAP de nombre consultaciesresponse con los campos: Variable Tipo Descripción cies::id integer Obligatorio. Identificador del CIE. cies::centro_impresion string Obligatorio. Nombre del CIE cies::fecha_vigencia Date Obligatorio. Fecha de vigencia (hasta) del contrato cies:: codigo_unidad_relacionada string Obligatorio. Código DIR3 del Organismo. cies:: string Obligatorio. Nombre del nombre_unidad_relacionada Organismo. cies::orden integer Obligatorio. Orden de preferencia del CIE. En caso que varios CIEs tengan el mismo orden, hará la seleccionará el CIE entre ellos en función de criterios como la capacidad del CIE o el reparto de cargas de trabajo. codigo_respuesta string Obligatorio. Código de tres dígitos asociado al resultado. descripcion_respuesta string Obligatorio. Descripción de la operación. 35

36 6. Servicio Adviser en Organismos para tiene implementado un servicio web, denominado Adviser, con el rol de parte cliente, que permite el envío de los Datados y Certificaciones de una notificación hacia el Organismo Emisor. La implementación de este servicio es opcional y solo se requiere si se desea obtener una comunicación automática del estado de los envíos cuando se produzca una modificación en dicho estado. Como alternativa, el Organismo Emisor que no desee implementar estos desarrollos, puede hacer uso de los métodos de consulta, bajo demanda, consultacertificacionenvio y consultadatadoenvio incluidos en los Servicios web para Organismos. La funcionalidad Adviser contiene los métodos es decir, la programación de los métodos que se describen a continuación. Método datadoorganismo() certificacionorganismo() Descripción Método que debe ser implementado para la recepción del Datado de un envío. Método que debe ser implementado para la recepción de la Certificación de un envío. A continuación se puede consultar el detalle de cada uno de los parámetros a recibir, así como de las respuestas a generar. Nota 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, se ha publicado el siguiente documento para clarificar conceptos: Validez%20de%20notificaciones%20por%20distintos%20medios%20- %20Datados%20y%20Certificaciones.ppsx?idIniciativa=706&idElemento=

37 Nota Las direcciones IP de salida que utiliza para comunicarse con el Adviser de los Organismos Emisores son las siguientes: Entorno de PRE o y Entorno de PRO o , , y Método datadoorganismo(). El método datadoorganismo() es un módulo del servicio web de Notific@, como parte cliente, que permite la recepción del Datado de un envío. Parámetros a recibir: El método datadoorganismo() debe implementarse para recibir los siguientes parámetros: Variable Tipo Descripción organismo_emisor tipoorganismoemisor Tipo compuesto que contendrá tanto el código DIR3 del organismo como su nombre. codigo_dir3 string Código DIR3 del organismo emisor. nombre string Nombre del organismo emisor. identificador_destinatario string Identificador del envío devuelto en la respuesta de altaenvio() resultado string Estado de la entrega del comunicado que se corresponderá con uno de los estados de Notific@. fecha datetime Fecha en la que se produjo el intento de entrega. receptor tipo_persona Datos del receptor del envío. nif string NIF del receptor del envío. nombre string Nombre del receptor del envío. modo string Indica quién ha originado el datado. Valores posibles: correos_cie, electrónico, sede, carpeta. 37

38 Datos a devolver: Se debe devolver una respuesta SOAP de nombre datadoorganismoresponse con los campos: Variable Tipo Descripción codigo_respuesta string Código de tres dígitos asociado al resultado. texto_respuesta string Descripción de la operación. Los valores a devolver en los campos codigo_respuesta y descripción_respuesta se pueden consultar en el Anexo IV Servicio Adviser Códigos de respuesta. En el Anexo V SW para Organismos Ejemplos del Adviser podrá consultar un ejemplo de este método Método certificacionorganismo(). El método certificacionorganismo() es un módulo del servicio web de Notific@, como parte cliente, que permite la recepción de la Certificación de un envío. Parámetros a recibir: El método certificacionorganismo() debe implementarse para recibir los siguientes parámetros: Variable Tipo Descripción organismo_emisor string Sólo el código DIR3 del Organismo. identificador_destinatario string Identificador del envío devuelto en la respuesta de altaenvio() acuse_o_sobre string Indica si es un acuse de recibo o un sobre escaneado. certificacion string Contiene el base64 del PDF con el contenido. hash_sha1 string Codificación base64 del sha1 del contenido binario del documento Datos a devolver: Se debe devolver una respuesta SOAP de nombre datadoorganismoresponse con los siguientes campos: 38

39 Variable Tipo Descripción codigo_respuesta string Código de tres dígitos asociado al resultado. texto_respuesta string Descripción de la operación. Los valores a devolver en los campos codigo_respuesta y descripción_respuesta se pueden consultar en el Anexo IV Servicio Adviser Códigos de respuesta. En el Anexo V SW para Organismos Ejemplos del Adviser podrá consultar un ejemplo de este método. 39

40 7. Servicios Web para Sedes Electrónicas. cuenta con varios Servicios Web, en el rol de parte servidora, encargados de recibir por parte de las Sedes Electrónicas la información relacionada a las funciones que se desean utilizar y en donde se emite una respuesta. El procedimiento general para la integración con el Servicio Web comprende: El desarrollo de la parte cliente, obligatoria y necesaria para poder usar los servicios web de Notific@ en el rol de parte servidora. El uso de los métodos citados a continuación en los siguientes apartados. La evaluación de los resultados junto con las respuestas esperadas Descripción de entornos para Sedes Electrónicas. Con el objetivo de cumplir con lo previsto para la 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): De igual forma, y con el objetivo de cumplir con lo previsto para la 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): Servicio web de Notific@, como parte servidora, para Sedes Electrónicas. Notific@ tiene implementado un servicio web, con el rol de parte servidora, que está relacionado con la consulta y monitorización de la entrega de una notificación, y que incluye los siguientes métodos: getenvios() getenvios2() Método Descripción Método que devuelve todos los identificadores de los envíos dependiendo de las opciones introducidas. Método similar a getenvios() pero que además dispone 40