Especificación WebService para: Bandeja de salida Carga masiva Consulta de reportes Bogotá, Diciembre 2010 Modelo Unico de Ingresos, Servicio y Control Automatizado
Contenido Procedimiento y Especificación Técnica para la Bandeja de Salida...1 Presentación de Información por Envío de Archivos a través de Web Service...10 Procedimiento y Especificación Técnica para la Consulta de Reportes...29
Procedimiento y Especificación Técnica para la Bandeja de Salida El objetivo de la siguiente especificación técnica es brindar la información detallada a las entidades competentes, para que puedan acceder a la Bandeja de Salida a través de Web Services ofrecidos por la DIAN. Definición de los casos de uso para la Bandeja de Salida a través de Web Services Los siguientes son los casos de uso de las operaciones que podrán utilizar las personas u organizaciones: Obtener las URLs del servicio web y del servlet para acceder a la bandeja de salida. Consultar el número de documento que representa una salida de información por envío de archivos. Consultar el listado de archivos que pertenecen a una salida de información por envío de archivos. Descargar archivos desde la bandeja de salida. A continuación se definen cada uno de los casos de uso como operaciones de los Web Services y operaciones ofrecidas por el servlet. 1
1. Web Service - Preguntar URLs Este servicio Web posee autenticación y por tal razón es necesario ver el apartado de configuración de seguridad, donde se explica cómo se maneja este tema por medio del Header del mensaje SOAP (ver especificación wsdl DWSPreguntarURLBandejaSalida.wsdl). 1.1. Obtener las URLs del servicio web para las opciones de bandeja de salida y del servlet para la descarga de archivos Nombre operación DESCRIPCIÓN geturlsbsa Permite obtener la url del servicio web que va a atender las peticiones de correspondientes al WebService - Acceder Bandeja de Salida, y la url del servlet que permite descargar archivos. PARÁMETROS DE ENTRADA formato Formato del cual va a realizar la consulta o descarga de archivos. int PARÁMETROS DE SALIDA geturlsbsareturn XML que contiene las urls del servlet y del web server. geturlsbsa.xsd 2
2. Web Service Acceder Bandeja de Salida Este servicio Web posee autenticación y por tal razón es necesario ver el apartado de configuración de seguridad, donde se explica cómo se maneja este tema por medio del Header del mensaje SOAP (ver especificación wsdl DWSConsultarDocSalidaInfo.wsdl ). Además, este servicio Web implemente WSS (Web Service Security), por lo que hay que tener en cuenta el callback que firma el mensaje SOAP. Ver configuración de seguridad. 2.1. Consultar documento salida de información Nombre operación DESCRIPCIÓN consultardocumentosalida Permite consultar el número de documento de una salida de información (documento con formato 10606), dado un identificador que representa el origen de la salida de información. PARÁMETROS DE ENTRADA identificadororigen Identificador que representa el origen de la salida de información. string PARÁMETROS DE SALIDA consultardocumentosalidareturn Elemento XML que contiene el número de documento de la salida de información (documento con formato 10606). consultardocumentosalida.xsd 3
2.2. Consultar archivos de salida Nombre DESCRIPCIÓN operación consultararchivossalida Permite consultar el nombre e identificador de los archivos que pertenecen a una salida de información, dado un documento con formato 10606 que representa la salida de información. PARÁMETROS DE ENTRADA numero Solicitud Documento con formato 10606 que representa la salida de información. long PARÁMETROS DE SALIDA consultararchivossalidareturn Elemento XML que contiene el nombre y el id de los archivos que pertenecen a una salida de información. consultararchivossalida.xsd 4
3. Servlet Manejo de Archivos El servlet posee autenticación y por tal razón es necesario ver el apartado de configuración de seguridad, donde se explica cómo se maneja este tema por medio del Header del Request. Por tal razón la comunicación se hace a través de HTTPS. Para determinar qué operación se desea ejecutar, es necesario enviar el parámetro operación, con la operación correspondiente. 3.1. Descargar archivos de salida Nombre operación DESCRIPCIÓN Descargar Archivo de Salida Permite descargar un archivo de la bandeja de salida. PARÁMETROS DEL HEADER Nombre Valor Descripción tipoidentificacion identificación tipoorganizacion nitorganizacion password Código del tipo de identificación. Ver configuración de seguridad. Numero de Identificación. Ver configuración de seguridad. Código del tipo de organización. Ver configuración de seguridad. NIT de la Organización, si se auténtica a nombre de una. Ver configuración de seguridad. La contraseña va codificada con UTF-8. Ver configuración de seguridad. 5
PARÁMETROS DEL GET DEL REQUEST Nombre Valor Descripción operacion 1 Operación que permite la descarga de archivos. numerosolicitud long Documento con formato 10606 que representa la salida de información. idarchivo int Identificador del archivo que se va a descargar. RESPUESTA Nombre Valor Descripción stream Respuesta servlet archivos.xsd A través del stream, envía el archivo, el cual es un comprimido cuyo nombre es el id del archivo con extensión zip, y contiene el archivo solicitado cuyo nombre y extensión depende de cómo esté registrado. Si se presento algún error, devuelve por este mismo medio, un xml con el error. Si se presentó algún error, devuelve por este mismo medio en vez del archivo, un xml con el error. 6
Configuración de Seguridad IPs autorizadas por la DIAN El servicio ofrecido debe contar con una dirección pública válida en Internet para poder consumir las operaciones de los Web Services ofrecidos por carga Masiva. Esta dirección debe ser informada a la DIAN para su autorización. Solamente desde las direcciones autorizadas se podrá acceder a estas operaciones. Protocolo HTTPS El protocolo de comunicación establecido para conectarse al Web Service y al servlet de la DIAN es HTTPS. Certificados Digitales Los certificados digitales que se utilizarán para validar el mensaje SOAP deben ser emitidos por una Entidad Certificadora autorizada por la Superintendencia de Industria y Comercio. Estos certificados deben ser de tipo Servidor Seguro que permitan generar firmas automatizadas. WS-Security Como mecanismo de seguridad para el envío y recepción de los mensajes SOAP, se establece el estándar internacional WS-Security. Los mensajes SOAP tendrán que cumplir las siguientes características: 7
Para la petición SOAP: Estar firmado digitalmente. Contener el elemento Timestamp, el cual indica la fecha y hora en que se crea la petición, y la fecha y hora en que expira el mensaje. Para la autenticación ante el DIAN se deberá usar el elemento accesomuisca (que se puede encontrar en http://muisca.dian.gov.co/ws-eys/xsd/seguridad/accesomuisca.xsd) en la cabecera (Header) del mensaje SOAP. Esta cabecera está definida en el WSDL del Web Service. La inclusión de este elemento dentro de la cabecera del mensaje SOAP varía dependiendo de la plataforma usada. Este elemento usa los siguientes atributos para permitir el acceso a DIAN: - tipoorganizacion: Tipo de la organización que va a realizar la autenticación. Los tipos de organizaciones permitidos están definidos en el XSD. - nitorganizacion: Corresponde al NIT de la organización que va a acceder. Este es requerido únicamente cuando el tipo de organización sea NIT_ORGANIZACION. - tipoidentificacion: Tipo de documento de identificación del usuario que solicita el acceso. Los tipos de documentos de identificación permitidos están definidos en el XSD. - identificacion: Número de identificación del usuario. - password: Contraseña de acceso a la DIAN. Un ejemplo es el siguiente: <soapenv:header> <ns1:accesomuisca xmlns:ns1=»http://www.dian.gov.co/ws/seguridad» soapenv:actor=»http://schemas.xmlsoap.org/soap/actor/next» soapenv:mustunderstand=»0" ns1:tipoorganizacion=»nit_organizacion» ns1:nitorganizacion=»99999999" ns1:tipoidentificacion=»sis»ns1:identificacion=»99999999" ns1:password=»xxxxxx»></ ns1:accesomuisca> </soapenv:header> Para la Respuesta SOAP: El mensaje SOAP deberá estar firmado digitalmente. Contendrá el elemento Timestamp. 8
Autenticación vía Servlet Para la autenticación ante el DIAN a través del servlet, se deben utilizar los siguientes parámetros, que viajarán por header del request: tipoorganizacion: Tipo de la organización que va a realizar la autenticación. Los tipos de organizaciones permitidos están definidos en el XSD. nitorganizacion: Corresponde al NIT de la organización que va a acceder. Este es requerido únicamente cuando el tipo de organización sea NIT_ORGANIZACION. tipoidentificacion: Tipo de documento de identificación del usuario que solicita el acceso. Los tipos de documentos de identificación permitidos están definidos en el XSD. identificacion: Número de identificación del usuario. password: Contraseña de acceso a la DIAN. 9
Presentación de Información por Envío de Archivos a través de Web Service El servicio de presentación de información por envío de archivos a través de web service (sistema a sistema), permite de manera general a los usuarios del mismo, las siguientes opciones: Realizar una solicitud de carga de archivos, Consultar el estado del procesamiento de la solicitud, Recibir la comunicación respectiva cuando se finalice el procesamiento. En forma detallada a través del nuevo servicio, podrán realizarse las siguientes operaciones, bien sea que se trate de personas u organizaciones: Preguntar URLs. Reservar números de documentos. Obtener el rango de consecutivos para los archivos a cargar. Presentar solicitud de envío de archivos. Consultar el estado de la solicitud. Consultar archivos de la bandeja de entrada. Eliminar archivos de la bandeja de entrada. Colocar archivos en la bandeja de entrada. Colocar los archivos con error de una solicitud en la bandeja de salida. Descargar los archivos con error de una solicitud de la bandeja de salida. Los siguientes son las operaciones que deben implementar las personas u organizaciones para recibir respuesta relacionada con el procesamiento de solicitudes: Informar fin de procesamiento de una solicitud de envío de archivos. Informar fin de colocación de archivos de error en la bandeja de salida. 10
11 A continuación se definen cada una de las operaciones de los Web Services así como de las operaciones ofrecidas por el servlet.
1. Web Service DIAN Preguntar URLs Esta operación Web posee autenticación y por tal razón es necesario ver el apartado de configuración de seguridad, donde se explica cómo se maneja este tema por medio del Header del mensaje SOAP (ver especificación wsdl DWSPreguntarURL.wsdl). 1.1. Obtener las URLs del servicio Web para las opciones de envío masivo y del servlet para carga y descarga de archivos Nombre Operación DESCRIPCIÓN geturls Permite obtener la URL del servicio Web que va a atender las peticiones correspondientes al WebService Presentar Solicitud, y la URL del servlet que permite cargar y descargar archivos. PARÁMETROS DE ENTRADA formato Formato del cual va a realizar la solicitud de carga de archivos. int PARAMETROS DE SALIDA geturlsreturn XML que contiene las urls del servlet y del web server. geturls.xsd 12
2. Web Service DIAN Presentar Solicitud Esta operación Web posee autenticación y por tal razón es necesario ver el apartado de configuración de seguridad, donde se explica cómo se maneja este tema por medio del Header del mensaje SOAP (ver especificación wsdl DWSPresentarSolicitud.wsdl). Además, esta operación Web implica implementar WSS (Web Service Security), por lo que hay que tener en cuenta el callback que firma el mensaje SOAP. Ver configuración de seguridad. 2.1. Reservar números de documentos Nombre Operación DESCRIPCIÓN reservarnumerosdocumento Permite reservar una numeración de consecutivos que como mínimo debería ser la misma cantidad de archivos a cargar. PARÁMETROS DE ENTRADA cantidadconsecutivos formato version Cantidad de números de documentos que se desean reservar. Formato para el cual se requiere reservar número de documentos. Versión del formato para el cual se requiere reservar número de documentos int int int PARÁMETROS DE SALIDA reservarnumeros DocumentoReturn XML con los números de documentos reservados. reservarnumerosdocumento.xsd 13
2.2. Obtener el rango de consecutivos para los archivos a cargar Nombre Operación DESCRIPCIÓN consultarrangoconsecutivos Permite reservar una numeración de consecutivos que como mínimo debería ser la misma cantidad de archivos a cargar. PARÁMETROS DE ENTRADA cantidadconsecutivos formato version Cantidad de consecutivos para los cuales va a reservar numeración. Formato para el cual se requiere reservar consecutivos. Versión del formato para el cual se requiere reservar consecutivos. int int int PARÁMETROS DE SALIDA consultarrango ConsecutivosReturn XML con el rango de consecutivos reservados. consultarrangoconsecutivos.xsd 14
2.3. Presentar solicitud de envío de archivos Nombre Operación DESCRIPCIÓN presentarsolicitud Permite presentar una solicitud para el envío de uno o varios archivos colocados previamente en la bandeja de entrada de la persona u organización. PARAMETROS DE ENTRADA xmldocsolicitud XML que contiene la información de la solicitud de envío de archivo (ver Anexo A). xmldocsolicitud.xsd PARAMETROS DE SALIDA reservarnumeros DocumentoReturn XML que contiene la información del acuse de recibo. presentarsolicitud.xsd 15
2.4. Consultar el estado de la solicitud Nombre Operación DESCRIPCIÓN consultarsolicitud Permite consultar el estado de la solicitud, y lista el nombre de los archivos que presentaron error. Esta operación tendrá políticas para poder utilizada cada cierto tiempo. PARAMETROS DE ENTRADA numerosolicitud Número de la solicitud sobre la que se desea hacer la consulta. long PARAMETROS DE SALIDA consultarsolicitudreturn XML que contiene el estado de la solicitud; si la solicitud presentó errores, incluye el listado de los archivos que tuvieron error. consultarsolicitud.xsd 16
2.5. Colocar los archivos con error de una solicitud en la bandeja de salida Nombre operación DESCRIPCIÓN colocararchivosbandejasalida Permite colocar en la bandeja de salida los archivos que presentaron error durante el procesamiento, de manera comprimida. Esta operación es asincrónica, lo que hace que se genere una respuesta usando el Web Service implementado por la organización para informar el fin de colocación de archivos de error. Para la descarga posterior de los archivos de error, se deben utilizar los Web Services ofrecidos por la bandeja de salida para consultar el número de la solicitud de descarga (10606) y un identificador de archivo a partir del documento de la solicitud de presentación de información por envío de archivos (10006). Luego a través del Servlet de la bandeja de salida, se podrá descargar el archivo, el cual es un zip cuyo nombre va a ser el mismo número de la solicitud de envío de archivos, y contendrá los XML de los archivos que presentaron error durante el procesamiento de la solicitud de envío de archivos. PARÁMETROS DE ENTRADA numerosolicitud Número de la solicitud, de la cual se desea colocar los archivos de error a la bandeja de salida. long PARÁMETROS DE SALIDA colocararchivosbandeja SalidaReturn XML que contiene el estado de éxito o los errores de la operación. colocararchivosbandejasalida.xsd 17
` 2.6. Consultar archivos de la bandeja de entrada Nombre Operación DESCRIPCIÓN consultararchivosbandejaentrada Permite consultar el nombre de los archivos que se encuentran en la bandeja de entrada, filtrados por formato y versión. PARÁMETROS DE ENTRADA formato Formato para el cual se van a consultar los archivos. int version Versión del formato para el cual se van a consultar los archivos. int PARAMETROS DE SALIDA consultararchivosbandeja EntradaReturn XML que contiene el nombre de los archivos que se encuentran en la bandeja de entrada, filtrados por formato y versión según los parámetros del web service. consultararchivosbandejaentrada.xsd 18
2.7. Eliminar archivos de la bandeja de entrada Nombre Operación DESCRIPCIÓN eliminararchivosbandejaentrada Permite eliminar archivos que se encuentran en la bandeja de entrada. PARÁMETROS DE ENTRADA xmlnomarchivos XML que contiene el nombre de los archivos a eliminar de la bandeja de entrada. xmlnomarchivos.xsd PARÁMETROS DE SALIDA eliminararchivobandeja EntradaReturn XML que contiene el nombre de los archivos y el estado del proceso de eliminación de cada uno. eliminararchivobandejaentrada.xsd 19
3. Servlet DIAN Manejo de Archivos El servlet posee autenticación y por tal razón es necesario ver el apartado de configuración de seguridad, donde se explica cómo se maneja este tema por medio del Header del Request. Por tal razón la comunicación se hace a través de HTTPS. Para determinar qué operación se desea ejecutar, es necesario enviar el parámetro operación, con la operación correspondiente. 3.1. Colocar archivos en la bandeja de entrada Nombre Operación DESCRIPCIÓN Colocar Archivo en la Bandeja de Entrada Permite colocar el archivo a cargar en la bandeja de entrada, en formato XML o comprimido con varios archivos XML en su contenido. PARAMETROS EN EL HEADER DEL REQUEST Nombre Valor Descripción tipoidentificacion Código del tipo de identificación. Ver configuración de seguridad. identificacion tipoorganizacion Número de Identificación. Ver configuración de seguridad. Código del tipo de organización. Ver configuración de seguridad. nitorganizacion password NIT de la Organización, si se auténtica a nombre de una. Ver configuración de seguridad. La contraseña va codificada con UTF-8. Ver configuración de seguridad. 20
PARAMETROS EN EL GET DEL REQUEST Nombre Valor Descripción operacion 2 Operación que permite la carga de archivos. nombrearchivo Dmuisca_ccmmmmmv vaaaacccccccc.xml o Dmuisca_ccmmm mmvvaaaacccccccc.zip o signdmuisca_ccmmmmmv vaaaacccccccc.xml.xml Dmuisca_ccmmmmmv vaaaacccccccc.xmlcc: Concepto (Inserción = 01 Reemplazo = 02).mmmmm: Formato.vv: Versión del formato.aaaa: Año de envío.cccccccc : Consecutivo de envío por año. PARAMETROS EN EL POST DEL REQUEST Nombre Valor Descripción A través del stream del request, envía el archivo. PARAMETROS EN EL RESPONSE Nombre Valor Descripción Respuesta servlet archivos.xsd A través del stream del response, se envía un xml el estado de los archivos que se cargaron y/o se descomprimieron. 21
4. Web Service Organización Respuestas de Procesamiento 4.1. Informar fin de procesamiento de una solicitud de envío de archivos Para esta operación, revisar la especificación técnica de WebService Para consulta de Reportes (ver especificación Especificación de WebService Para consulta de Reportes.doc). La respuesta está definida bajo el siguiente esquema: informarfinprocesamientosolicitud.xsd 4.2. Informar fin de colocación de archivos de error en la bandeja de salida Para esta operación, revisar la especificación técnica de WebService Para consulta de Reportes (ver especificación Especificación de WebService Para consulta de Reportes.doc). La respuesta está definida bajo el siguiente esquema: informarfinprocesamientosolicitud.xsd Configuración de Seguridad IPs autorizadas por la DIAN El servicio ofrecido debe contar con una dirección pública válida en Internet para poder consumir las operaciones de los Web Services ofrecidos por carga Masiva. Esta dirección debe ser informada a la DIAN para su autorización. Solamente desde las direcciones autorizadas se podrá acceder a estas operaciones. Protocolo HTTPS El protocolo de comunicación establecido para conectarse al Web Service y al servlet de la DIAN es HTTPS. Certificados Digitales Los certificados digitales que se utilizarán para validar el mensaje SOAP deben ser emitidos por una Entidad Certificadora autorizada por la Superintendencia de Industria y Comercio. Estos certificados deben ser de tipo Servidor Seguro que permitan generar firmas automatizadas. WS-Security Como mecanismo de seguridad para el envío y recepción de los mensajes SOAP, se establece el estándar internacional WS-Security. Los mensajes SOAP tendrán que cumplir las siguientes características: 22
Para la petición SOAP: Estar firmado digitalmente. Contener el elemento Timestamp, el cual indica la fecha y hora en que se crea la petición, y la fecha y hora en que expira el mensaje. Para la autenticación ante el DIAN se deberá usar el elemento accesomuisca (que se puede encontrar en: http://muisca.dian.gov.co/ws-eys/xsd/seguridad/accesomuisca.xsd) en la cabecera (Header) del mensaje SOAP. Esta cabecera está definida en el WSDL del Web Service. La inclusión de este elemento dentro de la cabecera del mensaje SOAP varía dependiendo de la plataforma usada. Este elemento usa los siguientes atributos para permitir el acceso a DIAN: - tipoorganizacion: Tipo de la organización que va a realizar la autenticación. Los tipos de organizaciones permitidos están definidos en el XSD. - nitorganizacion: Corresponde al NIT de la organización que va a acceder. Este es requerido únicamente cuando el tipo de organización sea NIT_ORGANIZACION. - tipoidentificacion: Tipo de documento de identificación del usuario que solicita el acceso. Los tipos de documentos de identificación permitidos están definidos en el XSD. - identificacion: Número de identificación del usuario. - password: Contraseña de acceso a la DIAN. Un ejemplo es el siguiente: <soapenv:header>... <ns1:accesomuisca xmlns:ns1=»http://www.dian.gov.co/ws/seguridad» soapenv:actor=»http://schemas.xmlsoap.org/soap/actor/next» soapenv:mustunderstand=»0" ns1:tipoorganizacion=»nit_organizacion» ns1:nitorganizacion=»99999999" ns1:tipoidentificacion=»sis»ns1:identificacion=»99999999" ns1:password=»xxxxxx»></ ns1:accesomuisca> </soapenv:header> Para la Respuesta SOAP: El mensaje SOAP deberá estar firmado digitalmente. Contendrá el elemento Timestamp. 23
Autenticación vía Servlet Para la autenticación ante el DIAN a través del servlet, se deben utilizar los siguientes parámetros, que viajarán por el header del request: tipoorganizacion: Tipo de la organización que va a realizar la autenticación. Los tipos de organizaciones permitidos están definidos en el XSD. nitorganizacion: Corresponde al NIT de la organización que va a acceder. Este es requerido únicamente cuando el tipo de organización sea NIT_ORGANIZACION. tipoidentificacion: Tipo de documento de identificación del usuario que solicita el acceso. Los tipos de documentos de identificación permitidos están definidos en el XSD. identificacion: Número de identificación del usuario. password: Contraseña de acceso a la DIAN. 24
Solicitud de Presentación de Información por Envío de Archivos a Través de WebService Especificación técnica La solicitud de presentación de información por envío de archivos a través de WebService, se debe hacer por medio de un XML que viaja por SOAP y que cumpla las siguientes especificaciones: 1. Formato del XML El xml de la solicitud esta compuesto por un elemento complejo: Solicitud de envió, el cual se describe en la tabla 1. El documento XML debe cumplir con la especificación 1.0 Tercera edición. El conjunto de caracteres utilizado en el documento XML debe ser ISO-8859-1. El documento XML debe estar bien formado y ser valido de acuerdo al esquema XSD que incluye en esta especificación técnica. 25
El archivo debe contener un elemento único raíz llamado solenvio, que a su vez contendrá toda la información de la solicitud del envió: Atributo Casilla Denominación casilla Tipo Longitud Obligatoria Observaciones cpt 42 Concepto int 1 S 1 = Inserción 2 = Reemplazo 3 = Reemplazo Parcial fmt 40 Código Formato int 5 S ver 41 Versión Formato int 2 S anovig 43 Año Informado int 4 S Formato AAAA pervig 44 Periodo Informado int 2 S 0 = Si es un formato aperiódico. nomarch 46 Nombre y Extensión del Primer Archivo de Envio. string 33 S Dmuisca_ccmmmmmvvaaaacccccccc.xml cc: Concepto (Inserción = 01 Reemplazo = 02). mmmmm: Formato. vv: Versión del formato. aaaa: Año de envío. cccccccc: Consecutivo de envío por año. numarch 47 Cantidad de Archivos int 3 S numreg 48 Número Total de Registros de los Archivos de Envio. int 5 S Máximo 50.000 registros y mínimo 1 registro. numsolant 49 No. de Solicitud Anterior long 15 N Es obligatoria cuando el atributo cpt es igual a 2 ó 3. 26
Dentro del elemento raíz, encontramos otros 3 elementos que se describen a continuación. Información del interesado Este elemento único llamado interesado, contiene la siguiente información. Atributo Casilla Denominacion casilla Tipo Longitud Obligatoria Observaciones tdoc 25 Tipo de documento de identificación int 2 S Códigos externos obtenidos del dominio 109 nid 26 Número del documento de identificación int 12 S Información del remitente Este elemento único llamado remitente, contiene la siguiente información. Atributo Casilla Denominacion casilla Tipo Longitud Obligatoria Observaciones tdoc 33 Tipo de documento de identificación int 2 S Códigos externos obtenidos del dominio 109 nid 34 Número del documento de identificación int 12 S 27
2. Validaciones Validaciones Generales El archivo debe contener todos los campos definidos para el encabezado y estos campos deben estar correctamente diligenciados. La información del contenido del archivo debe corresponder al esquema XSD entregado. Los atributos que registran valores numéricos, se reportan con valores numéricos positivos, sin signos ni puntuaciones, según lo reportado por el informante o en su defecto con cero (0). Validaciones en solenvio El número de la solicitud anterior es requerido si el concepto es reemplazo o reemplazo parcial. 3. Esquema XSD A continuación se incluye el esquema XSD para esta especificación técnica. Solicitud de Presentación de Información por Envío De Archivos a Través de WebService 28
Procedimiento y Especificación Técnica para la Consulta de Reportes El objetivo de la siguiente especificación técnica es brindar la información detallada a las entidades competentes, para que puedan acceder a la Consulta de reportes a través de Web Services ofrecidos por la DIAN. Definición de los casos de uso para la consulta de un reporte a través de Web Services Los siguientes son los casos de uso de las operaciones que podrán utilizar las personas u organizaciones: Consultar un reporte Recibir la respuesta del reporte A continuación se definen cada uno de los casos de uso como operaciones de los Web Services y operaciones ofrecidas por el servlet. 1. Web Service Consulta Reporte Este servicio Web posee autenticación y por tal razón es necesario ver el apartado de configuración de seguridad, donde se explica cómo se maneja este tema por medio del Header del mensaje SOAP. 1.1. Consultar el Reporte 29 Nombre operación DESCRIPCIÓN Permite consultar un reporte a partir de los parámetros definidos xmlreportemuisca PARAMETROS DE SALIDA Descripción del nombre del reporte que se va a consultar y parámetros que se envían Reportes.xsd idoperacion consultarreporte Identificador único de la solicitud del reporte String (32 caracteres)
2. Web Service Respuesta Servicio Este servicio Web debe ser implementado por el cliente para recibir la respuesta de alguna operación realizada en Muisca y debe ser registrada la URL de respuesta para cada uno de los servicios en la DIAN. (ver especificación wsdl (WSRespuestaMuisca.wsdl) 2.1. Respuesta Servicio Nombre operación DESCRIPCIÓN recibirrespuestamuisca Envía respuesta a alguna operación realizada a través de un servicio web MUISCA. PARAMETROS DE ENTRADA xmlrespuesta XML que indica si la respuesta fue exitosa o no. RespuestaServicioMuisca.xsd Configuración de Seguridad IPs autorizadas por la DIAN El servicio ofrecido debe contar con una dirección pública válida en Internet para poder consumir las operaciones de los Web Services ofrecidos por arquitectura. Esta dirección debe ser informada a la DIAN para su autorización. Solamente desde las direcciones autorizadas se podrá acceder a estas operaciones. Protocolo HTTPS El protocolo de comunicación establecido para conectarse al Web Service y al servlet de la DIAN es HTTPS. Certificados Digitales Los certificados digitales que se utilizaran para validar el mensaje SOAP deben ser emitidos por una Entidad Certificadora autorizada por la Superintendencia de Industria y Comercio. Estos certificados deben ser de tipo Servidor Seguro que permitan generar firmas automatizadas. 30
WS-Security Como mecanismo de seguridad para el envío y recepción de los mensajes SOAP, se establece el estándar internacional WS-Security. Los mensajes SOAP tendrán que cumplir las siguientes características: Para la petición SOAP: Estar firmado digitalmente. Contener el elemento Timestamp, el cual indica la fecha y hora en que se crea la petición, y la fecha y hora en que expira el mensaje. Para la autenticación ante el DIAN se deberá usar el elemento accesomuisca (que se puede encontrar en: http://muisca.dian.gov.co/ws-eys/xsd/seguridad/accesomuisca.xsd) en la cabecera (Header) del mensaje SOAP. Esta cabecera está definida en el WSDL del Web Service. La inclusión de este elemento dentro de la cabecera del mensaje SOAP varía dependiendo de la plataforma usada. Este elemento usa los siguientes atributos para permitir el acceso a DIAN: - tipoorganizacion: Tipo de la organización que va a realizar la autenticación. Los tipos de organizaciones permitidos están definidos en el XSD. - nitorganizacion: Corresponde al NIT de la organización que va a acceder. Este es requerido únicamente cuando el tipo de organización sea NIT_ORGANIZACION. - tipoidentificacion: Tipo de documento de identificación del usuario que solicita el acceso. Los tipos de documentos de identificación permitidos están definidos en el XSD. - identificacion: Número de identificación del usuario. - password: Contraseña de acceso a la DIAN. Un ejemplo es el siguiente: <soapenv:header>... <ns1:accesomuisca xmlns:ns1=»http://www.dian.gov.co/ws/seguridad» soapenv:actor=»http: /schemas.xmlsoap.org/soap/actor/next» soapenv:mustunderstand=»0" ns1:tipoorganizacion=»nit_organizacion» ns1:nitorganizacion=»99999999" ns1:tipoidentificacion=»sis»ns1:identificacion=»99999999" ns1:password=»xxxxxx»></ ns1:accesomuisca> </soapenv:header> 31