API REST 40 – bienvenido

Firma digital - FULL REST API v40 - Bienvenido

El siguiente documento tiene como objetivo dar detalles de las configuraciones y parámetros básicos para poder integrar la funcionalidad de la firma digital en tus aplicaciones de negocio mediante API REST.

Aquí encontraras todos los métodos y esquemas de firmar.online para integrar en tus procesos de negocio diferentes flujos de firma:

  • Enviar a firmar: envía documentos a otras Personas para que el firmen sobre su propio dispositivo (Firma Remota)
  • Solicitar la firma presencial en tus dispositivos: solicita la firma digital manuscrita a tus propios dispositivos
  • Firma de documentos con certificado electrónico y aplicar en sello de tiempo con garantías probatorias en servidor
  • Validar la firma digital de documentos

¿Por donde comenzar?

Paso 1: registrate y accede a tu API KEY

Lo primero, tienes que registrarte en nuestra aplicación web. Contamos con un entorno de producción, que ofrece los servicios de firma digital para tus documentos, y un entorno de pruebas (“sandbox”) que podrás utilizar para la fase de integración.

Sólo por registrarte, tendrás acceso a un paquete de 10 firmas para comenzar a funcionar!

entorno de producción

Aquí deberán estar los documentos reales
– Aplicación web: https://app.firmar.online
– endpoint API REST: https://app.firmar.online

entorno de pruebas - Sandbox

Puedes utilizarlo para pruebas de integración
– Aplicación web: https://app.firmar.info
– endpoint API REST: https://app.firmar.info

Paso 2: Integración

Aquí tienes algunos recursos que te ayudarán a integrar la firma digital en tus procesos de negocio:

Definiciones Swagger

Accede a las definiciones de los métodos en Swagger.
Recuerda que tienes una definición para cada tipo de flujo

Colección de POSTMAN

Descárgate la colección API REST para utilizarla en tus peticiones.

Esta colección contiene ejemplos de peticiones que comparten la misma estructura y parámetros de configuración.

La colección invoca distintas VARIABLES: Si estás utilizando POSTMAN, estas variables están pre-configuradas para usar como referencia, pero puedes cambiarlas segun te convenga.

Lo PRIMERO. Modificar la variable API-KEY que has generado en la WebApp en el paso anterior.

Tendrás 2 API – Key, una para Producción y otra para SandBox.

El endpoint contiene la variable: {{base_url}}/…/…

Dependiendo del ambiente en el que quieras firmar, debes modificar la variable {{base_url}}. Recuerda:

  • Sandbox: https://restapi.firmar.info
  • Producción: https://restapi.firmar.online

Paso 3: Pase a producción "estamos en el aire!!"

Si has realizado la integración en el entorno de pruebas, sólo tienes que cambiar el endpoint de producción.

Recuerda que también tienes que tomar el API KEY de la aplicación web de producción!!

Firma digital - Parámetros del API

En este apartado podrás ver los parámetros más relevantes para la automatización de tus procesos de firma digital

Widget: Posicionamiento de la firma en el documento

Es importante resaltar que la firma electrónica aplica a todo el documento, aunque se mantenga oculta o se visualice en una sola página. De forma que una sola firma electrónica garantiza que no hay modificaciones en ninguna de las páginas.

Llamamos Widget a la visualización de la firma en el documento electrónico. La definición del widget se realiza mediante tamaño (ancho y alto del rectángulo) y posicionamiento

firmar.online soporta los siguientes tipos de posicionamiento:

  • Posición fija: Se determina el número de la página en el parámetro “page” (si el numero informado es mayor que el numero de paginas, se aplica a la última página)
  • Posición flotante: se lee el contenido del documento en busca una cadena de caracteres determinada. El widget se posiciona en la primera cadena encontrada
  • Campo de firma: Adobe permite incorporar “signature fields”
  • Firma oculta: si queremos que el widget no se visualice en el documento, podemos informar Page = 1, Alto= 0 , Ancho = 0

Estado de los documentos (enviar a firmar y firma presencial)

Estos son los posibles estados de los documentos en los procesos de firma presencial y firma remota*:

  • 00 – Sin estado (None)
  • 100- Documento Creado (Created)
  • 200 – en progreso (In Process)
  • 300 Flujo de documento Completado (Completed)
  • 400 Flujo cancelado (Canceled)
  • 500 El interesado ha rechazado firmar el documento (Rejected)
  • 600 Documento eliminado (Deleted)
  • 700 Vencido: ha pasado el plazo para firmar el documento (Expired)

*Nota: recuerda que la firma digital en servidor y la validación de la firma son métodos “sincronos”. La acción se realiza en el momento de la solicitud y el documento no se guarda en el servidor. Por eso, documentos no tienen estado.

Webhook

El webhook te informará de los cambios de estado de los documentos, por lo que te permitirá realizar un seguimiento automatizado de cada uno de ellos. Aplica exclusivamente a las definiciones de “enviar a firmar” y “firma presencial”.

Recuerda que la firma en servidor y la validación de documentos firmados se realizan de forma síncrona. No tienen cambio de estado.

Puedes definir tu URL en el área de ajustes de la aplicación web.

Enviar a firmar - Comportamiento de los participantes

Cuando enviamos un nuevo sobre, podemos escoger cómo queremos autenticar al participante y qué acciones deben realizar sobre el documento.

Para ello, disponemos de los parámetros

  • authType: forma de autenticación del participante en el flujo del documento. Esta acción se realiza de forma previa a la visualización del documento.
  • actionType: Acción requerida al participante tras visualizar el documento (Aceptar el sobre, firma manuscrita, firma con OTP…)

 

authType: Posibles Valores

No es obligatorio informar este parámetro. Por defecto, toma el valor 10.

00: No se requiere autenticación 

10: Autenticación básica. El participante verá su nombre y aceptará los términos de uso 

20: Autenticación de doble factor, con clave de acceso. En la llamada se realiza una pregunta y se aporta la respuesta esperada.

40: Autenticación de doble factor, con clave OTP enviada al SMS

 

actionType: Posibles Valores

10 Notificacion. El participante recibirá el documento (anexo en un mail) y no tendrá que realizar ninguna acción sobre el mismo.

20 Aceptación: el participante aceptará el contenido del documento (el documento no se firma digitalmente )

21 Aceptación con sello de tiempo. El participante aceptará el contenido del documento (el documento se firma digitalmente con sello de tiempo)

30 Firma digital manuscrita

40 Firma con autenticación fuerte: el participante recibirá en su teléfono móvil un SMS con una contraseña de un solo uso (OTP One time password – SMS)

50 El participante realizará una firma digital manuscrita y posteriormente recibirá  en su teléfono móvil un SMS con una contraseña de un solo uso (OTP One time password – SMS)

60 Firma con el certificado electronico del usuario – CryptoAPI. Sólo disponible cuando el participante accede al documento desde un puesto PC con So windows y dispone de certificado electrónico)