VBot Documentation

Appearance

Quản lý khách hàng ​

API quản lý khách hàng

Các trường mặc định ​

Mỗi khách hàng luôn có các trường mặc định sau (không thể xóa):

TrườngTênMô tả
nameTên khách hàngBắt buộc
customer_codeMã khách hàngBắt buộc, duy nhất, chỉ chứa chữ/số/_/-
phoneSố điện thoại—
member_noNgười quản lýMã thành viên.
Truy cập Cài đặt nhóm -> Thành viên, xem cột Mã thành viên để lấy mã thành viên

Ngoài ra còn có các trường thông tin tùy chỉnh do người dùng tạo (xem Trường dữ liệu).

Danh sách khách hàng ​

POST[URL]/api/customer/get-all

Header

Tham sốGiá trị
X-API-Keytoken-open-api

Body

Tham sốKiểuBắt buộcMô tả
pageIntKhôngSố trang
sizeIntKhôngSố lượng trên 1 trang
field_searchArrayKhôngDanh sách filter theo từng trường thông tin

Cấu trúc mỗi phần tử field_search:

Tham sốKiểuMô tả
customer_field_codeStringMã trường thông tin
valueStringGiá trị filter
typeStringKiểu so sánh: EQUAL, CONTAIN, RANGER
is_searchBooltrue = áp dụng filter, false = chỉ lấy data của trường thông tin đó vào response, không filter

Kiểu so sánh (type):

Giá trịÁp dụng cho type fieldMô tả
EQUALTất cảSo sánh bằng
CONTAINSTRINGTìm kiếm chứa chuỗi
RANGERNUMBER, DATEKhoảng giá trị, value = min | max

Field đặc biệt create_at: Lọc tìm khách hàng theo khoảng ngày tạo, value format dd/MM/yyyy|dd/MM/yyyy (from|to), type sử dụng phải là RANGER.

Lưu ý: Trường thông tin có kiểu là TEXT không áp dụng tìm kiểm được

Ví dụ request

json
{
  "page": 1,
  "size": 10,
  "field_search": [
    {
      "customer_field_code": "name",
      "value": "Nguyen",
      "type": "CONTAIN",
      "is_search": true
    },
    {
      "customer_field_code": "create_at",
      "value": "01/01/2026|31/12/2026",
      "type": "RANGER",
      "is_search": true
    },
    {
      "customer_field_code": "customer_code",
      "value": "",
      "type": "",
      "is_search": false
    }
  ]
}

Response

Tham sốKiểuMô tả
errorIntMã lỗi (0: Thành công, khác 0: Có lỗi)
messageStringThông tin
dataList[Object]Danh sách khách hàng

Cấu trúc phần tử trong data

TrườngKiểuMô tả
create_atLongThời gian tạo (Unix timestamp - ms)
customer_field_itemsArrayDanh sách trường thông tin và các giá trị
customer_field_items[].codeStringMã trường thông tin
customer_field_items[].nameStringTên trường thông tin
customer_field_items[].typeStringLoại trường thông tin
customer_field_items[].valueStringGiá trị (dùng cho trường thông tin không phải option)
customer_field_items[].numberLongThứ tự sắp xếp
customer_field_items[].value_optionArrayDanh sách option đang chọn (dùng cho SELECT/CHECKBOX/RADIO)

Ví dụ response

json
{
  "error": 0,
  "message": "success",
  "data": [
    {
      "create_at": 1718000000000,
      "customer_field_items": [
        {
          "code": "name",
          "name": "Tên khách hàng",
          "type": "STRING",
          "value": "Nguyen Van A",
          "number": 1,
          "value_option": null
        },
        {
          "code": "status",
          "name": "Trạng thái",
          "type": "SELECT",
          "value": null,
          "number": 2,
          "value_option": [
            {
              "code": "active",
              "color": "#00FF00",
              "text_color": "#FFFFFF",
              "number": 1,
              "value": "Đang hoạt động"
            }
          ]
        }
      ]
    }
  ]
}

Đếm số lượng khách hàng ​

POST[URL]/api/customer/count-all

Header

Tham sốGiá trị
X-API-Keytoken-open-api

Body

Tham sốKiểuBắt buộcMô tả
field_searchArrayKhôngDanh sách filter theo trường thông tin

Cấu trúc mỗi phần tử field_search:

Tham sốKiểuMô tả
customer_field_codeStringMã trường thông tin
valueStringGiá trị filter
typeStringKiểu so sánh: EQUAL, CONTAIN, RANGER
is_searchBooltrue = áp dụng filter, false = bỏ qua

Ví dụ request

json
{
  "field_search": [
    {
      "customer_field_code": "name",
      "value": "Nguyen",
      "type": "CONTAIN",
      "is_search": true
    }
  ]
}

Response

Tham sốKiểuMô tả
errorIntMã lỗi (0: Thành công, khác 0: Có lỗi)
messageStringThông tin
dataIntSố lượng khách hàng

Ví dụ response

json
{
  "error": 0,
  "message": "success",
  "data": 125
}

Chi tiết khách hàng ​

GET[URL]/api/customer/get-detail

Header

Tham sốGiá trị
X-API-Keytoken-open-api

Tham số

Tham sốKiểuBắt buộcMô tả
customer_codeStringKhôngMã khách hàng. Để trống → trả về form mẫu (cấu trúc tất cả field, không có giá trị). Dùng để render form nhập liệu.

Response

Tham sốKiểuMô tả
errorIntMã lỗi (0: Thành công, khác 0: Có lỗi)
messageStringThông tin
dataObjectThông tin chi tiết khách hàng

