Object Information

28/7/2026

blog.summarize

blog.share_blog

Objects API (Đối tượng)

API quản lý metadata các loại đối tượng (Object Types) và các trường (fields) của chúng.

Xác thực

Tất cả request yêu cầu các header:

Authorization: Bearer {tokenId}-{secretToken}
Content-Type: application/json

Workspace được xác định từ access token. Nếu client gửi workspace_id, API sẽ thay thế bằng workspace ID đã xác thực trước khi forward request.

Tổng quan endpoint

Chức năng	Method	Endpoint
Danh sách Object	`POST`	`/bapi/v1/objects/list`
Tạo Object	`POST`	`/bapi/v1/objects`
Tạo Object (alias)	`POST`	`/bapi/v1/objects/create`
Cập nhật Object	`PUT`	`/bapi/v1/objects/{objectId}`
Xoá hoặc khôi phục Object	`POST`	`/bapi/v1/objects/delete`

Quy ước HTTP status:

Trường hợp	HTTP status
Tạo thành công (`r = 0`)	`201`
List, cập nhật, xoá hoặc khôi phục thành công	`200`
API trả lỗi nghiệp vụ (`r != 0`)	`400`
Token không hợp lệ hoặc hết hạn	`401`
Vượt rate limit	`429`
Lỗi máy chủ	`500`

Với các API thay đổi dữ liệu, r = 0 mới là điều kiện thành công ở cấp nghiệp vụ.

1. Danh sách đối tượng

Endpoint: POST /bapi/v1/objects/list

Request Body:

{
  "pageSize": 100,
  "keywords": ["lead"],
  "slugs": ["lead", "contact"],
  "ids": ["OT1GCPQEXKO2V"],
  "includeFields": true,
  "includeRelatedLists": false,
  "includeOptions": true,
  "includeMetaData": true,
  "includeNonStandard": true,
  "includeWorkflowObjects": false
}

Field	Type	Mặc định	Mô tả
`pageSize`	Integer	`2000`	Số lượng đối tượng tối đa trả về
`keywords`	Array<String>	`[]`	Danh sách từ khóa tìm kiếm. Tìm theo `name`, `slug`, `nameTranslations` (không phân biệt hoa thường). Object khớp nếu bất kỳ keyword nào match
`slugs`	Array<String>	`[]`	Lọc theo slug chính xác. Nếu có, chỉ trả về các object type có `slug` nằm trong danh sách này
`ids`	Array<String>	`[]`	Lọc theo ID chính xác. Nếu có, chỉ trả về các object type có `id` nằm trong danh sách này
`includeFields`	Boolean	`false`	Nếu `true`, trả về danh sách các fields của mỗi object
`includeRelatedLists`	Boolean	`false`	Nếu `true`, trả về danh sách relatedLists của mỗi object
`includeOptions`	Boolean	`true`	Chỉ có tác dụng khi `includeFields=true`. Nếu `true`, trả về options của các field lựa chọn
`includeMetaData`	Boolean	`true`	Chỉ có tác dụng khi `includeFields=true`. Nếu `true`, trả về metaData của field
`includeNonStandard`	Boolean	`true`	Nếu `true`, trả về tất cả object types (bao gồm cả non-standard). Nếu `false`, chỉ trả về object types chuẩn
`includeWorkflowObjects`	Boolean	`false`	Nếu `true`, bao gồm cả các object types thuộc workflow. Nếu `false`, loại trừ các workflow objects

Phân quyền

Mỗi object type được kiểm tra quyền object.viewFields dựa trên slug của object type. Chỉ trả về các object type mà user có quyền xem.

Response (200)

