Pular para o conteúdo principal

postFormsData

Envie dados do formulário para a plataforma OneEntry.

🎯 O que este método faz?​

Este método submete dados do formulário para a plataforma OneEntry. Pense nisso como clicar em "Enviar" em um formulário de contato - ele envia todas as entradas do usuário (nome, e-mail, mensagem, arquivos, etc.) para o servidor.

Casos de uso:

  • 📝 Formulários de contato
  • 📋 Formulários de registro
  • 💬 Formulários de feedback
  • 📤 Upload de arquivos
  • 🎫 Chamadas de suporte

📖 Explicação Simples​

Quando um usuário preenche um formulário em seu site, você precisa enviar esses dados para algum lugar. Este método faz exatamente isso - ele pega todos os campos do formulário (texto, números, arquivos, etc.) e os envia para o OneEntry.

Pense nisso como:

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

🚀 Exemplo Super Simples (Comece Aqui!)​

Cenário: Você tem um formulário de contato com apenas um campo de nome.

// 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);

É isso! Agora vamos ver como lidar com diferentes tipos de campos...

📋 O que você precisa saber antes de usar​

Antes de chamar este método, você precisa dessas 3 coisas do painel de administração do OneEntry:

  1. formIdentifier - O nome único do seu formulário (por exemplo, "contact_us")
  2. formModuleConfigId - ID da configuração do formulário (um número, por exemplo, 2)
  3. moduleEntityIdentifier - Onde armazenar os dados (por exemplo, "blog", "contacts")

Como encontrar isso?

  • Faça login no OneEntry Admin
  • Vá para a seção de Formulários
  • Copie os valores da configuração do seu formulário

🔧 Assinatura do Método​

.postFormsData(

,

);

Esquema de Parâmetros​

Esquema (corpo)

body(obrigatório): IBodyPostFormData
Corpo da requisição
exemplo:

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

body.formIdentifier(obrigatório): string
Identificador de texto (marcador) do formulário.
exemplo: "form"

body.formModuleConfigId(obrigatório): number
O identificador único da configuração do módulo do formulário.
exemplo: 2

body.moduleEntityIdentifier(obrigatório): string
Identificador de texto (marcador) da entidade do módulo.
exemplo: "blog"

body.replayTo(obrigatório): string | null
E-mail para resposta.
exemplo: "some@email.com"

body.status(obrigatório): string
Status do formulário.
exemplo: "sent"

body.formData(obrigatório): FormDataPostType[]
Array de objetos de dados do formulário. Os valores de uma submissão diferem das formas de leitura — veja FormDataPostType.
exemplo:

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

body.fileQuery: IUploadingQuery
Consulta de arquivo opcional para upload de arquivos. Mantido para compatibilidade: o SDK lê fileQuery do próprio campo de arquivo (veja IBodyTypeFile), não do corpo, então um conjunto aqui não muda onde um arquivo é enviado.
exemplo:

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

fileQuery.type(obrigatório): string
Tipo, determina o nome da pasta no armazenamento.
exemplo: "page"

fileQuery.entity(obrigatório): string
Nome da entidade da qual o arquivo é enviado, determina o nome da pasta no armazenamento.
exemplo: "editor"

fileQuery.id(obrigatório): number
Identificador do objeto do qual o arquivo é enviado, determina o nome da pasta no armazenamento.
exemplo: 3787

fileQuery.width: number
Parâmetro de largura.
exemplo: 0

fileQuery.height: number
Parâmetro de altura.
exemplo: 0

fileQuery.compress: boolean
Flag de otimização (compressão) para imagens.
exemplo: true

langCode: string
Código do idioma. Padrão: "en_US"
exemplo: "en_US"

Exemplos​

Exemplo mínimo​


const body = {
  ,
  ,
  ,
  ,
  ,
  
    {
      ,
      
      
    }
  ]
};

const response = await FormData.postFormsData(body);

Exemplo com um atributo de tipo simples "string", "number", "float"​


