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.
- 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:
- 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 y una URL de callback para notificaciones de firma.
- 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. Tendrás que realizar llamadas autenticadas a los endpoints del documento para poder descargarlo.
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.
- Una URL para que hagamos callback a tu servidor cuando todos hayan firmado el documento.
{
"file": "File",
"signatories": [{
"email": "[email protected]",
"name": "Nombre de Firmante",
"tax_id": "RFC de firmante"
}],
"callback_url": "https://my-site.com/mifiel-webhook"
}
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",
"original_hash": "f40243ee412ec8f297245feea8a489e7599c5e1b77bc4bf0e92bd3ed48d86b43",
"created_at": "2022-01-17T16:34:15.065Z",
"state": "pending",
"file_file_name": "contrato-ejemplo.pdf",
"callback_url": "https://my-site.com/mifiel-webhook",
"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 guardar el id del documento para que al recibir el callback de documento firmado puedas saber de cuál se trata.
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'
}],
callback_url: 'https://www.example.com/webhook/url',
)
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.
Callbacks
Si pasaste una URL para recibir callbacks de los eventos de firma (sign_callback_url), 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, si pasaste una URL para recibir callback de documento firmado por todos (callback_url), cuando todos los signatarios firmen y se obtenga la constancia de conservación Mifiel hará un POST a tu servidor para notificar que el documento ha sido firmado.
Entre los parámetros de la llamada se incluye un enlace para que tu servidor descargue el documento firmado en formato XML, así como la representación gráfica en formato PDF. Esta es la forma recomendada para que tu sistema sepa si un documento está firmado o no.
La otra opción 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.
Los parámetros para descargar el documento se verán así:
- “file_signed”: “/api/v1/documents/c914e1ed-a84d-465e-bee8-f3fadf7b7280/file_signed”,
- “file_xml”: “/api/v1/documents/c914e1ed-a84d-465e-bee8-f3fadf7b7280/xml”,
Para ambas llamadas el servidor de Mifiel espera que contestes con un código de respuesta exitoso (2xx). 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 el enlace de descarga del documento y tu servidor contesta con un 200, se da por terminado el ciclo de firma de un documento.
El request debe verse así:
{
"id": "c914e1ed-a84d-465e-bee8-f3fadf7b7280",
"original_hash": "f40243ee412ec8f297245feea8a489e7599c5e1b77bc4bf0e92bd3ed48d86b43",
"created_at": "2022-01-17T16:34:15.065Z",
"signed_at": "2022-01-17T17:34:15.065Z",
"state": "pending",
"file_file_name": "contrato-ejemplo.pdf",
"callback_url": "https://my-site.com/mifiel-webhook",
"file": "/api/v1/documents/c914e1ed-a84d-465e-bee8-f3fadf7b7280/file",
"file_signed": "/api/v1/documents/c914e1ed-a84d-465e-bee8-f3fadf7b7280/file_signed",
"file_xml": "/api/v1/documents/c914e1ed-a84d-465e-bee8-f3fadf7b7280/xml",
"file_zip": "/api/v1/documents/c914e1ed-a84d-465e-bee8-f3fadf7b7280/zip",
"signers": [{
"id": "dc9d63f6-11af-4840-af14-0e51e6da5da4",
"email": "[email protected]",
"name": "Nombre de Firmante",
"tax_id": "RFC de firmante",
"signed": true,
"signed_at": "2022-01-17T17:24:15.065Z",
"widget_id": null
}]
}
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('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í, puedes utilizar la API para descargar tus documentos firmados en Mifiel. Solo es necesario hacer el request mediante el callback como indicamos anteriormente.
¿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/.
- 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 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?
