mirror of
https://github.com/marcogll/molding_assesment.git
synced 2026-03-15 13:25:04 +00:00
a7dc46a4cc
- Updated JSON assessment files for all levels - Modified formbricks_assistant.py script - Updated markdown assessment documents - Added comprehensive Form_requirements.md documentation - Updated tasks.md with current status
492 lines
13 KiB
Markdown
492 lines
13 KiB
Markdown
# Formbricks Survey Requirements - API v1
|
|
|
|
## Overview
|
|
|
|
Este documento es la **guía definitiva** para crear encuestas en Formbricks utilizando la API REST para las evaluaciones técnicas de moldeo por inyección. Incluye todos los requisitos de formato, ejemplos completos y solución de problemas comunes.
|
|
|
|
## Instalación y Configuración
|
|
|
|
- **Idioma**: NO multiidioma. Todos los contenidos se proporcionan en español únicamente.
|
|
- **Versión API**: v1 (compatible con Formbricks actual)
|
|
- **Formato Requerido**: Todos los campos de texto DEBEN usar formato objeto `{"default": "texto"}`, no strings directos.
|
|
|
|
## Variables de Entorno Requeridas
|
|
|
|
```env
|
|
FORMBRICKS_BASEURL=https://app.formbricks.com
|
|
FORMBRICKS_API_KEY=tu-api-key
|
|
FORMBRICKS_ENVIRONMENT_ID=tu-environment-id
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
### Crear Encuesta (Create Survey)
|
|
|
|
```
|
|
POST https://{baseurl}/api/v1/management/surveys
|
|
```
|
|
|
|
**Headers:**
|
|
- `Content-Type: application/json`
|
|
- `x-api-key: <API_KEY>`
|
|
|
|
**Respuesta Éxito**: 200 OK con datos de la encuesta creada
|
|
**Respuesta Error**: 400 Bad Request si campos mal formateados
|
|
|
|
### Actualizar Encuesta (Update Survey)
|
|
|
|
```
|
|
PUT https://{baseurl}/api/v1/management/surveys/{surveyId}
|
|
```
|
|
|
|
**Headers:**
|
|
- `Content-Type: application/json`
|
|
- `x-api-key: <API_KEY>`
|
|
|
|
### Obtener Encuesta (Get Survey)
|
|
|
|
```
|
|
GET https://{baseurl}/api/v1/management/surveys/{surveyId}
|
|
```
|
|
|
|
**Headers:**
|
|
- `x-api-key: <API_KEY>`
|
|
|
|
## Estructura del Payload
|
|
|
|
### Campos Principales
|
|
|
|
| Campo | Tipo | Requerido | Descripción |
|
|
|-------|------|-----------|-------------|
|
|
| `environmentId` | string | Sí | ID del entorno de Formbricks |
|
|
| `name` | string | Sí | Nombre de la encuesta |
|
|
| `status` | enum | Sí | `draft`, `inProgress`, `paused`, `completed` |
|
|
| `type` | enum | Sí | `link`, `app` |
|
|
| `displayOption` | enum | No | `displayOnce`, `displayMultiple`, `respondMultiple`, `displaySome` |
|
|
| `questions` | array | Sí | Array de preguntas (ver formato abajo) |
|
|
| `welcomeCard` | object | No | Tarjeta de bienvenida (ver formato abajo) |
|
|
| `endings` | array | No | Pantallas de finalización (ver formato abajo) |
|
|
| `languages` | array | Sí | Array vacío `[]` (no multiidioma) |
|
|
|
|
### ⚠️ REQUISITO CRÍTICO: Formato de Texto
|
|
|
|
**TODOS** los campos de texto deben usar el formato objeto, NO strings directos:
|
|
|
|
```json
|
|
// ✅ CORRECTO
|
|
"headline": {"default": "Texto de la pregunta"}
|
|
|
|
// ❌ INCORRECTO
|
|
"headline": "Texto de la pregunta"
|
|
```
|
|
|
|
Campos afectados: `headline`, `subheader`, `buttonLabel`, `backButtonLabel`, `placeholder`, `label`, `html`
|
|
|
|
### Welcome Card
|
|
|
|
```json
|
|
{
|
|
"welcomeCard": {
|
|
"enabled": true,
|
|
"headline": {
|
|
"default": "Evaluación Técnica de Moldeo"
|
|
},
|
|
"html": {
|
|
"default": "<b>Nivel Básico</b><br>Prueba de conocimientos fundamentales.<br><br>• Preguntas: 51<br>• Tiempo estimado: 45 min"
|
|
},
|
|
"buttonLabel": {
|
|
"default": "Siguiente"
|
|
},
|
|
"showResponseCount": false,
|
|
"timeToFinish": false
|
|
}
|
|
}
|
|
```
|
|
|
|
**IMPORTANTE**: TODOS los campos de texto (`headline`, `html`, `buttonLabel`) DEBEN ser objetos con un campo `default`.
|
|
|
|
### Ending Card
|
|
|
|
```json
|
|
{
|
|
"endings": [
|
|
{
|
|
"id": "p73t62dgwq0cvmtt6ug0hmfc",
|
|
"type": "endScreen",
|
|
"headline": {
|
|
"default": "¡Gracias!"
|
|
},
|
|
"subheader": {
|
|
"default": "Tu evaluación ha sido enviada correctamente."
|
|
},
|
|
"buttonLabel": {
|
|
"default": "Completar"
|
|
},
|
|
"buttonLink": "https://example.com"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
**Nota**: Los campos `headline`, `subheader`, `buttonLabel` usan formato objeto.
|
|
|
|
## Mapeo de Preguntas
|
|
|
|
### Estructura General
|
|
|
|
Las preguntas del JSON original se mapean a Formbricks. **TODOS los campos de texto requieren formato objeto**.
|
|
|
|
| Campo Original | Campo Formbricks | Formato Requerido | Notas |
|
|
|----------------|------------------|-------------------|--------|
|
|
| `id` | `id` | string | ID único de la pregunta |
|
|
| `question` | `headline` | `{"default": "texto"}` | Texto principal de la pregunta |
|
|
| `description` | `subheader` | `{"default": "texto"}` | Contexto adicional |
|
|
| `type` | `type` | string | Mapeado a tipos de Formbricks |
|
|
| `required` | `required` | boolean | Campo obligatorio |
|
|
| `options` | `choices` | array de objetos | Opciones con `label: {"default": "texto"}` |
|
|
|
|
**CRÍTICO**: Los campos `headline`, `subheader`, `buttonLabel`, `backButtonLabel`, `placeholder`, `label` (en choices) DEBEN usar formato objeto.
|
|
|
|
### Tipos de Preguntas
|
|
|
|
#### 1. Texto Abierto (openText)
|
|
|
|
```json
|
|
{
|
|
"id": "employee_number",
|
|
"type": "openText",
|
|
"inputType": "text",
|
|
"headline": {
|
|
"default": "Número de empleado"
|
|
},
|
|
"subheader": {
|
|
"default": ""
|
|
},
|
|
"required": true,
|
|
"placeholder": {
|
|
"default": "Ingresa tu número de empleado"
|
|
},
|
|
"buttonLabel": {
|
|
"default": "Siguiente"
|
|
},
|
|
"backButtonLabel": {
|
|
"default": "Anterior"
|
|
}
|
|
}
|
|
```
|
|
|
|
**Nota**: Todos los campos de texto usan formato objeto.
|
|
|
|
#### 2. Selección Múltiple Única (multipleChoiceSingle)
|
|
|
|
```json
|
|
{
|
|
"id": "mach_1",
|
|
"type": "multipleChoiceSingle",
|
|
"headline": {
|
|
"default": "¿Cuál es el componente que gira para transportar el material?"
|
|
},
|
|
"subheader": {
|
|
"default": "La unidad de plastificación consta de varios elementos clave para procesar el material."
|
|
},
|
|
"required": true,
|
|
"choices": [
|
|
{
|
|
"id": "c0",
|
|
"label": {
|
|
"default": "El barril reforzado (cilindro)"
|
|
}
|
|
},
|
|
{
|
|
"id": "c1",
|
|
"label": {
|
|
"default": "El tornillo (husillo)"
|
|
}
|
|
}
|
|
],
|
|
"buttonLabel": {
|
|
"default": "Siguiente"
|
|
},
|
|
"backButtonLabel": {
|
|
"default": "Anterior"
|
|
},
|
|
"shuffleOption": "none"
|
|
}
|
|
```
|
|
|
|
#### 3. Selección Múltiple (multipleChoiceMulti)
|
|
|
|
```json
|
|
{
|
|
"id": "qual_1",
|
|
"type": "multipleChoiceMulti",
|
|
"headline": {
|
|
"default": "¿Qué defectos pueden ocurrir en el proceso?"
|
|
},
|
|
"subheader": {
|
|
"default": "Selecciona todas las opciones aplicables."
|
|
},
|
|
"required": true,
|
|
"choices": [
|
|
{
|
|
"id": "c0",
|
|
"label": {
|
|
"default": "Tiro Corto"
|
|
}
|
|
},
|
|
{
|
|
"id": "c1",
|
|
"label": {
|
|
"default": "Rebaba"
|
|
}
|
|
}
|
|
],
|
|
"buttonLabel": {
|
|
"default": "Siguiente"
|
|
},
|
|
"backButtonLabel": {
|
|
"default": "Anterior"
|
|
},
|
|
"shuffleOption": "none"
|
|
}
|
|
```
|
|
|
|
## Ejemplo Completo de Payload
|
|
|
|
```json
|
|
{
|
|
"environmentId": "clygwxsbh01v5aga1sdien2th",
|
|
"name": "Evaluación Técnica de Moldeo - Nivel Básico",
|
|
"type": "link",
|
|
"status": "draft",
|
|
"displayOption": "displayOnce",
|
|
"welcomeCard": {
|
|
"enabled": true,
|
|
"headline": {
|
|
"default": "Evaluación Técnica de Moldeo"
|
|
},
|
|
"html": "<b>Nivel Básico</b><br>Prueba de conocimientos fundamentales sobre maquinaria, proceso, calidad y seguridad.<br><br>• Preguntas: 51<br>• Tiempo estimado: 45 min",
|
|
"buttonLabel": {
|
|
"default": "Siguiente"
|
|
},
|
|
"showResponseCount": false,
|
|
"timeToFinish": false
|
|
},
|
|
"questions": [
|
|
{
|
|
"id": "employee_number",
|
|
"type": "openText",
|
|
"headline": {
|
|
"default": "Número de empleado"
|
|
},
|
|
"subheader": "",
|
|
"required": true,
|
|
"inputType": "text",
|
|
"placeholder": {
|
|
"default": "Ingresa tu número de empleado"
|
|
},
|
|
"buttonLabel": {
|
|
"default": "Siguiente"
|
|
},
|
|
"backButtonLabel": {
|
|
"default": "Anterior"
|
|
}
|
|
},
|
|
{
|
|
"id": "mach_1",
|
|
"type": "multipleChoiceSingle",
|
|
"headline": {
|
|
"default": "En el sistema de plastificación, ¿cuál es el componente que gira para cizallar, fundir y transportar el material hacia adelante?"
|
|
},
|
|
"subheader": "La unidad de plastificación consta de varios elementos clave para procesar el material.",
|
|
"required": true,
|
|
"choices": [
|
|
{
|
|
"id": "c0",
|
|
"label": {
|
|
"default": "El barril reforzado (cilindro)"
|
|
}
|
|
},
|
|
{
|
|
"id": "c1",
|
|
"label": {
|
|
"default": "El tornillo (husillo)"
|
|
}
|
|
},
|
|
{
|
|
"id": "c2",
|
|
"label": {
|
|
"default": "La válvula check (anillo)"
|
|
}
|
|
},
|
|
{
|
|
"id": "c3",
|
|
"label": {
|
|
"default": "La banda calefactora cerámica"
|
|
}
|
|
}
|
|
],
|
|
"buttonLabel": {
|
|
"default": "Siguiente"
|
|
},
|
|
"backButtonLabel": {
|
|
"default": "Anterior"
|
|
},
|
|
"shuffleOption": "none"
|
|
}
|
|
],
|
|
"endings": [
|
|
{
|
|
"id": "p73t62dgwq0cvmtt6ug0hmfc",
|
|
"type": "endScreen",
|
|
"headline": {
|
|
"default": "¡Gracias!"
|
|
},
|
|
"subheader": {
|
|
"default": "Tu evaluación ha sido enviada correctamente."
|
|
},
|
|
"buttonLabel": {
|
|
"default": "Completar"
|
|
},
|
|
"buttonLink": "https://example.com"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Mapeo de Tipos de Preguntas
|
|
|
|
| Tipo Original | Tipo Formbricks | Descripción |
|
|
|--------------|-----------------|-------------|
|
|
| N/A (texto abierto) | `openText` | Campo de texto libre |
|
|
| Opción única | `multipleChoiceSingle` | Una sola respuesta |
|
|
| Múltiples opciones | `multipleChoiceMulti` | Selección múltiple |
|
|
|
|
## Reglas de Validación
|
|
|
|
1. **IDs Únicos**: Cada pregunta debe tener un ID único
|
|
2. **Choices IDs**: Cada opción debe tener un ID único (ej. `c0`, `c1`, `c2`, `c3`)
|
|
3. **Required**: Las preguntas marcadas como requeridas deben tener `required: true`
|
|
4. **No Multiidioma**: El campo `languages` debe ser un array vacío `[]`
|
|
5. **Formato de Objetos CRÍTICO**: TODOS los campos de texto DEBEN usar `{"default": "texto"}`
|
|
- `headline`, `subheader`, `buttonLabel`, `backButtonLabel`, `placeholder`, `label`, `html`
|
|
- Error 400 si se usa string directo
|
|
|
|
### Conversión Automática
|
|
|
|
Usa el script `formbricks_assitant.py` que automáticamente convierte strings a objetos. Los JSON fuente pueden mantener strings para legibilidad, la conversión ocurre en runtime.
|
|
|
|
## Campos Opcionales
|
|
|
|
### shuffleOption
|
|
|
|
Controla si las opciones se muestran en orden aleatorio:
|
|
- `none`: Orden original
|
|
- `random`: Orden aleatorio
|
|
|
|
### displayLimit
|
|
|
|
Número máximo de veces que se puede mostrar la encuesta.
|
|
|
|
### delay
|
|
|
|
Retraso en segundos antes de mostrar la encuesta.
|
|
|
|
## Configuración de Entorno
|
|
|
|
Las variables de entorno requeridas están en el archivo `.env`:
|
|
|
|
```env
|
|
FORMBRICKS_BASEURL=https://app.formbricks.com
|
|
FORMBRICKS_API_KEY=tu-api-key
|
|
FORMBRICKS_ENVIRONMENT_ID=tu-environment-id
|
|
```
|
|
|
|
## Ejemplo de cURL
|
|
|
|
```bash
|
|
curl --request POST \
|
|
--url https://app.formbricks.com/api/v1/management/surveys \
|
|
--header 'Content-Type: application/json' \
|
|
--header 'x-api-key: YOUR_API_KEY' \
|
|
--data @survey_payload.json
|
|
```
|
|
|
|
## Estructura de Archivos y Scripts
|
|
|
|
### Archivos JSON
|
|
Los archivos generados para Formbricks tienen esta estructura:
|
|
|
|
```
|
|
formbricks/
|
|
├── .env # Variables de entorno
|
|
├── Form_requirements.md # Este documento (guía definitiva)
|
|
├── assessment_conv.py # Script conversor JSON a Formbricks
|
|
├── formbricks_assitant.py # Script de creación de encuestas (con conversión automática)
|
|
├── convert_json.py # Utilidad de conversión de archivos JSON
|
|
├── funnel_registration_formbricks.json # Nivel 0
|
|
├── basic_v2_formbricks.json # Nivel 1 (57 preguntas)
|
|
├── medium_v2_formbricks.json # Nivel 2 (60 preguntas)
|
|
└── advanced_v2_formbricks.json # Nivel 3 (43 preguntas)
|
|
```
|
|
|
|
### Scripts Disponibles
|
|
|
|
#### `formbricks_assitant.py` (Principal)
|
|
Crea encuestas en Formbricks con conversión automática de formato:
|
|
```bash
|
|
cd /home/marco/Work/Carol/questions/formbricks
|
|
python3 formbricks_assitant.py
|
|
```
|
|
|
|
#### `assessment_conv.py` (Conversor)
|
|
Convierte archivos JSON originales a Formbricks:
|
|
```bash
|
|
cd /home/marco/Work/Carol/questions
|
|
python3 assessment_conv.py
|
|
```
|
|
|
|
#### `convert_json.py` (Utilidad)
|
|
Convierte archivos JSON existentes al formato API-compliant:
|
|
```bash
|
|
cd /home/marco/Work/Carol
|
|
python3 questions/formbricks/convert_json.py
|
|
```
|
|
|
|
## Referencias
|
|
|
|
- [Documentación API REST de Formbricks](https://formbricks.com/docs/api-reference/rest-api)
|
|
- [API Reference - Survey](https://formbricks.com/docs/api-reference/management-api--survey/)
|
|
|
|
## Errores Comunes de la API
|
|
|
|
### Error 400: "Fields are missing or incorrectly formatted"
|
|
|
|
Este error ocurre cuando los campos de texto no tienen el formato correcto de objeto.
|
|
|
|
**Causa común**: Usar string directo en lugar de objeto para cualquier campo de texto.
|
|
|
|
**Incorrecto**:
|
|
```json
|
|
{
|
|
"headline": "Evaluación Técnica",
|
|
"buttonLabel": "Siguiente"
|
|
}
|
|
```
|
|
|
|
**Correcto**:
|
|
```json
|
|
{
|
|
"headline": {"default": "Evaluación Técnica"},
|
|
"buttonLabel": {"default": "Siguiente"}
|
|
}
|
|
```
|
|
|
|
### Errores típicos de validación:
|
|
- `welcomeCard.headline: Expected object, received string`
|
|
- `questions[0].headline: Expected object, received string`
|
|
- `questions[0].choices[0].label: Expected object, received string`
|
|
|
|
### Solución
|
|
Ejecuta el script `formbricks_assitant.py` - maneja automáticamente la conversión de formato.
|