postFormsData

Envía datos del formulario a la plataforma OneEntry.

🎯 ¿Qué hace este método?

Este método envía datos del formulario a la plataforma OneEntry. Piensa en ello como hacer clic en "Enviar" en un formulario de contacto: envía toda la entrada del usuario (nombre, correo electrónico, mensaje, archivos, etc.) al servidor.

Casos de uso:

• 📝 Formularios de contacto
• 📋 Formularios de registro
• 💬 Formularios de retroalimentación
• 📤 Cargas de archivos
• 🎫 Tickets de soporte

📖 Explicación Simple

Cuando un usuario completa un formulario en tu sitio web, necesitas enviar esos datos a algún lugar. Este método hace exactamente eso: toma todos los campos del formulario (texto, números, archivos, etc.) y los envía a OneEntry.

Piensa en ello como:

User fills form → Your code calls postFormsData() → Data saved in OneEntry ✅

---

🚀 Ejemplo Súper Simple (¡Empieza Aquí!)

Escenario: Tienes un formulario de contacto con solo un campo de nombre.

// Step 1: User fills the form (e.g., enters "John Doe")
// Step 2: Send it to OneEntry

const response = await FormData.postFormsData({
  formIdentifier: "contact_us",        // 👈 Your form's name
  formModuleConfigId: 2,               // 👈 Form config ID (from OneEntry admin)
  moduleEntityIdentifier: "blog",      // 👈 Where to save it (from OneEntry)
  replayTo: null,                      // 👈 Reply email (optional)
  status: "sent",                      // 👈 "sent" or "draft"
  formData: [                          // 👈 The actual form data
    {
      marker: "name",                  // 👈 Field name
      type: "string",                  // 👈 Field type
      value: "John Doe"                // 👈 User's input
    }
  ]
});

// ✅ Done! Form submitted successfully
console.log("Form submitted, ID:", response.formData.id);

¡Eso es todo! Ahora veamos cómo manejar diferentes tipos de campos...

---

📋 Lo Que Necesitas Saber Antes de Usar

Antes de llamar a este método, necesitas estas 3 cosas del panel de administración de OneEntry:

1. formIdentifier - El nombre único de tu formulario (por ejemplo, "contact_us")
2. formModuleConfigId - ID de configuración del formulario (un número, por ejemplo, 2)
3. moduleEntityIdentifier - Dónde almacenar los datos (por ejemplo, "blog", "contacts")

¿Cómo encontrarlos?

• Inicia sesión en OneEntry Admin
• Ve a la sección de Formularios
• Copia los valores de la configuración de tu formulario

---

🔧 Firma del Método

.postFormsData(

,

);

Esquema de Parámetros

Esquema (cuerpo)

body(required): IBodyPostFormData
Cuerpo de la solicitud
ejemplo:

{
  "formIdentifier": "test-form",
  "formModuleConfigId": 2,
  "moduleEntityIdentifier": "blog",
  "replayTo": null,
  "status": "sent",
  "formData": [
    {
      "marker": "name",
      "type": "string",
      "value": "Test"
    }
  ]
}

body.formIdentifier(required): string
Identificador de texto (marcador) del formulario.
ejemplo: "form"

body.formModuleConfigId(required): number
El identificador único de la configuración del módulo del formulario.
ejemplo: 2

body.moduleEntityIdentifier(required): string
Identificador de texto (marcador) de la entidad del módulo.
ejemplo: "blog"

body.replayTo(required): string | null
Correo electrónico para responder.
ejemplo: "some@email.com"

body.status(required): string
Estado del formulario.
ejemplo: "sent"

body.formData(required): FormDataPostType[]
Array de objetos de datos del formulario. Los valores de una presentación difieren de las formas de lectura — ver FormDataPostType.
ejemplo:

[
  {
    "marker": "name",
    "type": "string",
    "value": "Jack"
  }
]

body.fileQuery: IUploadingQuery
Consulta de archivo opcional para cargar archivos. Mantenido por compatibilidad: el SDK lee fileQuery del campo de archivo en sí (ver IBodyTypeFile), no del cuerpo, por lo que un conjunto aquí no cambia dónde se carga un archivo.
ejemplo:

{
  "type": "page",
  "entity": "editor",
  "id": 3787
}

fileQuery.type(required): string
Tipo, determina el nombre de la carpeta en el almacenamiento.
ejemplo: "page"

