Aller au contenu principal

postFormsData

Envoyer les données du formulaire à la plateforme OneEntry.

🎯 Que fait cette méthode ?​

Cette méthode soumet les données du formulaire à la plateforme OneEntry. Pensez-y comme à un clic sur "Soumettre" sur un formulaire de contact - cela envoie toutes les entrées de l'utilisateur (nom, email, message, fichiers, etc.) au serveur.

Cas d'utilisation :

  • 📝 Formulaires de contact
  • 📋 Formulaires d'inscription
  • 💬 Formulaires de retour d'expérience
  • 📤 Téléchargements de fichiers
  • 🎫 Tickets de support

📖 Explication simple​

Lorsque qu'un utilisateur remplit un formulaire sur votre site web, vous devez envoyer ces données quelque part. Cette méthode fait exactement cela - elle prend tous les champs du formulaire (texte, nombres, fichiers, etc.) et les envoie à OneEntry.

Pensez-y comme :

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

🚀 Exemple super simple (Commencez ici !)​

Scénario : Vous avez un formulaire de contact avec juste un champ de nom.

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

C'est tout ! Maintenant, voyons comment gérer différents types de champs...

📋 Ce que vous devez savoir avant d'utiliser​

Avant d'appeler cette méthode, vous avez besoin de ces 3 éléments du panneau d'administration OneEntry :

  1. formIdentifier - Le nom unique de votre formulaire (par exemple, "contact_us")
  2. formModuleConfigId - ID de configuration du formulaire (un nombre, par exemple, 2)
  3. moduleEntityIdentifier - Où stocker les données (par exemple, "blog", "contacts")

Comment les trouver ?

  • Connectez-vous à OneEntry Admin
  • Allez dans la section Formulaires
  • Copiez les valeurs de votre configuration de formulaire

🔧 Signature de la méthode​

.postFormsData(

,

);

Schéma des paramètres​

Schéma (body)

body(required): IBodyPostFormData
Corps de la requête
exemple :

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

body.formIdentifier(required): string
Identifiant textuel (marqueur) du formulaire.
exemple : "form"

body.formModuleConfigId(required): number
L'identifiant unique de la configuration du module de formulaire.
exemple : 2

body.moduleEntityIdentifier(required): string
Identifiant textuel (marqueur) de l'entité du module.
exemple : "blog"

body.replayTo(required): string | null
Email pour répondre.
exemple : "some@email.com"

body.status(required): string
Statut du formulaire.
exemple : "sent"

body.formData(required): FormDataPostType[]
Tableau d'objets de données de formulaire. Les valeurs d'une soumission diffèrent des formes de lecture — voir FormDataPostType.
exemple :

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

body.fileQuery: IUploadingQuery
Requête de fichier optionnelle pour le téléchargement de fichiers. Conservée pour compatibilité : le SDK lit fileQuery depuis le champ de fichier lui-même (voir IBodyTypeFile), pas depuis le corps, donc un ensemble ici ne change pas où un fichier est téléchargé.
exemple :

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

fileQuery.type(required): string
Type, détermine le nom du dossier dans le stockage.
exemple : "page"

fileQuery.entity(required): string
Nom de l'entité à partir de laquelle le fichier est téléchargé, détermine le nom du dossier dans le stockage.
exemple : "editor"

fileQuery.id(required): number
Identifiant de l'objet à partir duquel le fichier est téléchargé, détermine le nom du dossier dans le stockage.
exemple : 3787

fileQuery.width: number
Paramètre de largeur.
exemple : 0

fileQuery.height: number
Paramètre de hauteur.
exemple : 0

fileQuery.compress: boolean
Indicateur d'optimisation (compression) pour les images.
exemple : true

langCode: string
Code de langue. Par défaut : "en_US"
exemple : "en_US"

Exemples​

Exemple minimal​


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

const response = await FormData.postFormsData(body);

Exemple avec un type d'attribut simple "string", "number", "float"​


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

const response = await FormData.postFormsData(body);

Exemple avec un type d'attribut 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);

Exemple avec un type d'attribut simple "text" (Un seul de htmlValue, plainValue ou mdValue peut être fourni)​


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

const response = await FormData.postFormsData(body);

Exemple avec un type d'attribut simple "textWithHeader" (Un seul de htmlValue, plainValue ou mdValue peut être fourni)​


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

const response = await FormData.postFormsData(body);

Trois façons de joindre un fichier

Une valeur file / image / groupOfImages accepte l'une de ces options, et elles peuvent être mélangées dans un même tableau :

  1. Le fichier lui-même — un File, un Blob ou un FileList. Le SDK le télécharge d'abord et envoie ce que le téléchargement a retourné. Ajoutez fileQuery au champ pour choisir où il est stocké ; sans cela, le SDK télécharge vers page / editor sous un ID généré.
  2. Un fichier déjà dans le stockage — l'objet FileUploading.upload() retourné. Passez-le tel quel : depuis 1.0.171, le SDK l'envoie intact (moins contentType, que le point de terminaison rejette) au lieu de le télécharger une seconde fois.
  3. Une valeur construite à la main — IFileValue (filename, downloadLink, size) ou IImageValue (même plus previewLink, params).

Deux choses que le point de terminaison insiste sur :

  • La valeur doit être dans un tableau. Un objet seul — un descripteur ou un IFileValue — est répondu avec 400 formData's marker '…' value must be an array. Un seul File est acceptable : le résultat du téléchargement est déjà un tableau.
  • Un groupe d'images est groupOfImages, au pluriel. groupOfImage est répondu avec 400 formData's marker '…' type must be one of […].

