✍️ Firma Digital de Contratos

Introducción

Esta documentación cubre el proceso completo de firma digital de contratos:

• Envío inicial: Enviar contratos para firma digital por primera vez
• Reenvío: Reenviar solicitudes cuando el cliente no recibió la comunicación o necesita un recordatorio
• Consulta de estado: Obtener información en tiempo real del proceso de firma
• Auditoría: Datos detallados de cada firmante (IP, fecha/hora, estado)

Envío Inicial de Firma

El endpoint POST /firma permite enviar contratos ya creados en el sistema para firma digital del cliente. El contrato debe haber sido creado previamente mediante los endpoints de contratación.

Parámetros del Request

Canales de Envío

📧 Email ("email")

Envío del enlace de firma por correo electrónico. Canal más común y recomendado.

• Formato: direcciones_firma: "usuario@example.com"
• Validación: Email en formato RFC estándar
• Ventaja: El cliente puede firmar desde cualquier dispositivo

📱 SMS ("sms")

Envío del enlace de firma por mensaje de texto SMS.

• Formato: direcciones_firma: "606123456" o "+34606123456"
• Validación: 8-15 dígitos, opcional prefijo internacional +
• Ventaja: Entrega inmediata, ideal para clientes sin email

🔐 Email con OTP ("email_otp")

Envío dual: email con enlace + SMS con código OTP de verificación.

• Formato: direcciones_firma: "usuario@example.com;606123456"
• Ventaja: Máxima seguridad con doble factor de autenticación

Ejemplo de Request

POST /firma
Authorization: Bearer <tu-jwt-token>
Content-Type: application/json

{
  "contrato_id": 369877,
  "canal_envio": "email",
  "direcciones_firma": "cliente@example.com",
  "referencia_externa": "ZOHO-DEAL-12345"
}

Respuesta Exitosa (200)

{
  "request_id": 12345,
  "firma_result": {
    "status": "success",
    "message": "Contrato enviado para firma digital",
    "circuito_id": "123456"
  },
  "referencia_externa": "ZOHO-DEAL-12345"
}

Flujo de Uso Típico

1. Paso 1: Crear el contrato con no_enviar_firma: true
2. Paso 2: Obtener el contrato_id de la respuesta
3. Paso 3: Enviar a firma cuando estés listo:

   POST /firma
   
   {
     "contrato_id": 369877,
     "canal_envio": "email",
     "direcciones_firma": "cliente@example.com"
   }

4. Paso 4: Guardar el circuito_id de la respuesta para operaciones posteriores

Reenviar Solicitud de Firma

Reenvía una solicitud de firma existente al cliente. Útil para recordatorios o cuando el cliente no recibió la comunicación inicial.

Parámetros del Request

Ejemplo de Request

POST /firma/reenviar
Authorization: Bearer <tu-jwt-token>
Content-Type: application/json

{
  "circuito_id": "123456",
  "mode": "ds",
  "referencia_externa": "REENVIO-2024-001"
}

Respuesta Exitosa (200)

{
  "request_id": 789,
  "circuito_id": "123456",
  "estado": "reenviada",
  "mensaje": "Solicitud de firma reenviada exitosamente",
  "referencia_externa": "REENVIO-2024-001"
}

Consultar Estado de Firma

Obtiene información detallada del estado actual de una solicitud de firma, incluyendo datos de todos los firmantes y su progreso individual.

Parámetros del Request

Ejemplo de Request

GET /firma/123456?referencia_externa=CONSULTA-001
Authorization: Bearer <tu-jwt-token>

Respuesta Exitosa (200)

{
  "request_id": 790,
  "circuito_id": "123456",
  "estado": "en_proceso",
  "en_proceso": true,
  "fecha_inicio": "2024-06-09T10:30:00+02:00",
  "fecha_completado": null,
  "firmantes": [
    {
      "email": "juan.perez@example.com",
      "estado": "firmado",
      "fecha_firma": "2024-06-09T15:45:32+02:00"
    },
    {
      "email": "maria.lopez@example.com",
      "estado": "pendiente",
      "fecha_firma": null
    }
  ],
  "referencia_externa": "CONSULTA-001"
}

// Ejemplo de respuesta cuando está completado
{
  "request_id": 791,
  "circuito_id": "123456",
  "estado": "completado",
  "en_proceso": false,
  "fecha_inicio": "2024-06-09T10:30:00+02:00",
  "fecha_completado": "2024-06-09T18:06:40+02:00",
  "firmantes": [
    {
      "email": "juan.perez@example.com",
      "estado": "firmado",
      "fecha_firma": "2024-06-09T15:45:32+02:00"
    },
    {
      "email": "maria.lopez@example.com",
      "estado": "firmado",
      "fecha_firma": "2024-06-09T18:06:40+02:00"
    }
  ],
  "referencia_externa": "CONSULTA-001"
}

Campos de Firmantes

Autenticación

Todos los endpoints de gestión de firma requieren autenticación JWT. Para obtener información detallada sobre cómo autenticarse, consulta la documentación de autenticación.