fileQuery.entity(required): string
Nombre de la entidad desde la cual se carga el archivo, determina el nombre de la carpeta en el almacenamiento.
ejemplo: "editor"

fileQuery.id(required): number
Identificador del objeto desde el cual se carga el archivo, determina el nombre de la carpeta en el almacenamiento.
ejemplo: 3787

fileQuery.width: number
Parámetro de ancho.
ejemplo: 0

fileQuery.height: number
Parámetro de altura.
ejemplo: 0

fileQuery.compress: boolean
Indicador de optimización (compresión) para imágenes.
ejemplo: true

langCode: string
Código de idioma. Predeterminado: "en_US"
ejemplo: "en_US"

Ejemplos

Ejemplo mínimo

const body = {
  ,
  ,
  ,
  ,
  ,
  
    {
      ,
      
      
    }
  ]
};
const response = await FormData.postFormsData(body);

Ejemplo con un atributo de tipo simple "string", "number", "float"

const body = {
  ,
  ,
  ,
  ,
  ,
  
    {
      ,
      ,
      
    },
    {
      ,
      ,
      
    },
    {
      ,
      ,
      
    }
  ]
};
const response = await FormData.postFormsData(body);

---

Ejemplo con un atributo de tipo simple "date", "dateTime", "time"

const body = {
  ,
  ,
  ,
  ,
  ,
  
    {
      ,
      ,
      
        "fullDate": "2024-05-07T21:02:00.000Z",
        "formattedValue": "08-05-2024 00:02",
        "formatString": "DD-MM-YYYY HH:mm"
      }
    }
  ]
};
const response = await FormData.postFormsData(body);

---

Ejemplo con un atributo de tipo simple "text" (Solo uno de htmlValue, plainValue o mdValue puede ser proporcionado)

const body = {
  ,
  ,
  ,
  ,
  ,
  
    {
      ,
      ,
      
        {
          "htmlValue": "<p>Hello world</p>",
          
            "isImageCompressed": true,
            "editorMode": "html"
          }
        }
      ]
    }
  ]
};
const response = await FormData.postFormsData(body);

---

Ejemplo con un atributo de tipo simple "textWithHeader" (Solo uno de htmlValue, plainValue o mdValue puede ser proporcionado)

const body = {
  ,
  ,
  ,
  ,
  ,
  
    {
      marker: ,
      type: ,
      : [
        {
          "header": "Headline",
          "htmlValue": "<p>Hello World</p>",
          
            "isImageCompressed": true,
            "editorMode": "html"
          }
        }
      ]
    }
  ]
};
const response = await FormData.postFormsData(body);

---

Tres formas de adjuntar un archivo

Un valor file / image / groupOfImages acepta cualquiera de estos, y pueden mezclarse dentro de un mismo array:

1. El archivo en sí — un File, un Blob o un FileList. El SDK lo carga primero y envía lo que devolvió la carga. Agrega fileQuery al campo para elegir dónde se almacena; sin él, el SDK carga a page / editor bajo un id generado.
2. Un archivo ya en almacenamiento — el objeto FileUploading.upload() devuelto. Pásalo tal como está: desde 1.0.171 el SDK lo envía sin cambios (menos contentType, que el endpoint rechaza) en lugar de cargarlo una segunda vez.
3. Un valor construido a mano — IFileValue (filename, downloadLink, size) o IImageValue (lo mismo más previewLink, params).

Dos cosas que el endpoint insiste en:

• El valor va en un array. Un objeto solo — un descriptor o un IFileValue — se responde con 400 formData's marker '…' value must be an array. Un solo File está bien: el resultado de la carga ya es un array.
• Un grupo de imágenes es groupOfImages, plural. groupOfImage se responde con 400 formData's marker '…' type must be one of […].

Antes de 1.0.171, la segunda forma no funcionaba: un solo descriptor lanzaba fd.value.map is not a function dentro del paquete, y un array de descriptores se cargaba nuevamente como si los descriptores fueran archivos, lo que el endpoint rechazaba con value[0].filename is required. Si estás en una versión anterior, envía los archivos en sí o un valor construido a mano.

Ejemplo con un archivo ya en almacenamiento

