Una parte enorme del software de gestión que se usa en Ecuador está escrito en PHP, y buena parte de lo nuevo, en Laravel. Sistemas de facturación, portales de clientes, plataformas de recursos humanos y ERP a medida comparten un mismo destino: tarde o temprano les piden firmar documentos con certificado. La integración es perfectamente abordable, pero tropieza siempre con los mismos obstáculos del entorno PHP, que tienen poco que ver con el framework y mucho con cómo se ejecuta una petición web.
Esta guía recorre esos obstáculos en el orden en que aparecen y propone el diseño que evita la mayoría.
La petición web no es el lugar para firmar
El modelo de ejecución de PHP está pensado para responder rápido y morir. Firmar un documento —más aún un lote— es lo contrario: trabajo largo, con dependencia de un servicio externo y con posibilidad de reintento. Meterlo dentro del ciclo de una petición produce el cuadro clásico:
- Tiempo máximo de ejecución agotado a mitad del proceso.
- Tiempo de espera del servidor web agotado antes que el del intérprete, dejando al usuario sin respuesta mientras el proceso sigue corriendo.
- Límite de memoria superado al manipular documentos pesados.
- El usuario recarga la página y dispara una segunda firma del mismo documento.
La solución no es subir los límites: es sacar el trabajo del ciclo de la petición. La petición registra la solicitud, devuelve un identificador y termina. Un trabajo en cola hace la firma, y el sistema informa el resultado después. Es el mismo principio que ordena cualquier flujo documental serio, descrito en firma electrónica en flujos de documentos.
Colas: lo que hay que resolver además de encolar
Laravel facilita mucho el trabajo en cola, pero un despliegue completo exige atender varios puntos que no vienen resueltos por defecto:
- Supervisión del proceso trabajador: un trabajador detenido no avisa. Necesita un supervisor que lo reinicie y una alerta cuando la cola crece sin consumirse.
- Reinicio tras despliegue: los trabajadores mantienen el código en memoria. Si el despliegue no los reinicia, siguen ejecutando la versión anterior, con resultados desconcertantes.
- Idempotencia: un trabajo puede reintentarse. Sin una marca de "este documento ya se firmó", el reintento produce firmas duplicadas.
- Intentos y tiempo máximo: conviene distinguir errores temporales, que ameritan reintento con espera creciente, de los definitivos, que deben fallar de una vez y quedar registrados.
- Trabajos fallidos revisados: la tabla de fallos solo sirve si alguien la mira. Un tablero o una alerta diaria evita descubrir el problema semanas después.
Almacenamiento, permisos y el certificado
El segundo bloque de problemas es de sistema de archivos. El proceso web y el trabajador de cola pueden correr con usuarios distintos, y ahí nacen errores difíciles de leer: archivos creados por uno que el otro no puede modificar, carpetas temporales sin permiso de escritura, archivos generados con permisos que nadie más puede leer.
Recomendaciones concretas:
- Que el proceso web y el trabajador corran con el mismo usuario, o que compartan grupo con permisos coherentes.
- Documentos originales y firmados en discos configurados de forma explícita, no en rutas absolutas escritas a mano en el código.
- Si hay varias instancias de la aplicación, el almacenamiento debe ser compartido u objeto remoto; el disco local deja de servir apenas hay más de un servidor.
- El archivo .p12, si se usa, jamás en la carpeta pública ni en el repositorio. Fuera de la raíz web, con permisos restrictivos y con la contraseña en variables de entorno.
Un aviso sobre la caché de configuración: en despliegues optimizados, las variables de entorno leídas fuera de los archivos de configuración pueden quedar vacías. Si la contraseña del certificado se lee directamente desde el entorno en medio del código, funcionará en desarrollo y fallará en producción sin mensaje claro. Todo valor sensible debe pasar por un archivo de configuración.
Firma en la nube: el modelo que encaja mejor
Para una aplicación PHP en producción, la firma en la nube evita el grueso de los problemas anteriores: no hay archivo que custodiar en el servidor, no hay permisos de clave privada que ajustar, y la aplicación escala horizontalmente sin replicar material criptográfico en cada instancia. La comparación completa está en nube, .p12 y token, y el detalle de integración, en la guía de la API de firma electrónica.
Multiempresa: el error que se paga caro
Muchas aplicaciones PHP ecuatorianas atienden a varias empresas desde una misma instalación. Ahí el riesgo más grave no es de rendimiento sino de aislamiento: firmar un documento de una empresa con el certificado de otra. Para evitarlo:
| Control | Qué evita |
|---|---|
| Certificado asociado a la empresa, nunca global | Uso cruzado por configuración compartida |
| Verificación de pertenencia antes de firmar | Que un trabajo tome el certificado equivocado |
| Registro con empresa, usuario y documento | Imposibilidad de auditar después |
| Colas o rutas separadas por empresa | Que un lote grande frene al resto |
| Almacenamiento segregado | Acceso indebido a documentos de terceros |
La contraparte organizativa —quién administra los certificados, quién autoriza altas y bajas— está en administración y control de certificados en la nube.
Tareas programadas: vencimientos y limpieza
El programador de tareas de Laravel resuelve dos necesidades que aparecen a los pocos meses. La primera es el control de vigencias: una revisión diaria que avise con semanas de anticipación qué certificados están por vencer evita que un lote nocturno falle completo. El procedimiento está en renovación corporativa y vigencia. La segunda es la limpieza de archivos temporales, que en procesos de firma se acumulan rápido y llenan el disco en el peor momento.
Comprobantes electrónicos y XML
Si la aplicación emite comprobantes para el SRI, el objeto firmado es un XML y las reglas cambian: importa la codificación del archivo, la ubicación exacta del nodo de firma y el hecho de que cualquier modificación posterior —incluso agregar un espacio— invalida la firma. Es un error común: el sistema genera el XML, lo firma y luego un proceso de "limpieza" lo reformatea, dejándolo inválido sin que nadie lo note hasta el rechazo.
El panorama está en firma electrónica y facturación electrónica ante el SRI y en firma y factura electrónica para empresas. Si la empresa prefiere no construir el módulo de emisión, el grupo cuenta con Azur, sistema de facturación electrónica autorizado por el SRI que resuelve emisión, envío y custodia de comprobantes. Puedes conocerlo en azur.com.ec/registro.
Sobre certificados: la emisión es 100% en línea, toma aproximadamente 30 minutos y está disponible en archivo .p12, token USB o firma en la nube. Los valores vigentes, en la página de precios.
La bandeja del equipo
El grupo también desarrolla Omnifox, una plataforma omnicanal que reúne WhatsApp, correo, redes sociales y llamadas en una sola bandeja compartida. En una aplicación de gestión sirve para el tramo humano que no está en el sistema: avisar al cliente que su documento quedó listo, atender al que responde por WhatsApp, dejar registrada esa conversación junto al expediente en lugar de perderla en un celular. Más información en omnifox.io.
Preguntas frecuentes
¿Por qué el proceso de firma agota el tiempo de espera?
Porque está corriendo dentro del ciclo de una petición web, que no está diseñado para trabajo largo. Hay que encolar la firma y notificar el resultado después, en lugar de aumentar los límites del intérprete.
¿Dónde guardo el archivo .p12 en un proyecto Laravel?
Fuera de la carpeta pública, fuera del repositorio y con permisos restrictivos para el usuario del proceso. La contraseña, en variables de entorno leídas a través de un archivo de configuración. Para producción, la firma en la nube evita el problema por completo.
¿Por qué la contraseña del certificado queda vacía en producción?
Suele ocurrir cuando la configuración está optimizada en caché y el valor se lee directamente del entorno desde el código. Todo valor sensible debe pasar por un archivo de configuración para que sobreviva a esa optimización.
¿Cómo evito firmar dos veces el mismo documento?
Con una marca de estado por documento que el trabajo consulte antes de firmar. Las colas reintentan por diseño, así que la protección tiene que estar en la lógica, no en la confianza.
¿Qué precaución exige una aplicación que atiende a varias empresas?
Que el certificado esté siempre asociado a la empresa correspondiente y que se verifique la pertenencia antes de cada firma. Un certificado configurado de forma global es un incidente esperando ocurrir.
Si tu sistema corre sobre PHP o Laravel y necesita incorporar firma electrónica con validez legal en Ecuador, habla con un asesor corporativo de Firmas.com.ec. Solicita tu cotización corporativa.