{
  "items": [
    {
      "id": "OT1GCPQEXKO2V",
      "name": "Lead",
      "slug": "lead",
      "nameTranslations": {
        "vi": "Khách hàng tiềm năng",
        "en": "Lead"
      },
      "fields": [
        {
          "id": "FLD123",
          "name": "Status",
          "slug": "status",
          "fieldType": "select",
          "nameTranslations": { "vi": "Trạng thái" },
          "required": false,
          "status": true,
          "description": "Trạng thái của khách hàng",
          "multiple": false,
          "readOnly": false,
          "manualModifyAllow": true,
          "defaultValue": null,
          "metaData": {},
          "options": [
            {
              "id": "OPT1",
              "value": "Qualified",
              "slug": "qualified",
              "isDefault": false,
              "nameTranslations": { "vi": "Đủ điều kiện" }
            }
          ]
        }
      ],
      "relatedLists": [
        {
          "id": "RL001",
          "name": "Đơn hàng",
          "slug": "don-hang",
          "status": 1,
          "sort": 1,
          "displayColumn": "name,status",
          "minRecord": null,
          "maxRecord": null,
          "sourceObjectId": "OT1GCPQEXKO2V",
          "sourceObjectSlug": "lead",
          "sourceFieldId": "FLD456",
          "sourceFieldSlug": "lead_id",
          "lookupObjectId": "OT2ABCDEF",
          "lookupObjectSlug": "order",
          "lookupType": "one_to_many"
        }
      ]
    }
  ],
  "totalItems": 5
}

fields chỉ có khi includeFields=true. relatedLists chỉ có khi includeRelatedLists=true. options và metaData trong fields chỉ có khi includeOptions=true / includeMetaData=true tương ứng.

Field	Type	Mô tả
`items`	Array	Danh sách object types
`items[].id`	String	ID của object type
`items[].name`	String	Tên gốc
`items[].slug`	String	Slug định danh
`items[].nameTranslations`	Object	Bản dịch tên theo mã ngôn ngữ
`items[].fields`	Array	Danh sách fields (khi `includeFields=true`)
`items[].fields[].id`	String	ID của field
`items[].fields[].name`	String	Tên field
`items[].fields[].slug`	String	Slug của field
`items[].fields[].fieldType`	String	Loại dữ liệu field
`items[].fields[].nameTranslations`	Object	Bản dịch tên field
`items[].fields[].required`	Boolean	Trường bắt buộc hay không
`items[].fields[].status`	Boolean	Trạng thái của trường (đang hoạt động hay không)
`items[].fields[].description`	String	Mô tả của trường
`items[].fields[].multiple`	Boolean	`true` nếu trường dạng danh sách (list), `false` nếu đơn giá trị (single)
`items[].fields[].readOnly`	Boolean	Trường chỉ đọc hay không
`items[].fields[].manualModifyAllow`	Boolean	Cho phép sửa/tạo giá trị thủ công trên giao diện hay không
`items[].fields[].defaultValue`	String	Giá trị mặc định của trường (có thể `null` nếu chưa thiết lập)
`items[].fields[].metaData`	Object	Metadata của trường (khi `includeMetaData=true` và trường có metadata dạng JSON)
`items[].fields[].options`	Array	Các lựa chọn (khi `includeOptions=true` và field có multi-option)
`items[].relatedLists`	Array	Danh sách related lists (khi `includeRelatedLists=true`)
`items[].relatedLists[].id`	String	ID của related list
`items[].relatedLists[].name`	String	Tên related list
`items[].relatedLists[].slug`	String	Slug của related list
`items[].relatedLists[].status`	Integer	Trạng thái
`items[].relatedLists[].sort`	Integer	Thứ tự sắp xếp
`items[].relatedLists[].displayColumn`	String	Các cột hiển thị
`items[].relatedLists[].minRecord`	Integer	Số bản ghi tối thiểu được lookup đến 1 bản ghi đích
`items[].relatedLists[].maxRecord`	Integer	Số bản ghi tối đa được lookup đến 1 bản ghi đích
`items[].relatedLists[].sourceObjectId`	String	ID object nguồn
`items[].relatedLists[].sourceObjectSlug`	String	Slug object nguồn
`items[].relatedLists[].sourceFieldId`	String	ID field nguồn
`items[].relatedLists[].sourceFieldSlug`	String	Slug field nguồn
`items[].relatedLists[].lookupObjectId`	String	ID object đích lookup
`items[].relatedLists[].lookupObjectSlug`	String	Slug object đích lookup
`items[].relatedLists[].lookupType`	String	Loại lookup (vd: `one_to_many`)
`totalItems`	Integer	Tổng số đối tượng (trước khi phân trang)

