Bảng dữ liệu

Tổng quan

Bảng dữ liệu (custom object) là bảng do cửa hàng tự định nghĩa ở CRM → Bảng dữ liệu — VD cong_no (công nợ), hop_dong, bao_hanh. Mỗi khách có thể có nhiều bản ghi trong một bảng, nối với khách qua cột liên kết (relation).

Method + path	Scope	Dùng để
`GET /objects`	`custom_object_record_create` hoặc `_update`	Danh sách bảng và cột
`GET /objects/:objectKey/records`	`custom_object_record_create` hoặc `_update`	Liệt kê bản ghi của bảng
`PUT /objects/:objectKey/records`	`custom_object_record_create` + `_update`	Tạo hoặc cập nhật tối đa 50 bản ghi
`GET /customers/:id/objects/:objectKey/records`	`customers_detail`	Bản ghi đang gắn với một khách
`PUT /customers/:id/objects/:objectKey/records`	`customers_update`	Tạo / cập nhật bản ghi và gắn với khách đó

Danh sách bảng và cột

GET /api/open/v1/objects

{
  "data": [
    {
      "key": "cong_no",
      "label": "Công nợ",
      "fields": [
        { "key": "so_chung_tu", "label": "Số chứng từ", "type": "text", "required": true, "unique": true, "isDefault": false, "options": null, "relation": null },
        { "key": "so_tien", "label": "Số tiền", "type": "decimal", "required": true, "unique": false, "isDefault": false, "options": null, "relation": null },
        { "key": "han_thanh_toan", "label": "Hạn thanh toán", "type": "date", "required": false, "unique": false, "isDefault": false, "options": null, "relation": null },
        { "key": "khach_hang", "label": "Khách hàng", "type": "relation", "required": false, "unique": false, "isDefault": false, "options": null,
          "relation": { "target": "scrm_customer", "cardinality": "one" } }
      ]
    }
  ]
}

relation.target là scrm_customer (khách hàng), scrm_order (đơn hàng) hoặc key của một bảng khác.

Liệt kê bản ghi

GET /api/open/v1/objects/cong_no/records?page=1&limit=50
GET /api/open/v1/customers/1f0c6a7e-…/objects/cong_no/records

page từ 1, limit 1–50 (mặc định 50).

{
  "data": [
    {
      "id": "a41f…",
      "objectKey": "cong_no",
      "customerId": "1f0c6a7e-5d1b-4a8e-9a63-2c1f0f6b9d10",
      "fields": { "so_chung_tu": "CT-2026-0091", "so_tien": 1250000, "han_thanh_toan": "2026-10-30", "khach_hang": ["1f0c6a7e-…"] },
      "createdAt": "2026-10-02T08:00:00.000Z",
      "updatedAt": "2026-10-08T03:12:45.123Z"
    }
  ],
  "total": 37,
  "page": 1,
  "limit": 50
}

Cột liên kết trả về mảng id đích; customerId là khách đầu tiên được liên kết (hoặc null).

Tạo hoặc cập nhật bản ghi

Theo bảng
Theo khách hàng
Response

PUT /api/open/v1/objects/cong_no/records

{
  "matchField": "so_chung_tu",
  "records": [
    { "fields": { "so_chung_tu": "CT-2026-0091", "so_tien": 1250000, "khach_hang": "1f0c6a7e-5d1b-4a8e-9a63-2c1f0f6b9d10" } },
    { "fields": { "so_chung_tu": "CT-2026-0092", "so_tien": 480000, "han_thanh_toan": null } }
  ]
}

PUT /api/open/v1/customers/1f0c6a7e-5d1b-4a8e-9a63-2c1f0f6b9d10/objects/cong_no/records

{
  "matchField": "so_chung_tu",
  "relationField": "khach_hang",
  "records": [
    { "fields": { "so_chung_tu": "CT-2026-0093", "so_tien": 990000 } }
  ]
}

{
  "results": [
    { "index": 0, "status": "updated", "id": "a41f…" },
    { "index": 1, "status": "created", "id": "b802…" }
  ]
}

Trường	Ghi chú
`matchField`	Mã một cột văn bản có bật "duy nhất" của bảng. Giá trị trùng bản ghi có sẵn ⇒ cập nhật; chưa có ⇒ tạo. Không gửi ⇒ luôn tạo mới
`relationField`	Chỉ endpoint theo khách: mã cột liên kết tới khách để gắn — bắt buộc khi bảng có nhiều hơn một cột như vậy
`records[].fields`	Giá trị theo mã cột — kiểu giá trị như Trường tuỳ chỉnh; cột liên kết nhận một id hoặc mảng id

Cập nhật chỉ đổi cột bạn gửi; gửi null ⇒ xoá giá trị cột đó.
Endpoint theo khách tự gắn khách vào cột liên kết, và chỉ cập nhật được bản ghi đang gắn với khách đó — bản ghi khớp matchField nhưng thuộc khách khác trả lỗi CUSTOM_OBJECT_RECORD_NOT_FOUND ở dòng đó.

Ví dụ: đồng bộ công nợ từ kế toán

Tạo bảng cong_no với cột so_chung_tu (văn bản, duy nhất) và cột liên kết khach_hang. Mỗi đêm gọi PUT /customers/:id/objects/cong_no/records với matchField: "so_chung_tu" — chứng từ mới được thêm, chứng từ cũ được cập nhật số tiền, nhân viên thấy ngay trên hồ sơ khách.

Lỗi thường gặp ở từng dòng

Code	Khi nào
`CUSTOM_OBJECT_NOT_FOUND`	`objectKey` không tồn tại (trả cho cả request)
`OPEN_API_FIELD_UNKNOWN`	Mã cột không có trong bảng
`CUSTOM_OBJECT_VALUE_INVALID` / `CUSTOM_OBJECT_VALUE_REQUIRED`	Giá trị sai kiểu / thiếu cột bắt buộc
`CUSTOM_OBJECT_VALUE_DUPLICATE`	Cột "duy nhất" đã có giá trị này ở bản ghi khác
`CUSTOM_OBJECT_CUSTOMER_FIELD_REQUIRED`	Bảng có nhiều cột liên kết tới khách mà thiếu `relationField`
`CUSTOM_OBJECT_RECORD_NOT_FOUND`	Bản ghi khớp không gắn với khách ở đường dẫn

Tổng quan​

Danh sách bảng và cột​

Liệt kê bản ghi​

Tạo hoặc cập nhật bản ghi​

Lỗi thường gặp ở từng dòng​

Tổng quan

Danh sách bảng và cột

Liệt kê bản ghi

Tạo hoặc cập nhật bản ghi

Lỗi thường gặp ở từng dòng