Consulta individual de folio

Este endpoint permite consultar el estado completo de un folio individual dentro de la plataforma Firmaris.

Su función es exclusivamente informativa:

No modifica datos
No avanza el proceso
No altera estados de firma

En palabras simples:

Sirve para mirar
No sirve para cambiar nada

Se utiliza principalmente para:

Monitorear el avance de un proceso de firma
Verificar si un folio fue firmado, rechazado o expirado
Obtener información estructurada de documentos y firmantes

Endpoint

Consulta de un folio existente mediante su identificador único (folioId).

Este endpoint opera únicamente en modo lectura.

GET https://www.sandboxadmin.firmaris.co/api/integrations/consult?folioId={folioId}

El folioId se envía como query parameter.

Autenticación

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

x-api-key: Bearer {TOKEN_EMPRESA}

Si el token:

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

La solicitud será rechazada automáticamente.

Parámetros de Entrada

Query Parameters

Parámetro	Tipo	Requerido	Qué es
folioId	string	Sí	Identificador único del folio

Reglas de Validación del `folioId`

El identificador del folio debe cumplir todas las siguientes condiciones:

Ser un hash hexadecimal
Tener una longitud exacta de 64 caracteres
No contener caracteres especiales
Existir en el sistema
Pertenecer a la empresa asociada al token utilizado

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

Respuesta Exitosa

Cuando la consulta es válida, la API retorna la información completa del folio.

La respuesta se divide en tres bloques principales:

Información general del folio
Documentos asociados
Firmantes del proceso

Estructura de la Respuesta

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	Ú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 al 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 al folio.

Campo	Tipo	Descripción
name	string	Nombre completo
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 rechazo
4	FIRMADO Y APROBADO	Se aprobó por interventor
5	RECHAZADO GESTION/ADMINISTRADOR	Rechazado por interventor o 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 – Folio inválido

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

403 – Acceso denegado

El token no es válido, está vencido o el folio no pertenece a la empresa.

404 – Recurso no encontrado

El folio solicitado no existe en el sistema.

Consideraciones Importantes

Este endpoint no modifica el estado del folio
Puede consultarse múltiples veces sin efectos secundarios
Es ideal para:
- Dashboards
- Seguimiento de procesos
- Automatizaciones
- Auditoría y control

Este endpoint es clave para entender y monitorear el ciclo de vida de un folio dentro de Firmaris.