API para firma electrónica: implementación en tu organización

Al evaluar una solución de firma electrónica para tu organización, uno de los puntos relevantes es si cuenta con una API y qué implica su integración para un equipo de desarrollo.

En Mifiel tenemos una API REST que permite:

Automatizar la preparación y envío de documentos a firma.
Recibir notificaciones de eventos de firma mediante webhooks.
Realizar búsquedas avanzadas sobre tus documentos pendientes de firma.
Eliminar documentos.
Integrar un widget de firma en tu sitio web.

Para resolver las dudas principales de quienes buscan una solución de firma digital con API, más allá de los conocimientos técnicos y requisitos, te mostraremos cómo se ve una implementación de API con ejemplos de código y cómo se muestra visualmente a tus firmantes al interactuar con la plataforma.

Pasos esenciales para integrar una API de firma digital

Integrar la API implica la necesidad de crear documentos y gestionar firmas. Los pasos principales para integrarla son:

Registra tus webhooks. Los webhooks son la forma en que tu sistema se entera de lo que pasa con tus documentos. Es una configuración que haces una sola vez por cuenta, no por documento: con una solicitud POST indicas la URL de tu servidor y el evento al que te quieres suscribir.
Genera tu documento. Primero tienes que generar una versión del documento que será firmado en formato PDF. Puedes ayudarte de alguna librería en tu lenguaje de programación para crear o convertir documentos a PDF. Es posible hacer uso de templates (plantillas) HTML con la API, pero esta funcionalidad no se cubrirá en este artículo (contáctanos para platicar sobre esto, puedes usar el botón en la parte inferior derecha de la página para abrir nuestro chat).
Envía el documento al servidor de Mifiel mediante la API. Esto se hace mediante una solicitud POST. Deberás incluir detalles como los correos electrónicos de los firmantes.
Presenta el flujo de firma a tu firmante. Para hacerlo dentro de tu sitio web, debes utilizar el widget de firma de Mifiel, es la parte visible de la integración de Mifiel en un sitio web, el cual se muestra como una interfaz donde los firmantes pueden revisar el contenido del documento y firmarlo. Para integrar el widget de firma en tu sitio web, debes insertar un script en tu página web el cual carga un iframe.
Obtén el documento firmado. Cuando recibas la notificación de que el documento se cerró, haz una llamada autenticada a GET /api/v1/documents/{id}/zip para descargar el paquete completo (XML, PDF y metadatos cuando aplique).

Creación de un documento desde la API

Vamos a suponer que quieres crear un documento con un solo firmante. 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 el correo de cada uno de los firmantes. En este ejemplo solo será un correo.

{
  "file": "File",
  "signatories": [{
      "email": "[email protected]",
      "name": "Nombre de Firmante",
      "tax_id": "RFC de firmante"
  }],
  "external_id": "tu-identificador-interno"
}

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.

{
  "id": "c914e1ed-a84d-465e-bee8-f3fadf7b7280",
  "external_id": "tu-identificador-interno",
  "original_hash": "f40243ee412ec8f297245feea8a489e7599c5e1b77bc4bf0e92bd3ed48d86b43",
  "created_at": "2022-01-17T16:34:15.065Z",
  "state": "pending",
  "file_file_name": "contrato-ejemplo.pdf",
  "file": "/api/v1/documents/c914e1ed-a84d-465e-bee8-f3fadf7b7280/file",
  "signers": [{
    "id": "dc9d63f6-11af-4840-af14-0e51e6da5da4",
    "email": "[email protected]",
    "name": "Nombre de Firmante",
    "tax_id": "RFC de firmante",
    "signed": false,
    "widget_id": "5suH28S3f2"
  }]
}

Debes guardar estos widget_ids ya que los vas a necesitar al implementar el widget de firma para tus firmantes de manera eficiente, de lo contrario estarías creando un nuevo documento de manera indiscriminada cada que un firmante recargue la página.

También te sugerimos enviar un external_id con tu propio identificador: lo recibirás de vuelta en las notificaciones de webhook, lo que te permite correlacionar el documento con tus registros sin necesidad de guardar el id de Mifiel.

Veamos el ejemplo en Ruby:

require 'mifiel'

document = Mifiel::Document.create(
  file: 'path/to/my-file.pdf',
  signatories: [{
    name: 'Signer 1',
    email: '[email protected]',
    tax_id: 'AAA010101AAA'
  }],
  external_id: 'tu-identificador-interno'
)

Consulta el ejemplo en otros lenguajes de programación dando clic aquí.

Firma de un documento creado mediante API

Puedes implementar Mifiel de dos maneras distintas para tus firmantes: mediante mifiel.com, para que firmen ingresando directamente a nuestra plataforma, o integrando el widget de Mifiel en tu sitio web mediante la API.

Las ventajas de la firma en mifiel.com son:

