Introducción

Maneja envíos de formularios y recupera datos de formularios.

🎯 ¿Qué hace este módulo?

El módulo FormData te permite enviar formularios llenos por los usuarios (formularios de contacto, encuestas, registros) a OneEntry y recuperar los datos enviados para análisis, informes y gestión.

Piénsalo como tu gestor de envíos de formularios: los usuarios envían formularios, tú los almacenas en OneEntry y los recuperas siempre que necesites ver respuestas, generar informes o analizar datos.

---

📖 Explicación Simple

Imagina que tienes un formulario de contacto en tu sitio web. Cuando los usuarios lo llenan:

1. Enviar - El usuario hace clic en "Enviar" → Los datos del formulario van a OneEntry
2. Almacenar - OneEntry guarda el envío (nombre, correo electrónico, mensaje)
3. Recuperar - Tú obtienes los envíos para ver, exportar o analizar
4. Gestionar - Filtrar, buscar y organizar las respuestas del formulario

Flujo de trabajo en el mundo real:

El usuario llena el formulario de contacto
↓
postFormsData() → Guardado en OneEntry
↓
getFormsDataByMarker() → OneEntry devuelve los datos
↓
El Admin ve los envíos 

Lo que puedes hacer:

• 📤 Enviar formularios - Enviar datos llenos por el usuario a OneEntry
• 📥 Ver envíos - Obtener todas las respuestas del formulario con paginación
• 🔍 Buscar envíos - Encontrar envíos específicos por marcador o filtro
• 📊 Exportar datos - Recuperar envíos para informes y análisis
• 📧 Gestionar respuestas - Rastrear envíos de formularios en un solo lugar

Escenarios de ejemplo:

Escenario	Qué Sucede
Formulario de Contacto	El usuario envía → Recibes notificación por correo → Ver en el panel de control
Encuesta	Recoger respuestas → Exportar a CSV → Analizar resultados
Registro	El usuario se registra → Datos almacenados → Enviar correo de confirmación
Comentarios	El cliente deja comentarios → El equipo revisa → Responder al cliente

---

✨ Conceptos Clave

¿Qué es el Datos del Formulario?

Los datos del formulario son la información que los usuarios envían a través de formularios.

Estructura del Envío del Formulario

Cada envío en OneEntry tiene:

  const body: IBodyPostFormData = {
    formIdentifier: 'contact_form', // Marcador del formulario
    formModuleConfigId: 9,          // ID de configuración del módulo
    moduleEntityIdentifier: 'blog', // Identificador de entidad del módulo
    replayTo: null,                 // Dirección de correo electrónico para responder
    status: 'sent',                 // Estado del envío
    formData: [                     // Campos del formulario
      {
        marker: 'string',           // Marcador del campo
        type: 'string',             // Tipo de campo
        value: 'Test',              // Valor del campo
      },
    ]
  };

Ciclo de Vida de los Datos del Formulario

1. El usuario llena el formulario en el navegador
   ↓
2. El frontend valida la entrada
   ↓
3. postFormsData() envía a OneEntry
   ↓
4. OneEntry valida y almacena el envío de datos del formulario
   ↓
5. Se envían notificaciones (correo, webhook)
   ↓
6. El Admin recupera con getFormsDataByMarker()
   ↓
7. Revisar, exportar o responder

Casos de Uso Comunes

Caso de Uso	Descripción	Ejemplo
Formularios de Contacto	Los clientes se comunican con preguntas	El equipo de soporte revisa y responde
Generación de Leads	Recoger información de clientes potenciales	El equipo de ventas hace seguimiento
Encuestas	Recoger comentarios y opiniones	Marketing analiza resultados
Registros	Registrarse para eventos, boletines	Rastrear asistentes/suscriptores
Solicitudes de Empleo	Recoger currículos y cartas de presentación	RRHH revisa candidatos
Formularios de Comentarios	Satisfacción del cliente y reseñas	Mejorar productos/servicios

---

📋 Lo Que Necesitas Saber

Enviar Formularios Requiere Configuración

Antes de enviar, necesitas:

1. Marcador del formulario - Identificador de texto único del formulario
2. ID de configuración del módulo del formulario - De la configuración del formulario
3. Identificador de entidad del módulo - De la configuración del formulario

Cómo obtener estos:

// Obtener formulario
const form = await Forms.getFormByMarker('contact_form');

// Extraer IDs requeridos
const formModuleConfigId = form.moduleFormConfigs[0].id;
const moduleEntityIdentifier = form.moduleFormConfigs[0].entityIdentifiers[0].id;

// Ahora puedes enviar

¿Por qué es necesario? OneEntry necesita saber:

• Qué plantilla de formulario usar
• Dónde almacenar los datos
• Qué reglas de validación aplicar

Estructura de los Datos del Formulario

El array formData contiene objetos de campo:

formData: [
  {
    marker: "field_name", // Identificador del campo
    type: "text"          // Tipo de campo
    value: "user_input",  // Entrada del usuario
  }
]

Importante:

• marker debe coincidir con los marcadores de campo de la definición del formulario
• type es útil para la validación
• value contiene la entrada del usuario

