postFormsData

Gửi dữ liệu biểu mẫu đến nền tảng OneEntry.

🎯 Phương thức này làm gì?

Phương thức này gửi dữ liệu biểu mẫu đến nền tảng OneEntry. Hãy nghĩ về nó như việc nhấn "Gửi" trên một biểu mẫu liên hệ - nó gửi tất cả thông tin người dùng nhập (tên, email, tin nhắn, tệp, v.v.) đến máy chủ.

Trường hợp sử dụng:

📝 Biểu mẫu liên hệ
📋 Biểu mẫu đăng ký
💬 Biểu mẫu phản hồi
📤 Tải tệp lên
🎫 Phiếu hỗ trợ

📖 Giải thích đơn giản

Khi một người dùng điền vào một biểu mẫu trên trang web của bạn, bạn cần gửi dữ liệu đó đến một nơi nào đó. Phương thức này làm chính xác điều đó - nó lấy tất cả các trường biểu mẫu (văn bản, số, tệp, v.v.) và gửi chúng đến OneEntry.

Hãy nghĩ về nó như:

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

🚀 Ví dụ siêu đơn giản (Bắt đầu từ đây!)

Tình huống: Bạn có một biểu mẫu liên hệ chỉ với một trường tên.

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

Chỉ vậy thôi! Bây giờ hãy xem cách xử lý các loại trường khác nhau...

📋 Những điều bạn cần biết trước khi sử dụng

Trước khi gọi phương thức này, bạn cần 3 điều từ bảng điều khiển quản trị OneEntry:

formIdentifier - Tên duy nhất của biểu mẫu của bạn (ví dụ: "contact_us")
formModuleConfigId - ID cấu hình biểu mẫu (một số, ví dụ: 2)
moduleEntityIdentifier - Nơi lưu trữ dữ liệu (ví dụ: "blog", "contacts")

Làm thế nào để tìm những điều này?

Đăng nhập vào OneEntry Admin
Đi đến phần Biểu mẫu
Sao chép các giá trị từ cấu hình biểu mẫu của bạn

🔧 Chữ ký phương thức

FormData.postFormsData(
body*,
body.formIdentifier*,
body.formModuleConfigId*,
body.moduleEntityIdentifier*,
body.replayTo*,
body.status*,
body.formData*,
body.fileQuery,
langCode
);

Sơ đồ tham số

Sơ đồ (body)

body(bắt buộc): IBodyPostFormData
Nội dung yêu cầu
ví dụ:

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

body.formIdentifier(bắt buộc): string
Định danh văn bản (đánh dấu) của biểu mẫu.
ví dụ: "form"

body.formModuleConfigId(bắt buộc): number
Định danh duy nhất của cấu hình mô-đun biểu mẫu.
ví dụ: 2

body.moduleEntityIdentifier(bắt buộc): string
Định danh văn bản (đánh dấu) của thực thể mô-đun.
ví dụ: "blog"

body.replayTo(bắt buộc): string | null
Email để trả lời.
ví dụ: "some@email.com"

body.status(bắt buộc): string
Trạng thái của biểu mẫu.
ví dụ: "sent"

body.formData(bắt buộc): FormDataType[]
Mảng các đối tượng dữ liệu biểu mẫu.
ví dụ:

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

body.fileQuery: IUploadingQuery
Truy vấn tệp tùy chọn để tải tệp lên.
ví dụ:

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

fileQuery.type(bắt buộc): string
Loại, xác định tên thư mục trong bộ nhớ.
ví dụ: "page"

fileQuery.entity(bắt buộc): string
Tên thực thể từ đó tệp được tải lên, xác định tên thư mục trong bộ nhớ.
ví dụ: "editor"

fileQuery.id(bắt buộc): number
Định danh của đối tượng từ đó tệp được tải lên, xác định tên thư mục trong bộ nhớ.
ví dụ: 3787

fileQuery.width: number
Tham số chiều rộng.
ví dụ: 0

fileQuery.height: number
Tham số chiều cao.
ví dụ: 0

fileQuery.compress: boolean
Cờ tối ưu hóa (nén) cho hình ảnh.
ví dụ: true

langCode: string
Mã ngôn ngữ. Mặc định: "en_US"
ví dụ: "en_US"

Ví dụ

Ví dụ tối thiểu


const body = {
  "formIdentifier": "contact_us",
  "formModuleConfigId": 2,
  "moduleEntityIdentifier": "blog",
  "replayTo": null,
  "status": "sent",
  "formData": [
    {
      "marker": "last_name",
      "type": "string",
      "value": "Andrey"
    }
  ]
};

const response = await FormData.postFormsData(body);

Ví dụ với thuộc tính loại đơn giản "string", "number", "float"


const body = {
  "formIdentifier": "test-form",
  "formModuleConfigId": 2,
  "moduleEntityIdentifier": "blog",
  "replayTo": null,
  "status": "sent",
  "formData": [
    {
      "marker": "string_marker",
      "type": "string",
      "value": "Username"
    },
    {
      "marker": "number_marker",
      "type": "number",
      "value": 1
    },
    {
      "marker": "float_marker",
      "type": "float",
      "value": 2.256
    }
  ]
};

