Consulta múltiple de folios

Este endpoint permite consultar el estado de varios folios en una sola llamada a la API de Firmaris.

Su comportamiento es estrictamente informativo:

• No modifica datos
• No altera estados
• No avanza procesos de firma

En palabras simples:

• Sirve para consultar muchos folios a la vez
• No sirve para cambiar nada

Se utiliza principalmente para:

• Dashboards con múltiples procesos
• Seguimiento masivo de firmas
• Auditoría y control
• Optimizar llamadas evitando consultas individuales repetidas

---

Endpoint

Consulta múltiple de folios mediante un arreglo de identificadores (folioId).

Este endpoint opera únicamente en modo lectura.

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

---

Autenticación

La autenticación se realiza mediante una API Key asociada a la empresa propietaria de los folios.

x-api-key: Bearer {TOKEN_EMPRESA}

Si el token:

• No es válido
• Está vencido
• No pertenece a la empresa dueña de uno o más folios

La solicitud será rechazada o los folios no autorizados fallarán individualmente.

---

Body de la Solicitud

El cuerpo de la solicitud debe enviarse en formato JSON.

Parámetros

Campo	Tipo	Requerido	Qué es
folioId	array de string	Sí	Lista de identificadores únicos de folios

---

Reglas de Validación del folioId

Cada elemento del arreglo folioId se valida de forma independiente.

Cada ID debe cumplir todas las siguientes condiciones:

• Ser un string
• Tener formato de hash hexadecimal
• Tener una longitud válida
• Existir en el sistema
• Pertenecer a la empresa asociada al token utilizado

Si un folio no cumple las reglas, ese folio:

• No rompe la consulta completa
• Retorna su propio error dentro del arreglo de respuesta

---

Comportamiento de la Consulta

• El orden de la respuesta coincide exactamente con el orden del arreglo enviado
• Cada folio retorna su propio:
  • success
  • status
  • message
  • data (si aplica)

Esto permite manejar resultados mixtos en una sola respuesta.

---

Estructura General de la Respuesta

La respuesta siempre retorna un objeto principal con un arreglo data.

Cada elemento del arreglo representa un folio consultado.

Campos por folio

Campo	Tipo	Descripción
success	boolean	Indica si la consulta de ese folio fue exitosa
status	number	Código HTTP lógico del resultado
message	string	Mensaje descriptivo del resultado
folioId	string	ID del folio consultado
data	object | null	Información del folio (si aplica)

---

Estados del Folio

Código	Estado	Qué significa
1	FIRMADO	El proceso fue completado
2	PENDIENTE	Aún faltan firmas
3	RECHAZADO FIRMANTE	Un firmante rechazó
4	FIRMADO Y APROBADO	Aprobado por interventor
5	RECHAZADO GESTIÓN / ADMIN	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 Generales Remember

400 – Solicitud inválida

El body no cumple el formato esperado o el arreglo folioId es inválido.

403 – Acceso denegado

El token no es válido, está vencido o no tiene permisos.

---

Consideraciones Importantes

• Este endpoint no modifica estados ni procesos
• Puede consultarse múltiples veces sin efectos secundarios
• Está optimizado para consultas masivas
• Es ideal para:
  • Dashboards
  • Reportes
  • Automatizaciones
  • Seguimiento operativo
  • Auditoría

Este endpoint permite escalar la consulta de folios sin perder control individual sobre cada resultado.