WebService. Versión Preliminar. whelperdeclaracion. Manual del Desarrollador. Validaciones para la Carátula de una Declaración.

Transcripción

1 WebService whelperdeclaracion Manual del Desarrollador Fecha: 31/05/2017 Versión Preliminar

2 Contenido INTRODUCCIÓN... 3 OBJETIVO Y ALCANCE... 3 PRERREQUISITOS... 3 TERMINOLOGÍA Y ACRÓNIMOS... 3 ESPECIFICACIONES DEL SERVICIO... 4 PROPIEDADES DE LA ESTRUCTURA AUTENTICACION... 5 MANEJO DE LAS TRANSACCIONES... 5 TABLAS DE REFERENCIA... 5 WS DE NEGOCIO... 6 MÉTODOS... 6 CLASES DEL SISTEMA CÓDIGOS Y MENSAJES DE ERROR... 12

3 INTRODUCCIÓN OBJETIVO Y ALCANCE Presentar los lineamientos para el consumo del WS whelperdeclaracion por parte de los sistemas pertenecientes al Ministerio de Modernización, a fin de informar las siguientes acciones: Validación de Agente Validación de Subregimen / Tipo de Declaración PRERREQUISITOS Para poder invocar al WS, AFIP cuenta con otro WS de autenticación donde previamente deberá gestionar el ticket de Conexión con el cual será validado el ingreso al WS de negocio. La información de cómo gestionar el ticket y los certificados correspondientes se encuentran en los siguientes link: Consideraciones Generales: WSAA - WebService de Autenticación y Autorización: Por cualquier consulta referida al proceso de Autenticación y Autorización de WS en el ambiente de homologación dirigir mail a la siguiente dirección de correo: webservices@afip.gob.ar TERMINOLOGÍA Y ACRÓNIMOS No aplica. Página 3 de 13

4 ESPECIFICACIONES DEL SERVICIO Nombre NameSpace URL Testing URL Producción ValidarAgente whelperdeclaracion Ar.Gob.Afip.Dga.whelperdeclaracion Parámetro Parámetros de Entrada argwsautenticacionempresa argvalidaragenteparams Resultado de Salida ValidarAgenteRta Tipo WSAutenticacionEmpresa ValidarAgenteParams ValidarTipoDeclaracion Verifica si el agente informado se encuentra habilitado para operar Parámetro Tipo Parámetros de Entrada argwsautenticacionempresa WSAutenticacionEmpresa argvalidartipodeclaracionparams ValidarTipoDeclaracionParams Resultado de Salida ValidarTipoDeclaracionRta Dummy Verifica si el tipo de declaración (subregimen), el IMEX y el Despachante cumplen con los requisitos necesarios para operar Resultado de Salida Estructura WSDummyResponse Devuelve variables que determinan el correcto funcionamiento del web service (conectividad con la base de datos, respuesta desde el servidor y correcto funcionamiento del servidor de tickets). DIAGRAMA DE CLASES No aplica. Página 4 de 13

5 PROPIEDADES DE LA ESTRUCTURA AUTENTICACION A excepción del método Dummy, cada método del web service tiene dos parámetros, uno para la autenticación y autorización y otro con la información propia de cada método en particular. Con respecto al primero, sus características son siempre las mismas y se detallan a continuación: Autenticacion Información para la autenticación y autorización. ATRIBUTO DESCRIPCIÓN TIPO OBL OBSERVACIONES Token Token retornado por el WSAA - S Sign Firma retornada por el WSAA - S CuitEmpresa Conectada Cuit de la empresa que se conecta String(11) S TipoAgente Código del tipo de agente que se conecta String(4) S IMEX (Importador/Exportador); IEOC (Importador/Exportador ocasional); DESP (Despachante); USUD (Usuarios Directos) Rol Rol String(4) S EXTE Aduana Número de Aduana String(3) P [NO APLICA] Lugar Operativo Lugar Operativo String(5) P [NO APLICA] MANEJO DE LAS TRANSACCIONES No posee. TABLAS DE REFERENCIA Aquellos datos que corresponden a códigos incluidos en tablas de referencia deben ser consultados utilizando el webservice wgestabref que contiene la información actualizada de los códigos disponibles para cada tabla citada en particular. Página 5 de 13

6 WS DE NEGOCIO MÉTODOS A) VALIDARAGENTE Método para validar si una CUIT se corresponde con el Tipo de Agente informado. El método retorna true en el elemento ResultadoValidacion si la validación es correcta, y false en caso de error. Si el resultado es false, se retorna también una lista de los errores detectados por medio del elemento ListaErrores. public ValidarAgenteRta ValidarAgente(ValidarAgenteParams argvalidaragenteparams) Estructura del método <?xml version="1.0" encoding="utf-8"?> <soap:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap=" <soap:header> <WSAutenticacionEmpresa xmlns=" <CuitEmpresaConectada>string</CuitEmpresaConectada> <TipoAgente>string</TipoAgente> <Rol>string</Rol> <Aduana>string</Aduana> <LugarOperativo>string</LugarOperativo> </WSAutenticacionEmpresa> </soap:header> <soap:body> <ValidarAgente xmlns=" <argvalidaragenteparams> <CuitEmpresa>string</CuitEmpresa> <TipoAgenteEmpresa>string</TipoAgenteEmpresa> </argvalidaragenteparams> </ValidarAgente> </soap:body> </soap:envelope> Ejemplo de Respuesta <?xml version="1.0" encoding="utf-8"?> <soap:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap=" <soap:body> <ValidarAgenteResponse xmlns=" <ValidarAgenteResult> <ResultadoValidacion>boolean</ResultadoValidacion> <RazonSocial>string</RazonSocial> </ValidarAgenteResult> </ValidarAgenteResponse> </soap:body> </soap:envelope> Página 6 de 13

