molding_assesment/questions/formbricks/Form_requirements.md

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

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:

// ✅ CORRECTO
"headline": {"default": "Texto de la pregunta"}

// ❌ INCORRECTO
"headline": "Texto de la pregunta"

Campos afectados: headline, subheader, buttonLabel, backButtonLabel, placeholder, label, html

Welcome Card

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

{
  "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)

{
  "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)

{
  "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)

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

{
  "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:

FORMBRICKS_BASEURL=https://app.formbricks.com
FORMBRICKS_API_KEY=tu-api-key
FORMBRICKS_ENVIRONMENT_ID=tu-environment-id

Ejemplo de cURL

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:

cd /home/marco/Work/Carol/questions/formbricks
python3 formbricks_assitant.py

assessment_conv.py (Conversor)

Convierte archivos JSON originales a Formbricks:

cd /home/marco/Work/Carol/questions
python3 assessment_conv.py

convert_json.py (Utilidad)

Convierte archivos JSON existentes al formato API-compliant:

cd /home/marco/Work/Carol
python3 questions/formbricks/convert_json.py

Referencias

• Documentación API REST de Formbricks
• API Reference - 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:

{
  "headline": "Evaluación Técnica",
  "buttonLabel": "Siguiente"
}

Correcto:

{
  "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.