const uploaded = await FileUploading.(file, {
  type: 'page',
  entity: 'editor',
  id: 3492
});
const stored = Array.isArray(uploaded) ? uploaded[0] : uploaded;
const body = {
  ,
  ,
  ,
  ,
  ,
  
    {
      ,
      ,
      ]
    }
  ]
};
const response = await FormData.postFormsData(body);

---

Ejemplo con atributo de tipo "image"

const testImageUrl = ;
const filename = 'test-image.png';
/* En un escenario del mundo real deberías usar la API de archivos para crear un archivo desde la URL, pero por simplicidad usaremos una URL de archivo predefinida y usaremos el método createFileFromUrl para este ejemplo */
const file = await FileUploading.createFileFromUrl(testImageUrl, filename);
const body = {
  ,
  ,
  ,
  ,
  ,
  
    {
      marker: ,
      type: ,
      : [
        file
      ]
    }
  ]
};
const response = await FormData.postFormsData(body);

---

Ejemplo con atributo de tipo "groupOfImages"

const testImageUrl = ;
const filename = 'test-image.png';
/* En un escenario del mundo real deberías usar la API de archivos para crear un archivo desde la URL, pero por simplicidad usaremos una URL de archivo predefinida y usaremos el método createFileFromUrl para este ejemplo */
const file = await FileUploading.createFileFromUrl(testImageUrl, filename);
const body = {
  ,
  ,
  ,
  ,
  ,
  
    {
      marker: ,
      type: ,
      : [
        file
      ]
    }
  ]
};
const response = await FormData.postFormsData(body);

---

Ejemplo con atributo de tipo "files"

const testImageUrl = ;
const filename = 'test-image.png';
/* En un escenario del mundo real deberías usar la API de archivos para crear un archivo desde la URL, pero por simplicidad usaremos una URL de archivo predefinida y usaremos el método createFileFromUrl para este ejemplo */
const file = await FileUploading.createFileFromUrl(testImageUrl, filename);
const body = {
  ,
  ,
  ,
  ,
  ,
  
    {
      ,
      ,
      
        {
          "filename": "files/project/page/10/image/Screenshot-from-2024-05-02-15-23-14.png",
          "downloadLink": "http://my-site.com/cloud-static/files/project/page/10/image/Screenshot-from-2024-05-02-15-23-14.png",
          "size": 392585
        }
      ]
    }
  ]
};
const response = await FormData.postFormsData(body);

---

Ejemplo con atributo de tipo "radioButton" o "list"

const body = {
  ,
  ,
  ,
  ,
  ,
  
    {
      ,
      ,
      ]
    }
  ]
};
const response = await FormData.postFormsData(body);

⚠️ Una presentación envía las opciones elegidas como cadenas. La forma [{ title, value }] que almacena un atributo de página es rechazada aquí con 400 formData's marker '<marker>' value[0] must be a string.

---

Ejemplo con atributo de tipo "spam" (captcha)

La plataforma genera claves Google reCAPTCHA v3 — no hay casilla de verificación ni rompecabezas de imágenes. Al visitante no se le pregunta nada: el token se obtiene en el navegador al enviar el formulario, y la puntuación se evalúa en el servidor.

Lee la clave del sitio desde el propio formulario: un campo spam la lleva en settings.captcha.key, junto a domainNames — el dominio para el cual se emitió la clave. Tómala de getFormByMarker en lugar de codificarla, y ten en cuenta que una clave emitida para localhost no pasará en un dominio de producción.

<script src="https://www.google.com/recaptcha/api.js?render=YOUR_SITE_KEY"></script>

const siteKey = form..find((a) => a.type === 'spam').settings.captcha.key;
const token = await window..execute(siteKey, { action: 'submit' });
const body = {
  "formIdentifier": "contact_us",
  "formModuleConfigId": 2,
  "moduleEntityIdentifier": "contact-us",
  "replayTo": null,
  "status": "sent",
  "formData": [
    { "marker": "your_name", "type": "string", "value": "John Doe" },
    {
      ,
      ,
      , "siteKey": siteKey } }
    }
  ]
};
const response = await FormData.postFormsData(body);

⚠️ El valor es el objeto de evento, no la cadena de token. Un token en bruto, un valor vacío o una forma incorrecta son todos rechazados con la misma frase — 400 Captcha Validation Failed, captcha type is: google — por lo que una solicitud mal formada es indistinguible de un bot. Verifica la forma antes de culpar la puntuación.