2. Tạo Object

Endpoint: POST /bapi/v1/objects

Alias tương đương: POST /bapi/v1/objects/create.

Request Body

Trường	Kiểu	Bắt buộc	Mặc định	Mô tả
`name`	String	Có	—	Tên hiển thị gốc. Phải hợp lệ và không trùng trong workspace
`plural_name`	String	Không	`name`	Tên số nhiều gốc. Phải không trùng trong workspace
`slug`	String	Không	Sinh từ `name`	Định danh ổn định. Nếu truyền vào thì phải hợp lệ và không trùng
`description`	String	Không	`null`	Mô tả Object
`status`	Integer	Không	`1`	`0` = inactive, `1` = active
`type`	Integer	Không	`0`	`0` = normal, `1` = child, `2` = junction
`name_field`	Object	Có khi tạo qua public API	—	Định nghĩa trường tên chính của Object
`translations`	Array	Không	`[]`	Bản dịch Object. Hỗ trợ hai thuộc tính `name` và `plural_name`
`meta_data`	String	Không	`null`	Chuỗi chứa JSON metadata hợp lệ
`standard_fields`	Boolean	Không	`true`	Cờ tương thích dùng khi validate request; public API vẫn khởi tạo các field chuẩn
`standard_layout`	Boolean	Không	`true`	Tạo layout chuẩn
`standard_buttons`	Boolean	Không	`true`	Tạo các button chuẩn
`standard_filter`	Boolean	Không	`true`	Tạo filter chuẩn
`creatable`	Integer	Không	`1`	Cho phép tạo record của Object (`0` hoặc `1`)
`editable`	Integer	Không	`1`	Cho phép sửa record của Object (`0` hoặc `1`)
`viewable`	Integer	Không	`1`	Cho phép xem record của Object (`0` hoặc `1`)
`quick_search`	Integer	Không	`1`	Cho phép Object tham gia quick search (`0` hoặc `1`)
`parent_field`	Object	Không	`null`	Định nghĩa field cha cho child Object; khi truyền sẽ chuyển `type` thành `1`
`composite_keys`	Array	Không	`null`	Các định nghĩa composite unique key

Public client chỉ tạo custom Object; is_standard=1 sẽ bị từ chối. Public API luôn khởi tạo các field chuẩn, vì vậy client nên truyền name_field và giữ standard_fields ở giá trị mặc định. Nếu có workspace_id, API sẽ thay thế bằng workspace lấy từ access token.

Trường tên chính name_field hỗ trợ short_text hoặc auto_number. Giá trị meta_data của field này cũng là JSON string. Các thuộc tính field khác tuân theo Object Fields API.

Bản dịch

Mỗi phần tử translations chứa mã language và một hoặc cả hai thuộc tính có thể dịch:

{
  "translations": [
    {
      "language": "en-US",
      "name": "Customer",
      "plural_name": "Customers"
    }
  ]
}

Ví dụ cURL tạo Object

curl --location 'https://{workspace-domain}/bapi/v1/objects' \
  --header 'Authorization: Bearer {tokenId}-{secretToken}' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Khách hàng",
    "plural_name": "Danh sách khách hàng",
    "slug": "customer",
    "description": "Quản lý thông tin khách hàng",
    "translations": [
      {
        "language": "en-US",
        "name": "Customer",
        "plural_name": "Customers"
      }
    ],
    "name_field": {
      "name": "Mã khách hàng",
      "type": "auto_number",
      "required": 1,
      "meta_data": "{\"prefix\":\"CUS-\",\"format\":\"00000\",\"start\":\"1\",\"step\":\"1\",\"is_identifier\":true}"
    }
  }'

Response thành công (201)

{
  "r": 0,
  "msg": "OK",
  "requestId": "RQ87dce633-ef58-4ec1-9bb5-e279afedb1ce",
  "data": {
    "id": "OTRPIUQEDKM9Y",
    "slug": "customer",
    "options": [],
    "standard_fields": [
      {
        "id": "OF93OAQE4KMF1",
        "slug": "name",
        "options": []
      }
    ]
  }
}

