marcogll/molding_assesment
1
0
Fork 0
mirror of https://github.com/marcogll/molding_assesment.git synced 2026-03-15 21:25:11 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
9d5b17c3914bad2a6e4b836f311c816a0220e5c6
molding_assesment/questions/formbricks/Form_requirements.md

16 KiB
Raw Blame History

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

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.

Carga y Visualización de Encuestas

Para responder a consultas sobre Formbricks, es importante distinguir entre obtener los datos (API) y mostrar la encuesta (Renderizado).

¿Cuál es la forma correcta de cargar encuestas?

Aunque mencionas la REST API, la forma estándar y recomendada para cargar encuestas en una aplicación web no es llamando manualmente a los endpoints REST, sino utilizando el SDK de Formbricks (@formbricks/js).

El SDK se encarga automáticamente de llamar a la API correcta (Client API), verificar si el usuario debe ver una encuesta (basado en triggers) y renderizar la interfaz.

Código de inicialización estándar (SDK):

import formbricks from "@formbricks/js";

if (typeof window !== "undefined") {
  formbricks.init({
    environmentId: "TU_ENV_ID",
    apiHost: "https://app.formbricks.com", // O tu propia URL si usas self-hosting
    userId: "ID_DEL_USUARIO", // Opcional: para identificar al usuario
  });
}

Si realmente necesitas usar la REST API manual: Si tu caso de uso es muy personalizado (ej. un backend propio que sirve encuestas), tendrías que llamar al endpoint de Displays para saber qué encuesta mostrar:

  • Endpoint: POST /api/v1/client/displays
  • Respuesta: Te devuelve el objeto de la encuesta (preguntas, lógica y estilos).

Desventaja: Tendrás que construir tú mismo todo el HTML y la lógica del formulario basándote en ese JSON.

¿Es posible definir el color principal y usar otros backgrounds?

Sí, es totalmente posible. Tienes dos caminos principales para lograrlo:

Opción A: Sobrescribir estilos vía CSS (Recomendado para desarrolladores)

Esta es la forma más flexible si usas el SDK. Formbricks utiliza variables CSS que puedes redefinir en tu hoja de estilos global (globals.css o similar) para forzar tus colores y fondos sin importar lo que diga la configuración de la encuesta.

Añade esto a tu CSS:

:root {
  /* Color principal (botones, bordes activos, etc.) */
  --fb-brand-color: #ff5733;

  /* Color del texto sobre el color principal */
  --fb-brand-text-color: #ffffff;

  /* Fondo de la tarjeta de la encuesta */
  --fb-card-bg: #ffffff;

  /* Fondo general (detrás de la tarjeta en encuestas de enlace o modales) */
  --fb-survey-background-color: #f0f0f0;

  /* Bordes */
  --fb-border-color: #e2e8f0;
}

Al definir estas variables en tu proyecto, el SDK de Formbricks las usará automáticamente.

Opción B: Definirlo en la configuración de la encuesta (UI o API)

Si prefieres que el estilo venga definido desde la base de datos de Formbricks:

  • Desde la Interfaz (UI): Ve a la pestaña "Styling" (o "Look & Feel") dentro del editor de tu encuesta. Ahí puedes definir el Brand Color y el Background Styling (puedes subir una imagen, usar un degradado o un color sólido).

  • Desde la API (Payload): Si estás creando la encuesta programáticamente (POST /api/v1/management/surveys), el objeto JSON de la encuesta incluye una propiedad styling. Puedes enviarla así:

{
  "name": "Mi Encuesta",
  "styling": {
    "brandColor": "#ff5733",
    "cardBackgroundColor": "#ffffff",
    "cardBorderColor": "#e2e8f0",
    "background": {
       "bg": "#f0f0f0", // Color de fondo sólido
       "bgType": "color" // o "image" / "animation"
    }
  },
  "questions": [...]
}

Resumen

  • Carga: Usa el SDK (formbricks.init) para la integración más fácil. Usa la API REST solo si vas a construir tu propia interfaz de usuario desde cero.
  • Estilos: La forma más robusta de "definir" el color es usando las variables CSS (--fb-brand-color) en tu sitio web. Esto asegura que la encuesta siempre coincida con tu marca, independientemente de la configuración individual de la encuesta.
Reference in New Issue View Git Blame Copy Permalink