const body = {
  ,
  ,
  ,
  ,
  ,
  
    {
      ,
      ,
      
    },
    {
      ,
      ,
      
    },
    {
      ,
      ,
      
    }
  ]
};

const response = await FormData.postFormsData(body);

Exemplo com um atributo de tipo simples "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);

Exemplo com um atributo de tipo simples "text" (Apenas um dos htmlValue, plainValue ou mdValue pode ser fornecido)​


const body = {
  ,
  ,
  ,
  ,
  ,
  
    {
      ,
      ,
      
        {
          "htmlValue": "<p>Hello world</p>",
          
            "isImageCompressed": true,
            "editorMode": "html"
          }
        }
      ]
    }
  ]
};

const response = await FormData.postFormsData(body);

Exemplo com um atributo de tipo simples "textWithHeader" (Apenas um dos htmlValue, plainValue ou mdValue pode ser fornecido)​


const body = {
  ,
  ,
  ,
  ,
  ,
  
    {
      marker: ,
      type: ,
      : [
        {
          "header": "Headline",
          "htmlValue": "<p>Hello World</p>",
          
            "isImageCompressed": true,
            "editorMode": "html"
          }
        }
      ]
    }
  ]
};

const response = await FormData.postFormsData(body);

Três maneiras de anexar um arquivo

Um valor file / image / groupOfImages aceita qualquer um desses, e eles podem ser misturados dentro de um único array:

  1. O próprio arquivo — um File, um Blob ou um FileList. O SDK o envia primeiro e envia o que o upload retornou. Adicione fileQuery ao campo para escolher onde ele é armazenado; sem isso, o SDK envia para page / editor sob um id gerado.
  2. Um arquivo já armazenado — o objeto FileUploading.upload() retornado. Passe-o como está: desde 1.0.171 o SDK o envia intocado (menos contentType, que o endpoint rejeita) em vez de enviá-lo novamente.
  3. Um valor construído manualmente — IFileValue (filename, downloadLink, size) ou IImageValue (o mesmo mais previewLink, params).

Duas coisas que o endpoint insiste:

  • O valor vai em um array. Um objeto solitário — um descritor ou um IFileValue — é respondido com 400 formData's marker '…' value must be an array. Um único File está bem: o resultado do upload já é um array.
  • Um grupo de imagens é groupOfImages, plural. groupOfImage é respondido com 400 formData's marker '…' type must be one of […].

Antes de 1.0.171, a segunda maneira não funcionava: um descritor solitário lançava fd.value.map is not a function dentro do pacote, e um array de descritores era enviado novamente como se os descritores fossem arquivos, o que o endpoint rejeitava com value[0].filename is required. Se você estiver em uma versão mais antiga, envie os arquivos ou um valor construído manualmente.

Exemplo com um arquivo já armazenado​


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);

Exemplo com atributo tipo "image"​


const testImageUrl = ;
const filename = 'test-image.png';

/* Em um cenário do mundo real, você deve usar a API de Arquivos para criar um arquivo a partir da URL, mas para simplificar, usaremos uma URL de arquivo predefinida e usaremos o método createFileFromUrl para este exemplo */
const file = await FileUploading.createFileFromUrl(testImageUrl, filename);

const body = {
  ,
  ,
  ,
  ,
  ,
  
    {
      marker: ,
      type: ,
      : [
        file
      ]
    }
  ]
};

const response = await FormData.postFormsData(body);

Exemplo com atributo tipo "groupOfImages"​


const testImageUrl = ;
const filename = 'test-image.png';

/* Em um cenário do mundo real, você deve usar a API de Arquivos para criar um arquivo a partir da URL, mas para simplificar, usaremos uma URL de arquivo predefinida e usaremos o método createFileFromUrl para este exemplo */
const file = await FileUploading.createFileFromUrl(testImageUrl, filename);

const body = {
  ,
  ,
  ,
  ,
  ,
  
    {
      marker: ,
      type: ,
      : [
        file
      ]
    }
  ]
};