Lưu ý trường thông tin value_options trong data.fields:

  • Với trường thông tin có option (SELECT/CHECKBOX/RADIO): trả danh sách tất cả option, is_select: true = option đang được chọn
  • Với trường thông tin khác: mảng rỗng

Ví dụ response

json
{
  "error": 0,
  "message": "success",
  "data": {
    "customer_code": "KH001",
    "fields": [
      {
        "code": "name",
        "name": "Tên khách hàng",
        "type": "STRING",
        "color": "",
        "text_color": "",
        "is_required": true,
        "value": "Nguyen Van A",
        "number": 1,
        "is_unique": false,
        "value_options": []
      },
      {
        "code": "status",
        "name": "Trạng thái",
        "type": "SELECT",
        "color": "#EEEEEE",
        "text_color": "#000000",
        "is_required": false,
        "value": "",
        "number": 2,
        "is_unique": false,
        "value_options": [
          {
            "code": "active",
            "is_select": true,
            "name": "Đang hoạt động",
            "color": "#00FF00",
            "text_color": "#FFFFFF",
            "number": 1,
            "type": "OPTION",
            "customer_field_option_code": "active"
          },
          {
            "code": "inactive",
            "is_select": false,
            "name": "Ngừng hoạt động",
            "color": "#FF0000",
            "text_color": "#FFFFFF",
            "number": 2,
            "type": "OPTION",
            "customer_field_option_code": "inactive"
          }
        ]
      }
    ]
  }
}

Kiểm tra trùng thông tin khách hàng ​

GET[URL]/api/customer/check-exist-field-value

Chỉ có tác dụng với trường thông tin có is_unique = true.

Header

Tham sốGiá trị
X-API-Keytoken-open-api

Tham số

Tham sốKiểuBắt buộcMô tả
customer_field_codeStringCóMã trường thông tin
valueStringCóGiá trị muốn kiểm tra
customer_codeStringKhôngĐể trống khi kiểm tra thêm khách hàng mới. Truyền customer_code của khách hàng đang sửa để tránh báo lỗi trùng với chính mình

Response

Tham sốKiểuMô tả
errorIntMã lỗi (0: Thành công, khác 0: Có lỗi)
messageStringThông tin
dataBoolKết quả kiểm tra

Ý nghĩa data

dataÝ nghĩa
trueGiá trị đã tồn tại (trùng)
falseKhông trùng hoặc trường thông tin không phải là duy nhất

Ví dụ response

json
{
  "error": 0,
  "message": "success",
  "data": false
}

Thêm khách hàng mới ​

POST[URL]/api/customer/insert

Header

Tham sốGiá trị
X-API-Keytoken-open-api

Body

Tham sốKiểuMô tả
fieldsObjectObject chứa các thông tin của khách hàng theo dạng key-value với key là customer_field_code

Các key đặc biệt trong fields:

KeyBắt buộcMô tả
customer_codeBắt buộcMã khách hàng. Duy nhất trong project. Chỉ chứa chữ cái, số, _, -
member_noKhôngMã thành viên quản lý

Format giá trị theo kiểu của các trường thông tin (Xem thêm Phân loại trường dữ liệu):

TypeFormat
STRING, PHONE, TEXTChuỗi văn bản
NUMBERSố (ví dụ: "1500000")
DATEdd/MM/yyyy
SELECT, RADIO, CHECKBOXcustomer_field_option_code của option được chọn

Ví dụ request

json
{
  "fields": {
    "customer_code": "KH001",
    "name": "Nguyen Van A",
    "phone": "0901234567",
    "member_no": "MEM01",
    "birth_date": "15/06/1990",
    "status": "active"
  }
}

Response

Tham sốKiểuMô tả
errorIntMã lỗi (0: Thành công, khác 0: Có lỗi)
messageStringThông tin
dataBoolTrạng thái thực hiện

Ví dụ response

json
{
  "error": 0,
  "message": "success",
  "data": true
}

Cập nhật khách hàng ​

POST[URL]/api/customer/update

Header

Tham sốGiá trị
X-API-Keytoken-open-api

Chỉ cập nhật các trường dữ liệu có trong fields. Trường dữ liệu không truyền thì sẽ giữ nguyên giá trị cũ

Body

Tham sốKiểuBắt buộcMô tả
customer_codeStringCóMã khách hàng
fieldsObjectCóCác field muốn cập nhật

Các key đặc biệt trong fields:

KeyMô tả
customer_codeMã khách hàng. Mã mới phải duy nhất, chỉ chứa chữ/số/_/-
member_noMã người quản lý. Truyền chuỗi rỗng "" để xóa người quản lý

Ví dụ request

json
{
  "customer_code": "KH001",
  "fields": {
    "name": "Nguyen Van B",
    "customer_code": "KH001_NEW",
    "member_no": "MEM02"
  }
}

Response

Tham sốKiểuMô tả
errorIntMã lỗi (0: Thành công, khác 0: Có lỗi)
messageStringThông tin
dataBoolTrạng thái thực hiện

Ví dụ response

json
{
  "error": 0,
  "message": "success",
  "data": true
}

Xóa khách hàng ​

POST[URL]/api/customer/delete

Header

Tham sốGiá trị
X-API-Keytoken-open-api

Body

Tham sốKiểuBắt buộcMô tả
customer_codeStringCóMã khách hàng cần xóa

Ví dụ request

json
{
  "customer_code": "KH001"
}

Response

Tham sốKiểuMô tả
errorIntMã lỗi (0: Thành công, khác 0: Có lỗi)
messageStringThông tin
dataBoolTrạng thái thực hiện

Ví dụ response

json
{
  "error": 0,
  "message": "success",
  "data": true
}