Consulta masiva de folios

Este endpoint permite consultar todos los folios que pertenecen a una operación de firma masiva dentro de Firmaris.

Su función es exclusivamente informativa:

• No crea folios
• No modifica estados
• No avanza procesos de firma
• No altera información existente

En palabras simples:

• Sirve para ver cómo va una firma masiva
• No sirve para cambiar nada

Es especialmente útil cuando se necesita:

• Monitorear el progreso de una firma masiva
• Saber cuántos folios ya fueron firmados
• Identificar folios pendientes, rechazados o anulados
• Construir reportes y tableros de seguimiento

---

Endpoint

Consulta todos los folios asociados a una operación masiva mediante su identificador (massiveId).

GET https://www.sandboxadmin.firmaris.co/api/integrations/consult_massive_sign?massiveId={massiveId}

El massiveId se envía como query parameter.

---

Autenticación

La autenticación se realiza mediante una API Key asociada a la empresa que creó la operación masiva.

x-api-key: Bearer {TOKEN_EMPRESA}

Si el token:

• No es válido
• Está vencido
• No pertenece a la empresa dueña de la operación masiva

La solicitud será rechazada automáticamente.

---

Parámetros de entrada

Query Parameters

Parámetro	Tipo	Requerido	Qué es
massiveId	string	Sí	Identificador único de la operación de firma masiva

---

Reglas de validación del massiveId

El identificador de la operación masiva debe cumplir todas las siguientes condiciones:

• Ser un identificador válido del sistema
• No estar vacío
• Existir en la plataforma
• Pertenecer a la empresa asociada al token utilizado
• Corresponder a una operación de firma masiva activa o histórica

Si una sola de estas reglas no se cumple, la consulta será rechazada.

---

Respuesta exitosa

Cuando la consulta es válida, la API retorna un arreglo de folios.

Cada elemento del arreglo representa un folio individual que pertenece a la operación masiva.

La respuesta mantiene la misma estructura que la consulta individual de folios, lo que permite reutilizar lógica de procesamiento.

---

Estructura general de la respuesta

La respuesta contiene un arreglo llamado data.

Cada elemento del arreglo incluye tres bloques principales:

• folioData: Información general del folio
• documents: Documentos asociados al folio
• signers: Firmantes del proceso

---

folioData

Información principal del folio.

Campo	Tipo	Descripción
folioId	string	Identificador único del folio
name	string	Nombre del proceso o documento
message	string	Mensaje mostrado a los firmantes
observation	string | null	Observaciones adicionales
dateCreate	string	Fecha de creación del folio
dateLastUpdate	string | null	Última actualización
state	string	Código numérico del estado
stateName	string	Nombre legible del estado
flag_drop	string	Indica si el folio fue eliminado
signatureType	string	Código del tipo de firma
signatureTypeName	string	Nombre del tipo de firma

---

documents

Listado de documentos asociados a cada folio.

Campo	Tipo	Descripción
documentId	string	Identificador del documento
name	string	Nombre del archivo
dateCreate	string	Fecha de creación

---

signers

Listado de firmantes asociados a cada folio.

Campo	Tipo	Descripción
name	string	Nombre completo del firmante
documentType	string	Tipo de documento
documentNumber	string	Número de identificación
email	string	Correo electrónico
cellPhoneNumber	string	Teléfono
folioState	string	Código del estado del firmante
folioStateName	string	Nombre del estado
ipSignatureAddress	string | null	IP desde donde se realizó la firma
dateLastUpdate	string | null	Última acción del firmante

---

Estados del folio

Código	Estado	Qué significa
1	FIRMADO	El proceso fue completado
2	PENDIENTE	Aún faltan firmas
3	RECHAZADO FIRMANTE	El firmante rechazó
4	FIRMADO Y APROBADO	Aprobado por interventor
5	RECHAZADO GESTIÓN / ADMINISTRADOR	Rechazado por administrador
6	ANULADO	Proceso cancelado

---

Tipos de firma

Código	Tipo	Descripción
1	OTP Básico	Código enviado por correo
2	OTP Móvil Verificado	Código enviado por SMS

---

Errores comunes

400 — MassiveId inválido

El massiveId no cumple las reglas de validación o no existe.

403 — Acceso denegado

El token no es válido, está vencido o la operación masiva no pertenece a la empresa.

404 — Recurso no encontrado

La operación masiva solicitada no existe.

500 — Error interno

Error inesperado al procesar la consulta.

---

Consideraciones importantes

• Este endpoint no modifica ningún folio
• Puede consultarse múltiples veces sin efectos secundarios
• La cantidad de datos retornados depende del tamaño de la operación masiva
• Ideal para:
  • Monitoreo de procesos masivos
  • Dashboards administrativos
  • Reportes
  • Auditoría y control

Este endpoint es clave para entender el estado global de una firma masiva sin necesidad de consultar cada folio individualmente.