Cómo preparar documentos, recolectar firmas, obtener documentos y notificaciones mediante API

Contenidos

  1. Introducción
  2. Cómo preparar un documento mediante API
  3. Cómo recolectar firmas de un documento mediante el widget de Mifiel
  4. Cómo obtener el documento firmado mediante API
  5. Notificaciones enviadas por correo durante el ciclo del documento
    1. Notificaciones por correo para participantes (firmantes y revisores)
    2. Notificaciones por correo para quienes preparan o administran documentos
    3. Notificaciones por correo para espectadores
  6. Diagrama de interacciones: flujo básico

En Mifiel existen tres tipos de documentos: los regulares, los encriptados y los pagarés endosables. Para este artículo nos centraremos en los documentos regulares, que son la base de los otros dos tipos de documentos.

Antes de comenzar, ya debes tener creada una cuenta en Mifiel y haber generado tus access tokens.

Cómo preparar un documento mediante API

La preparación de cualquier documento en Mifiel siempre debe ser autenticada.

El endpoint que debes utilizar para preparar documentos es /documents y los parámetros mínimos sugeridos son:

  • Archivo a firmar (file), debe indicar la ruta de un archivo en formato PDF, cuyo peso no sea mayor a 20 MB.
  • Participantes, para cada uno debe indicarse:
    • Correo electrónico (email).
    • RFC (tax_id), en caso de contar con la funcionalidad de restricción de RFC.
    • Nombre (name).
    • Tipo, puedes agregar firmantes (signer) o en caso de contar con las funcionalidades de Revisores o Secuencias automatizadas, revisores del documento (reviewer).
  • Webhook del participante (sign_callback_url), es la URL donde puedes recibir notificaciones cada que alguien firme el documento y es la misma para todos los participantes.
  • Webhook del documento (callback_url), es la URL donde se te notificará cuando todos los participantes hayan firmado o aprobado el documento.

En nuestra documentación de API podrás consultar a detalle cómo realizar este proceso, encontrar todos los parámetros disponibles para preparar un documento de acuerdo a tus necesidades tales como frecuencia de envío de recordatorios y fecha de expiración, y ver un ejemplo de cómo se implementa.

Cuando termines de preparar el documento (y si enviaste los parámetros correctamente), recibirás una respuesta indicando que lo hiciste exitosamente. Esta incluirá diversos datos, pero los más relevantes son:

  • widget_id del participante, se usa para firmar el documento mediante el widget de Mifiel y es único para cada participante.
  • id del documento, te permitirá consultar el estado del documento.

Cómo recolectar firmas de un documento mediante el widget de Mifiel

Una vez agregado el script (Javascript) del widget de firmas a tu aplicación, deberás agregar el widget_id del participante a quien le presentarás el flujo de firma.

Recuerda que puedes personalizar los colores de diferentes elementos del flujo de firma desde nuestra interfaz en mifiel.com.

Cómo obtener el documento firmado mediante API

Si definiste un webhook para el documento, cuando todos los participantes lo hayan firmado o aprobado recibirás una notificación al respecto. Esta incluirá información relevante del documento firmado, como las URLs que te permitirán obtenerlo.

Para obtener el documento firmado, deberás realizar las llamadas a sus endpoints. Estas llamadas para obtener los documentos deben ser autenticadas. Así podrás obtener ya sea el PDF firmado (con la hoja de firmas) o el XML (archivo con validez legal).

Notificaciones enviadas por correo durante el ciclo del documento

Tanto la persona que prepara o administra el documento como sus participantes reciben diferentes notificaciones vía correo electrónico durante el ciclo de vida del documento. Estas son:

Notificaciones por correo para participantes (firmantes y revisores)

  • Invitaciones a firmar: cuando indiques el parámetro send_invites: true al preparar el documento y solicitar sus firmas, se notificará a los participantes mediante un correo de invitación. Este correo contiene un enlace que los dirige a firmar o aprobar dentro de mifiel.com. Si tu flujo de firma es mediante el widget de Mifiel implementado en tu sitio web, te sugerimos no activar esta notificación.
  • Cuando otros participantes firmen o aprueben el documento.
  • Cuando el documento termine de firmarse, adjuntando el PDF y XML firmado.
  • Entre otras.

Notificaciones por correo para quienes preparan o administran documentos

  • Cuando un participante firme o apruebe el documento.
  • Cuando el documento termine de firmarse, adjuntando el PDF y XML firmado.
  • Cuando un participante rechace firmar o aprobar el documento.
  • Entre otras.

Notificaciones por correo para espectadores

  • Cuando se prepara un documento y se solicitan sus firmas, adjuntando el PDF original.
  • Cuando un participante firme o apruebe el documento.
  • Cuando el documento termine de firmarse, adjuntando el PDF y XML firmado.

Diagrama de interacciones: flujo básico

Para que puedas visualizar las interacciones entre tu aplicación y la API de Mifiel durante la preparación y firma de documentos, creamos este diagrama.

Diagrama-secuencia-API-Mifiel-creacion-y-firma-de-documento-v2

Si requieres ayuda para integrar documentos encriptados o pagarés endosables, por favor contáctanos por chat o mediante tu canal de integración en Slack.