Implementación de firma electrónica usando el webservice o API de Mifiel

Con la API de Mifiel puedes implementar flujos de firma digital personalizados directamente en tu página web.

Existen varias formas de utilizar la API de Mifiel. En este post vamos a describir de manera conceptual los pasos necesarios para integrar Mifiel de tal manera que tus usuarios puedan firmar dentro de tu página o aplicativo.

Para esta integración se asume que tu servidor genera documentos en formato PDF listos para que tus usuarios los firmen. Es posible hacer uso de templates con la API, pero esta funcionalidad no se cubrirá en este escrito (contáctanos para platicar sobre esto, puedes usar el botón en la parte inferior derecha de la página para abrir nuestro chat).

La API de Mifiel se compone de dos partes. La primera es una API REST con librerías para varios lenguajes de programación que te permiten subir documentos para enviar a firma y que también te notifica cuando estos son firmados. La segunda es un widget de javascript que puedes incluir en tu página para que tus usuarios visualicen y firmen documentos sin tener que salir de tu sitio web. Es un iframe que se encarga de la criptografía necesaria para generar las firmas de manera que tú no tengas que preocuparte de esta parte.

Paso 1 – Crear un documento 

Vamos a suponer que quieres crear un documento con dos firmantes. Por medio de un POST le pasas al servidor de Mifiel un documento en formato PDF junto con varios parámetros. Entre estos parámetros vas a incluir:

a) El correo de cada uno de los firmantes. En este ejemplo serían dos correos.

b) Dos URLs para que hagamos callbacks a tu servidor. Una de las URLs será para recibir eventos de firma que se disparan cada que un firmante firma. La otra URL será para recibir un callback cuando todos los firmantes hayan firmado el documento. Puedes usar la misma URL para ambos callbacks y tú filtrar el tipo de llamada usando código.

La respuesta del servidor de Mifiel a tu POST va a contar con varios parámetros entre los cuales vas a ver dos números llamados widget_ids, uno para cada firmante. Si tuvieras tres firmantes obtendrías tres widget_ids, cuatro firmantes, cuatro widget_ids, etc.

Es importante que guardes estos widget_ids ya que los vas a necesitar al implementar el widget de firma para tus firmantes.

Paso 2 – Tu usuario firma usando el widget

Una vez que tu servidor creó el documento y recibiste los widget_ids es momento de mostrarle el widget a tus usuarios. Para esto tienes que incluir el código del widget en la página en dónde quieres que se lleve a cabo la firma y pasarle al widget el widget_id de cada usuario. Si le estás presentando el documento al usuario 1 debes pasarle al widget el widget_id correspondiente al usuario 1. Al usuario 2 le vas a pasar el 2 y así sucesivamente.

El widget mostrará a tus usuarios el documento a firmar y les permitirá hacerlo ejecutando la criptografía de firma “browser side” de tal manera que la llave privada y contraseña de tu usuario no salgan de su navegador, respetando así los lineamientos establecidos por el Código de Comercio y por lo tanto contribuyendo a garantizar la presunción de atribución.

Durante el proceso de firma, el widget genera eventos de JavaScript que tu página puede usar para disparar acciones. Por ejemplo, si el usuario ingresa una contraseña errónea de su FIEL o e.firma se generará un evento de error. Puedes ignorar los eventos de error ya que Mifiel se encarga de mostrarle al usuario los errores, pero hay un evento que no debes ignorar: el de firma exitosa. Cuando el usuario firme exitosamente, el widget generará este evento el cual es recomendable que utilices para llevar a tu usuario al siguiente paso que debe seguir dentro de tu página.

Aquí puedes ver un ejemplo del código y de cómo se ve el widget. El código de este ejemplo apunta a sandbox.mifiel.com, nuestro servidor de pruebas. Para producción tienes que modificarlo para que apunte a mifiel.com.

Paso 3 – Callbacks

Si pasaste una URL para recibir callbacks de los eventos de firma, cada vez que uno de los signatarios firme, Mifiel hará una llamada de tipo POST a tu servidor con información sobre la persona que acaba de firmar.

De igual manera, cuando todos los signatarios firmen, Mifiel hará un POST a tu servidor para notificar que el documento ha sido firmado. Entre los parámetros de la llamada se incluye una liga para que tu servidor descargue el documento firmado en formato XML, así como la representación gráfica en formato PDF.

Para ambos tipos de llamadas el servidor de Mifiel espera que contestes con un 200. En caso de que tu servidor no conteste, o conteste algo diferente, el servidor de Mifiel volverá a intentar en 10 minutos. Mifiel hace 10 de estos intentos espaciados 10 minutos entre sí. 

Cuando recibes el POST con la liga de descarga del documento y tu servidor contesta con un 200 se da por terminado el ciclo de firma de un documento.

Alternativas de implementación

En caso de que no requieras que tus usuarios firmen en tu página, es posible hacer la integración de tal manera que tu servidor genere el documento, Mifiel recabe las firmas y notifique a tu servidor por medio del callback cuando este haya sido firmado por todas las partes. Para este escenario sólo se requieren los pasos 1 y 3.

También existe otro esquema de implementación que te permite integrar el widget de firma en tu página pero sin compartir los documentos con Mifiel. Esta modalidad es útil cuando por un tema de seguridad o regulatorio no quieres/puedes compartir la información contenida en tus documentos con proveedores externos.

¿Cómo iniciar?

Probablemente después de leer la teoría de implementación de la API de Mifiel —como buen programador— ya te están entrando las ganas de pegarle al código. Para iniciar debes: 

  1. Crear una cuenta en el Sandbox de Mifiel.
  2. Cuando tengas una cuenta creada y confirmada ve a la sección de “Mi cuenta” en “Mi perfil” y en la sección Reclamar Cupón ingresa el código SANDBOX. Esto acreditará 500 documentos de prueba a tu cuenta. En caso de que te los termines contáctanos por chat o correo para asignarte más.
  3. Genera tus Access tokens para poder autenticar tus llamadas por la API.
  4. Revisa la documentación de la API en http://docs.mifiel.com/.
  5. Opcional: Si no tienes una FIEL/e.firma a la mano puedes generar una de prueba aquí. Tienes que ingresar tus datos correctos (Nombre, RFC y CURP) ya que se valida que las estructuras del RFC y la CURP sean correctas.
  6. Opcional: Instala alguna de las librerías que tenemos en https://github.com/Mifiel. Actualmente hay librerías para PHP, Ruby, Java, Python, Javascript (Node), y C# (.NET).

Cuando estés satisfecho con tu código, pasar a producción es simple. Crea una cuenta en mifiel.com, obtén tus Access tokens y asegúrate de que todos tus endpoints —incluyendo el del widget— apunten a producción en vez de a Sandbox.

Conclusión

Utilizando la API de Mifiel puedes fácilmente integrar la funcionalidad de firma electrónica avanzada en tu página en cuestión de días. Además, debido a la implementación por medio de widget no es necesario que te preocupes por el manejo de las llaves privadas y contraseñas de tus usuarios.

¿Quieres preguntar sobre nuestra API?

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *

Quizá también te interese