Cómo Implementar la Firma Electrónica en PHP con la API de Mifiel

¿Te has preguntado si puedes integrar la firma electrónica en el sistema PHP que utilizan en tu empresa? La respuesta es clara: sí es posible. Mediante la API de firma digital de Mifiel, integrar la firma electrónica en los procesos de tu organización es muy sencillo y eficiente.

Pero ¿qué es Mifiel? Es la principal plataforma de firma electrónica de contratos en México, la cual simplifica el proceso de firma electrónica sin sacrificar solidez jurídica. Mifiel cuenta con una API REST, por lo que funciona con cualquier lenguaje de programación con el que quieras integrarla. Para eficientar tu proceso de integración, contamos con librerías de los principales lenguajes de programación, incluyendo PHP, la cual puedes añadir mediante Composer usando este comando: php composer.phar require mifiel/api-client

Este artículo se enfoca en resolver las dudas más comunes sobre la implementación de la firma electrónica mediante una API en sistemas que utilizan PHP, guiándote paso a paso.

Proceso de Integración de la API: un Vistazo

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

1. Genera tu documento. Primero tienes que generar una versión del documento que será firmado en formato PDF. Puedes apoyarte de alguna librería PHP para crear o convertir documentos a PDF, como FPDF o TCPDF.
2. 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.
3. Presenta el flujo de firma a tu firmante. Para hacerlo dentro de tu sitio web, debes utilizar el widget de firma de Mifiel, el cual es la interfaz visual integrada en tu sitio web donde los firmantes pueden revisar el contenido del documento y firmarlo.
4. Obtén el documento firmado. Tendrás que realizar llamadas autenticadas a los endpoints del documento para poder descargarlo.

Cómo Enviar el Documento al Servidor

La solicitud POST en PHP para enviar el documento debe verse similar a esta:

require 'vendor/autoload.php';
use Mifiel\Document;

$document = new Document([
  'file_path' => 'path/to/my-file.pdf',
  'signatories' => [[
    'name' => 'Nombre de Firmante',
    'email' => '[email protected]',
    'tax_id' =>  'RFC de firmante'
  ]]
]);
$document->save();

Y la respuesta del servidor debe verse así:

{
  "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"
  }]
}

Cómo Integrar el Widget de Firma en tu Sitio Web

El widget 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. 
Aquí puedes ver un ejemplo del código HTML para implementar el widget en tu página y cómo lo vería el firmante. Al cargarlo, pone disponible a través de `window.mifiel` una función para cargar el widget dinámicamente. 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.

Manejo de Callbacks y Respuestas del Servidor

Gestión de Callbacks de Firma

La integración efectiva con la API de Mifiel también implica manejar adecuadamente los callbacks. Cuando un documento se firma en el widget, Mifiel enviará una solicitud POST a tu servidor con información relevante. Esto requiere que configures un endpoint que pueda procesar estas solicitudes. Por ejemplo, cuando todos los firmantes hayan firmado un documento, recibirás un callback con detalles para descargar el documento firmado que se verá así:

Obtención de Documentos Firmados

Una vez que recibas la notificación de que un documento ha sido firmado, puedes proceder a descargarlo. Esto se hace mediante solicitudes a los endpoints proporcionados en el callback.

Actualización del Estado del Documento

Finalmente, es importante que actualices el estado del documento en tu sistema para reflejar que ha sido firmado. Esto asegura que tu flujo de trabajo y tus registros estén siempre actualizados.

Ahora, seguramente quieres comenzar a realizar tu implementación de la API de firma electrónica de Mifiel usando PHP. A continuación te presentamos los pasos a seguir para lograrlo.

Cómo Comenzar a Usar la API de Mifiel en PHP

Para iniciar con la API de Mifiel en tu proyecto PHP, sigue estos pasos:

1. Crea una cuenta en el ambiente de pruebas (sandbox) de Mifiel. Esto te permitirá experimentar tanto como requieras.
2. Cuando tengas una cuenta creada y confirmada, se te acreditarán 5 documentos. Si los agotas, puedes solicitarnos más a través del chat de Mifiel o al correo [email protected] indicando tu correo de usuario y los acreditaremos en tu cuenta de ambiente sandbox.
3. Obtén tus Access Tokens. Necesitarás estos tokens para autenticar tus llamadas a la API.
4. Revisa la documentación de la API. Encuentra ejemplos y detalles técnicos en nuestra documentación.
5. Instala la librería PHP de Mifiel. Disponible en nuestro repositorio de GitHub, esta librería te facilitará el trabajo.
6. Requerirás una e.firma para firmar los documentos en sandbox. Si no cuentas con una, puedes generar una de prueba.
7. Desarrolla y prueba tu implementación. Utiliza el entorno de sandbox para probar tu integración.
8. Pasa a producción. Una vez que estés listo, cambia tus endpoints y tokens para utilizar la versión de producción de la API. Para ello, no olvides crear tu cuenta en ambiente de producción y obtener tus access tokens para dicho ambiente.

Preguntas Frecuentes

¿Cuánto tiempo lleva integrar la API de firma electrónica en PHP?

El tiempo de integración puede variar. Para algunos, puede ser cuestión de semanas; para otros, puede tomar más tiempo, dependiendo de la complejidad de tu sistema. La clave es tener un diseño claro de tu implementación antes de comenzar a escribir código.

¿Mifiel ofrece librerías específicas para PHP?

Sí, Mifiel ofrece una librería específica para PHP, facilitando la integración. Esta librería está disponible en nuestro repositorio de GitHub y proporciona una base sólida para empezar tu implementación. Puedes instalar rápidamente esta librería mediante Composer con el siguiente comando:

php composer.phar require mifiel/api-client

Ahora que tienes tu archivo composer.json actualizado, requerirá el archivo vendor/autoload.php para usar PSR-4 y así poder cargar automáticamente la librería.

¿Puedo personalizar el widget de firma para que se integre mejor en mi sitio web PHP?

Sí, puedes personalizar aspectos del widget como sus colores y su ubicación en tu página para que se alinee con el diseño de tu sitio web y tu marca.

En Conclusión: Maximizando Tus Procesos con la API de Mifiel Usando PHP

A lo largo de este artículo, hemos explorado detalladamente cómo integrar la API de firma digital de Mifiel en sistemas que utilizan PHP. Desde la generación de documentos en formato PDF, hasta la obtención de documentos firmados, ahora conoces a detalle el proceso para realizarlo.

Con la información y ejemplos proporcionados, tienes una base sólida para comenzar tu propia implementación. Si tienes preguntas adicionales o necesitas asistencia específica para tu caso, no dudes en contactarnos a través de nuestro chat.