Manejo de Errores

Cómo detectar, manejar y recuperarse de errores durante el proceso de firma.

Qué vas a lograr

Implementar un manejo robusto de errores que permita a tus usuarios entender qué salió mal y cómo resolverlo.

Tipos de errores

Errores del iframe

El iframe envía errores mediante el mensaje lakaut.error:

window.addEventListener('message', (event) => {
    if (event.origin !== 'https://www.lakautac.com.ar') return;

    if (event.data.type === 'lakaut.error') {
        // code y message están en el nivel raíz, NO en payload
        const { code, message } = event.data;
        manejarError(code, message);
    }
});

Estructura del mensaje

A diferencia de otros mensajes, lakaut.error tiene los campos code y message en el nivel raíz del mensaje, no dentro de un payload.

Errores de red/carga

El iframe puede no cargar por problemas de red o configuración:

const iframe = document.getElementById('lakaut-firma');

iframe.onerror = () => {
  mostrarMensaje('No se pudo cargar el servicio de firma. Verificá tu conexión.');
};

// Timeout si no hay respuesta
let iframeReady = false;
const timeout = setTimeout(() => {
  if (!iframeReady) {
    mostrarMensaje('El servicio de firma está tardando en responder.');
  }
}, 10000);

// Cancelar timeout cuando llegue lakaut.ready
window.addEventListener('message', (event) => {
  if (event.origin !== 'https://www.lakautac.com.ar') return;
  if (event.data.type === 'lakaut.ready') {
    iframeReady = true;
    clearTimeout(timeout);
  }
});

---

Códigos de error y acciones

Código	Causa	Qué mostrar al usuario	Acción técnica
INVALID_REQUEST	Datos mal formateados	"Hubo un problema con los datos. Intentá de nuevo."	Verificar payload enviado
SESSION_EXPIRED	Token JWT expiró	"Tu sesión expiró. Recargá la página."	Recargar iframe
INSUFFICIENT_BALANCE	Sin créditos	"No hay créditos disponibles. Contactá al administrador."	Notificar al admin
ORIGIN_NOT_ALLOWED	Dominio no permitido	"No tenés permisos para usar este servicio."	Verificar configuración
INTERNAL_ERROR	Error del servidor	"Ocurrió un error. Intentá de nuevo en unos minutos."	Reintentar

---

Implementación recomendada

Función centralizada de manejo de errores

function manejarError(code, message) {
  // Log para debugging
  console.error(`[Firma Error] ${code}: ${message}`);

  // Acciones según el código
  switch (code) {
    case 'SESSION_EXPIRED':
      // Sesión expirada - recargar
      mostrarModal({
        titulo: 'Sesión expirada',
        mensaje: 'Tu sesión ha expirado. ¿Querés recargar para continuar?',
        acciones: [
          { texto: 'Recargar', onClick: () => location.reload() },
          { texto: 'Cancelar', onClick: cerrarModal }
        ]
      });
      break;

    case 'INSUFFICIENT_BALANCE':
      // Sin créditos - notificar
      mostrarModal({
        titulo: 'Sin créditos disponibles',
        mensaje: 'No hay créditos para realizar firmas. Contactá al administrador.',
        acciones: [
          { texto: 'Entendido', onClick: cerrarModal }
        ]
      });
      // Opcional: enviar notificación al admin
      notificarAdmin('Sin créditos para firma');
      break;

    case 'INTERNAL_ERROR':
      // Error del servidor - permitir reintento
      mostrarModal({
        titulo: 'Error del servicio',
        mensaje: 'Ocurrió un error inesperado. ¿Querés intentar de nuevo?',
        acciones: [
          { texto: 'Reintentar', onClick: reiniciarFirma },
          { texto: 'Cancelar', onClick: cerrarModal }
        ]
      });
      break;

    default:
      // Error genérico
      mostrarModal({
        titulo: 'Error',
        mensaje: message || 'Ocurrió un error durante la firma.',
        acciones: [
          { texto: 'Cerrar', onClick: cerrarModal }
        ]
      });
  }
}

