Firma masiva de folios

Este endpoint permite iniciar una firma de varios folios en una sola operación, utilizando un único firmante.

Su objetivo es optimizar procesos masivos, evitando que el firmante tenga que ingresar y firmar cada folio por separado.

En palabras simples:

• Se envían muchos folioId
• Se define un solo firmante
• Se genera una única URL
• El firmante firma todo en una sola sesión

---

Endpoint

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

---

Autenticación

La autenticación se realiza mediante una API Key asociada a la empresa.

x-api-key: Bearer {TOKEN_EMPRESA}

Si el token:

• No es válido
• Está vencido
• No pertenece a la empresa dueña de los folios

La solicitud será rechazada automáticamente.

---

Tipo de contenido

Este endpoint NO utiliza JSON tradicional.
Los datos deben enviarse como:

Content-Type: multipart/form-data

---

Parámetros de Entrada (form-data)

Parámetro	Tipo	Requerido	Descripción	Validaciones
foliosIds	JSON string	Sí	Lista de IDs de folios a firmar	JSON válido, array de strings, sin duplicados
signer	JSON string	Sí	Información del firmante	JSON válido, array con exactamente un objeto
urlReturn	string	Sí	URL de retorno o callback	URL válida, máximo 500 caracteres

---

Estructura del parámetro foliosIds

Debe enviarse como string JSON.

[
  "FOLIO_ID_1",
  "FOLIO_ID_2",
  "FOLIO_ID_3"
]

Reglas:

• Debe ser un array
• No se permiten IDs duplicados
• Todos los folios deben existir
• Todos deben estar en estado PENDIENTE

---

Estructura del parámetro signer

Debe enviarse como array JSON con exactamente un objeto.

[
  {
    "name": "Nombre Completo",
    "email": "correo@ejemplo.com",
    "documentType": "CC",
    "documentNumber": "123456789",
    "cellPhoneNumber": "3001234567"
  }
]

⚠️ Importante
Aunque solo haya un firmante, DEBE enviarse como array.

---

Tipos de documento permitidos (documentType)

Código	Descripción
CC	Cédula de ciudadanía
CE	Cédula de extranjería
NIT	Número de identificación tributaria
TI	Tarjeta de identidad

---

Respuesta exitosa (200 OK)

Cuando la operación es válida, la API genera una URL única de firma masiva.

{
  "success": true,
  "status": 200,
  "message": "Generación de URL para firma masiva completada con éxito",
  "data": {
    "signProcessMassiveUrl": "https://www.devapp.firmaris.co/?msv=ENCRYPTED_PACKAGE_ID&a=ENCRYPTED_ACCOUNT_ID&cc=BASE64_DOCUMENT_NUMBER&ur=https://miweb.com/callback&rej=false",
    "massiveId": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
  }
}

---

Significado de los campos de respuesta

Campo	Qué es
signProcessMassiveUrl	URL que el firmante debe abrir para firmar todos los folios
massiveId	Identificador de la operación masiva para seguimiento

---

Errores comunes

Error 400 — Validación de parámetros

Ocurre cuando alguno de los datos enviados no cumple las reglas.

Ejemplos de causas:

• JSON mal formado
• Folios duplicados
• Firmante mal definido
• URL inválida

---

Error 403 — Acceso denegado

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

---

Error 404 — Folio no encontrado

{
  "success": false,
  "status": 404,
  "error": {
    "message": "Acceso denegado. No tiene los permisos necesarios para acceder a este recurso o es posible que el recurso al que intenta acceder ya no exista."
  }
}

---

Error 409 — Firmante ya firmó o rechazó

{
  "success": false,
  "status": 409,
  "error": {
    "message": "El firmante ya ha realizado la firma o rechazado este folio."
  }
}

---

Error 410 — Folio ya firmado o vencido

{
  "success": false,
  "status": 410,
  "error": {
    "message": "Acceso denegado. No tiene los permisos necesarios para acceder a este recurso o es posible que el recurso al que intenta acceder ya no exista."
  }
}

---

Error 500 — Error interno

{
  "success": false,
  "status": 500,
  "error": {
    "message": "Se produjo un error al generar la URL para la firma masiva"
  }
}

---

Consideraciones importantes

• Máximo 50 folios por operación
• Solo un firmante por firma masiva
• Todos los folios deben estar PENDIENTES
• La URL generada expira en 24 horas
• Si un folio falla, toda la operación falla

---

Seguimiento posterior

El massiveId retornado permite:

• Consultar estado de la operación
• Auditar resultados
• Construir reportes
• Integrar dashboards

Se consulta mediante:

GET /api/integrations/consult_massive_sign?massiveId={massiveId}