Modelos y estructura de datos — API de Firmaris

Esta sección describe los modelos de datos principales utilizados en la API de Firmaris.

El objetivo es que cualquier integrador pueda entender:

• Qué entidades existen
• Qué campos las componen
• Cómo se relacionan entre sí
• Cómo interpretar las respuestas del sistema

---

Visión general de los modelos

Los modelos fundamentales del sistema son:

1. Folio
2. Firmante (Signer)
3. Documento
4. Respuestas estándar de la API
5. Errores

Todos los endpoints de integración trabajan directa o indirectamente con estos modelos.

---

1. Modelo Folio

El folio representa un proceso de firma completo.

Es la entidad central del sistema y agrupa:

• Documentos
• Firmantes
• Estado del proceso
• Configuración de firma

---

Estructura del modelo Folio

{
  "folioId": "string",
  "name": "string",
  "message": "string | null",
  "observation": "string | null",
  "dateCreate": "YYYY-MM-DD HH:mm:ss",
  "dateLastUpdate": "YYYY-MM-DD HH:mm:ss",
  "state": "string",
  "stateName": "string",
  "signatureType": "string",
  "signatureTypeName": "string",
  "flag_drop": "string"
}

---

Campos principales

Campo	Tipo	Descripción
folioId	string	Identificador único del folio
name	string	Nombre interno del folio
message	string | null	Mensaje enviado a los firmantes
observation	string | null	Observación administrativa
dateCreate	string	Fecha de creación
dateLastUpdate	string	Última actualización
state	string	Código interno de estado
stateName	string	Estado legible del folio
signatureType	string	Código del tipo de firma
signatureTypeName	string	Nombre del tipo de firma
flag_drop	string	Indicador de eliminación lógica

---

Estados comunes del folio

Estado	Descsripción
FIRMADO	El proceso fue completado
PENDIENTE	Aún faltan firmas
RECHAZADO FIRMANTE	El firmante rechazo
FIRMADO Y APROBADO	Se aprobó por interventor
RECHAZADO GESTION/ADMINISTRADOR	Rechazado por interventor o administrador
ANULADO	Proceso cancelado

---

2. Modelo Firmante (Signer)

Un firmante representa a una persona que debe firmar uno o más documentos dentro del folio.

Los firmantes no existen fuera del contexto de un folio.

---

Estructura del modelo Firmante

{
  "name": "string",
  "documentType": "string",
  "documentNumber": "string",
  "email": "string",
  "cellPhoneNumber": "string",
  "folioState": "string",
  "folioStateName": "string",
  "ipSignatureAddress": "string | null",
  "dateLastUpdate": "YYYY-MM-DD HH:mm:ss"
}

---

Campos principales

Campo	Tipo	Descripción
name	string	Nombre completo del firmante
documentType	string	Tipo de documento (CC, CE, etc.)
documentNumber	string	Identificador único del firmante
email	string	Correo de notificación
cellPhoneNumber	string	Teléfono para OTP
folioState	string	Estado del firmante dentro del folio
folioStateName	string	Estado legible
ipSignatureAddress	string | null	IP desde la que firmó
dateLastUpdate	string	Última acción del firmante

---

Estados comunes del firmante

Estado	Descripción
PENDIENTE	No ha firmado
FIRMADO	Firma completada
RECHAZADO	Rechazó la firma
ERROR	Error durante la firma

---

3. Modelo Documento

Un documento representa un archivo asociado a un folio.

Puede estar:

• Pendiente de firma
• Firmado
• Disponible para descarga

---

Estructura del modelo Documento

{
  "documentId": "string",
  "name": "string",
  "dateCreate": "YYYY-MM-DD HH:mm:ss"
}

---

Campos principales

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

---

4. Modelo de respuesta estándar

Todas las respuestas de la API siguen una estructura uniforme.

---

Respuesta exitosa

{
  "success": true,
  "status": 200,
  "message": "string",
  "data": {}
}

---

Campos comunes

Campo	Tipo	Descripción
success	boolean	Indica éxito o error
status	number	Código HTTP
message	string	Mensaje descriptivo
data	object	Información específica del endpoint

---

5. Modelo de error

Los errores siguen una estructura consistente para facilitar su manejo.

---

Error estándar

{
  "success": false,
  "status": 400,
  "error": {
    "message": "string"
  }
}

---

Buenas prácticas de manejo

• No asumas que data existe cuando hay errores
• Usa status para la lógica de control
• Registra message para auditoría
• No reintentes errores de negocio (400, 403)

---

6. Relación entre modelos

Relación conceptual:

• Un folio tiene:
  • Uno o más documentos
  • Uno o más firmantes
• Un firmante pertenece a un solo folio
• Un documento pertenece a un solo folio
• Todas las acciones giran alrededor del folioId

---

Conclusión

Comprender estos modelos es fundamental para:

• Integrar correctamente la API
• Interpretar respuestas
• Manejar errores de forma adecuada
• Construir flujos robustos y auditables

Esta estructura garantiza consistencia, trazabilidad y seguridad en toda la integración.

---