Estado del Envío

Usa status para rastrear el estado del envío:

Estado	Significado	Cuándo Usar
"sent"	Enviado con éxito	Predeterminado para nuevos envíos
"pending"	Esperando revisión	Moderación requerida
"processed"	Manejado por el admin	Marcado como revisado
"archived"	Envío antiguo/cerrado	Mantener para registros

Paginación

Recupera envíos en lotes.

Marcador del Formulario

Una forma de identificar envíos:

Identificador	Qué Es	Cuándo Usar
Marcador del Formulario	Identificador de plantilla del formulario	Obtener todos los envíos para un formulario específico

---

📊 Tabla de Referencia Rápida

Método	Descripción	Caso de Uso
postFormsData()	Enviar nuevos datos de formulario	El usuario envía el formulario de contacto
getFormsDataByMarker()	Obtener envíos para un formulario específico	Ver todos los envíos del formulario de contacto

❓ Preguntas Frecuentes (FAQ)

¿Cómo envío un formulario?

Necesitas tres cosas:

1. Configuración del formulario de Forms.getFormByMarker()
2. Datos de entrada del usuario
3. Llamar a FormData.postFormsData()

---

¿Puedo actualizar los datos del formulario enviados?

No directamente. Los envíos de formularios son típicamente inmutables para mantener la integridad de los datos.

Soluciones alternativas:

• Enviar una nueva versión con datos actualizados
• Usar el campo status para marcar envíos antiguos como obsoletos
• Implementar lógica de actualización personalizada en tu frontend

---

¿Cómo manejo las cargas de archivos en formularios?

Simplemente usa File o FileList con FormData.postFormsData() o sube archivos por separado usando el módulo FileUploading, luego incluye las URL de los archivos en los datos del formulario.

---

¿Cómo filtro envíos por fecha?

Usa los parámetros del cuerpo dateFrom y dateTo.

---

¿Puedo buscar envíos por valor de campo?

Sí, recupera envíos y busca del lado del cliente.

---

¿Cómo pagino a través de todos los envíos?

Usa offset y limit.

---

¿Cómo manejo errores de validación?

Usa try/catch y verifica los mensajes de error.

---

💡 Notas Importantes

⚠️ Se Requiere Configuración del Formulario

No puedes enviar formularios sin configuración:

• formModuleConfigId y moduleEntityIdentifier son requeridos
• Obtén estos de Forms.getFormByMarker() antes de enviar
• Almacénalos en tu aplicación para evitar llamadas API repetidas

---

🔒 Consideraciones de Seguridad

Nunca expongas datos sensibles:

• No envíes contraseñas en texto plano
• Valida la entrada tanto en el cliente como en el servidor
• Sanea la entrada del usuario antes de mostrarla

---

📦 Conjuntos de Datos Grandes

La paginación es importante:

• No recuperes miles de envíos a la vez
• Usa limit y offset para la paginación
• Considera el almacenamiento en caché para datos de acceso frecuente

---

🔄 Solo Lectura Después del Envío

Los datos del formulario son inmutables:

• No se pueden actualizar los envíos a través del SDK
• Envía una nueva versión si se necesitan cambios
• Usa el campo status para rastrear el estado del envío

---

🎓 Mejores Prácticas

• Caché de configuración del formulario - Evita obtener en cada envío
• Valida antes de enviar - Verifica campos requeridos del lado del cliente
• Usa paginación - Recupera envíos en lotes
• Maneja errores de manera adecuada - Siempre usa try/catch
• Usa marcadores de manera consistente - Referencia formularios por marcador, no por ID
• Rastrea el estado del envío - Usa el campo de estado para organizar envíos
• Exporta datos regularmente - Realiza copias de seguridad de los envíos a CSV/base de datos
• Monitorea nuevos envíos - Implementa sondeo o webhooks

---

Definición del módulo FormData

const { FormData } = defineOneEntry(
  "tu-url-del-proyecto", {
    "token": "tu-token-de-aplicación"
  }
);

Configuración del formulario:

1. Obtén el formulario por marcador usando Forms.getFormByMarker('tu-marcador-de-formulario').
2. Usa el campo moduleFormConfigs del formulario recuperado para la configuración utilizada al enviar los datos del formulario.
3. Crea el cuerpo usando moduleFormConfig y publica los datos del formulario.

const formModuleConfigId = moduleFormConfigs[0].id;
const moduleEntityIdentifier = moduleFormConfigs[0].entityIdentifiers[0].id;
const body = {
  "formIdentifier": "tu-marcador-de-formulario",
  "formModuleConfigId": formModuleConfigId,
  "moduleEntityIdentifier": moduleEntityIdentifier,
  "replayTo": null,
  "status": "sent",
  "formData": [...]
};
const response = await FormData.postFormsData(body);

---

🔗 Documentación Relacionada

• Módulo de Formularios - Crear y gestionar estructuras de formularios
• Módulo de Carga de Archivos - Manejar cargas de archivos en formularios
• Módulo de Eventos - Configurar notificaciones impulsadas por eventos
• Módulo de Usuarios - Gestionar usuarios que envían formularios

---