Descripción

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

✅ Características principales

  • Operación síncrona: Respuesta inmediata (típicamente < 1 segundo)
  • Múltiples canales: Email, SMS, o Email con OTP
  • Reenvío permitido: Puedes enviar firma múltiples veces para el mismo contrato
  • Trazabilidad completa: Cada envío genera un request_id único
  • Referencia externa: Vincula con tus sistemas internos (CRM, tickets, etc.)

ℹ️ ¿Cuándo usar este endpoint?

Utiliza este endpoint cuando:

  • Creaste un contrato con no_enviar_firma: true
  • El cliente no recibió la comunicación inicial y necesitas reenviar
  • Quieres controlar el momento exacto del envío de firma
  • Necesitas cambiar el canal de envío (de email a SMS, por ejemplo)

Endpoint

POST /firma

Este endpoint está disponible en los siguientes servidores:

  • PRE: https://pre-webhooks.imaginaenergia.com/firma
  • PRO: https://webhooks.imaginaenergia.com/firma

Autenticación

El endpoint requiere autenticación mediante token JWT en el header Authorization.

Authorization: Bearer {tu_token_jwt}

Para obtener un token JWT, consulta la Guía de Autenticación.

⚠️ Importante

El token JWT debe ser válido y no estar expirado. Un token inválido resultará en un error 401 Unauthorized.

Parámetros del Request

Parámetro Tipo Requerido Descripción
contrato_id integer ✅ Sí ID del contrato. Se obtiene del campo contrato_result.id en la respuesta del endpoint de contratación.
canal_envio string ✅ Sí Canal de envío: "email", "sms", o "email_otp"
direcciones_firma string ✅ Sí Email, teléfono, o ambos separados por ;
referencia_externa string ❌ No Referencia opcional para tracking interno (ej: "DEAL-12345")

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 (nombre@dominio.tld)
  • 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"
  • Validación: Ambos formatos deben ser válidos, separados por ;
  • Ventaja: Máxima seguridad con doble factor de autenticación

💡 Tip: Selección del Canal

Recomendación por tipo de cliente:

  • Email: Uso general para residencial y empresa (95% de los casos)
  • SMS: Clientes sin acceso a email o preferencia explícita
  • Email OTP: Contratos de alto valor o cuando el cliente lo solicita

Ejemplos de Uso

Ejemplo 1: Envío por email (caso más común)

POST /firma Content-Type: application/json Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... { "contrato_id": 369877, "canal_envio": "email", "direcciones_firma": "cliente@example.com", "referencia_externa": "ZOHO-DEAL-12345" }

Ejemplo 2: Envío por SMS

POST /firma Content-Type: application/json Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... { "contrato_id": 369877, "canal_envio": "sms", "direcciones_firma": "606123456" }

Ejemplo 3: Email con OTP (doble factor)

POST /firma Content-Type: application/json Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... { "contrato_id": 369877, "canal_envio": "email_otp", "direcciones_firma": "cliente@example.com;606123456" }

Ejemplo 4: Reenvío (cliente no recibió)

POST /firma Content-Type: application/json Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... { "contrato_id": 369877, "canal_envio": "email", "direcciones_firma": "cliente@example.com", "referencia_externa": "REENVIO-001" }

Respuesta del Endpoint

Respuesta Exitosa (200 OK)

{ "request_id": 12345, "firma_result": { "status": "success", "message": "Contrato enviado para firma digital" }, "referencia_externa": "ZOHO-DEAL-12345" }
Campo Tipo Descripción
request_id integer ID único del request. Úsalo para auditoría y troubleshooting.
firma_result object Contiene el estado del envío.
referencia_externa string Referencia externa proporcionada en el request (si se envió).

Errores Comunes

400 Bad Request - Parámetros Inválidos

{ "error": "Error de validación: El parámetro 'contrato_id' es requerido", "request_id": 12345, "referencia_externa": "REF-001" }

Causas comunes:

  • Falta contrato_id, canal_envio, o direcciones_firma
  • contrato_id no es un número entero
  • canal_envio tiene un valor no permitido
  • Formato de email o teléfono inválido en direcciones_firma
  • JSON malformado en el body del request

401 Unauthorized - Autenticación Fallida

{ "error": "Authentication failed" }

Causas comunes:

  • Token JWT no proporcionado en el header Authorization
  • Token JWT inválido o expirado
  • Token JWT con formato incorrecto

404 Not Found - Contrato No Existe

{ "error": "Error en firma digital: Error sending contract for signature: 404 Client Error: Not Found", "request_id": 12345, "referencia_externa": "REF-001" }

Causas comunes:

  • El contrato_id no existe
  • El contrato fue eliminado o está en un estado que no permite firma

500 Internal Server Error

{ "error": "Error en firma digital: Error sending contract for signature: 502 Bad Gateway", "request_id": 12345, "referencia_externa": "REF-001" }

Causas comunes:

  • Error en la comunicación con la API de firma
  • Servidor de firma temporalmente no disponible
  • Error de configuración en variables de entorno del servidor

⚠️ Manejo de Errores

En caso de error:

  1. Revisa el campo error para entender la causa
  2. Usa el request_id para buscar detalles en logs o base de datos
  3. Verifica que el contrato existe y está en estado correcto
  4. Si el error persiste, contacta con soporte técnico

Flujo de Uso Típico

Escenario 1: Creación de contrato sin envío automático de firma

  1. Paso 1: Crear el contrato con no_enviar_firma: true
    POST /contrato/residencial { "operacion": { "no_enviar_firma": true, ... }, "cliente": { ... }, "punto_suministro": { ... }, ... }
  2. Paso 2: Obtener el contrato_id de la respuesta
    { "request_id": 100, "contrato_result": { "id": 369877, // ← Este es el contrato_id "codigo": "CON-2026-12345", ... }, ... }
  3. Paso 3: Enviar a firma cuando estés listo
    POST /firma { "contrato_id": 369877, "canal_envio": "email", "direcciones_firma": "cliente@example.com" }

Escenario 2: Reenvío de firma (cliente no recibió email)

  1. Paso 1: Cliente reporta que no recibió el email de firma
  2. Paso 2: Verifica que tienes el contrato_id
  3. Paso 3: Reenvía la firma (puedes hacerlo múltiples veces)
    POST /firma { "contrato_id": 369877, "canal_envio": "email", "direcciones_firma": "cliente@example.com", "referencia_externa": "REENVIO-001" }

Escenario 3: Cambio de canal (de email a SMS)

  1. Paso 1: Email original no fue recibido o cliente prefiere SMS
  2. Paso 2: Envía por SMS en lugar de email
    POST /firma { "contrato_id": 369877, "canal_envio": "sms", "direcciones_firma": "606123456", "referencia_externa": "CAMBIO-A-SMS" }

Documentación OpenAPI / Swagger

Para una documentación interactiva completa con todos los detalles técnicos, consulta nuestra especificación OpenAPI:

📚 Recursos Disponibles

La especificación OpenAPI incluye:

  • ✅ Esquemas completos de request y response
  • ✅ Validaciones de formato y tipos de datos
  • ✅ Múltiples ejemplos de uso por caso
  • ✅ Todos los posibles códigos de error y sus causas
  • ✅ Descripción detallada de cada parámetro

💡 ¿Necesitas ayuda?

Si tienes preguntas o encuentras problemas:

  • 📧 Email: serviciosistemas@imaginaenergia.com
  • 📚 Documentación: Volver al índice
  • 🔍 Auditoría: Usa el request_id para buscar en logs