data.standard_fields chứa toàn bộ các field chuẩn được tạo cùng Object.

3. Cập nhật Object

Endpoint: PUT /bapi/v1/objects/{objectId}

Đây là API partial update. Các thuộc tính không xuất hiện trong payload sẽ được giữ nguyên.

Quy tắc quan trọng

objectId trên URL là nguồn tin cậy. Nếu body chứa id khác, API sẽ thay bằng giá trị trên URL.
workspace_id luôn được thay bằng workspace ID đã xác thực.
Không thể cập nhật Object đang ở trạng thái chờ xoá (status=2).
name và plural_name gốc phải tiếp tục không trùng trong workspace.
Với standard Object, chỉ cho phép sửa name, plural_name, description, translations và các metadata key được hỗ trợ.

Các thuộc tính có thể cập nhật

Trường	Kiểu	Mô tả
`name`	String	Tên hiển thị gốc mới
`plural_name`	String	Tên số nhiều gốc mới
`description`	String	Mô tả Object mới; gửi chuỗi rỗng để xoá mô tả
`status`	Integer	`0` = inactive, `1` = active
`meta_data`	String	Chuỗi chứa JSON metadata hợp lệ
`quick_search`	Integer	Bật hoặc tắt quick search (`0` hoặc `1`)
`translations`	Array	Upsert `name` và/hoặc `plural_name` theo ngôn ngữ
`name_field`	Object	Partial update trường tên chính
`parent_field`	Object	Cập nhật field cha của child Object, tuỳ thuộc ràng buộc quan hệ/dữ liệu
`composite_keys`	Array	Toàn bộ tập composite key mong muốn

Với mỗi ngôn ngữ có trong translations, API chỉ cập nhật các thuộc tính xuất hiện trong phần tử đó. Thuộc tính và ngôn ngữ không được gửi sẽ được giữ nguyên. Giá trị bản dịch rỗng sẽ fallback về giá trị gốc tương ứng của Object.

Với custom Object, nếu gửi meta_data, API sẽ thay toàn bộ chuỗi metadata đã lưu; client cần merge các key hiện có trước khi cập nhật nếu muốn giữ lại. Với standard Object, API chỉ chấp nhận và merge các key: enable_auto_fill, enable_smart_paste, hide_create_button, allow_report, is_config_field_name_with_view, config_field_name_with_view, config_text, config_text_formula và is_show_avatar_before.

Ví dụ cURL cập nhật

curl --location --request PUT \
  'https://{workspace-domain}/bapi/v1/objects/OTRPIUQEDKM9Y' \
  --header 'Authorization: Bearer {tokenId}-{secretToken}' \
  --header 'Content-Type: application/json' \
  --data '{
    "description": "mô tả 2",
    "translations": [
      {
        "language": "en-US",
        "name": "Customer"
      }
    ]
  }'

Ví dụ trên chỉ cập nhật mô tả Object và tên tiếng Anh. Bản dịch plural_name tiếng Anh đã có sẽ được giữ nguyên.

Response thành công (200)

{
  "r": 0,
  "msg": "OK",
  "requestId": "RQ87dce633-ef58-4ec1-9bb5-e279afedb1ce"
}

4. Xoá hoặc khôi phục Object

Endpoint: POST /bapi/v1/objects/delete

Endpoint nhận request dạng danh sách. Để thao tác một Object, gửi đúng một phần tử trong data.

Request Body

{
  "data": [
    {
      "id": "OTRPIUQEDKM9Y",
      "delete_type": 1
    }
  ]
}

Trường	Kiểu	Bắt buộc	Mô tả
`data`	Array	Có	Danh sách Object cần thao tác
`data[].id`	String	Có	Object ID
`data[].delete_type`	Integer	Có	Loại thao tác xoá hoặc khôi phục

Giá trị `delete_type`