Avant 1.0.171, la deuxième méthode ne fonctionnait pas : un seul descripteur lançait fd.value.map is not a function à l'intérieur du package, et un tableau de descripteurs était téléchargé à nouveau comme si les descripteurs étaient des fichiers, ce que le point de terminaison refusait avec value[0].filename is required. Si vous êtes sur une version antérieure, envoyez les fichiers eux-mêmes ou une valeur construite à la main.

Exemple avec un fichier déjà dans le stockage​


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

Exemple avec un type d'attribut "image"​


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

/* Dans un scénario réel, vous devriez utiliser l'API File pour créer un fichier à partir de l'URL, mais pour des raisons de simplicité, nous allons utiliser une URL de fichier prédéfinie et utiliser la méthode createFileFromUrl pour cet exemple */
const file = await FileUploading.createFileFromUrl(testImageUrl, filename);

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

const response = await FormData.postFormsData(body);

Exemple avec un type d'attribut "groupOfImages"​


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

/* Dans un scénario réel, vous devriez utiliser l'API File pour créer un fichier à partir de l'URL, mais pour des raisons de simplicité, nous allons utiliser une URL de fichier prédéfinie et utiliser la méthode createFileFromUrl pour cet exemple */
const file = await FileUploading.createFileFromUrl(testImageUrl, filename);

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

const response = await FormData.postFormsData(body);

Exemple avec un type d'attribut "files"​


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

/* Dans un scénario réel, vous devriez utiliser l'API File pour créer un fichier à partir de l'URL, mais pour des raisons de simplicité, nous allons utiliser une URL de fichier prédéfinie et utiliser la méthode createFileFromUrl pour cet exemple */
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);

Exemple avec un type d'attribut "radioButton" ou "list"​


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

const response = await FormData.postFormsData(body);

⚠️ Une soumission envoie les options choisies sous forme de chaînes. La forme [{ title, value }] qu'un attribut de page stocke est refusée ici avec 400 formData's marker '<marker>' value[0] must be a string.

Exemple avec un type d'attribut "spam" (captcha)​

La plateforme génère des clés Google reCAPTCHA v3 — il n'y a pas de case à cocher ni de puzzle d'images. Le visiteur n'est rien demandé : le token est obtenu dans le navigateur au moment de la soumission du formulaire, et le score est évalué sur le serveur.

Lisez la clé du site à partir du formulaire lui-même : un champ spam la porte dans settings.captcha.key, à côté de domainNames — le domaine pour lequel la clé a été émise. Prenez-la à partir de getFormByMarker plutôt que de la coder en dur, et gardez à l'esprit qu'une clé émise pour localhost ne passera pas sur un domaine de production.

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

⚠️ La valeur est l'objet événement, pas la chaîne de token. Un token brut, une valeur vide ou une forme incorrecte sont tous refusés avec la même phrase — 400 Captcha Validation Failed, captcha type is: google — donc une requête malformée est indistinguable d'un bot. Vérifiez la forme avant de blâmer le score.

Un formulaire dont le champ spam est configuré mais non envoyé est refusé avec 400 formData doesn't have spam attribute.

Exemple avec un type d'attribut "entity" (liste imbriquée)​


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

const response = await FormData.postFormsData(body);

Valeur - identifiants numériques pour les pages et identifiants textuels pour les produits. Les identifiants pour les produits doivent inclure le préfixe 'p-', par exemple, 'p-1-', 'p-2-', etc. p-[parentId]-[productId]

Exemple avec un type d'attribut "timeInterval"​


const body = {
  ,
  ,
  ,
  ,
  ,
  
    {
      marker: ,
      type: ,
      : [
        [
          "2025-02-11T16:00:00.000Z",
          "2025-02-13T16:00:00.000Z"
        ]
      ]
    },
  ]
};

const response = await FormData.postFormsData(body);

valeur — tableau de tableaux d'intervalles au format ISO 8601. par exemple 2025-02-11T16:00:00:000Z

2025 — année ; 02 — mois ; 11 — jour du mois ; T — séparateur entre la date et l'heure ; 16:00:00 — heure au format heures:minutes:secondes ; 000Z — millisecondes et indication de fuseau horaire. Z signifie que l'heure est spécifiée au format UTC.

Exemple de retour :​

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

Schéma de réponse​

Schéma : IPostFormResponse

formData: object
Données du formulaire.
exemple :

{
  "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
L'identifiant unique de la page de formulaire.
exemple : 12345

formData.formIdentifier: string
L'identifiant du formulaire.
exemple : "contact_form"

formData.time: string
L'heure de la soumission du formulaire.
exemple : "2023-10-01T12:00:00Z"

formData.entityIdentifier: string
L'identifiant de l'entité.
exemple : "blog"

formData.isUserAdmin: boolean
L'utilisateur est-il administrateur ?
exemple : false

formData.formModuleId: number
L'identifiant du module de formulaire.
exemple : 2

formData.userIdentifier: string | null
L'identifiant de l'utilisateur.
exemple : null

formData.parentId: number | null
L'identifiant parent.
exemple : null

formData.formData: FormDataType[]
Données des champs du formulaire.
exemple :

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

actionMessage: string
Message d'action pour les données du formulaire (peut être localisé).
exemple : "Formulaire soumis avec succès"

Exemples d'utilisation​

Guides étape par étape dans la documentation :

Essayez-le en direct​

Exécutez cette méthode de manière interactive dans le bac à sable JS SDK — connectez votre URL de projet et votre jeton d'application lors de votre première visite, puis ouvrez n'importe quel scénario ci-dessous pour voir de réelles soumissions de formulaires :