API Modulo Forms

⚡ Referencia de Endpoints

A continuación, los servicios expuestos organizados por método HTTP. Haz clic en cada bloque para expandir la documentación.

🟩 GET (Consultas y Lecturas)

GET /api/v1/categories

Devuelve un listado completo de todas las categorías configuradas en el sistema para la empresa del usuario autenticado.

Respuesta Exitosa (200 OK)

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

GET /api/v1/folders

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

GET /api/v1/forms/stats

Calcula y devuelve los indicadores clave (KPIs) globales del Workspace para la empresa.

Respuesta Exitosa (200 OK)

{
  "respuestasHoy": 142,
  "respuestasTotal": 12850,
  "formulariosActivos": 18
}

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).

Parámetros

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

🟦 POST (Creación y Procesos)

POST /api/v1/forms

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

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
Body	Object	Sí	Datos requeridos para la plantilla de formulario.

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"
}

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

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

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). No utiliza JWT, sino el encabezado HTTP X-Secret-Key.

🟧 PUT (Actualizaciones)

PUT /api/v1/forms/{uuid}

Actualiza el título, descripción y estructura de preguntas (Esquema JSON) de un formulario existente.

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
uuid	String	Sí (Path)	UUID del formulario a actualizar.
Body	Object	Sí	Datos actualizados del formulario.

PUT /api/v1/forms/{uuid}/toggle-status

Alterna el estado de un formulario entre Activo e Inactivo (bloquea la recepción de respuestas).

PUT /api/v1/forms/{uuid}/move

Reubica un formulario en otra carpeta contenedora o en la raíz del Workspace enviando ?carpetaId=25.

🟥 DELETE (Eliminaciones)

DELETE /api/v1/categories/{id}

Elimina de forma física y permanente una categoría. Fallará si la categoría posee carpetas activas.

DELETE /api/v1/folders/{id}

Realiza un borrado lógico en cascada de una carpeta y de todas sus subcarpetas y formularios dependientes.

DELETE /api/v1/forms/{uuid}

Ejecuta un borrado lógico (Soft Delete) del formulario, desactivándolo y moviéndolo a la papelera sin perder respuestas históricas. Requiere estar apagado previamente.

Códigos de Error Posibles

• 400 Bad Request: El formulario está Activo. Debe desactivarse antes de eliminarse.
• 401 Unauthorized: No autenticado.
• 404 Not Found: Formulario inexistente.