Cómo integrar la firma electrónica de Mifiel con su API: preguntas frecuentes

Contenido

Antes de empezar
Integración
Firma
Webhooks y documento firmado
Búsquedas y limpieza
Sandbox y producción

Antes de empezar

¿Mifiel tiene API para firma electrónica?

Sí. Mifiel tiene una API REST para que tu sistema prepare documentos, recolecte firmas y obtenga los documentos firmados sin trabajo manual. La documentación completa está en docs.mifiel.com.

¿Qué puedo hacer con la API?

Con la API de Mifiel puedes:

Automatizar la preparación y el envío de documentos a firma.
Recibir notificaciones de eventos de firma mediante webhooks.
Hacer búsquedas avanzadas sobre tus documentos pendientes de firma.
Eliminar documentos.
Integrar un widget de firma en tu sitio web.
Generar constancias de conservación NOM-151 para documentos que no necesitan firma.

¿Cuánto tiempo toma integrar la API?

Puede llevar desde unas pocas semanas hasta varios meses. No hay un tiempo promedio, porque depende de la complejidad de tu sistema y del diseño de la integración entre tu sistema y el de Mifiel.

Define cómo quieres que funcione la integración antes de escribir código. Si empiezas a programar sin un diseño claro, tendrás que modificar o reescribir el código constantemente y la integración final tardará más.

¿Tienen librerías para la API?

Sí. Hay librerías para PHP, Ruby, Java, Python, Node.js y C# (.NET) en el repositorio de GitHub de Mifiel. Usarlas es opcional.

¿Tienen ejemplos de código?

Sí. En esta guía encuentras ejemplos en Ruby, Node.js, Python, PHP, C# y cURL para crear y eliminar documentos. La documentación de la API incluye ejemplos de request y response para cada endpoint.

Integración

¿Cuáles son los pasos para integrar la API?

Son cinco pasos:

Registra tus webhooks. Los webhooks le avisan a tu sistema lo que pasa con tus documentos. Se configuran 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 en PDF. Puedes usar una librería de tu lenguaje de programación para crear o convertir documentos a PDF. La API también permite usar plantillas (templates) HTML; si te interesa, escríbenos por el chat de Mifiel.
Envía el documento a Mifiel mediante la API. Haz una solicitud POST con el PDF y los datos de los firmantes, como su correo electrónico.
Presenta el flujo de firma a tu firmante. Para que firme dentro de tu sitio, usa el widget de firma de Mifiel: una interfaz donde el firmante revisa el contenido del documento y lo firma. Lo integras insertando un script en tu página, 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 un .zip con el PDF y el XML del documento firmado.

¿Cómo creo un documento?

Con una solicitud POST /api/v1/documents que incluya el documento en PDF y los datos de cada firmante. El PDF puede pesar máximo 20 MB.

Estos ejemplos crean un documento con dos firmantes

En la pestaña Solicitud ves el cuerpo de la solicitud para un documento con un solo firmante. La respuesta incluye el id del documento y un widget_id por cada firmante: si tienes tres firmantes, recibes tres widget_id.

Encuentra todos los parámetros en la documentación para crear documentos.

¿Qué son los widget_id y por qué debo guardarlos?

El widget_id es el identificador único de cada firmante dentro de un documento, y es lo que le pasas al widget para que muestre el documento correcto. Guárdalo al crear el documento: lo necesitas cada vez que muestres el widget. Si no lo guardas, tu sistema terminaría creando un documento nuevo cada vez que el firmante recargue la página.

Pasa a cada firmante su propio widget_id: al firmante 1, el widget_id del firmante 1; al firmante 2, el del firmante 2, y así sucesivamente.

Firma

¿Mis firmantes deben firmar en mifiel.com o con el widget?

Depende de si quieres integrar la firma en tu sitio. Tus firmantes pueden firmar directamente en la plataforma de Mifiel (mifiel.com) o en tu sitio con el widget de Mifiel.

Firma en mifiel.com. Te conviene si:

Necesitas que tus clientes firmen sus contratos y no puedes desarrollar una implementación propia.
Quieres una integración más simple y ligera: no tienes que integrar el proceso de firma en tu sitio, solo te ocupas de las automatizaciones.
Quieres que la experiencia de firma lleve los colores y el logo de tu marca sin escribir código. Lo configuras desde la plataforma si tu cuenta tiene la función de personalización de marca.