7 Parámetros de entrada PARAMETRO DESCRIPCIÓN TIPO CuitEmpresa CUIT a validar String(11) TipoAgenteEmpresa Tipo de Agente asociado a la CUIT String(4) Respuesta del método DESCRIPCIÓN Incluye la información del resultado de la ejecución (código y descripción del error) TIPO ValidarAgenteRta B) VALIDARTIPODECLARACION Método para validar la correcta combinación de los siguientes datos da una declaración: Subregimen Aduana de registro CUIT declarante Tipo de agente declarante CUIT Importador/Exportador Se realizan las siguientes validaciones: El subregimen y la aduana informados deben estar vigentes. Los CUITs estén habilitados. La aduana de registro permita operar el subregimen declarado. Si el subregimen declarado es de zona franca que el CUIT del declarante esté habilitado para dicha operación. El CUIT esté declarado como Gran Operador en caso de haber seleccionado un subregimen de Gran Operador. public ValidarTipoDeclaracionRta ValidarTipoDeclaracion(ValidarTipoDeclaracionParams argvalidartipodeclaracionparams) Estructura del método <?xml version="1.0" encoding="utf-8"?> <soap:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap=" <soap:header> <WSAutenticacionEmpresa xmlns=" <CuitEmpresaConectada>string</CuitEmpresaConectada> <TipoAgente>string</TipoAgente> <Rol>string</Rol> <Aduana>string</Aduana> <LugarOperativo>string</LugarOperativo> </WSAutenticacionEmpresa> </soap:header> <soap:body> <ValidarTipoDeclaracion xmlns=" <argvalidartipodeclaracionparams> <subregimen>string</subregimen> <codigoaduanaregistro>string</codigoaduanaregistro> Página 7 de 13

8 <cuitdeclarante>string</cuitdeclarante> <tipoagentedeclarante>string</tipoagentedeclarante> <cuitimportadorexportador>string</cuitimportadorexportador> </argvalidartipodeclaracionparams> </ValidarTipoDeclaracion> </soap:body> </soap:envelope> Ejemplo de Respuesta <?xml version="1.0" encoding="utf-8"?> <soap:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap=" <soap:body> <ValidarTipoDeclaracionResponse xmlns=" <ValidarTipoDeclaracionResult> <ResultadoValidacion>boolean</ResultadoValidacion> </ValidarTipoDeclaracionResult> </ValidarTipoDeclaracionResponse> </soap:body> </soap:envelope> Parámetros de entrada PARAMETRO DESCRIPCIÓN TIPO subregimen El tipo de declaración a validar String(4) codigoaduanaregistro Código de la Aduana donde se desea validar String(3) cuitdeclarante La CUIT del que declarante de la destinación String(11) tipoagentedeclarante Tipo de agente del que declara String(4) cuitimportadorexportador La CUIT del IMEX responsable String(11) Respuesta del método DESCRIPCIÓN Incluye la información del resultado de la ejecución (código y descripción del error) TIPO ValidarTipoDeclaracionRta C) DUMMY DESCRIPCIÓN Método Dummy para verificación de funcionamiento. Utilizando este método se accede a la verificación del funcionamiento de la infraestructura con respecto a: Servidor de Aplicación. Servidor de Ticket. Servidor de Base de Datos. El método no recibe parámetros. Página 8 de 13

9 Public Function Dummy() As WsDummyResponse Parámetros de entrada <WsDummyResponse>..<appserver>String</appserver>..<dbserver>String</dbserver>..<authserver>String</authserver> </WsDummyResponse> Respuesta del método WsDummyResponse Información del estado de la conexión ATRIBUTO DESCRIPCIÓN TIPO Appserver Respuesta Servidor de Aplicación. String OK correcto, NO en caso contrario Dbserver Respuesta Servidor de Base de Datos. String OK correcto, NO en caso contrario AuthServer Respuesta Servidor de Ticket. String OK correcto, NO en caso contrario Página 9 de 13