Giá trị	Ý nghĩa	Khuyến nghị cho public client
`1`	Soft delete: chuyển Object sang pending delete và đặt lịch xoá thực tế sau 14 ngày	Nên dùng cho thao tác xoá thông thường
`2`	Undo soft delete: khôi phục trạng thái trước đó và huỷ lịch xoá	Dùng để khôi phục Object
`3`	Actual delete: xoá cấu hình liên quan và dữ liệu Object	Có tính phá huỷ; chỉ dùng sau khi xác nhận rõ ràng

Không thể xoá standard Object. Yêu cầu xoá cũng có thể bị từ chối nếu Object đang được Object Picker tham chiếu hoặc các field, relationship, filter, workflow hay thực thể liên kết khác đang ngăn cản thao tác.

Ví dụ cURL soft delete

curl --location 'https://{workspace-domain}/bapi/v1/objects/delete' \
  --header 'Authorization: Bearer {tokenId}-{secretToken}' \
  --header 'Content-Type: application/json' \
  --data '{
    "data": [
      {
        "id": "OTRPIUQEDKM9Y",
        "delete_type": 1
      }
    ]
  }'

Ví dụ cURL khôi phục

curl --location 'https://{workspace-domain}/bapi/v1/objects/delete' \
  --header 'Authorization: Bearer {tokenId}-{secretToken}' \
  --header 'Content-Type: application/json' \
  --data '{
    "data": [
      {
        "id": "OTRPIUQEDKM9Y",
        "delete_type": 2
      }
    ]
  }'

Response thành công (200)

{
  "r": 0,
  "msg": "Success",
  "requestId": "RQ87dce633-ef58-4ec1-9bb5-e279afedb1ce"
}

Response lỗi thường gặp

`r`	Mô tả
`405`	Thiếu hoặc sai Object ID
`407`	Thiếu hoặc sai tên Object
`413`	`status` hoặc cờ standard không hợp lệ
`418`	`delete_type` không hợp lệ
`430`	Tên số nhiều không hợp lệ
`435`	Slug không hợp lệ
`436`	Thiếu hoặc sai trường tên chính
`438`	Thao tác không được phép với standard Object
`445`	Object type không hợp lệ
`501`	Không tìm thấy Object
`503`	Slug Object đã tồn tại
`506`	Tên Object đã tồn tại
`512`	Object đang chờ xoá nên không thể cập nhật
`517`	Object đang được Object Picker chọn nên không thể xoá
`518`	Tên số nhiều của Object đã tồn tại
`534`	Workspace đã đạt giới hạn Object của gói thuê bao

Ví dụ response lỗi:

{
  "r": 503,
  "msg": "Object slug customer already existed",
  "requestId": "RQ87dce633-ef58-4ec1-9bb5-e279afedb1ce"
}

Lưu ý sử dụng

Coi Object ID và field ID là chuỗi opaque, không phân tích cấu trúc ID.
Dùng slug ổn định, chữ thường; API này không hỗ trợ đổi slug sau khi tạo.
Ưu tiên soft delete (delete_type=1) để có thể khôi phục Object trong thời gian lưu giữ.
Actual delete (delete_type=3) có tính phá huỷ và có thể xoá record cùng cấu hình liên quan của Object.
Không chỉ dựa vào HTTP status; với API thay đổi dữ liệu, cần kiểm tra thêm r = 0.

blog.blogs_related

Object Information

Objects API (Đối tượng)

Xác thực

Tổng quan endpoint

1. Danh sách đối tượng

Phân quyền

Response (200)

2. Tạo Object

Request Body

Bản dịch

Ví dụ cURL tạo Object

Response thành công (201)

3. Cập nhật Object

Quy tắc quan trọng

Các thuộc tính có thể cập nhật

Ví dụ cURL cập nhật

Response thành công (200)

4. Xoá hoặc khôi phục Object

Request Body

Giá trị delete_type

Ví dụ cURL soft delete

Ví dụ cURL khôi phục

Response thành công (200)

Response lỗi thường gặp

Lưu ý sử dụng

Số hóa và tự động hóa hoàn toàn công tác vận hành và quản trị doanh nghiệp với Cogover!

Giá trị `delete_type`