Si eliges esta opción, crea el documento con send_invites en true para que Mifiel le avise por correo a cada firmante y pueda firmar en el portal de firma de Mifiel. Si tus firmantes firman con el widget en tu sitio, puedes dejarlo así y enviar tus propios correos.

Firma con el widget. Te conviene si:

Tu sitio es una plataforma donde tus clientes hacen procesos con tu organización (no solo un sitio informativo) y tienes un equipo de desarrollo que puede implementar y mantener integraciones de API.
Quieres personalizar colores, textos, tamaño del widget e información del documento.
Quieres colocar la firma en cualquier parte de tu página: el widget se implementa con un iframe responsive.

¿Cómo muestro el widget de firma en mi sitio?

Incluye el widget en la página donde quieres que se firme y pásale el widget_id del firmante. Hazlo después de que tu servidor cree el documento y reciba los widget_id. Las opciones de instalación (componente web por CDN o npm, y versiones para Angular, React y Vue) y de configuración están en la sección Widget de Firma de la documentación de la API.

El widget le muestra el documento al firmante y le permite firmarlo; la criptografía de firma se ejecuta en el navegador del firmante. Tus firmantes pueden firmar con su e.firma o con la firma electrónica con verificación de identidad de Mifiel.

Durante la firma, el widget genera eventos de JavaScript que tu página puede usar para disparar acciones. Por ejemplo, si el firmante escribe mal la contraseña de su e.firma, el widget genera un evento de error.

Eventos de error: puedes ignorarlos, porque Mifiel se encarga de mostrarle los errores al firmante.
Evento de firma exitosa: no lo ignores. Úsalo para llevar al firmante al siguiente paso en tu página.

En el componente actual del widget, estos eventos se llaman signSuccess y signError.

¿Puedo modificar el widget para que combine con mi sitio?

Solo en parte. En general no puedes modificar el widget de Mifiel, porque podrías causar problemas que invaliden la firma electrónica o que afecten la experiencia de tus firmantes.

Sí puedes hacer algunas modificaciones para que combine con el diseño de tu sitio, como los colores de los botones o el tamaño y la ubicación del widget.

¿Mi sistema tiene que manejar las llaves privadas de mis firmantes?

No. Como la firma ocurre en el widget, no tienes que preocuparte por manejar las llaves privadas ni las contraseñas de tus firmantes.

Webhooks y documento firmado

¿Por qué usar webhooks en lugar de consultar el estado del documento?

Porque los webhooks te avisan de cada evento sin que tengas que consultar la API continuamente. Consultar el estado del documento cada cierto tiempo, de forma manual o automática, se vuelve un problema cuando escalas: Mifiel limita las llamadas para consultar el estado de los documentos y bloquea la IP que excede ese límite, lo que retrasaría tus procesos.

¿Cómo registro un webhook?

Con una solicitud POST /api/v1/webhooks que indique la URL de tu servidor y el tipo de evento al que te suscribes. Los webhooks se configuran a nivel cuenta, no por documento.

La respuesta incluye el id del webhook. Guárdalo, porque lo necesitas para consultarlo o eliminarlo después.

Para ver tus webhooks activos: GET /api/v1/webhooks.
Para dar de baja un webhook: DELETE /api/v1/webhooks/{id}.

Encuentra más detalles en la sección de webhooks de la documentación.

¿Qué eventos hay?

Hay cuatro eventos:

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

¿Cómo obtengo una copia del documento firmado?

Usa el evento document_closed: cuando lo recibas, haz una llamada autenticada a GET /api/v1/documents/{id}/zip con el id del documento. Te devuelve un .zip con el PDF y el XML del documento firmado.

El POST que recibe tu servidor con el evento document_closed se ve así:

Tu servidor debe responder con un código de éxito (2xx). El ciclo de firma de un documento termina cuando recibes el webhook, descargas el .zip y tu servidor responde con 200.

¿Los documentos firmados incluyen constancia de conservación NOM-151?

Sí. Los documentos firmados electrónicamente en Mifiel incluyen una constancia de conservación de forma automática. La constancia demuestra que el documento existía en un momento determinado y que su contenido no ha cambiado desde entonces.

