Introducción #
En el producto ReconoSer – Modo Integrado, la aplicación Windows ReconoSer se integra con el backend del cliente haciendo uso de un servicio REST, el cual permite crear solicitudes de validación biométrica, consultar el estado de las solicitudes y cancelar solicitudes que no hayan sido finalizadas.
Ubicación del servicio #
El servicio REST ha sido expuesto en las siguientes URL:
- https://xx.xx.xx.xx:XXXX/api/Solicitudes
- https://xx.xx.xx.xx:XXXX/api/SolicitudesEstado
Recomendaciones #
Para agilizar todo el proceso de acciones sobre el servicio REST, se debe tener en cuenta lo siguiente:
- El cliente debe existir y estar activo en la DB de Olimpia.
- El cliente debe tener configurado un convenio de autenticación.
- El cliente debe tener registradas las oficinas y productos correspondientes.
- Las oficinas deben tener configuradas la máquinas para la consulta, creación o actualización de las solicitudes y su respectivo tipo de identificador (MAC, IP, NOMBRE etc…).
Las recomendaciones descritas con anterioridad, debieron haberse configurado previamente haciendo uso del portal cliente y el portal de operación, los cuales facilitan la creación de todos estos detalles, de no ser así, debe comunicarse con la línea de soporte para obtener las instrucciones a seguir.
Crear o actualizar solicitudes #
Para crear o actualiza una solicitud usted deberá enviar la petición con los parámetros correspondientes y el verbo HTTP indicado como se muestra a continuación:
- URL de servicio: https://xx.xx.xx.xx:6401/api/Solicitudes
- Verbo: POST
- Parámetros: Se deben enviar en formato JSON de la siguiente forma:
Los datos mostrados en la imagen deben ser remplazados por los valores correspondientes.
Si él envió de la petición es correcta el servicio le arrojara una respuesta como la siguiente:
Respuesta de petición:
Si es necesario, el campo “PeticionRegistrada” deberá ser almacenado teniendo en cuenta si se desea actualizar por distintas razones el estado de la solicitud a “CANCELADA”, o desea realizar un seguimiento de la
solicitud, esto se podrá hacer solo si cuenta con este identificador. Este identificador está asociado en la base de datos de ReconoSer (y es equivalente) al NUT de validación con RNEC, además, está presente en la metadata del formato de autorización de tratamiento de datos para fines de no repudio.
Nota: Los códigos de error son referenciados en el índice Apartado de excepciones
Definición de campos
Cancelar una solicitud #
Para cancelar una solicitud usted deberá enviar la petición con los parámetros correspondientes y el verbo HTTP indicado como se muestra a continuación:
- URL de servicio: https://xx.xx.xx.xx:6401/api/Solicitudes
- Verbo: PUT
- Parámetros: (idCliente, convenio, idPeticion). Estos parámetros pueden ser enviados de la siguiente forma o la que mejor se ajuste a los estándares de desarrollo que maneje.
https://xx.xx.xx.xx:6401/api/Solicitudes?idCliente=1052&convenio=EC09446C-4A5A-4C26-AF1E0C7C5C4423FF&idPeticion=3987b6b5-9b90-40a0-af8c-f5a0d6ac99d4
Si él envió de la petición es correcta el servicio le arrojara una respuesta como la siguiente:
Nota: Los códigos de error son referenciados en el índice Apartado de excepciones.
Consultar una solicitud #
Para consultar una solicitud usted deberá enviar la petición con los parámetros correspondientes y el verbo HTTP indicado como se muestra a continuación:
- URL de servicio: https://xx.xx.xx.xx:6401/api/SolicitudesEstado
- Verbo: GET
- Parámetros: (idCliente, convenio, idPeticion). Estos parámetros pueden ser enviados de la siguiente forma o la que mejor se ajuste a los estándares de desarrollo que maneje.
https://xx.xx.xx.xx:6401/api/Solicitudes?idCliente=1052&convenio=EC09446C-4A5A-4C26-AF1E0C7C5C4423FF&idPeticion=3987b6b5-9b90-40a0-af8c-f5a0d6ac99d4
Si él envió de la petición es correcta el servicio le arrojara una respuesta como la siguiente:
Petición de respuesta:
A continuación, se describen las posibles respuestas entregadas por el servicio basados en cada uno de los estados manejados por el servicio.
Si la solicitud es cancelada antes de realizar la validación de identidad obtendrá una respuesta como la siguiente:
En esta respuesta el parámetro “EstadoSolicitud” retornara “CANCELADA”
Si la respuesta de la solicitud es un “NOHIT”, siendo este el resultado al no haber coincidencia en las huellas al momento de la comparación, la respuesta que retornará el servicio será:
Dentro del flujo de la solución de ReconoSer puede realizarse el reintento de validación, aunque esta ya se haya realizado, al ser el mismo número de IdPeticion, esta retornara nuevamente a estado creada, aunque la validación haya sido correcta, como se muestra en la siguiente imagen.
Es de considerar que la petición tiene un tiempo de expiración, este es uno de los parámetros al momento de realizar la petición, en este escenario si la petición ha expirado, retornara estado “CANCELADA” en el parámetro “EstadoSolicitud” como se muestra en la siguiente imagen:
Es de considerar que la autocancelación solo es considerada si la aplicación de ReconoSer se encuentra en ejecución o en su defecto que esta esté ejecutándose durante el tiempo en que expira la solicitud.
Nota: Si el campo “Respuesta Solicitud” NOHIT o CANCELADA la información del candidato no será devuelta por el servicio, los códigos de error son referenciados en el índice Apartado de excepciones en caso de que requiera los parámetros CodigoError y DescripcionError tendrán sus respectivos valores.
Apartado de excepciones #
En esta tabla se describen los códigos de excepción que arroja la aplicación durante el envío de solicitudes al servicio REST.
Se presenta cuando el convenio de autenticación no existe aún o este no se encuentra activo.
Descripción error: El convenio de autenticación no existe o no está activo.
Se presenta cuando la oficina no existe aún para el cliente o esta no se encuentra asociada al convenio de autenticación.
Descripción error: La oficina, no existe para el cliente.
Se presenta cuando el producto no existe aún o este no tiene relación con la oficina.
Descripción error: El producto, no existe para el cliente.
Se presenta cuando el tipo de identidad no existe aún o este no tiene relación con el tipo de identidad configurado.
Descripción error: El tipo de identidad para la máquina, no existe.
Se presenta cuando el nombre de la maquina no tiene relación alguna con la oficina configurada.
Descripción error: La máquina, no pertenece a la oficina
Se presenta cuando el nombre de la maquina no tiene relación alguna con el cliente configurado.
Descripción error: La máquina, no existe para el cliente.
Se presenta cuando la maquina ingresada para la consulta de una solicitud especifica no es encontrada durante la validación de la petición al servicio REST.
Descripción error: La máquina ingresada para la consulta no existe.
Se presenta cuando el cliente no existe en la base de datos o este se encuentra en estado “Activo”
Descripción error: El cliente no existe o no está activo.
Se presenta cuando el tipo de documento no concuerda con el que se configuro en el convenio de autenticación
Descripción error: El tipo de documento, no es válido para el convenio
Se presenta cuando el tipo de documento no existe en la base de datos.
Descripción error: El tipo de documento, no existe.
Se presenta cuando, durante la creación o actualización de una solicitud se presenta un error de origen indeterminado.
Descripción error: Error al crear o actualizar la solicitud.
Se presenta en el momento en el que se desea cancelar la solicitud, pero esta ya fue usada es decir cambio su estado a un estado diferente de “CREADA”, en cuyo estado debe encontrarse la solicitud para poder ser cancelada correctamente.
Descripción error: La solicitud, está siendo o ya fue utilizada y no se puede cancelar.
Se presenta cuando, el id de la solicitud suministrado en la petición no se encuentra relacionado con el cliente o este no existe en la base de datos
Descripción error: La solicitud, no existe para el cliente.
Se presenta cuando, el estado del proceso no existe en la base de datos.
Descripción error: El estado no existe.
Se presenta cuando, el resultado del proceso no existe en la base de datos.
Descripción error: El resultado no existe.
Se presenta cuando, la petición no cuenta con registros del proceso en la base de datos.
Descripción error: No existen procesos para la solicitud
Se presenta cuando, el convenio ingresado en la petición no se encuentra registrado en la base de datos.
Descripción error: El cliente aún no tiene configurado ningún convenio.
Se presenta cuando, en la consulta de peticiones por maquina no se encuentran solicitudes relacionadas.
Descripción error: No se encontraron solicitudes.
Se presenta cuando, el cliente no se encuentra en estado “Activo”.
Descripción error: El cliente no se encuentra activo.
Se presenta cuando, el cliente no se encuentra registrado en la base de datos.
Descripción error: El cliente no existe en la base de datos.
Se presenta cuando, la solicitud o petición no existe en la base de datos.
Descripción error: La solicitud o petición no existe
Propiedad de Olimpia #
El presente documento es de carácter confidencial y está protegido por las normas de derechos de autor, cualquier reproducción, distribución o modificación total o parcial a usuarios no autorizados o cualquier uso indebido de la información confidencial será considerado un delito conforme a lo establecido por el Código Penal y Leyes vigentes del estado colombiano.