const response = await FormData.postFormsData(body);

Ví dụ với thuộc tính loại đơn giản "date", "dateTime", "time"


const body = {
  "formIdentifier": "contact_us",
  "formModuleConfigId": 2,
  "moduleEntityIdentifier": "blog",
  "replayTo": null,
  "status": "sent",
  "formData": [
    {
      "marker": "date_marker",
      "type": "date",
      "value": {
        "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);

Ví dụ với thuộc tính loại đơn giản "text" (Chỉ một trong htmlValue, plainValue hoặc mdValue có thể được cung cấp)


const body = {
  "formIdentifier": "contact_us",
  "formModuleConfigId": 2,
  "moduleEntityIdentifier": "blog",
  "replayTo": null,
  "status": "sent",
  "formData": [
    {
      "marker": "about_marker",
      "type": "text",
      "value": [
        {
          "htmlValue": "<p>Hello world</p>",
          "params": {
            "isImageCompressed": true,
            "editorMode": "html"
          }
        }
      ]
    }
  ]
};

const response = await FormData.postFormsData(body);

Ví dụ với thuộc tính loại đơn giản "textWithHeader" (Chỉ một trong htmlValue, plainValue hoặc mdValue có thể được cung cấp)


const body = {
  "formIdentifier": "contact_us",
  "formModuleConfigId": 2,
  "moduleEntityIdentifier": "blog",
  "replayTo": null,
  "status": "sent",
  "formData": [
    {
      marker: "textwithheader_marker",
      type: "textWithHeader",
      value: [
        {
          "header": "Tiêu đề",
          "htmlValue": "<p>Hello World</p>",
          "params": {
            "isImageCompressed": true,
            "editorMode": "html"
          }
        }
      ]
    }
  ]
};

const response = await FormData.postFormsData(body);

Ví dụ với thuộc tính loại "image"


const testImageUrl = 'https://your-project.oneentry.cloud/cloud-static/files/project/product/2954/image/7e0a6a70-a23d-410f-8b6a-f8b4f7483244.png';
const filename = 'test-image.png';

/* Trong kịch bản thực tế, bạn nên sử dụng API Tệp để tạo tệp từ URL nhưng vì lý do đơn giản, chúng tôi sẽ sử dụng URL tệp đã định nghĩa trước và sử dụng phương thức createFileFromUrl cho ví dụ này */
const file = await FileUploading.createFileFromUrl(testImageUrl, filename);

const body = {
  "formIdentifier": "contact_us",
  "formModuleConfigId": 2,
  "moduleEntityIdentifier": "blog",
  "replayTo": null,
  "status": "sent",
  "formData": [
    {
      marker: "image_marker",
      type: "image",
      value: [
        file
      ]
    }
  ]
};

const response = await FormData.postFormsData(body);

Ví dụ với thuộc tính loại "groupOfImages"


const testImageUrl = 'https://your-project.oneentry.cloud/cloud-static/files/project/product/2954/image/7e0a6a70-a23d-410f-8b6a-f8b4f7483244.png';
const filename = 'test-image.png';

/* Trong kịch bản thực tế, bạn nên sử dụng API Tệp để tạo tệp từ URL nhưng vì lý do đơn giản, chúng tôi sẽ sử dụng URL tệp đã định nghĩa trước và sử dụng phương thức createFileFromUrl cho ví dụ này */
const file = await FileUploading.createFileFromUrl(testImageUrl, filename);

const body = {
  "formIdentifier": "contact_us",
  "formModuleConfigId": 2,
  "moduleEntityIdentifier": "blog",
  "replayTo": null,
  "status": "sent",
  "formData": [
    {
      marker: "groupofimages_marker",
      type: "groupOfImages",
      value: [
        file
      ]
    }
  ]
};

const response = await FormData.postFormsData(body);

Ví dụ với thuộc tính loại "files"


const testImageUrl = 'https://your-project.oneentry.cloud/cloud-static/files/project/product/2954/image/7e0a6a70-a23d-410f-8b6a-f8b4f7483244.png';
const filename = 'test-image.png';

/* Trong kịch bản thực tế, bạn nên sử dụng API Tệp để tạo tệp từ URL nhưng vì lý do đơn giản, chúng tôi sẽ sử dụng URL tệp đã định nghĩa trước và sử dụng phương thức createFileFromUrl cho ví dụ này */
const file = await FileUploading.createFileFromUrl(testImageUrl, filename);

const body = {
  "formIdentifier": "contact_us",
  "formModuleConfigId": 2,
  "moduleEntityIdentifier": "blog",
  "replayTo": null,
  "status": "sent",
  "formData": [
    {
      "marker": "picture_marker",
      "type": "file",
      "value": [
        {
          "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);

Ví dụ với thuộc tính loại "radioButton" hoặc "list"


const body = {
  "formIdentifier": "contact_us",
  "formModuleConfigId": 2,
  "moduleEntityIdentifier": "blog",
  "replayTo": null,
  "status": "sent",
  "formData": [
    {
      "marker": "selector_marker",
      "type": "list",
      "value": [
        {
          "marker": "list",
          "type": "list",
          "value": ["1"]
        }
      ]
    }
  ]
};

const response = await FormData.postFormsData(body);

Ví dụ với thuộc tính loại "entity" (danh sách lồng nhau)


const body = {
  "formIdentifier": "contact_us",
  "formModuleConfigId": 2,
  "moduleEntityIdentifier": "blog",
  "replayTo": null,
  "status": "sent",
  "formData": [
    {
      "marker": "entity_marker",
      "type": "entity",
      "value": [25, 32, 24]
    }
  ]
};

const response = await FormData.postFormsData(body);

Giá trị - các định danh số cho các trang và các định danh chuỗi cho các sản phẩm. Các định danh cho sản phẩm nên bao gồm tiền tố 'p-', ví dụ, 'p-1-', 'p-2-', v.v. p-[parentId]-[productId]

Ví dụ với thuộc tính loại "timeInterval"


const body = {
  "formIdentifier": "contact_us",
  "formModuleConfigId": 2,
  "moduleEntityIdentifier": "blog",
  "replayTo": null,
  "status": "sent",
  "formData": [
    {
      marker: 'timeinterval_marker',
      type: 'timeInterval',
      value: [
        [
          "2025-02-11T16:00:00.000Z",
          "2025-02-13T16:00:00.000Z"
        ]
      ]
    },
  ]
};

const response = await FormData.postFormsData(body);

giá trị — mảng các mảng khoảng thời gian theo định dạng ISO 8601. ví dụ 2025-02-11T16:00:00:000Z

2025 — năm; 02 — tháng; 11 — ngày trong tháng; T — dấu phân cách giữa ngày và giờ; 16:00:00 — giờ theo định dạng giờ:phút:giây; 000Z — mili giây và chỉ định múi giờ. Z có nghĩa là thời gian được chỉ định theo định dạng UTC.

Ví dụ trả về:

{
  "formData": {
    "formIdentifier": "test-form",
    "time": "2026-04-15T14:20:00.731Z",
    "formData": [
      {
        "marker": "name",
        "type": "string",
        "value": "Test"
      }
    ],
    "userIdentifier": "test@test.ru",
    "entityIdentifier": "blog",
    "fingerprint": "UQ_mo04zghpfp7i0o0li6c88sb4b4nlqu",
    "isUserAdmin": false,
    "formModuleId": 2,
    "parentId": null,
    "id": 5811
  },
  "actionMessage": ""
}

Sơ đồ phản hồi

Sơ đồ: IPostFormResponse

formData: object
Dữ liệu biểu mẫu.
ví dụ:

{
  "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
Định danh duy nhất của trang biểu mẫu.
ví dụ: 12345

formData.formIdentifier: string
Định danh của biểu mẫu.
ví dụ: "contact_form"

formData.time: string
Thời gian gửi biểu mẫu.
ví dụ: "2023-10-01T12:00:00Z"

formData.entityIdentifier: string
Định danh thực thể.
ví dụ: "blog"

formData.isUserAdmin: boolean
Người dùng có phải là quản trị viên không.
ví dụ: false

formData.formModuleId: number
Định danh mô-đun biểu mẫu.
ví dụ: 2

formData.userIdentifier: string | null
Định danh người dùng.
ví dụ: null

formData.parentId: number | null
Định danh cha.
ví dụ: null

formData.formData: FormDataType[]
Dữ liệu các trường biểu mẫu.
ví dụ:

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

actionMessage: string
Thông điệp hành động cho dữ liệu biểu mẫu (có thể được địa phương hóa).
ví dụ: "Biểu mẫu đã được gửi thành công"

🎯 Phương thức này làm gì?​

📖 Giải thích đơn giản​

🚀 Ví dụ siêu đơn giản (Bắt đầu từ đây!)​

📋 Những điều bạn cần biết trước khi sử dụng​

🔧 Chữ ký phương thức​

Sơ đồ tham số​

Ví dụ​

Ví dụ tối thiểu​

Ví dụ với thuộc tính loại đơn giản "string", "number", "float"​

Ví dụ với thuộc tính loại đơn giản "date", "dateTime", "time"​

Ví dụ với thuộc tính loại đơn giản "text" (Chỉ một trong htmlValue, plainValue hoặc mdValue có thể được cung cấp)​

Ví dụ với thuộc tính loại đơn giản "textWithHeader" (Chỉ một trong htmlValue, plainValue hoặc mdValue có thể được cung cấp)​

Ví dụ với thuộc tính loại "image"​

Ví dụ với thuộc tính loại "groupOfImages"​

Ví dụ với thuộc tính loại "files"​

Ví dụ với thuộc tính loại "radioButton" hoặc "list"​

Ví dụ với thuộc tính loại "entity" (danh sách lồng nhau)​

Ví dụ với thuộc tính loại "timeInterval"​

Ví dụ trả về:​

Sơ đồ phản hồi​