API Modulo Forms

✨ SERPI Forms Core API (v1)

Descripción

El microservicio SERPI Forms proporciona almacenamiento, renderizado y análisis histórico de respuestas para formularios dinámicos. Opera bajo una arquitectura multi-tenant y se integra de forma nativa con el ERP SERPI, permitiendo a las empresas gestionar encuestas, auditorías y captura de datos en terreno.

Autorización

La API utiliza un esquema de seguridad basado en tokens JWT (Bearer Token). Para acceder a los endpoints protegidos, debes incluir el token en las cabeceras HTTP de tu petición:

Authorization: Bearer <TOKEN_JWT>

> Nota de Desarrollo: Si el bypass de desarrollo local está habilitado, se puede utilizar el encabezado `X-Empresa-Id: <ID>` en lugar del JWT.

Beneficio

• Trazabilidad y Auditoría: Inmutabilidad de respuestas en el histórico y captura automática de la IP de origen (`ip_origen`).
• Aislamiento de Datos (Multi-Tenant): Despliegue de bases de datos dedicadas por cliente para máxima seguridad.
• Flexibilidad Estructural: Modelo híbrido Relacional/JSON que ofrece compatibilidad instantánea con motores de Inteligencia de Negocios (BI).

Tipos de peticiones

El API sigue los estándares RESTful utilizando los siguientes métodos HTTP:

• GET: Recuperar información (ej. listar formularios, consultar carpetas o métricas).
• POST: Crear nuevos recursos en el sistema o enviar respuestas públicas.
• PUT: Actualizar recursos existentes, reubicar carpetas o cambiar estados (activo/inactivo).
• DELETE: Ejecutar eliminaciones lógicas (soft-delete) o físicas de recursos protegidos.

¿Cómo funciona?

El ciclo de vida transaccional en SERPI Forms consta de los siguientes pasos:

1. Configuración y Organización: Se crean Categorías (con reglas de roles) y Carpetas para organizar el entorno (Workspace).
2. Diseño del Formulario: Se registra el esquema dinámico JSON que define las preguntas y lógicas del formulario.
3. Distribución: Se generan URLs públicas o se habilitan para consultas en tiempo real durante visitas comerciales (aplicando reglas de frecuencia).
4. Recolección: El encuestado diligencia los datos, impactando el endpoint público que registra la respuesta y orquesta el cobro SaaS (folios).
5. Análisis: Se consultan los indicadores globales y el histórico de respuestas a través de los endpoints de gestión.

---

⚡ Referencia de Endpoints

<tabber> Categorías y Roles=

GET /api/v1/categories

Devuelve un listado completo de todas las categorías configuradas en el sistema para la empresa del usuario autenticado. Las categorías permiten organizar formularios y establecer políticas de acceso basado en roles (RBAC).

• Ruta y Método: GET /api/v1/categories

Respuesta Exitosa (200 OK)

[
  {
    "categoriaId": 1,
    "nombre": "Encuestas de Satisfacción",
    "color": "#3B82F6",
    "roleIds": [101, 102]
  }
]

• Errores posibles: 401 Unauthorized, 403 Forbidden

POST /api/v1/categories

Registra una nueva categoría en el sistema.

• Ruta y Método: POST /api/v1/categories

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
Body	Object	Sí	Objeto JSON con nombre, color hexadecimal y roleIds.

Payload y Respuesta (201 Created)

{
  "nombre": "Control de Calidad",
  "color": "#F59E0B",
  "roleIds": [105, 108]
}

PUT y DELETE /api/v1/categories/{id}

• PUT: Actualiza las propiedades de una categoría existente. Retorna 204 No Content.
• DELETE: Elimina de forma física una categoría (falla si posee carpetas activas). Retorna 204 No Content.

GET /api/v1/categories/roles

Recupera todos los roles y perfiles configurados en la base de datos maestra del ERP (MvcSERPI) para la empresa actual.

• Ruta y Método: GET /api/v1/categories/roles

|-| Carpetas y Workspace=

GET /api/v1/folders

Retorna la estructura jerárquica completa de carpetas, subcarpetas y formularios, filtrada automáticamente por los roles del usuario.

• Ruta y Método: GET /api/v1/folders