const response = await FormData.postFormsData(body);

Exemplo com atributo tipo "files"​


const testImageUrl = ;
const filename = 'test-image.png';

/* Em um cenário do mundo real, você deve usar a API de Arquivos para criar um arquivo a partir da URL, mas para simplificar, usaremos uma URL de arquivo predefinida e usaremos o método createFileFromUrl para este exemplo */
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);

Exemplo com atributo tipo "radioButton" ou "list"​


const body = {
  ,
  ,
  ,
  ,
  ,
  
    {
      ,
      ,
      ]
    }
  ]
};

const response = await FormData.postFormsData(body);

⚠️ Uma submissão envia as opções escolhidas como strings. A forma [{ title, value }] que um atributo de página armazena é rejeitada aqui com 400 formData's marker '<marker>' value[0] must be a string.

Exemplo com atributo tipo "spam" (captcha)​

A plataforma gera chaves Google reCAPTCHA v3 — não há caixa de seleção e nem quebra-cabeça de imagem. O visitante não é solicitado a nada: o token é obtido no navegador assim que o formulário é enviado, e a pontuação é avaliada no servidor.

Leia a chave do site do próprio formulário: um campo spam a carrega em settings.captcha.key, ao lado de domainNames — o domínio para o qual a chave foi emitida. Pegue-a de getFormByMarker em vez de codificá-la diretamente, e tenha em mente que uma chave emitida para localhost não passará em um domínio de produção.

<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);

⚠️ O valor é o objeto de evento, não a string do token. Um token puro, um valor vazio ou uma forma errada são todos rejeitados com a mesma mensagem — 400 Captcha Validation Failed, captcha type is: google — então uma requisição malformada é indistinguível de um bot. Verifique a forma antes de culpar a pontuação.

Um formulário cujo campo spam está configurado, mas não enviado, é rejeitado com 400 formData doesn't have spam attribute.

Exemplo com atributo tipo "entity" (lista aninhada)​


const body = {
  ,
  ,
  ,
  ,
  ,
  
    {
      ,
      ,
      , 32, 24]
    }
  ]
};

const response = await FormData.postFormsData(body);

Valor - identificadores numéricos para páginas e identificadores de string para produtos. Identificadores de produtos devem incluir o prefixo 'p-', por exemplo, 'p-1-', 'p-2-', etc. p-[parentId]-[productId]

Exemplo com atributo 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 em formato ISO 8601. por exemplo 2025-02-11T16:00:00:000Z

2025 — ano; 02 — mês; 11 — dia do mês; T — separador entre data e hora; 16:00:00 — hora no formato horas:minutos:segundos; 000Z — milissegundos e indicação de fuso horário. Z significa que a hora está especificada no formato UTC.

Exemplo 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 Resposta​

Esquema: IPostFormResponse

formData: object
Dados do formulário.
exemplo:

{
  "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
O identificador único da página do formulário.
exemplo: 12345

formData.formIdentifier: string
O identificador do formulário.
exemplo: "contact_form"

formData.time: string
O tempo da submissão do formulário.
exemplo: "2023-10-01T12:00:00Z"

formData.entityIdentifier: string
O identificador da entidade.
exemplo: "blog"

formData.isUserAdmin: boolean
O usuário é administrador.
exemplo: false

formData.formModuleId: number
O identificador do módulo do formulário.
exemplo: 2

formData.userIdentifier: string | null
O identificador do usuário.
exemplo: null

formData.parentId: number | null
O identificador do pai.
exemplo: null

formData.formData: FormDataType[]
Dados dos campos do formulário.
exemplo:

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

actionMessage: string
Mensagem de ação para os dados do formulário (pode ser localizada).
exemplo: "Formulário enviado com sucesso"

Exemplos de uso​

Guias passo a passo na documentação:

Experimente ao vivo​

Execute este método interativamente no sandbox do JS SDK — conecte sua URL do Projeto e Token do App na primeira visita, depois abra qualquer cenário abaixo para ver submissões reais de formulários: