Firmar un documento

Información	Detalle
Permiso requerido	FIR00
ID operación	io.documentos.firmar

Para poder firmar un documento PDF se debe seguir un ciclo de firma que involucra varios pre-requisitos y 2 APIs
distintas que permiten este proceso.

Primero, es necesario que el usuario que desea firmar, tenga configurado su doble factor de autenticación, para ello se pueden consultar
las API's io.fes.2fa.crear y io.fes.2fa.validar para permitir al usuario final configurar y validar la configuración del segundo factor de autenticación.

Opcionalmente el usuario puede establecer el aspecto que tendrá su firma digital al momento de firmar los PDF, si esto no es configurado, se utilizarán las configuraciones
por defecto. Cada usuario puede configurar esto desde su perfil de usuario en Febos, o configurarlo por medio de la API, para ver qué implica y cómo realizar este proceso,
puedes consultar la API io.parametros.configurar y conversalo con nuestro equipo técnico en un canal de slack.

Por último, para firmar un documento, primero el documento debe ser subido a Febos, para ello puedes consultar la API io.archivos.prefirmar.url ya que esta API necesita la ruta virtual
del archivo a firmar electrónicamente.

¿Qué significa prefirmar una URL? Es un mecanismo de seguridad para poder subir archivos a nuestro repositorio de archivos, de tal forma que antes de poder subir el archivo, Febos autoriza a subir ese archivo en particular. De otra forma, cualquier persona sin autorización podría subir archivos a nuestro repositorio. Al decir que la URL está "prefirmada", es porque la URL de retorno lleva una firma digital especial, que permite asegurarnos de que esa URL fue entregada por nosotros mismos.

Ciclo de vida para el firmado de un documento:

METADATA
Febos cuenta con la opción para incrustar un código QR donde se verifica el archivo firmado (este se puede incrustar siempre y cuando no este previamente firmado)
y su tamaño es de 100 X 100 píxeles.

PARAMETRO	VALOR	POR DEFECTO	DESCRIPCION
qr	si/no	no	Indica si se debe incrustar el código QR
qr-url	https:...	URL configurada en FEBOS	URL personalizada donde apuntará el QR
qr-pos-x	0	470	Posición X (cartesiana) en donde se sitúa la esquina inferior izquierda
qr-pos-y	0	0	Posición Y (cartesiana) en donde se sitúa la esquina inferior izquierda
qr-pos-h	0	60	Alto de QR a incrustar
qr-pos-w	0	60	Ancho de QR a incrustar
qr-pos-pagina	ULTIMA/PRIMERA/TODAS	ULTIMA	En que página se sitúa el QR

EJEMPLO

  {
    ...
    "meta": {
      "qr":"si",
      "qr-pos-x":"200",
    }
  }

Algunos proveedores pueden contar con particularidades en el flujo de firma, los cuales describiremos a continuación.

Firma simple

Febos

Firma de terceros se debe enviar el RUT de quien firma y se pueden agregar las siguientes metadatas

PARAMETRO	VALOR	DESCRIPCION
firma-tipo	1,2,4	Tipo de estampa para la firma a mano alzada. 1: solo el texto, 2: imagen desde S3, 4: emulacion de firma desde texto
firma-texto	texto	Si firma es de tipo 4, aqui se puede mandar un texto para construir la firma eje: Fxx
firma-imagen	febos-io/.../imagen.png	Si tipo es 2, se debe enviar la url en S3 donde se cargo la imagen de la firma
firma-template	texto 4 líneas	Texto de 4 líneas que se mostrará en la firma

en el template de la firma se pueden usar los comodines para remplazar el valor

{fechaHoraCompleta} : formato "dd' de Mes del 'YYYY' a las 'HH:mm' Hrs.'

{fechaCorta}: formato dd-MM-yyyy

{horaCorta}: formato HH:mm

{horaCompleta}: formato HH:mm:ss

Firma avanzada

Esign

Firma de terceros se debe enviar el RUT de quien firma con esto se utilizara la estampa configurada para el usuario.

Thomas Signe Atendida

Para la operación con firma atendida se requiere un paso extra, por lo cual
se genera una URL en donde el usuario se auténtica, ingresa sus credenciales y código de seguridad para poder dar
fin al proceso de firma.

Por lo cual se requiere en primera instancia enviar un parámetro de meta-data con la url (url-callback) en donde
se generara al callback de la llamada y donde se manejará para finalizar el proceso de firma en la api,
si por ejemplo tenemos una url de callback en la cual solicitamos que nos respondan en
https://url.ejemplo.cl/firmas/avanzada/ts/callback
una vez finalizado el flujo de firma esta responderá de la siguiente manera

https://url.ejemplo.cl/firmas/avanzada/ts/callback?oid=A529A35B-9854-49B2-B349-626E61FAE11C&state=OK&exeCode=a835fea0ca7542d8a5967f0fcebd6533

  {
    ...
    "meta": {
      "url-callback":"https://portal.febos.cl/..../firma/callback",
    }
  }

y tendremos que volver a llamar a la API de firma con los códigos de confirmacion de la API (oid y exeCode)
con esto se firma recupera el documento autorizado para firma y finaliza el proceso.

 {
   ...
   "meta": {
     "oid":"A529A35B-9854-49B2-B349-626E61FAE11C",
     "exeCode":"a835fea0ca7542d8a5967f0fcebd6533",
   }
 }

Podemos realizar integración de firma a nombre de otro usuario, enviando el campo rutFirmante

Flujo de firma con autorización por parte del usuario

curl --location --request POST '/documentos/firmar?aplicacion=FEB' \ --header 'token;' \ --header 'token: xx' \ --header 'empresa: 98765432-1' \ --header 'empresa: 1111111-1' \ --header 'Content-Type: application/json' \ --data-raw '{ "OTP": "034154", "tipoFirma": "SIMPLE", "adjuntoUrlS3": "/febos-io/chile/pruebas/98765432-1/contratos/ABC123.pdf", "febosId": "1f77d0f0-abde-481b-a2bb-aed9be803d34", "passwordCertificado": "miClaveSecreta123", "numeroFirma": 1, "remplazarS3": "si", "ponerQr": "si", "rutFirmante": "12345678-5", "pagina": -1, "x": 300, "y": 700, "meta": { "qr": "si" } }'

{ "codigo": 10, "duracion": 780, "hora": "2019-03-05T15:03:42.245Z", "mensaje": "Acción realizada satisfactoriamente", "febosId": "bb55b048-e8c7-490f-a353-01e5b70f480e", "seguimientoId": "bb55b048-e8c7-490f-a353-01e5b70f480e", "url": "https://archivos.febos.io/temporal/bb55b048-e8c7-490f-a353-01e5b70f480e_E76179952-5_R76179952-5_FacturaElectronica_107_.0.cpsf.pdf", "adjuntoUrlS3Firmado": "https://archivos.febos.io/temporal/bb55b048-e8c7-490f-a353-01e5b70f480e_E76179952-5_R76179952-5_FacturaElectronica_107_.0.cpsf.pdf" }

Firmar un documento

Solicitud

Respuestas