Respuesta Exitosa (200 OK)

[
  {
    "id": "folder_10",
    "name": "Comercial 2026",
    "parentId": null,
    "categoriaId": 1,
    "color": "#3B82F6",
    "children": [],
    "forms": []
  }
]

POST /api/v1/folders

Crea una nueva carpeta en la raíz o como subcarpeta.

• Ruta y Método: POST /api/v1/folders

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
Body	Object	Sí	Datos de la carpeta (name, parentId, categoriaId).

PUT y DELETE /api/v1/folders/{id}

• PUT: Renombra o mueve una carpeta existente. Retorna 204 No Content.
• DELETE: Borrado lógico en cascada de una carpeta y sus dependencias. Retorna 204 No Content.

GET /api/v1/folders/{id}/history

Obtiene la bitácora de auditoría histórica de eventos sobre la carpeta (creación, renombramiento, etc).

|-| Formularios Dinámicos=

POST /api/v1/forms

Crea un nuevo formulario dinámico asociando su esquema JSON y retornando un UUID no secuencial para la URL pública.

• Ruta y Método: POST /api/v1/forms

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
Body	Object	Sí	Payload con nombre, título, descripción, carpetaId y esquemaJson.

Respuesta Exitosa (201 Created)

{
  "formId": 45,
  "uuid": "d3b07384-d113-4f4a-a62e-336712345678",
  "titulo": "Encuesta de Satisfacción en Visita",
  "urlPublica": "/f/15/d3b07384-d113-4f4a-a62e-336712345678"
}

Endpoints de Gestión de Formularios

• PUT /api/v1/forms/{uuid}: Actualiza esquema JSON y detalles.
• DELETE /api/v1/forms/{uuid}: Borrado lógico (Soft Delete) hacia la papelera.
• PUT /api/v1/forms/{uuid}/toggle-status: Activa o desactiva el formulario.
• PUT /api/v1/forms/{uuid}/move?carpetaId={id}: Reubica el formulario en otra carpeta.
• GET /api/v1/forms/{uuid}/history: Auditoría cronológica de modificaciones.
• PUT /api/v1/forms/{uuid}/restore: Restaura un formulario desde la papelera.

Endpoints de Respuestas y Métricas

• GET /api/v1/forms/stats: Devuelve KPIs globales (respuestasHoy, respuestasTotal, formulariosActivos).
• GET /api/v1/forms/{formId}/responses: Listado detallado de respuestas (soporta startDate y endDate).
• GET /api/v1/forms/{formId}/responses/count: Conteo numérico total de respuestas.

Disponibilidad y Terceros

• GET /api/v1/forms/surveys/available: Evalúa encuestas disponibles para un tercero, aplicando reglas anti-spam.
• POST /api/v1/forms/terceros/verificar: Valida registros activos en gdttercero enviando un arreglo de NITs.

|-| Público, SaaS y Empresa=

GET /api/v1/forms/public/{empresaid}/{uuid}

Devuelve el esquema y diseño público de un formulario para renderizarse en el frontend. (No requiere JWT).

• Ruta y Método: GET /api/v1/forms/public/{empresaid}/{uuid}

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
empresaid	Integer	Sí (Path)	ID de la empresa o 0 para autocompletar.
uuid	String	Sí (Path)	UUID público del formulario.

POST /api/v1/forms/public/{empresaid}/{uuid}/responses

Endpoint público para registrar la respuesta de un encuestado. Garantiza inmutabilidad y orquesta el cobro de folio SaaS.

• Ruta y Método: POST /api/v1/forms/public/{empresaid}/{uuid}/responses

Payload Esperado

{
  "respuestaJson": "{\"idtercero\":1502,\"idsucursal\":1,\"respuestas\":[{\"pregunta_id\":\"q1\",\"valor\":\"Excelente\"}]}"
}

POST /api/v1/billing/process

Orquestación interna SaaS para debitar folios transaccionales (Zero-Trust).

• Autenticación: Utiliza el encabezado HTTP X-Secret-Key en lugar de JWT.

GET /api/v1/companies/logo

Obtiene el logotipo corporativo configurado en la base de datos maestra (retorna Base64 o URL). </tabber>