Reenvío de correos de firma

Este endpoint permite reenviar los correos de firma de un folio ya creado.

Su función es corregir o reenviar notificaciones, no crear firmantes nuevos ni modificar el proceso de firma.

En palabras simples:

• El folio ya existe
• Los firmantes ya existen
• Solo se actualiza correo y/o teléfono
• Se vuelve a enviar la notificación de firma

---

Endpoint

POST https://www.sandboxadmin.firmaris.co/api/integrations/forward_emails

---

Autenticación

La autenticación se realiza mediante una API Key asociada a la empresa dueña del folio.

x-api-key: Bearer {TOKEN_EMPRESA}

Si el token:

• No es válido
• Está vencido
• No pertenece a la empresa del folio

La solicitud será rechazada automáticamente.

---

Headers requeridos

x-api-key: Bearer {TOKEN_EMPRESA}
Content-Type: multipart/form-data

---

Parámetros de entrada (form-data)

Parámetro	Tipo	Requerido	Qué es
folioId	string	Sí	Identificador único del folio
signers	JSON string	Sí	Lista de firmantes a los que se les reenviará el correo
urlReturn	string	Sí	URL de retorno o callback

---

Reglas importantes de los parámetros

folioId

• Debe ser un hash válido
• Debe existir en el sistema
• Debe pertenecer a la empresa del token
• El folio debe estar activo (no anulado ni finalizado completamente)

---

signers

Este campo siempre se envía como un JSON convertido a string.

Debe ser:

• Un array
• Con uno o más objetos
• Cada objeto representa un firmante existente del folio

[
  {
    "documentNumber": "123456789",
    "email": "correo@ejemplo.com",
    "cellPhoneNumber": "3001234567"
  }
]

Reglas clave:

• documentNumber debe coincidir con un firmante existente del folio
• Solo se permiten estos campos
• No se puede cambiar nombre ni tipo de documento
• No se pueden agregar firmantes nuevos

---

urlReturn

• Debe ser una URL válida
• Máximo 500 caracteres
• Se utiliza como retorno después del proceso de firma

---

Qué hace este endpoint

✓ Reenvía el correo de firma
✓ Actualiza email y/o teléfono del firmante
✓ Mantiene el mismo link de firma
✓ Registra el evento en el historial del folio

---

Qué NO hace este endpoint

✘ No crea folios
✘ No crea firmantes nuevos
✘ No cambia el estado del folio
✘ No genera nuevos links de firma

---

Respuesta exitosa (200 OK)

Cuando el reenvío se realiza correctamente, la API responde:

{
  "success": true,
  "status": 200,
  "message": "Emails have been forwarded successfully."
}

---

Errores comunes

Error 400 — Datos inválidos

Ocurre cuando:

• Faltan parámetros obligatorios
• signers no es un JSON válido
• El documentNumber no existe en el folio

{
  "success": false,
  "status": 400,
  "error": {
    "message": "Invalid parameters"
  }
}

---

Error 403 — Acceso denegado

Ocurre cuando:

• El token no es válido
• El folio no pertenece a la empresa

{
  "success": false,
  "status": 403,
  "error": {
    "message": "Acceso denegado. No tiene los permisos necesarios para acceder a este recurso."
  }
}

---

Error 500 — Error interno

Ocurre cuando el sistema no pudo procesar el reenvío.

{
  "success": false,
  "status": 500,
  "error": {
    "message": "An error occurred while forwarding emails, please try again."
  }
}

---

Casos de uso comunes

• Correo del firmante mal digitado
• Número de teléfono incorrecto
• El firmante no recibió el email original
• Reenvío manual como recordatorio
• Actualización de datos de contacto

---

Consideraciones importantes

• Solo se pueden actualizar firmantes existentes
• El documentNumber es el identificador del firmante
• Cada reenvío queda registrado en el historial
• Evita reenvíos excesivos (anti-spam)
• El proceso de firma no se reinicia

Este endpoint es clave para mantener la comunicación correcta con los firmantes y evitar bloqueos por errores de contacto.