Un formulario cuyo campo spam está configurado pero no se envía es rechazado con 400 formData doesn't have spam attribute.

---

Ejemplo con atributo de tipo "entity" (lista anidada)

const body = {
  ,
  ,
  ,
  ,
  ,
  
    {
      ,
      ,
      , 32, 24]
    }
  ]
};
const response = await FormData.postFormsData(body);

Valor - identificadores numéricos para páginas e identificadores de cadena para productos. Los identificadores de productos deben incluir el prefijo 'p-', por ejemplo, 'p-1-', 'p-2-', etc. p-[parentId]-[productId]

---

Ejemplo con atributo de tipo "timeInterval"

const body = {
  ,
  ,
  ,
  ,
  ,
  
    {
      marker: ,
      type: ,
      : [
        [
          "2025-02-11T16:00:00.000Z",
          "2025-02-13T16:00:00.000Z"
        ]
      ]
    },
  ]
};
const response = await FormData.postFormsData(body);

valor — array de intervalos en formato ISO 8601. por ejemplo 2025-02-11T16:00:00:000Z

2025 — año; 02 — mes; 11 — día del mes; T — separador entre fecha y hora; 16:00:00 — hora en formato horas:minutos:segundos; 000Z — milisegundos e indicación de zona horaria. Z significa que la hora está especificada en formato UTC.

---

Ejemplo de retorno:

{
  "formData": {
    "formIdentifier": "test-form",
    "time": "2026-10-08T10:08:17.069Z",
    "formData": [
      {
        "marker": "name",
        "type": "string",
        "value": "Test"
      }
    ],
    "userIdentifier": "test@test.ru",
    "entityIdentifier": "blog",
    "fingerprint": "UQ_6e681661-9a58-4c18-9e94-ede07ecfd132",
    "isUserAdmin": false,
    "formModuleId": 2,
    "parentId": null,
    "id": 9087
  },
  "actionMessage": ""
}

Esquema de respuesta

Esquema: IPostFormResponse

formData: object
Datos del formulario.
ejemplo:

{
  "id": 42,
  "formIdentifier": "contact_form",
  "time": "2023-10-01T12:00:00Z",
  "entityIdentifier": "blog",
  "isUserAdmin": false,
  "formModuleId": 2,
  "parentId": null,
  "userIdentifier": null,
  "formData": [
    {
      "marker": "name",
      "type": "string",
      "value": "Jack"
    }
  ]
}

formData.id: number
El identificador único de la página del formulario.
ejemplo: 12345

formData.formIdentifier: string
El identificador del formulario.
ejemplo: "contact_form"

formData.time: string
La hora de la presentación del formulario.
ejemplo: "2023-10-01T12:00:00Z"

formData.entityIdentifier: string
El identificador de la entidad.
ejemplo: "blog"

formData.isUserAdmin: boolean
¿Es el usuario administrador?
ejemplo: false

formData.formModuleId: number
El identificador del módulo del formulario.
ejemplo: 2

formData.userIdentifier: string | null
El identificador del usuario.
ejemplo: null

formData.parentId: number | null
El identificador del padre.
ejemplo: null

formData.formData: FormDataType[]
Datos de los campos del formulario.
ejemplo:

[
  {
    "marker": "name",
    "type": "string",
    "value": "Jack"
  }
]

actionMessage: string
Mensaje de acción para los datos del formulario (puede ser localizado).
ejemplo: "Formulario enviado con éxito"

---

Ejemplos de uso

Guías paso a paso en la documentación:

• Enviar un formulario — recopilar la entrada del formulario de contacto y enviarla de vuelta a OneEntry.
• Formulario de entidad — enviar un formulario con campos de tipo entidad (páginas o productos).

Pruébalo en vivo

Ejecuta este método de forma interactiva en el sandbox del SDK de JS — conecta tu URL de Proyecto y Token de Aplicación en la primera visita, luego abre cualquier escenario a continuación para ver envíos de formularios reales:

• Enviar un formulario — recopilar la entrada del formulario de contacto y enviarla de vuelta a OneEntry.
• Formulario de entidad — enviar un formulario con campos de tipo entidad (páginas o productos).
• Formulario de archivo — enviar un formulario que incluye un archivo adjunto.
• Formulario de spam — enviar un formulario con protección contra spam.
• Formulario de programación — enviar un intervalo de tiempo seleccionado a través de un campo timeInterval.