10 CLASES DEL SISTEMA Clase: DetalleError Descripción: detalle de los errores obtenidos en la validación Utilizada en el método: ValidarAgente / ValidarTipoDeclaracion ATRIBUTO DESCRIPCIÓN TIPO TABLA DE REFERENCIA EJEMPLO OBL Codigo Código del error obtenido INT - S Descripcion Descripción del error VARCHAR2 (50) - S DescripcionAdicional Datos adicionales sobre el error y cómo solucionarlo VARCHAR2 (50) - N Clase: ValidarAgenteParams Utilizada en el método: ValidarAgente Descripción: parámetros para la validación de un Agente/empresa ATRIBUTO DESCRIPCIÓN TIPO TABLA DE REFERENCIA EJEMPLO OBL CUIT CuitEmpresa Importador/Exportador/De VARCHAR2 (11) - S spachante TipoAgenteEmpresa Tipo de Agente VARCHAR2 (4) - S Clase: ValidarAgenteRta Descripción: respuesta de la validación de un Agente Utilizada en el método: ValidarAgente ATRIBUTO DESCRIPCIÓN TIPO TABLA DE REFERENCIA EJEMPLO OBL Resultado de la ResultadoValidacion validación, true si es correcta, si no false BOOL - S RazonSocial ListaErrores Razón social correspondiente a la CUIT informada Errores obtenidos durante el proceso de validación VARCHAR2 (50) - S DetalleError - S Clase: ValidarTipoDeclaracionParams Descripción: respuesta de la validación de un Agente Utilizada en el método: ValidarTipoDeclaracion TABLA DE ATRIBUTO DESCRIPCIÓN TIPO REFERENCIA EJEMPLO OBL Subregimen El subregimen a validar VARCHAR2 (4) - S CodigoAduanaRegistro Código que identifica a VARCHAR2 (3) la Aduana de trabajo - S CuitDeclarante CUIT del Declarante VARCHAR2 (11) - S TipoAgenteDeclarante Tipo de Agente del VARCHAR2 (4) Declarante - S CuitImportadorExportador CUIT del VARCHAR2 (11) Importador/Exportador - S Página 10 de 13

11 Clase: ValidarTipoDeclaracionRta Descripción: respuesta de la validación del Tipo de Declaración ATRIBUTO DESCRIPCIÓN TIPO Resultado de la ResultadoValidacion validación, true si es BOOL correcta, si no false ListaErrores Errores obtenidos durante el proceso de validación DetalleError Utilizada en el método: ValidarTipoDeclaracion TABLA DE REFERENCIA EJEMPLO OBL - S - S Página 11 de 13

12 CÓDIGOS Y MENSAJES DE ERROR 1) ERRORES DEL NEGOCIO ValidarAgente NRO DE ERROR DESCRIPCION DEL MENSAJE OBSERVACIONES Importador/Exportador inexistente Despachante inexistente ValidarTipoDeclaracion NRO DE ERROR DESCRIPCION DEL MENSAJE OBSERVACIONES ERROR de DATOS : Anomalia en la tabla Destinación inexistente Aduana no habilitada para Grandes Operadores Código de aduana xxxx inexistente o no vigente Destinación Prohibida Código inexistente El particular realizo una operación en el último año Importador no habilitado a trabajar bajo Régimen de Grandes Operadores 2) ERRORES DE AUTENTICACIÓN CÓDIGO DESCRIPCIÓN 0 OK Procesado Validación de conexión no coincide con opciones seleccionadas 6003 Validación de usuario registrado. CUIT,CUIL y/o tipo de agente invalido para el servicio 6005 Validación de CUIT/CUIL/Tipo de Agente con respecto al servicio. Rol invalido para el tipo de agente y el servicio solicitado 6006 El rol informado no está permitido para el servicio. Aduana invalida para el CUIT y el tipo de agente informados Controla que el usuario tenga domicilio registrado para la aduana informada. Solo aplica para los servicios que controlan aduana. Lugar Operativo invalido para el CUIT y la Aduana informados Controla que el lugar operativo informado se corresponda con el CUIT del usuario. Solo aplica para los servicios que controlan lugar operativo. Aduana invalida para el domicilio registrado del CUIT/Tipo de Agente Controla que el usuario tenga domicilio registrado para la aduana informada. Solo aplica para los servicios que controlan aduana. Página 12 de 13

13 Error Interno. Error inesperado; en estos casos se requiere informar a Sistemas el código de excepción que se retorna como información adicional. Token no vigente o caducado. Validación de la vigencia del token Debe ingresar la firma. Control de validez de la firma informada Debe ingresar el token. Control de presencia del token Token Inválido. El token recibido no pudo ser identificado. El Servicio no se corresponde con el informado en el Token. No existe coincidencia entre el servicio invocado y el informado en el token Cuit con el que desea operar no informado Control de presencia del campo del CUIT Tipo Agente con el que desea operar no informado Control de presencia del campo del TIPOAGENTE Rol con el que desea operar no informado Control de presencia del campo del ROL Campo xxxxx longitud invalida. Cuando el tamaño de algún campo supera el tamaño máximo esperado. El campo xxxxx no debe ser inferior a xxxxx. Cuando el dato informado es menor al esperado. Aplica a campos numéricos o fechas. El campo xxxxx no debe ser superior a xxxxx. Cuando el dato informado es mayor al esperado. Aplica a campos numéricos o fechas. El campo xxxxx tiene un formato erroneo. Debe ser xxxxx. Cuando el formato informado para el campo es inválido o distinto del esperado. Falta el dato obligatorio xxxxx Si falta algún atributo/parámetro obligatorio Página 13 de 13