Gestión de Errores

Códigos de Error Comunes

Ejemplo de Respuesta de Error

{
  "error": "Circuito no encontrado o sin permisos",
  "request_id": 791,
  "details": {
    "circuito_id": "999999",
    "canal": "mi-canal"
  },
  "referencia_externa": "REF-123"
}

Ejemplos Completos de Integración

Ejemplo 1: Reenviar Firma (Python)

import requests

# Tu token JWT
jwt_token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
headers = {
    "Authorization": f"Bearer {jwt_token}",
    "Content-Type": "application/json"
}

# Reenviar solicitud de firma
payload = {
    "circuito_id": "123456",
    "mode": "ds",
    "referencia_externa": "REENVIO-2024-001"
}

response = requests.post(
    "https://pre-webhooks.imaginaenergia.com/firma/reenviar",
    headers=headers,
    json=payload
)

if response.status_code == 200:
    result = response.json()
    print(f"✅ Recordatorio enviado. Request ID: {result['request_id']}")
else:
    print(f"❌ Error: {response.json()['error']}")

Ejemplo 2: Consultar Estado (Python)

import requests

# Tu token JWT
jwt_token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
headers = {"Authorization": f"Bearer {jwt_token}"}

# Consultar estado de firma
circuito_id = "123456"
response = requests.get(
    f"https://pre-webhooks.imaginaenergia.com/firma/{circuito_id}",
    headers=headers
)

if response.status_code == 200:
    data = response.json()
    progreso = data['progreso']
    
    print(f"📊 Estado de firma del circuito {circuito_id}")
    print(f"Total firmantes: {progreso['total_firmantes']}")
    print(f"Completados: {progreso['firmantes_completados']}")
    print(f"Progreso: {progreso['porcentaje_completado']}%")
    
    print("\n👥 Firmantes:")
    for firmante in data['firmantes']:
        estado = "✅ Firmado" if firmante['completado'] else "⏳ Pendiente"
        print(f"  {firmante['nombre']}: {estado}")
        if firmante['completado']:
            print(f"    📅 Fecha: {firmante['fecha_firma']}")
            print(f"    🌐 IP: {firmante['ip_firma']}")
else:
    print(f"❌ Error: {response.json()['error']}")

Ejemplo 3: Workflow Completo (JavaScript)

// Función para reenviar firma y verificar estado
async function gestionarFirmaContrato(circuitoId, jwtToken) {
  const baseUrl = "https://pre-webhooks.imaginaenergia.com";
  const headers = {
    "Authorization": `Bearer ${jwtToken}`,
    "Content-Type": "application/json"
  };

  try {
    // 1. Reenviar solicitud de firma
    console.log("🔄 Reenviando solicitud de firma...");
    const reenvioResponse = await fetch(`${baseUrl}/firma/reenviar`, {
      method: "POST",
      headers: headers,
      body: JSON.stringify({
        circuito_id: circuitoId,
        mode: "ds",
        referencia_externa: `REENVIO-${Date.now()}`
      })
    });

    if (!reenvioResponse.ok) {
      throw new Error(`Error en reenvío: ${reenvioResponse.statusText}`);
    }

    const reenvioData = await reenvioResponse.json();
    console.log(`✅ Recordatorio enviado. Request ID: ${reenvioData.request_id}`);

    // 2. Esperar un momento y consultar estado
    await new Promise(resolve => setTimeout(resolve, 2000));

    console.log("\n🔍 Consultando estado actual...");
    const estadoResponse = await fetch(`${baseUrl}/firma/${circuitoId}`, {
      method: "GET",
      headers: headers
    });

    if (!estadoResponse.ok) {
      throw new Error(`Error consultando estado: ${estadoResponse.statusText}`);
    }

    const estadoData = await estadoResponse.json();
    const progreso = estadoData.progreso;

    console.log(`\n📊 Progreso: ${progreso.porcentaje_completado}%`);
    console.log(`   ${progreso.firmantes_completados}/${progreso.total_firmantes} firmantes han completado`);

    // 3. Mostrar estado de cada firmante
    console.log("\n👥 Estado de firmantes:");
    estadoData.firmantes.forEach(firmante => {
      const estado = firmante.completado ? "✅ Firmado" : "⏳ Pendiente";
      console.log(`   ${firmante.nombre} (${firmante.email}): ${estado}`);
      if (firmante.completado) {
        console.log(`      📅 ${firmante.fecha_firma}`);
      }
    });

    return {
      exito: true,
      progreso: progreso,
      firmantes: estadoData.firmantes
    };

  } catch (error) {
    console.error("❌ Error:", error.message);
    return {
      exito: false,
      error: error.message
    };
  }
}

// Uso
gestionarFirmaContrato("123456", "tu-jwt-token-aqui");

Recursos Relacionados

• Notificaciones de cambios de estado
• Seguridad de webhooks y callbacks
• Autenticación JWT
• Descargar especificación OpenAPI (envío inicial)
• Descargar especificación OpenAPI (gestión)
• Volver a la documentación principal