Adecuado cuando requieres que tus clientes firmen sus contratos y no puedes desarrollar una implementación propia.
La experiencia de firma está personalizada con los colores y logo de tu marca sin necesidad de escribir ni una sola línea de código.
La implementación de la API será más simple y ligera de realizar, pues no tendrás que preocuparte de integrar el proceso de firma en tu sitio web, solo te ocuparás de las automatizaciones.

Las ventajas del widget de Mifiel son:

Adecuado para integrar si tu sitio web es una plataforma que tus clientes utilizan para realizar procesos con tu organización —más allá de ser un sitio informativo— y tienes un equipo de desarrollo que puede implementar y mantener integraciones de API.
Personalización de colores, textos, tamaño del widget e información del documento.
Integración en cualquier parte de tu página ya que el widget se implementa mediante un iframe con diseño responsive.

Firmando con el widget de Mifiel

Una vez que tu servidor creó el documento y recibiste los widget_ids, es momento de mostrar el widget a tus usuarios. Para esto tienes que incluir el snippet del widget en la página en donde quieres que se lleve a cabo la firma y pasarle el widget_id de cada usuario. Si le estás presentando el documento al usuario 1, debes pasarle 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”. Así, sin importar que tus usuarios utilicen su e.firma o la firma con verificación biométrica de Mifiel, garantizamos la validez legal de la firma electrónica.

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 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, debes usarlo para llevar al usuario al siguiente paso dentro de tu página.

Aquí puedes ver un ejemplo del código y del 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.

Webhooks

Los webhooks de Mifiel te permiten recibir notificaciones sobre eventos relacionados con tus documentos sin necesidad de consultar la API continuamente.

La alternativa es consultar mediante la API el estado del documento cada cierto tiempo de manera manual o automática. Sin embargo, esto rápidamente se puede convertir en un problema cuando escalas: nuestro sistema limita las llamadas para consultar el estado de los documentos y bloquea la IP que excede ese límite, lo cual retrasaría tus procesos.

Registrar un webhook

Los webhooks se configuran a nivel cuenta con POST /api/v1/webhooks. Indicas la URL de tu servidor y el tipo de evento al que te suscribes:

{
  "url": "https://my-site.com/api/webhooks/mifiel",
  "callback_type": "document_closed"
}

La respuesta incluye el id del webhook, que vas a necesitar para consultarlo o eliminarlo después:

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "url": "https://my-site.com/api/webhooks/mifiel",
  "callback_type": "document_closed",
  "created_at": "2019-08-24T14:15:22Z"
}

Puedes revisar todos tus webhooks activos con GET /api/v1/webhooks y darlos de baja con DELETE /api/v1/webhooks/{id}.

Eventos disponibles

document_closed: el documento fue firmado por todas las partes y se generó la constancia de conservación (NOM-151).
signer_completed: cualquier participante firmó o aprobó el documento.
signer_rejected: un participante rechazó la firma o aprobación del documento.
document_deleted: un documento fue eliminado.

Descargar el documento firmado

document_closed es el evento que tu sistema debe usar para descargar el documento. El POST que recibes en tu servidor se ve así:

{
  "event": "document_closed",
  "data": {
    "id": "c914e1ed-a84d-465e-bee8-f3fadf7b7280",
    "external_id": "tu-identificador-interno",
    "file_file_name": "contrato-ejemplo.pdf",
    "signed_at": "2022-01-17T17:34:15.065Z"
  }
}

Con el id del documento haces una llamada autenticada a GET /api/v1/documents/{id}/zip, que te devuelve un paquete con todo lo que necesitas conservar.

Mifiel espera que tu servidor responda con un código de respuesta exitoso (2xx). En caso de que no conteste, o conteste algo diferente, se reintentará la entrega hasta 10 veces, una vez cada 10 minutos, y se detiene al recibir un 2xx.

Cuando recibes el webhook, descargas el zip y tu servidor contesta con un 200, se da por terminado el ciclo de firma de un documento.

Probar tu integración

Puedes disparar un webhook manualmente contra un recurso específico con POST /api/v1/webhooks/{id}/trigger, enviando el id del documento en resource:

{
  "resource": "02e85ee9-336f-4a83-851b-9b444359861e",
  "instant": true
}

Con instant: true el envío se hace una sola vez de forma inmediata, en lugar de encolar los 10 intentos. La respuesta incluye el status, los headers y el body que devolvió tu servidor, lo cual es útil para depurar tu endpoint:

{
  "status": "success",
  "request": {
    "url": "https://my-site.com/api/webhooks/mifiel",
    "body": { }
  },
  "response": {
    "status_code": 200,
    "headers": { },
    "body": "OK"
  }
}

Recomendaciones para una integración exitosa de API para firma electrónica

Cómo hacer búsquedas avanzadas en la API

Una API para firma digital debe permitirte realizar búsquedas avanzadas para optimizar tu implementación. En la API de Mifiel los atributos y relaciones están definidas, así que puedes hacer uso de cada uno dependiendo de tus necesidades.

Por ejemplo, puedes buscar documentos por una parte de su nombre, identificar todos los documentos que un firmante en específico necesita firmar, o identificar todos los documentos sin firmar para eliminarlos si ya no los requieres.

