DEPOSITARIO FIEL Aplicativo Visualizador de Carpetas Digitalizadas Especificación de Intercambio de Información AFIP PSAD Última Actualización 17/02/2014 Página 1 de 11
Historial de modificaciones Versión Fecha Descripción 1.0.0 29/01/2010 Versión inicial del Documento 1.1.0 22/02/2010 Incorporación de Diagrama faltante y aclaraciones producto de las consultas recibidas. 1.2.0 19/05/2010 Incorporación de un nuevo servicio de Registro de PSAD y sus implicancias con la interfaz Visualizador. 1.3.0 20/05/2010 Incorporación de proceso de Homologación de la Implementación. 1.3.1 21/05/2010 Especificación de los Actores intervinientes y aclaración de términos dentro del documento. 1.3.2 28/05/2010 Modificación de método para solicitar el Certificado Digital 2.0.0 27/07/2011 Modificación del Ticket de solicitud de acuerdo a la nueva reglamentación AFIP. 2.1.0 02/09/2011 Incorporación al Ticket de solicitud un dato adicional 2.2.0 06/09/2011 Incorporación al Ticket de solicitud datos adicionales únicamente para la interfaz AFIP sobre los documentos enviados por el servicio SETIDJ. 2.3.0 04/01/2011 Incorporación al Ticket de solicitud el HASH enviado en el aviso de digitalización para solicitar a los Digitalizadores información que fuera redigitalizada previo a la implementación de las Rectificativas A y B. 2.3.1 17/07/2012 Incorporación de códigos de error. 3.0.0 17/02/2014 Nueva versión preliminar para atender la necesidad de visualización de Legajos Electrónicos de Viaje del Medio de Transporte Página 2 de 11
1 Objetivo El presente documento define el esquema a utilizar para la visualización de documentación digitalizada. El documento esta dirigido a personas de perfil técnico encargadas del desarrollo de la interfaz para el intercambio de información con la AFIP, ya sea un PSAD u otro operador - debidamente autorizado - que haya optado por desarrollar Servicios Web específicos para este propósito. 2 Esquema General El siguiente gráfico presenta el esquema definido para la arquitectura del intercambio de documentación digitalizada implementada por el aplicativo visualizador. El mismo contempla los siguientes actores: Usuario AFIP: Es un operador de la Administración Federal de Ingresos Públicos utilizando un servicio interno. Aplicativo Visualizador: Servicio Interno desarrollado por AFIP que será utilizado por el Usuario AFIP y enviara requerimientos al Servicio desarrollado por el Ente Digitalizador. Ente Digitalizador: Es la persona o empresa responsable por el proceso de digitalización y archivo de la documentación. Puede ser un PSAD u otro operador - debidamente autorizado - que haya optado por desarrollar Servicios Web específicos para este propósito. El Usuario AFIP ingresará al Aplicativo Visualizador autenticado de acuerdo a sus propias normas de seguridad informática. En este aplicativo el usuario podrá realizar búsquedas por distintos parámetros sobre la base de datos de documentos digitalizadas. Una vez identificada el documento buscado, podrá solicitar las imágenes asociadas a ese documento de manera completa, o bien solamente un subconjunto de las mismas mediante ciertos criterios de selección. Página 3 de 11
Al realizar la solicitud de los documentos digitalizados, el Aplicativo Visualizador identificará al Ente Digitalizador que ha realizado la digitalización de la documentación y generará una solicitud al servicio Web publicado por esta entidad. Esta solicitud será implementada a través de un ticket de solicitud (ver punto 3.1) firmado digitalmente y codificado en formato Base64 para asegurar el correcto intercambio entre plataformas. El servicio Web de la entidad deberá recibir el ticket de solicitud, verificar su integridad, interpretar la solicitud realizada y generar como resultado un documento PDF conteniendo las digitalizaciones solicitadas, una imagen por página, sin incorporar formatos, leyendas, inscripciones, logos, o cualquier agregado que no corresponda con los documentos digitalizados. En el documento PDF generado el ente digitalizador deberá respetar el orden en que fuera digitalizado cada documento incluido en cada uno de los avisos de digitalización. Para iniciar la operación en producción de ésta solución, el Ente Digitalizador deberá primero homologar su implementación con la AFIP. El punto 6 Proceso de Homologación de la Implementación del presente documento describe los pasos a seguir por un Ente Digitalizador que ha decidido consumir los WebServices de Aviso de Digitalización y por consiguiente desarrollará y homologará también la interfaz de intercambio de información para el Aplicativo Visualizador AFIP. 3 Requerimientos técnicos 3.1 Ticket de Solicitud El ticket de solicitud se representa como un documento XML versionado con el siguiente formato: <?xml version='1.0'?> <req version="3.0"> <id unique_id="req#" src="dn del Emisor" dst="cuit del Receptor" gen_time="abs_time" exp_time="abs_time"/> <operation type="[folder-req trip-req]" response="online"> <folder id="id Legajo" codigo="código de Tipo de Documento" sigea="nro de SIGEA" nro_ticket="número de Ticket" hash="hash-info"> <info-afip envio="transaccion_afip" tipo= Original/Rectificativa situacion= Ratificado/NoRatificado vigente= S/N /> <doctypes> <doctype id="id Familia Doc" />... <doctype id="id Familia Doc" /> </doctypes> </folder> <trip id= ID Viaje codigo=" Código de Tipo de Documento"> <doctypes> <doctype id="id Familia Doc" /> Página 4 de 11
... <doctype id="id Familia Doc" /> </doctypes> <pages from="nnnn" count="nn" /> </trip> </operation> </req> El ticket se encuentra versionado, para permitir y administrar metodológicamente las modificaciones que puedan llegar a resultar necesarias con la evolución de este mecanismo. La AFIP se compromete a publicar la documentación correspondiente a la nueva versión del ticket con una anticipación mínima de 30 días a la fecha prevista de su implementación. La versión actual del Ticket es la 3.0 que será implementada en Marzo de 2014, fecha en la que la versión anterior (2.3) quedará deshabilitada. En esta nueva versión se incorpora un nuevo tipo de requerimiento (trip-req) al existente actualmente (folder-req). Este requerimiento responde a la necesidad de solicitar al Ente Digitalizador documentación del Legajo Electrónico del Viaje del Medio de Transporte. La estructura <folder> utilizada para solicitar información de Legajos Aduaneros no sufre alteraciones, por lo que aquellos Entes Digitalizadores que no procesen documentos del tipo Legajo Electrónico del Viaje del Medio de Transporte no necesitaran realizar mayores adaptaciones a sus sistemas, simplemente soportar la versión 3.0 del ticket. Referencias <id unique_id= REQ# : Cada ticket generado será identificado con un numero entero de un máximo de 16 dígitos, único para el momento en que se genero (aleatorio). <id src= DN del Emisor : Contendrá la información del certificado digital (Distinguish Name) utilizado por el servicio emisor (AFIP). <id dst= CUIT del Receptor : C.U.I.T. de la entidad que ha declarado haber digitalizado el legajo. <id gen_time= abs_time : Instante de generación del ticket. Valor abs_time. <id exp_time= abs_time : Tiempo de expiración del ticket. Valor abs_time. abs_time: Es un número entero en formato decimal que representa el tiempo según las especificaciones Posix. Representa la cantidad de segundos desde el 1 de enero de 1970, 0hs GMT. La función que normalmente devuelve este valor es time() o gettimeofday(). <operation type= [folder-req trip-req] : Cada ticket de solicitud indica que solicitud se está realizando. A partir de la version 3.0 del ticket se aceptan operaciones folder-req (Requerimiento de Legajos Aduaneros) o trip-req (Requerimiento de Legajos Electrónicos del Viaje del Medio de Transporte). Dependiendo del tipo de operación indicado en este atributo será la presencia o no de las estructuras <folder> y <trip>. <operation response= online : El ticket incluye el tipo de respuesta esperada por el usuario a la solicitud realizada. Actualmente, el único tipo de respuesta habilitado es la respuesta en línea al solicitador (online). <folder id= ID Legajo : Este elemento indica cual es el legajo que se esta solicitando. El valor es un alfanumérico de 16 posiciones. Página 5 de 11
<folder cuit_desp= CUIT Despachante : El elemento indica en un número entero de 11 posiciones la CUIT del Despachante asociado al Legajo solicitado. [Campo ELIMINADO] <folder codigo= Código de Tipo de Documento : Este elemento indica cual es código asociado a la carpeta. El valor es un numérico de 3 posiciones, completado con ceros a izquierda. o 000 Carpeta Original o 001 Documentación Adicional o 002 Rectificativa A o 003 Rectificativa B o 004 Documentación Post Libramiento <folder sigea= Nro de SIGEA : Este elemento indica cual es el número SIGEA asociado a la multinota electrónica presentada para una rectificativa. Es un valor opcional, con el formato: NNNNNNNNNN-NNNNNNNNNNNNNNN-AAAA/NNNN (Código de Área AFIP- Numero Documento-Año/Alcance). El código de Área AFIP es un valor numérico de un máximo de 10 dígitos, el Número de Documento es un valor numérico de un máximo de 15 dígitos. El año es un valor numérico de 4 dígitos y el alcance es un valor numérico de un máximo de 4 dígitos. Ninguno de los valores será completado con ceros a izquierda. El alcance es un dato opcional y puede no aparecer. En ese caso el formato será NNNNNNNNNN-NNNNNNNNNNNNNNN-AAAA. <folder nro_ticket= Número de Ticket : Este elemento indica cual es el número de ticket de entrega de documentación Adicional (Código 001) emitido por la Aduana. Numérico de 24 posiciones. <folder hash= HASH-INFO : Este elemento opcional se utilizara para identificar a los envios que fueran redigitalizados por el Digitalizador previo a la implementacion de las Rectificativas A y B. <info-afip envio= TRANSACCION_AFIP : Este elemento de Uso exclusivo AFIP indica el número de transacción asociado al envío realizado por el Declarante a traves del sistema Presentación de Declaraciones Juradas y Pagos. <info-afip tipo= Original/Rectificativa : Este elemento de Uso exclusivo AFIP indica si se deberá obtener las imágenes digitalizadas en el envio original o en la rectificativa del legajo. <info-afip situacion= Ratificado/NoRatificado : Este elemento de Uso exclusivo AFIP indica si las imágenes solicitadas se encuentran Ratificadas o No. <trip id= ID Viaje : Este elemento indica cual es el numero del viaje. Es la referencia univoca y aglutinador de toda la documentación asociada al viaje. El formato es AAAAVV999999999X, donde AAAA corresponde al año de generación del viaje, VV el código numérico de Vía asociado a ese viaje, 999999999 es el numero secuencial del viaje y X el digito verificador del código. <trip codigo= Código de Tipo de Documento : Este elemento indica cual es código asociado a la carpeta. El valor es un numérico de 3 posiciones, completado con ceros a izquierda. o 001 Manifiesto Original de Importación Página 6 de 11
<doctype id= ID Familia Doc : Cada solicitud puede incluir 0, 1 o varias familias de documentos. Si la solicitud no incluye una familia de documentos, entonces la respuesta deberá incluir todas las familias de documentos incluidas en la carpeta. En caso de contener 1 o más familias identificadas, la respuesta deberá contener solo aquellos documentos digitalizados que correspondan a las familias solicitadas. (Detalle de Familias de Documentos en http://www.afip.gob.ar/depositariofiel/ Información Especifica ) <pages from= NNN : Indica el número de foja inicial dentro de la documentación seleccionada a partir de la cual se comenzara a adjuntar las paginas digitalizadas. La numeración de páginas se tomará de la cantidad de fojas indicadas en el Aviso de Digitalización realizado por el Ente. <pages count= NN : Indica la cantidad de paginas a incluir en el PDF solicitado. La numeración de páginas se tomará de la cantidad de fojas indicadas en el Aviso de Digitalización realizado por el Ente. Si el valor del atributo es cero (0) entonces se deberá devolver la totalidad de las paginas correspondientes a la selección realizada. 3.2 Firma El servicio Web destino deberá verificar o controlar la firma utilizando el certificado digital correspondiente al DN del Emisor informado en el ticket de solicitud. AFIP publicará en el sitio http://www.afip.gob.ar/depositariofiel el certificado digital utilizado para firmar las solicitudes, así como el certificado raíz de la Autoridad Certificante AFIP emisora de los certificados digitales utilizados para esta implementación. 3.3 Dirección del servicio destino El punto de acceso al servicio deberá ser de forma segura mediante la utilización de SSL (empleando el protocolo HTTPS) para lo cual deberá contar con un certificado digital que será emitido por AFIP para este propósito específico y a pedido del interesado. El documento Especificación Técnica de certificados emitidos por AFIP para Sitios Seguros de PSAD publicado en el Micrositio http://www.afip.gob.ar/depositariofiel brinda mayor información al respecto. Esta URL de acceso deberá ser referenciada mediante su FQDN (fully qualified domain name) del servidor en el que reside el servicio y no mediante una dirección IP. Dicho FQDN deberá estar disponible en el Servidor de Nombres (DNS) correspondiente al dominio. A este punto de acceso, el aplicativo Visualizador enviará por POST dos variables denominadas: token y sign. La variable token es la codificación base64 de la representación como texto del ticket XML, mientras sign es la codificación base64 de la firma del documento anterior (previo a la codificación en base64). Ambas codificaciones en base64 deben dar como resultado un string sin nuevas líneas o caracteres de retorno. La dirección URL del punto de acceso al servicio deberá ser informada utilizando la transacción Desistimiento / Inclusión Anexo II RG2721, donde al optar por el desarrollo del WebService, deberá informar tanto esta URL como puntos de contacto (teléfono y correo electrónico) para posibles intercambios técnicos con AFIP. Hasta tanto el Ente Digitalizador no haya informado esta dirección URL y la AFIP haya realizado el control de calidad de la implementación, no estará finalizado el proceso de acreditación y no estará habilitado para operar los WebServices desarrollados por AFIP. Página 7 de 11
3.4 Sincronización de clocks El clock del equipo que recibe el token deberá estar sincronizado a través del protocolo ntp. Dicha sincronización se podrá realizar con el servidor time.afip.gov.ar u otro servidor que preste dicho servicio. Para más información sobre el protocolo y/o para bajar el software necesario consultar: http://www.ntp.org/. 4 Obligaciones del Ente Digitalizador Utilizar esta interfaz de intercambio de información, obliga a la entidad a realizar las siguientes acciones al recibir un ticket de solicitud: 1. Verificar la firma digital de la solicitud. Utilizando el correspondiente certificado digital publicado por AFIP, deberá validar la firma del ticket de solicitud emitiendo, en caso de no validación de la firma, el mensaje de error código PSAD.V.001. 2. Validar la generación del ticket. La generación del ticket no puede ser posterior a la fecha actual. En caso de no validación, emitirá el mensaje de error código PSAD.V.002. 3. Validar la expiración del ticket. La expiración del ticket no puede ser anterior a la fecha actual (ticket vencido). En caso de no validación, emitirá el mensaje de error código PSAD.V.003. 4. Generar la respuesta a la solicitud realizada, de acuerdo a los parámetros solicitados. 5. Generar un registro de auditoria relacionado con la solicitud recibida. El mismo deberá contener la fecha y hora de recepción de la solicitud, el identificador de la solicitud, el Identificador del Legajo solicitado, el contenido completo del ticket de solicitud y el resultado generado. En caso de respuesta exitosa código PSAD.V.000, caso contrario, el código de error emitido. Es obligación del Ente Digitalizador mantener operativo el servicio que responde a las solicitudes AFIP con un up-time superior al 98%, así como solicitar y renovar el certificado digital necesario para asegurar el canal seguro HTTPS. La AFIP realizara controles periódicos sobre los servicios publicados por los Entes Digitalizadores para verificar estas condiciones. 5 Códigos de Resultado de Operación Código Descripción Observaciones PSAD.V.000 Resultado OK PSAD.V.001 Firma Inválida No se pudo verificar la firma del ticket enviado. Verificar estar utilizando el certificado digital vigente Página 8 de 11
PSAD.V.002 Ticket emitido con posterioridad a la fecha actual. publicado en http://www.afip.gob.ar/depositariofiel. El ticket ha sido generado con una fecha posterior a la fecha actual del sistema receptor. Verificar la sincronización del reloj del equipo. PSAD.V.003 Ticket vencido La fecha actual del sistema es posterior a la fecha de expiración del ticket. Esto puede deberse a que exista una dessincronización del reloj del equipo receptor, o bien que el ticket este siendo utilizado con posterioridad a su periodo de vigencia. PSAD.V.004 Formato de SIGEA incorrecto El numero de SIGEA enviado como parametro no tiene el formato esperado. PSAD.V.005 No existen imágenes No se encontraron imágenes digitalizadas para la combinación de Legajo-Número de Carpeta- Número Ticket-HASH-Familia. 6 Proceso de Homologación de la Implementación Para poder iniciar la operación en un ambiente productivo como Ente Digitalizador de documentos (ya sea PSAD o Declarante con más de 5000 declaraciones) la entidad deberá cumplimentar una serie de pasos, a saber: 1. Descargar, leer y comprender el presente documento. Es de primordial importancia ponerse al tanto de las definiciones realizadas por AFIP. Las mismas surgen del consenso de la mayoría de los actores involucrados en el sistema. 2. Solicitar los Certificados Digitales necesarios para la implementación de los Servicios informáticos requeridos por el sistema. El documento Especificación Técnica de certificados emitidos por AFIP para Sitios Seguros de PSAD publicado en el Micrositio http://www.afip.gob.ar/depositariofiel brinda mayor información al respecto. 3. Registrarse como Consumidor de WebService. Para esto deberá solicitar primero el servicio con Clave Fiscal denominado Desistimiento / Inclusión Anexo II RG2721. Mediante este servicio manifiesta su voluntar de ser incluido en los términos del Anexo II de la RG2721, por lo cual se compromete a desarrollar los servicios informáticos relacionados con el sistema. Al manifestar su voluntad de ser incluido, la transacción le permitirá registrar su información de contacto (Teléfono y Correo Electrónico) así como la dirección URL donde publicará la dirección de su servicio (ver punto 3.3). 4. Comunicarse con los contactos técnicos AFIP para realizar la homologación de sus desarrollos. Para homologar el Webservice de Digitalización, deberá comunicarse con la dirección psad_webservices@afip.gov.ar. Para la homologación de la interfaz del visualizador, la dirección a utilizar es psad_visualizador@afip.gov.ar. Para poder realizar la homologación le será solicitada la información detallada en el punto anterior, por lo que se recomienda cumpla los pasos en el orden establecido. 5. Una vez cumplimentados estos pasos y aprobada la homologación de ambos servicios, la inscripción realizada en el punto 3 quedará HABILITADA y le permitirá solicitar el WebService de Digitalización a través del Administrador de Relaciones de Clave Fiscal. Página 9 de 11
Hasta tanto la homologación no este cumplimentada, este servicio no estará disponible para el operador. 6.1 Homologación para nuevas versiones del ticket Cada vez que sea generara una nueva versión del ticket de solicitud, la AFIP realizará un nuevo proceso de homologación de todos los Entes Digitalizadores habilitados. Para esto inicialmente se distribuirá una actualización del documento Especificación de Intercambio de Información AFIP-PSAD a todos los referentes técnicos registrados. Es obligación del referente técnico informar a la dirección de correo electrónico psad_visualizador@afip.gov.ar una dirección URL de Testing habilitada en INTERNET así como por lo menos cinco legajos de prueba. De esta manera se mantendrán separados los ambientes Testing y Producción para permitir la homologación de la nueva versión del ticket sin afectar el nivel de servicio productivo de cada Ente Digitalizador. Cabe aclarar que aquellos Entes Digitalizadores que no hayan homologado la nueva versión del ticket a la fecha de implementación del mismo informada por AFIP, serán deshabilitados del sistema hasta tanto no hayan finalizado la homologación de la nueva versión. 6.2 Puntos de Control El siguiente checklist determina los puntos de control a cumplir para la homologación de la implementación del operador. Este mismo listado será utilizado por los contactos técnicos AFIP para determinar la homologación de los servicios. 1. Aspectos Generales Básicos HOMOLOGACION INICIAL PARA HABILITACION El Ente Digitalizador ha manifestado su voluntad de ser incluido en los términos del Anexo II RG2721 AFIP. El Ente Digitalizador ha solicitado y obtenido los certificados digitales necesarios para la implementación productiva de la solución. El Ente Digitalizador ha registrado la información de contacto (Teléfono y Mail) y los mismos han podido ser corroborados (llamada telefónica y respuesta recibida por correo electrónico). 2. Aspectos relativos al Visualizador El Ente Digitalizador ha declarado una URL valida. La URL declarada existe (no se obtiene error HTTP 404) y el certificado digital expuesto por la dirección coincide con el certificado emitido por AFIP para tal propósito. El Ente Digitalizador ha informado un legajo de prueba que contenga información para todas las familias de documentos habilitadas por AFIP. El test de obtención de documentos del legajo de prueba fue ejecutado exitosamente (Caso de Prueba exitoso). Página 10 de 11
El test de obtención de mensaje de error fue ejecutado exitosamente (Caso de Prueba Mensaje de Error). 3. Aspectos relativos al Consumo de los WebServices AFIP El Ente Digitalizador cuenta con la homologación de su Aplicación consumidora del Webservice de Digitalización. Una vez homologada la implementación, se habilitará a la entidad para solicitar a través del Administrador de Relaciones los WebServices provistos por AFIP para la integración de los sistemas. Posteriormente a la habilitación y de manera periódica, la AFIP ejecutará tests automáticos para controlar el nivel de servicio provisto. Para eso se tendrá en cuenta el siguiente checklist. En caso de no tener éxito en alguna de las pruebas, se emitirá un mensaje de correo electrónico al mail declarado solicitando la inmediata corrección del servicio. CONTROLES PERIODICOS 1. Testeo de la Interfaz del Aplicativo Visualizador La URL declarada existe (no se obtiene error HTTP 404) y el certificado digital expuesto por la dirección coincide con el certificado emitido por AFIP para tal propósito. El certificado digital expuesto por el servicio se encuentra vigente (control de fecha de expiración) El test de obtención de documentos del legajo de prueba fue ejecutado exitosamente (Caso de Prueba exitoso). El test de obtención de mensaje de error fue ejecutado exitosamente (Caso de Prueba Mensaje de Error). Página 11 de 11