Descripción del proceso
Carga y envio de documentos. El sistema externo carga y envía uno o mas documentos PDF para firmar. El envío de documentos se puede hacer de dos formas:
a. Envío de documentos en base64 dentro de un json e invocando la api de tipo POST“/api/v1/externos/proceso1”, un ejemplo es:
Figura 2. Ejemplo de iniciar proceso base64
b. Envio de documentos utilizado 2 apis, la primera “carga de archivo” api “/api/v1/ex-ternos/archivo” envía cada documento y devuelve un identificador de documento que después se utilizará para iniciar el proceso de firma, los identificadores de archivos van dentro de un json y se envían a la api “/api/v1/externos/proceso2”, los ejemplos de lo anterior son:
Carga de archivo.
Figura 3. Ejemplo de carga de archivo (uno por uno)
Envío de Json con los idenƟficadores de archivos, previamente cargados
Figura 4. Ejemplo de iniciar proceso con los identificadores de archivos.png
En el body en ambos procesos se debe de agregar algunas propiedades opcionales, nombreSistema, cantidadFirmantes, fechaExpiracion, urlNotificacion, urlRetorno. Se amplía esto más adelante en la documentación de cada api.
Las apis de inicio de proceso devuelvén un identificador, claveSeguridad y fechaExpiracion, siendo el identificador y claveSeguridad necesarios para identificar al proceso defirma.
Redirección a “firma.gub.uy”
Una vez que la aplicación externa comenzó un proceso de firma, obtiene como resultadoun identificador y una clave de seguridad, el usuario del sistema externo debe ser redirigido a una página específica de la plataforma para que pueda realizar la firma del documento.
Esta página es identificada por la siguiente URL:
https://<host>:<port>/es/pp/firmar?id=c44c34b4-4d1f-4b1f-b5db-1639e55ff504&pass=58d2b20e-52f4-43fa-a4a7-d051bd48630c
Donde “c44c34b4-4d1f-4b1f-b5db-1639e55ff504” debe ser sustituido por el identificador del proceso y “58d2b20e-52f4-43fa-a4a7-d051bd48630c” es la clave de seguridad, asignado por la plataforma al proceso de firma.
En la plataforma de “firma.gub.uy”.
- La plataforma identifica el proceso de firma por medio de “id” y “pass” pasados comoparametros.
- Dentro de la plataforma el usuario debe de elegir como quiere firmar, la plataformaguiará dependiendo su elección
- En el caso que seleccione firmar con Antel o Abitab la firma se completara en la plataforma de ellos, siguiendo los pasos que se indiquen, como punto final este proceso incluye el envío de los documentos firmados al servidor.
- Si selecciona firmar con dispositivo, tendrá las opciones de firmar con cédula, tokenabitab o token correo, en todos estos casos la firma se hará descargando un archivocon extensión “.firmagubuy” que la plataforma le guiara hasta llegar a la descarga. Luego se abrirá este archivo el cual a su vez abre al aplicativo de firma en donde se completará la firma. Como punto final el aplicativo de firma enviara al servidor los archivos firmados mediante apis.
La plataforma detecta que se ha completado el proceso de firma
La plataforma de “firma.gub.uy”, se quedó esperando, cuando detecta que el proceso defirma ha sido completado, la plataforma hará una redirección hacía la url de retorno pro-porcionada al inicio del proceso de firma, agregando como parámetro el estado del proce-so de firma.
De regreso al sistema externo
El sistema externo, podra consultar el estado del proceso de firma (si lo esƟma convenien-te) haciendo esto por medio del api “{URL}/api/v1/externos/estado/681c0f6b-e3f1-483a-91b8-a74a5c76a575”, se detalla un ejemplo en la siguiente imagen.
Figura 5. Ejemplo de consulta de estado de proceso de firma
Descarga de documentos
El sistema externo invoca el api para descargar los documentos, aquí tiene 2 opciones.
Descargar documento uno a uno, invocando la api “{URL}/api/v1/externos/archivo/598e3a87-3894-4678-9cb2-a4a3f1dadf87”, siendo en este caso “598e3a87-3894-4678-9cb2-a4a3f1dadf87” el identificador de archivo que deseamos descargar . Para usar esta op-ción se debe de iniciar el proceso de firma desde el api “/api/v1/externos/proceso2”y el sistema externo debe de guardar los idenƟficadores de archivos asociados al pro-ceso, para pedir los archivos individualmente por medio de estos. (ver documentaciónde api)
Figura 6. Ejemplo de descarga de archivo (individual)
Descargar de documentos todos juntos, se uƟlizara el api “{URL}/api/v1/externos/ar-chivos/681c0f6b-e3f1-483a-91b8-a74a5c76a575” siendo “681c0f6b-e3f1-483a-91b8-a74a5c76a575” el idenƟficador del proceso de firma. Esta api nos devolverá en un jsonel listado de archivos en base64. Ejemplo:
Figura 7. Ejemplo de obtener documentos firmados (todos).png