Elimina los documentos que se hayan quedado sin firmar

Es común que algunos documentos se queden sin firmar y ya no sea necesario firmar el documento, o que algún documento se suba con errores y necesites reemplazarlo por el documento correcto. Para tener una mejor organización, debes eliminar esos documentos en bloque mediante la API.

En este ejemplo hacemos la petición para que la API nos muestre todos los documentos pendientes creados entre el 1 de enero de 2021 y el 31 de julio de 2021, los cuales queremos eliminar. Estos documentos incluirán entre otros parámetros el id, que permitirá realizar llamadas en el endpoint correspondiente para eliminar estos documentos de manera más rápida.

{
  "version": "1.0.0",
  "resource": "document",
  "page": 1,
  "per_page": 20,
  "q": {
    "created_at": {
      "gteq": "2021-01-01",
      "lteq": "2021-07-31"
    },
    "state": {
      "eq": "pending"
    }
  },
  "sort": "created_at-desc",
  "fields": "file_file_name,created_at,state,id"
}

La respuesta de la API en nuestro ejemplo es esta:

{
  "_metadata": {
    "page": 1,
    "per_page": 20,
    "page_count": 1,
    "total_count": 10
  },
  "records": [
    {
      "id": "32214f64-f695-4691-8f6c-073681b05543",
      "file_file_name": "demo.pdf",
      "created_at": "2021-07-21T17:05:36.821Z",
      "state": "pending"
    }
  ]
}

Por lo tanto, tu request en Ruby debería verse así (da clic aquí para ver el ejemplo en otros lenguajes de programación):

require 'mifiel'

Mifiel::Document.delete('32214f64-f695-4691-8f6c-073681b05543')
Mifiel::Document.delete('1180ecb4-7478-4eaf-9267-e4349a238a7a')
# …

Preguntas frecuentes sobre la integración de API de firma electrónica de Mifiel

Antes de decidir implementar una API de firma electrónica como la de Mifiel, seguramente tienes dudas. Estas son algunas de las preguntas más frecuentes sobre nuestra API.

¿Cuánto tiempo toma integrar la API de firma electrónica?

No hay un tiempo promedio de integración, bien puede llevar unas pocas semanas o demorar varios meses. Esto se debe a que todo depende de la complejidad de tu sistema y al diseño e implementación entre tu sistema y el nuestro.

Si en el diseño de tu implementación no hay una idea clara de cómo quieres que sea la integración pero comienzas a escribir código de inmediato, tendrás que modificarlo o reescribirlo constantemente, retrasando tu implementación final.

¿Tienen librerías para la API?

Sí, contamos con librerías para PHP, Ruby, Java, Python, Node.js, y C#. Puedes obtenerlas en el repositorio de Github de Mifiel.

¿Tienen ejemplos de código?

Sí, a lo largo de toda la documentación de la API de Mifiel tenemos ejemplos de request y response en diferentes lenguajes de programación.

¿Puedo hacer modificaciones al widget para que sea congruente con mi página?

En general no puedes hacer modificaciones al widget de Mifiel ya que esto podría generar problemas que invaliden la firma electrónica o que impacten negativamente en la experiencia de los firmantes.

Pero hay algunas modificaciones que sí puedes realizar para asegurar la congruencia con el diseño de tu sitio web, como los colores de los botones, o el tamaño y ubicación del widget.

¿Puedo obtener mediante la API una copia del documento firmado?

Sí. Cuando recibas el webhook de document_closed, usa el id del documento para hacer una llamada autenticada a GET /api/v1/documents/{id}/zip.

¿Cómo comenzar a usar la API de firma electrónica de Mifiel?

Probablemente después de leer la teoría de implementación de la API de Mifiel, como buena persona dedicada a la programación ya te están entrando las ganas de pegarle al código. Para iniciar:

Crea una cuenta en el ambiente de pruebas (Sandbox) de Mifiel.
Cuando tengas una cuenta creada y confirmada, se te acreditarán 5 documentos. Contáctanos a través del chat de Mifiel o al correo [email protected] indicándonos tu correo de usuario para acreditarte más documentos en ambiente sandbox.
Genera tus Access tokens para poder autenticar tus llamadas por la API.
Revisa la documentación de la API en https://docs.mifiel.com/.
Registra tus webhooks en sandbox y pruébalos con el endpoint de disparo manual antes de escribir el resto de tu integración.
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.
Opcional: Instala alguna de las librerías que tenemos en https://github.com/Mifiel, actualmente tenemos librerías para PHP, Ruby, Java, Python, Javascript (Node), y C# (.NET).
Cuando tu código esté listo, pasar a producción es simple (requieres contar con la funcionalidad de API contratada y activa). Crea una cuenta en mifiel.com, obtén tus Access tokens, registra de nuevo tus webhooks apuntando a tu servidor de producción 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 automatizar tu creación, búsqueda y eliminación de documentos, así como 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?