mirror of
https://github.com/marcogll/molding_assesment.git
synced 2026-03-15 14:25:02 +00:00
Update assessments, scripts, and documentation
- 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
This commit is contained in:
Marco Gallegos
491
questions/formbricks/Form_requirements.md
Normal file
491
questions/formbricks/Form_requirements.md
Normal file
@@ -0,0 +1,491 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user