La constancia no es lo que hace válida una firma electrónica: esa validez depende de cómo se creó la firma.

Si necesitas constancias para documentos que no requieren firma, la API tiene un endpoint específico (POST /api/v1/psc/nom151). Consulta cómo usarlo en la guía Constancias de Conservación NOM-151 vía API.

¿Qué pasa si mi servidor no responde al webhook?

Mifiel reintenta la entrega hasta 10 veces, una vez cada 10 minutos, y se detiene en cuanto recibe una respuesta 2xx. Esto aplica tanto si tu servidor no contesta como si contesta con un código distinto de 2xx.

¿Cómo pruebo mi integración?

Dispara un webhook manualmente con POST /api/v1/webhooks/{id}/trigger y envía el id del documento en resource.

Con instant: true, el envío se hace una sola vez y de inmediato, en lugar de encolar los 10 intentos. La respuesta incluye el status, los headers y el body que devolvió tu servidor, así que te sirve para depurar tu endpoint.

Te recomendamos probar tus webhooks en sandbox antes de escribir el resto de tu integración.

Búsquedas y limpieza

¿Cómo hago búsquedas avanzadas?

Con una solicitud POST /api/query. Los atributos y relaciones de cada recurso están definidos, así que puedes usarlos según lo que necesites. Por ejemplo, puedes:

Buscar documentos por una parte de su nombre.
Identificar todos los documentos que un firmante en específico necesita firmar.
Identificar todos los documentos sin firmar para eliminarlos si ya no los necesitas.

Encuentra más ejemplos en la guía Cómo hacer búsquedas avanzadas utilizando la API.

¿Cómo elimino documentos pendientes?

Encuéntralos con una búsqueda avanzada y elimina cada uno por su id con DELETE /api/v1/documents/{id}. Solo puedes eliminar documentos que no estén completados.

Conviene hacerlo con documentos que se quedaron sin firmar y ya no se necesitan, o que se subieron con errores y vas a reemplazar por el correcto.

Por ejemplo, esta búsqueda pide todos los documentos pendientes creados entre el 1 de enero y el 31 de julio de 2021. La respuesta incluye el id de cada documento:

Encuentra más detalles en la documentación para eliminar documentos.

Sandbox y producción

¿Cómo empiezo?

Mifiel tiene dos ambientes: el de pruebas (sandbox) y el productivo. Puedes empezar con pruebas en sandbox o contratar la funcionalidad directamente.

Para hacer pruebas en sandbox:

Crea una cuenta en el sandbox de Mifiel. Cuando tu cuenta esté creada y confirmada, se te acreditarán 5 documentos.
Escríbenos por el chat (ícono verde en la esquina inferior derecha) y solicita que habilitemos la API y los créditos para pruebas. Si después necesitas más documentos de prueba, escríbenos por el mismo chat o a [email protected] con el correo de tu usuario.
Genera tus API keys en la sección de Configuraciones de API, en Access tokens. Son el APP_ID y el APP_SECRET con los que autenticas tus llamadas a la API.
Revisa la documentación de la API.
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 e.firma (FIEL) a la mano, genera una de prueba. Ingresa tu nombre, RFC y CURP correctos, porque se valida que la estructura del RFC y la CURP sea correcta.
Opcional: instala alguna de las librerías de Mifiel (PHP, Ruby, Java, Python, Node.js o C#).

Los documentos firmados en sandbox no tienen la misma validez legal que los firmados en producción, así que úsalo solo para pruebas.

Para contratar directamente: si prefieres omitir sandbox, escríbenos por el chat y te ayudamos a configurar tu ambiente productivo.

¿Cómo paso a producción?

Cuando termines tus pruebas, o si decidiste contratar directamente:

Crea una cuenta en mifiel.com, si aún no tienes una.
Escríbenos por el chat para contratar la funcionalidad de API y activar tu ambiente productivo.
Genera tus API keys de producción en Configuraciones de API, en Access tokens. Las API keys de sandbox no funcionan en producción.
Registra de nuevo tus webhooks apuntando a tu servidor de producción.
Cambia app-sandbox.mifiel.com por app.mifiel.com en todos tus endpoints, incluido el del widget.

¿Tienes dudas sobre la API? Escríbenos por el chat de Mifiel.