Reintentar firma

function reiniciarFirma() {
  // Cerrar modal de error
  cerrarModal();

  // Recargar el iframe
  const iframe = document.getElementById('lakaut-firma');
  const src = iframe.src;
  iframe.src = '';
  setTimeout(() => {
    iframe.src = src;
  }, 100);

  // Mostrar loading
  mostrarLoading('Reconectando...');
}

---

Errores comunes de integración

El iframe no carga

Síntomas: El iframe queda en blanco o muestra error del navegador.

Causas posibles:

• Dominio no autorizado en la configuración de Lakaut
• Bloqueado por Content Security Policy de tu sitio
• URL incorrecta

Solución:

// Verificar en consola del navegador
// Si ves errores de CSP, agregar lakaut a tu configuración:

// En tu servidor, header Content-Security-Policy:
// frame-src https://www.lakautac.com.ar;

No recibo el handshake

Síntomas: Enviás lakaut.init pero nunca llega lakaut.handshake.ack.

Causas posibles:

• El origen en postMessage es incorrecto
• El iframe aún no terminó de cargar
• Error de autenticación interno

Solución:

// Asegurate de enviar después de recibir lakaut.ready
window.addEventListener('message', (event) => {
  if (event.origin !== 'https://www.lakautac.com.ar') return;

  if (event.data.type === 'lakaut.ready') {
    // Enviar init aquí, cuando el iframe está listo
    iframe.contentWindow.postMessage({
      type: 'lakaut.init',
      payload: {
        // ...
      }
    }, 'https://www.lakautac.com.ar'); // Verificar este origen
  }
});

El documento no se carga

Síntomas: Enviás lakaut.load.file pero el documento no aparece.

Causas posibles:

• Enviaste antes del handshake
• El Base64 está mal formateado
• El archivo excede el límite de tamaño

Solución:

// Siempre esperar el handshake
let iframeReady = false;
let documentoPendiente = null;

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://www.lakautac.com.ar') return;

  if (event.data.type === 'lakaut.handshake.ack') {
    iframeReady = true;
    if (documentoPendiente) {
      enviarDocumento(documentoPendiente);
    }
  }
});

// Verificar Base64
function validarBase64(str) {
  try {
    return btoa(atob(str)) === str;
  } catch (e) {
    return false;
  }
}

---

Logging y debugging

Habilitar logs detallados

const DEBUG = true; // Cambiar a false en producción

function logFirma(tipo, datos) {
  if (!DEBUG) return;

  const timestamp = new Date().toISOString();
  console.log(`[Firma ${timestamp}] ${tipo}:`, datos);
}

// Uso
window.addEventListener('message', (event) => {
  if (event.origin !== 'https://www.lakautac.com.ar') return;

  logFirma('Mensaje recibido', event.data);
  // ...
});

Enviar errores a tu sistema de monitoreo

function reportarError(error) {
  // Ejemplo con tu sistema de logging
  fetch('/api/logs/firma-error', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      timestamp: new Date().toISOString(),
      error: error,
      userAgent: navigator.userAgent,
      url: window.location.href
    })
  }).catch(console.error);
}

---

Checklist de troubleshooting

Cuando algo no funciona, verificá en este orden:

1. ✅ ¿La URL del iframe es correcta? (https://iframe.lakautac.com.ar/embed)
2. ✅ ¿Tu dominio está autorizado? (contactar a Lakaut)
3. ✅ ¿Enviás lakaut.init después de recibir lakaut.ready?
4. ✅ ¿El origen en postMessage es exactamente 'https://www.lakautac.com.ar'?
5. ✅ ¿Validás el origen en los mensajes recibidos?
6. ✅ ¿Esperás lakaut.handshake.ack antes de enviar el documento?
7. ✅ ¿El Base64 no incluye el prefijo data:application/pdf;base64,?
8. ✅ ¿El PDF es menor a 10MB?

---

Próximos pasos

• Seguridad - Buenas prácticas de seguridad
• FAQ - Preguntas frecuentes