Khách hàng
Tìm, lọc và đếm khách hàng trên LadiWork, xem hồ sơ và lịch sử tương tác của từng khách, xuất danh sách, tạo khách hàng mới.
Mọi API trong trang gọi bằng POST https://api.ladipage.net/2.0/api/{tên-api} với header api-key. Xem Xác thực và Mã lỗi.
| API | Việc làm | Loại |
|---|---|---|
lw-search-customers | Tìm kiếm khách hàng | Đọc |
lw-filter-customers | Lọc khách hàng theo điều kiện | Đọc |
lw-count-customers | Đếm khách hàng | Đọc |
lw-get-customer | Xem chi tiết khách hàng | Đọc |
lw-get-customer-overview | Xem tổng quan khách hàng | Đọc |
lw-list-customer-activity | Liệt kê hoạt động của khách hàng | Đọc |
lw-list-customer-calls | Liệt kê cuộc gọi của khách hàng | Đọc |
lw-list-customer-deals | Liệt kê giao dịch của khách hàng | Đọc |
lw-list-customer-fields | Lấy danh sách trường lọc khách hàng | Đọc |
lw-list-customer-interactions | Liệt kê tương tác automation của khách hàng | Đọc |
lw-list-customer-notes | Liệt kê ghi chú của khách hàng | Đọc |
lw-list-customer-orders | Liệt kê đơn hàng automation của khách hàng | Đọc |
lw-list-customer-sale-orders | Liệt kê đơn hàng LadiSales của khách hàng | Đọc |
lw-list-customer-segments | Liệt kê phân khúc khách hàng | Đọc |
lw-list-customer-tags | Liệt kê tag khách hàng | Đọc |
lw-list-customer-tasks | Liệt kê công việc của khách hàng | Đọc |
lw-list-organizations | Liệt kê công ty/tổ chức | Đọc |
lw-export-customers | Xuất danh sách khách hàng ra Excel | Đọc |
lw-create-customer | Tạo khách hàng | Tạo |
Quy ước chung
store_idlà tham số chung của mọi APIlw-*: giá trịstore_idlấy từaccount-list-workspaces. Tài khoản chỉ có một workspace thì bỏ trống được; từ hai workspace trở lên mà thiếustore_idthì API trả lỗi kèm danh sách workspace hợp lệ (tên + mã). Truyền mã không thuộc tài khoản cũng bị từ chối.- Mọi kết quả thành công có thêm trường
store_contextgồmstore_id,store_name(tên workspace) và you (tên người cầm token). - Email và số điện thoại trong kết quả (các trường email, phone,
phone_2) bị che một phần, ví dụ ma***@gmail.com, 0912***678. Đầu vào không bị ảnh hưởng: tìm theo email/số điện thoại đầy đủ vẫn chạy bình thường. Trường tuỳ chỉnh có nhãn nhạy cảm (OTP, mật khẩu, CCCD/CMND, số thẻ, token...) bị thay bằng [đã ẩn]. - Token của nhân viên chỉ thấy dữ liệu trong quyền của họ: không có quyền xem khách hàng thì bị từ chối; không có quyền xem tất cả khách thì chỉ thấy khách mình phụ trách hoặc theo dõi. API về giao dịch, công việc, tổ chức còn yêu cầu nhân viên đã được thêm vào LadiWork của workspace.
- Thời gian trả về theo múi giờ của workspace (mặc định +07:00), dạng ISO 8601 có offset.
- Lỗi nghiệp vụ trả HTTP 400, message là câu mô tả lỗi bằng tiếng Việt.
Tìm kiếm khách hàng Đọc
POST/2.0/api/lw-search-customers
Tìm khách hàng theo từ khoá (tên, email, số điện thoại), kết hợp lọc theo công ty, nhóm, tag và điều kiện trên từng trường. Dùng để tra cứu nhanh; mỗi trang tối đa 20 khách.
Tham số
| Tham số | Kiểu | Mô tả |
|---|---|---|
| store_id | string | Mã workspace lấy từ account-list-workspaces. Bắt buộc khi tài khoản có từ hai workspace trở lên. |
| keyword | string | Tên, email hoặc số điện thoại. Chuỗi có ký tự @ phải là email hợp lệ, nếu không API báo lỗi. Email hợp lệ: tìm đúng email đó. Số điện thoại hợp lệ: tìm đúng số đó. Còn lại: tìm gần đúng theo tên. Khi keyword là email hoặc số điện thoại, các tham số company, group, tags, filters bị bỏ qua. Bỏ trống: lấy khách mới cập nhật gần nhất. |
| company | string | Tên công ty/tổ chức, không phân biệt hoa thường. Khớp đúng tên, hoặc khớp một phần nếu chỉ có đúng một công ty chứa chuỗi này. Không khớp thì lỗi kèm gợi ý. Danh sách lấy từ lw-list-organizations. |
| group | string | Tên nhóm khách hàng (phân khúc), cách khớp giống company. Danh sách lấy từ lw-list-customer-segments. |
| tags | array<string> | Danh sách tên tag, khớp đúng tên (không phân biệt hoa thường). Mỗi tag là một điều kiện, nối theo match. Có tag không tồn tại thì lỗi. Danh sách lấy từ lw-list-customer-tags. |
| filters | array<object> | Điều kiện lọc trên từng trường. Mỗi phần tử là một điều kiện, nối theo match. |
| filters[].fieldbắt buộc | string | Tên trường. Trường hệ thống: name (hoặc full_name), first_name, last_name, email, phone, postal_code, gender, score, dob, dob_day, dob_month, dob_year, created_at, updated_at, total_order, total_order_value, avg_order_value, total_pending_order, total_pending_order_value, avg_pending_order_value, total_paid_order, total_paid_order_value, avg_paid_order_value, total_cancel_order, total_cancel_order_value, avg_cancel_order_value, bounce, complaint, is_email_verified, email_subscribe_status, phone_verified (nhận cả dạng viết hoa như TOTAL_ORDER). Tên khác được hiểu là trường tuỳ chỉnh, so theo nhãn, tên hoặc alias của trường, không phân biệt dấu và hoa thường (xem lw-list-customer-fields). Trường tuỳ chỉnh kiểu Đối tượng (OBJECT) không lọc được ở đây, hãy dùng lw-filter-customers. |
| filters[].operator | string | Toán tử; bỏ trống thì dùng mặc định theo kiểu trường. Chữ (name, first_name, last_name, email, phone, trường tuỳ chỉnh TEXT_INPUT/TEXT_AREA/COUPON): CONTAINS (mặc định), NOT_CONTAIN, EQUAL, NOT_EQUAL, BEGIN_WITH, HAS_ANY_VALUE, IS_UNKNOWN. Số (score, dob_day, dob_month, dob_year, total_*, avg_*, bounce, complaint, trường tuỳ chỉnh NUMBER/AUTO_INCREMENT): IS_EXACTLY (mặc định), NOT_EQUAL, GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, HAS_ANY_VALUE, IS_UNKNOWN. Ngày (dob, created_at, updated_at, trường tuỳ chỉnh DATE): ON (mặc định), BEFORE, AFTER, HAS_ANY_VALUE, IS_UNKNOWN. gender: EQUAL (mặc định), HAS_ANY_VALUE, IS_UNKNOWN. Đúng/sai (is_email_verified, email_subscribe_status, phone_verified, trường tuỳ chỉnh BOOLEAN): EQUAL. postal_code và trường tuỳ chỉnh lựa chọn (DROPDOWN, CHECK_BOX, LIST): EQUAL (mặc định), NOT_EQUAL. Nhận cả dạng viết tắt: contains, not_contain, equal, eq, =, not_equal, ne, !=, begin_with, starts_with, gt, >, gte, >=, lt, <, lte, <=, is_exactly, on, before, after, has_any_value, is_unknown. Với trường số, EQUAL được hiểu là IS_EXACTLY. |
| filters[].value | string | Giá trị so sánh; bắt buộc trừ khi toán tử là HAS_ANY_VALUE hoặc IS_UNKNOWN. Ngày: ISO 8601 (vd 2026-10-01). gender: male hoặc female. Đúng/sai: true hoặc false. Trường lựa chọn: nhãn hoặc giá trị của lựa chọn. |
| match | string | Cách nối các điều kiện (company, group, tags, filters): AND = thoả tất cả, OR = thoả ít nhất một.Giá trị: AND, ORMặc định: AND |
| sort_by | string | Trường sắp xếp.Giá trị: updated_at, created_atMặc định: updated_at |
| sort_order | string | Thứ tự sắp xếp.Giá trị: DESC, ASCMặc định: DESC |
| page | number | Số trang, bắt đầu từ 1.Mặc định: 1 |
| limit | number | Số khách mỗi trang, tối đa 20 (lớn hơn sẽ bị hạ về 20).Mặc định: 20 |
Ví dụ
curl -X POST https://api.ladipage.net/2.0/api/lw-search-customers \
-H "api-key: $LADIPAGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"store_id": "5f8a3c2e9b1d4a7e6c0f1234",
"keyword": "Nguyễn",
"tags": [
"VIP"
],
"filters": [
{
"field": "total_order",
"operator": "gt",
"value": "0"
}
],
"page": 1,
"limit": 20
}'Kết quả
{
"code": 200,
"message": "Success",
"data": {
"total": 2,
"total_verified": 1,
"page": 1,
"limit": 20,
"keyword": "Nguyễn",
"applied_filters": 1,
"match": "AND",
"count": 2,
"items": [
{
"id": "64b7e2f1a9c3d5e7f8a1b2c3",
"name": "Nguyễn Văn An",
"email": "an***@example.com",
"phone": "******5678",
"created_at": "2026-10-05T09:12:30+07:00",
"updated_at": "2026-10-21T14:05:10+07:00",
"detail_url": "https://ladiwork.ladipage.com/customer/64b7e2f1a9c3d5e7f8a1b2c3"
},
{
"id": "64b7e2f1a9c3d5e7f8a1b2d4",
"name": "Nguyễn Thị Bình",
"email": "bi***@gmail.com",
"phone": "******4321",
"created_at": "2026-10-12T16:40:02+07:00",
"updated_at": "2026-10-20T08:22:45+07:00",
"detail_url": "https://ladiwork.ladipage.com/customer/64b7e2f1a9c3d5e7f8a1b2d4"
}
]
}
}total_verified là số khách đã xác minh email; applied_filters là số điều kiện đã áp. Email và số điện thoại bị che một phần. Khách bị ẩn do workspace vượt hạn mức khách hàng của gói có thêm is_hidden. Khi total lớn hơn số dòng trả về, kết quả có thêm more_available, export (kết quả xuất Excel, cấu trúc như lw-export-customers) và suggestion.
Lưu ý
- Khi tổng số khách lớn hơn số dòng của trang, API tự xuất Excel TOÀN BỘ khách theo company, group, tags, filters (không áp keyword) và gắn vào trường export. Trên 10.000 khách thì file được xử lý nền và gửi link qua email chủ workspace. Để tránh việc này, thu hẹp bộ lọc hoặc dùng
lw-filter-customersđể phân trang. - Khi keyword là email hoặc số điện thoại, total là số khách tìm thấy trong trang, không phải tổng thật.
- Email và số điện thoại trong items bị che một phần.
- Muốn lọc phức tạp hơn (phân khúc theo id, trường Đối tượng, sắp theo trường tuỳ chỉnh, tối đa 50 dòng/trang) dùng
lw-filter-customers.
Lọc khách hàng theo điều kiện Đọc
POST/2.0/api/lw-filter-customers
Lọc khách hàng theo nhiều điều kiện có toán tử trên trường hệ thống, tag, tổ chức, phân khúc và trường tuỳ chỉnh, trả danh sách có phân trang (tối đa 50 dòng/trang). Gọi lw-list-customer-fields trước để lấy mã trường, tên trường tuỳ chỉnh và id tag/tổ chức/phân khúc.
Tham số
| Tham số | Kiểu | Mô tả |
|---|---|---|
| store_id | string | Mã workspace lấy từ account-list-workspaces. Bắt buộc khi tài khoản có từ hai workspace trở lên. |
| keyword | string | Tìm gần đúng theo tên khách (so dạng không dấu). Bỏ trống: không lọc theo từ khoá. |
| operator | string | Cách ghép các điều kiện: AND = thoả tất cả, OR = thoả ít nhất một.Giá trị: AND, ORMặc định: AND |
| conditions | array<object> | Danh sách điều kiện, mỗi phần tử dạng { condition: { code, name }, operator: { code }, value: { value, name, path } }. Bỏ trống: lấy tất cả khách theo thứ tự sắp xếp. |
| conditions[].condition.codebắt buộc | string | Trường hệ thống: mã trường viết hoa, vd FULL_NAME, FIRST_NAME, LAST_NAME, EMAIL, PHONE, GENDER, DOB, DOB_DAY, DOB_MONTH, DOB_YEAR, CITY, DISTRICT, WARD, COUNTRY, ADDRESS, COMPANY, JOB_TITLE, TAG, ORGANIZATION, SEGMENT, SCORE, CREATED_AT, UPDATED_AT, TOTAL_ORDER, TOTAL_ORDER_VALUE, TOTAL_PAID_ORDER, TOTAL_PAID_ORDER_VALUE, UTM_SOURCE, UTM_CAMPAIGN, IS_EMAIL_VERIFIED, EMAIL_SUBSCRIBE_STATUS, PHONE_VERIFIED, SCOPE_USERS (người phụ trách). Danh sách đầy đủ ở system_fields[].code của lw-list-customer-fields. Trường tuỳ chỉnh: truyền KIỂU dữ liệu của trường (TEXT_INPUT, TEXT_AREA, NUMBER, DATE, DROPDOWN, CHECK_BOX, LIST, BOOLEAN, COUPON, AUTO_INCREMENT, TAG, OBJECT), lấy ở custom_fields[].code. Mã không hợp lệ thì lỗi. |
| conditions[].condition.name | string | Bắt buộc với trường tuỳ chỉnh: tên trường (custom_fields[].name của lw-list-customer-fields, không phải nhãn hiển thị). Bỏ trống với trường hệ thống. |
| conditions[].operator.codebắt buộc | string | Mã toán tử viết hoa, chọn theo type của trường trong lw-list-customer-fields. TEXT: EQUAL, NOT_EQUAL, CONTAINS, NOT_CONTAIN, BEGIN_WITH, HAS_ANY_VALUE, IS_UNKNOWN. NUMBER: EQUAL (hoặc IS_EXACTLY), NOT_EQUAL, GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, HAS_ANY_VALUE, IS_UNKNOWN. DATE: ON, BEFORE, AFTER (value là ngày); GREATER_THAN N = trong vòng N ngày gần đây; LESS_THAN N = cách đây hơn N ngày; EXACTLY_EQUAL_TO_DAYS_AGO N = đúng N ngày trước; TODAY, YESTERDAY, TOMORROW, THIS_WEEK, LAST_WEEK, NEXT_WEEK, THIS_MONTH, LAST_MONTH, NEXT_MONTH, THIS_YEAR, LAST_YEAR, BEFORE_CURRENT_DATE, AFTER_CURRENT_DATE (không cần value); LAST_N_DAYS, NEXT_N_DAYS, LAST_N_MONTHS, NEXT_N_MONTHS (value = N); HAS_ANY_VALUE, IS_UNKNOWN. SELECT (TAG, ORGANIZATION, DROPDOWN, CHECK_BOX, LIST, BOOLEAN): EQUAL, NOT_EQUAL, HAS_ANY_VALUE, IS_UNKNOWN. SEGMENT: EQUAL. OBJECT: xem conditions[].value.path. Mã toán tử không tồn tại thì lỗi. |
| conditions[].value.value | string | number | boolean | Giá trị so khớp; bỏ trống với toán tử không cần giá trị. TAG, ORGANIZATION, SEGMENT: id lấy từ lw-list-customer-fields. DROPDOWN, CHECK_BOX, LIST: giá trị (value) của lựa chọn, không phải nhãn. BOOLEAN: true hoặc false. GENDER: male hoặc female. Ngày: YYYY-MM-DD hoặc ISO 8601. |
| conditions[].value.name | string | Chỉ dùng cho TAG và ORGANIZATION: truyền tên thay cho id (khớp đúng tên, phân biệt hoa thường). Tên không khớp thì API không báo lỗi, nên ưu tiên dùng id. |
| conditions[].value.path | string | Chỉ dùng cho trường tuỳ chỉnh OBJECT (Đối tượng JSON): đường dẫn khoá cần so, vd product_type hoặc dia_chi.tinh, lấy ở custom_fields[].keys của lw-list-customer-fields. Khoá chữ/số/đúng sai: EQUAL, IS_EXACTLY, NOT_EQUAL, BEGIN_WITH, HAS_ANY_VALUE, IS_UNKNOWN. Khoá ngày: ON, BEFORE, AFTER (YYYY-MM-DD) và các toán tử khoảng thời gian như kiểu DATE. Không có path kèm HAS_ANY_VALUE / IS_UNKNOWN = khách có / không có trường này. Điều kiện không hợp lệ thì lỗi. |
| sort_by | string | Trường sắp xếp, vd created_at, updated_at, total_order, total_order_value, score. Trường tuỳ chỉnh: custom_fields.<tên trường> (sắp theo số) hoặc custom_fields.<tên trường>.keyword (sắp theo chữ).Mặc định: created_at |
| sort_order | string | Thứ tự sắp xếp.Giá trị: asc, descMặc định: desc |
| page | number | Số trang, bắt đầu từ 1. page × limit không được vượt 10.000, vượt thì lỗi; khi đó hãy thu hẹp bộ lọc.Mặc định: 1 |
| limit | number | Số khách mỗi trang, tối đa 50.Mặc định: 20 |
Ví dụ
curl -X POST https://api.ladipage.net/2.0/api/lw-filter-customers \
-H "api-key: $LADIPAGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"store_id": "5f8a3c2e9b1d4a7e6c0f1234",
"operator": "AND",
"conditions": [
{
"condition": {
"code": "TOTAL_ORDER"
},
"operator": {
"code": "GREATER_THAN"
},
"value": {
"value": 0
}
},
{
"condition": {
"code": "TAG"
},
"operator": {
"code": "EQUAL"
},
"value": {
"value": "65a1c9e2b4d6f8a0c2e4f6a8"
}
},
{
"condition": {
"code": "DROPDOWN",
"name": "nguon_khach"
},
"operator": {
"code": "EQUAL"
},
"value": {
"value": "facebook"
}
}
],
"sort_by": "created_at",
"sort_order": "desc",
"page": 1,
"limit": 50
}'Kết quả
{
"code": 200,
"message": "Success",
"data": {
"total": 2,
"page": 1,
"limit": 20,
"count": 2,
"field_labels": {
"id": "Mã khách hàng",
"name": "Họ tên",
"email": "Email",
"phone": "Số điện thoại",
"tags": "Tag",
"total_order": "Tổng số đơn",
"total_order_value": "Tổng giá trị đơn",
"created_at": "Ngày tạo",
"detail_url": "Link chi tiết"
},
"items": [
{
"id": "64b7e2f1a9c3d5e7f8a1b2c3",
"name": "Nguyễn Văn An",
"email": "an***@example.com",
"phone": "******5678",
"tags": ["Khách VIP", "Đã mua"],
"total_order": 3,
"total_order_value": 4500000,
"created_at": "2026-10-05T09:12:30+07:00",
"detail_url": "https://ladiwork.ladipage.com/customer/64b7e2f1a9c3d5e7f8a1b2c3"
},
{
"id": "64b7e2f1a9c3d5e7f8a1b2d4",
"name": "Trần Thị Bình",
"email": "bi***@gmail.com",
"phone": "******4321",
"tags": ["Lead mới"],
"total_order": 0,
"total_order_value": 0,
"created_at": "2026-10-12T16:40:02+07:00",
"detail_url": "https://ladiwork.ladipage.com/customer/64b7e2f1a9c3d5e7f8a1b2d4"
}
]
}
}field_labels là nhãn tiếng Việt của các trường trong item; tags là tên tag. Email và số điện thoại bị che một phần.
Lưu ý
- Để đếm khách theo nhóm (mỗi tag, mỗi phân khúc bao nhiêu khách) dùng
lw-count-customers. - Email và số điện thoại trong items bị che một phần.
- Nhân viên cần quyền xem khách hàng; không có quyền xem tất cả thì chỉ thấy khách mình phụ trách hoặc theo dõi.
Đếm khách hàng Đọc
POST/2.0/api/lw-count-customers
Đếm tổng số khách hàng theo bộ lọc, hoặc đếm theo nhóm: tag, tổ chức, phân khúc hoặc giá trị của một trường tuỳ chỉnh. Không trả danh sách khách, phù hợp cho thống kê trên tập lớn.
Tham số
| Tham số | Kiểu | Mô tả |
|---|---|---|
| store_id | string | Mã workspace lấy từ account-list-workspaces. Bắt buộc khi tài khoản có từ hai workspace trở lên. |
| group_by | string | Chiều đếm. Bỏ trống: chỉ trả tổng số khách theo bộ lọc. SEGMENT chỉ đếm tối đa 30 phân khúc đầu tiên của workspace.Giá trị: TAG, ORGANIZATION, SEGMENT, CUSTOM_FIELD |
| custom_field_name | string | Bắt buộc khi group_by = CUSTOM_FIELD: tên trường (custom_fields[].name của lw-list-customer-fields). |
| custom_field_data_type | string | Bắt buộc khi group_by = CUSTOM_FIELD: kiểu dữ liệu của trường, vd DROPDOWN, TEXT_INPUT. Không đếm theo nhóm được với kiểu OBJECT (hãy đếm từng giá trị bằng conditions có value.path). |
| operator | string | Cách ghép các điều kiện trong conditions.Giá trị: AND, ORMặc định: AND |
| conditions | array<object> | Bộ lọc áp trước khi đếm, cùng cấu trúc với conditions của lw-filter-customers. Bỏ trống: đếm tất cả khách. |
| conditions[].condition.codebắt buộc | string | Mã trường hệ thống, hoặc kiểu dữ liệu nếu là trường tuỳ chỉnh. Giống lw-filter-customers. |
| conditions[].condition.name | string | Tên trường tuỳ chỉnh; bắt buộc khi là trường tuỳ chỉnh. |
| conditions[].operator.codebắt buộc | string | Mã toán tử, cùng danh sách và ý nghĩa như lw-filter-customers. |
| conditions[].value.value | string | number | boolean | Giá trị so khớp (id với TAG/ORGANIZATION/SEGMENT). |
| conditions[].value.name | string | Tên tag hoặc tổ chức thay cho id (khớp đúng tên, phân biệt hoa thường). |
| conditions[].value.path | string | Đường dẫn khoá, chỉ cho trường tuỳ chỉnh OBJECT. Giống lw-filter-customers. |
| from_date | string | Chỉ đếm khách tạo từ thời điểm này, ISO 8601, vd 2026-01-01T00:00:00Z. |
| to_date | string | Chỉ đếm khách tạo đến thời điểm này, ISO 8601, vd 2026-12-31T23:59:59Z. |
| size | number | Số nhóm tối đa trả về (nhóm đông nhất trước), tối đa 30. Áp cho TAG, ORGANIZATION, CUSTOM_FIELD.Mặc định: 20 |
Ví dụ
curl -X POST https://api.ladipage.net/2.0/api/lw-count-customers \
-H "api-key: $LADIPAGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"store_id": "5f8a3c2e9b1d4a7e6c0f1234",
"group_by": "TAG",
"conditions": [
{
"condition": {
"code": "TOTAL_ORDER"
},
"operator": {
"code": "GREATER_THAN"
},
"value": {
"value": 0
}
}
],
"from_date": "2026-01-01T00:00:00Z",
"size": 20
}'Kết quả
{
"code": 200,
"message": "Success",
"data": {
"total": 1250,
"group_by": "TAG",
"groups": [
{
"key": "65a1c3e5f7b9d1e3a5c7e9f1",
"name": "Khách VIP",
"count": 180
},
{
"key": "65a1c3e5f7b9d1e3a5c7ea02",
"name": "Lead mới",
"count": 620
}
],
"field_labels": {
"TOTAL_ORDER": "Tổng số đơn",
"CREATED_AT": "Ngày tạo"
}
}
}total là tổng khách khớp bộ lọc và khoảng ngày. Trong groups, key là id tag/tổ chức/phân khúc hoặc giá trị trường tuỳ chỉnh; name là tên tag/tổ chức/phân khúc, không có khi đếm theo trường tuỳ chỉnh. field_labels là nhãn tiếng Việt của các mã trường hệ thống.
Lưu ý
- Ví dụ đếm số khách có ít nhất một đơn: không truyền
group_by, conditions = [{ condition: { code: 'TOTAL_ORDER' }, operator: { code: 'GREATER_THAN' }, value: { value: 0 } }]. - Số đếm chỉ tính khách mà người cầm token được xem.
- Muốn xem danh sách khách thay vì con số, dùng
lw-filter-customers.
Xem chi tiết khách hàng Đọc
POST/2.0/api/lw-get-customer
Lấy hồ sơ đầy đủ của một khách hàng: thông tin cá nhân, liên hệ, địa chỉ, nguồn, trạng thái nhận tin, tag, người phụ trách, chỉ số đơn hàng và trường tuỳ chỉnh.
Tham số
| Tham số | Kiểu | Mô tả |
|---|---|---|
| store_id | string | Mã workspace lấy từ account-list-workspaces. Bắt buộc khi tài khoản có từ hai workspace trở lên. |
| customer_idbắt buộc | string | Id khách hàng (chuỗi 24 ký tự) lấy từ lw-search-customers hoặc lw-filter-customers. Nhận cả mã khách bên LadiSales. |
Ví dụ
curl -X POST https://api.ladipage.net/2.0/api/lw-get-customer \
-H "api-key: $LADIPAGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"store_id": "5f8a3c2e9b1d4a7e6c0f1234",
"customer_id": "64b7e2f1a9c3d5e7f8a1b2c3"
}'Kết quả
{
"code": 200,
"message": "Success",
"data": {
"id": "64b7e2f1a9c3d5e7f8a1b2c3",
"name": "Nguyễn Văn An",
"detail_url": "https://ladiwork.ladipage.com/customer/64b7e2f1a9c3d5e7f8a1b2c3",
"profile": {
"first_name": "An",
"last_name": "Nguyễn Văn",
"gender": "male",
"dob": "1990-05-12",
"language": "vi",
"score": 35,
"company": "Công ty TNHH Minh Phát",
"job_title": "Trưởng phòng Marketing",
"avatar": "https://w.ladicdn.com/avatar/an-nguyen.jpg"
},
"contact": {
"email": "an***@example.com",
"is_email_verified": true,
"phone": "******5678",
"phone_2": "******1234",
"phone_verified": true,
"zalo": "******5678",
"zalo_uid": "4823917560213847",
"skype": "an.nguyen",
"website": "https://minhphat.vn",
"facebook_url": "https://facebook.com/an.nguyen",
"twitter_url": "https://x.com/annguyen",
"linkedIn_url": "https://linkedin.com/in/an-nguyen"
},
"address": {
"address": "12 Nguyễn Trãi",
"address_2": "Tầng 5",
"ward": "Phường Bến Thành",
"district": "Quận 1",
"city": "Hồ Chí Minh",
"state": "Hồ Chí Minh",
"country": "Việt Nam",
"postal_code": "700000"
},
"source": {
"source": "landing_page",
"utm_source": "facebook",
"utm_medium": "cpc",
"utm_campaign": "khuyen-mai-thang-10",
"utm_term": "khoa-hoc-marketing",
"utm_content": "video-a",
"last_url": "https://minhphat.vn/khuyen-mai"
},
"status": {
"status": "SUBSCRIBER",
"email_subscribe_status": "SUBSCRIBED",
"subscribed_at": "2026-10-05T09:12:30+07:00",
"unsubscribed_at": null,
"is_verified": true,
"is_merge": false
},
"order_metrics": {
"total_order": 3,
"total_order_value": 4500000,
"avg_order_value": 1500000,
"total_paid_order": 2,
"total_paid_order_value": 3500000,
"total_pending_order": 1,
"total_cancel_order": 0
},
"channels": ["DASHBOARD", "EMAIL"],
"tags": ["Khách VIP", "Đã mua"],
"assignees": ["Lê Minh Hoàng"],
"followers": ["Phạm Thu Trang"],
"custom_fields": [
{
"label": "Nhu cầu",
"value": "Khoá học nâng cao"
},
{
"label": "Sản phẩm quan tâm",
"values": ["Gói Pro", "Gói Business"]
},
{
"label": "Thông tin xuất hoá đơn",
"value": {
"ma_so_thue": "0312345678",
"ten_cong_ty": "Công ty TNHH Minh Phát"
},
"key_labels": {
"ma_so_thue": "Mã số thuế",
"ten_cong_ty": "Tên công ty"
}
}
],
"created_at": "2026-10-05T09:12:30+07:00",
"updated_at": "2026-10-21T14:05:10+07:00",
"related_info": [
{
"tab": "Tổng quan",
"description": "Doanh thu, tương tác và hoạt động gần đây",
"tool": "get_customer_overview",
"args": {
"customer_id": "64b7e2f1a9c3d5e7f8a1b2c3"
}
},
{
"tab": "Ghi chú",
"description": "Ghi chú nội bộ về khách hàng",
"tool": "list_customer_notes",
"args": {
"customer_id": "64b7e2f1a9c3d5e7f8a1b2c3"
}
}
]
}
}tags là tên tag; assignees, followers là tên nhân viên. Trong custom_fields[], trường nhiều giá trị trả values thay cho value, trường lựa chọn trả nhãn, trường Đối tượng có thêm key_labels. related_info[] gợi ý các API xem thêm.
Lưu ý
related_info[].toollà tên không có tiền tố lw_; ghép thêm lw_ để gọi (vdget_customer_overview→lw-get-customer-overview).- Trường tuỳ chỉnh để trống không được trả về.
- Email và số điện thoại bị che một phần; trường tuỳ chỉnh có nhãn nhạy cảm (OTP, mật khẩu, CCCD, số thẻ...) trả [đã ẩn].
- Khách nằm ngoài phạm vi người cầm token được xem, hoặc khách tạo sau thời điểm workspace vượt hạn mức khách hàng của gói, đều trả lỗi không tìm thấy.
Xem tổng quan khách hàng Đọc
POST/2.0/api/lw-get-customer-overview
Lấy số liệu tổng quan của một khách hàng: doanh thu và số đơn, số lượt tham gia automation, kênh nhận tin, thiết bị và vài hoạt động gần nhất. Tương ứng tab Tổng quan trên trang khách hàng.
Tham số
| Tham số | Kiểu | Mô tả |
|---|---|---|
| store_id | string | Mã workspace lấy từ account-list-workspaces. Bắt buộc khi tài khoản có từ hai workspace trở lên. |
| customer_idbắt buộc | string | Id khách hàng (chuỗi 24 ký tự) lấy từ lw-search-customers hoặc lw-filter-customers. |
Ví dụ
curl -X POST https://api.ladipage.net/2.0/api/lw-get-customer-overview \
-H "api-key: $LADIPAGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"store_id": "5f8a3c2e9b1d4a7e6c0f1234",
"customer_id": "64b7e2f1a9c3d5e7f8a1b2c3"
}'Kết quả
{
"code": 200,
"message": "Success",
"data": {
"customer_id": "64b7e2f1a9c3d5e7f8a1b2c3",
"detail_url": "https://ladiwork.ladipage.com/customer/64b7e2f1a9c3d5e7f8a1b2c3",
"revenue": {
"total_order": 3,
"revenue": 4500000,
"avg_order_value": 1500000
},
"interactions": {
"flow": 2,
"campaign": 5,
"sequence": 1,
"total": 8
},
"top_channels": [
{
"channel": "EMAIL",
"total_send": 12,
"total_delivery": 12,
"total_read": 8,
"total_click": 3
},
{
"channel": "ZALO_ZNS",
"total_send": 4,
"total_delivery": 4,
"total_read": 3,
"total_click": 1
}
],
"devices": [
{
"device": "Mobile",
"total_read": 9,
"last_interaction": "2026-10-20T20:15:00+07:00"
},
{
"device": "Desktop",
"total_read": 2,
"last_interaction": "2026-10-14T10:02:00+07:00"
}
],
"recent_activity": [
{
"description": "Khách hàng mở email «Ưu đãi tháng 10»",
"created_at": "2026-10-20T20:15:00+07:00"
},
{
"description": "Khách hàng được thêm tag Khách VIP",
"created_at": "2026-10-18T09:30:00+07:00"
}
]
}
}avg_order_value = doanh thu / số đơn. interactions là số lượt tham gia từng loại. recent_activity[] gồm tối đa 8 mục mới nhất.
Lưu ý
- Khách ngoài phạm vi được xem thì API từ chối.
Liệt kê hoạt động của khách hàng Đọc
POST/2.0/api/lw-list-customer-activity
Lấy dòng thời gian hoạt động của một khách hàng (email, đơn hàng, form, Zalo, SMS, cuộc gọi...), mới nhất trước, có lọc theo khoảng ngày. Phân trang bằng scroll_id.
Tham số
| Tham số | Kiểu | Mô tả |
|---|---|---|
| store_id | string | Mã workspace lấy từ account-list-workspaces. Bắt buộc khi tài khoản có từ hai workspace trở lên. |
| customer_idbắt buộc | string | Id khách hàng (chuỗi 24 ký tự) lấy từ lw-search-customers hoặc lw-filter-customers. |
| from_date | string | Từ thời điểm (ISO 8601). Bỏ trống: từ đầu lịch sử. |
| to_date | string | Đến thời điểm (ISO 8601). Bỏ trống: đến hiện tại. |
| scroll_id | string | scroll_id của lần gọi trước để lấy trang tiếp theo. scroll_id chỉ còn hiệu lực khoảng 30 giây; khi đã truyền scroll_id thì from_date, to_date không còn tác dụng. |
Ví dụ
curl -X POST https://api.ladipage.net/2.0/api/lw-list-customer-activity \
-H "api-key: $LADIPAGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"store_id": "5f8a3c2e9b1d4a7e6c0f1234",
"customer_id": "64b7e2f1a9c3d5e7f8a1b2c3",
"from_date": "2026-10-01T00:00:00+07:00",
"to_date": "2026-10-29T23:59:59+07:00"
}'Kết quả
{
"code": 200,
"message": "Success",
"data": {
"customer_id": "64b7e2f1a9c3d5e7f8a1b2c3",
"scroll_id": "FGluY2x1ZGVfY29udGV4dF91dWlkDXF1ZXJ5QW5kRmV0Y2gBFkR3",
"count": 2,
"items": [
{
"_id": "6712a3b4c5d6e7f8a9b0c1d2",
"event": "EMAIL_OPEN",
"payload": "{\"campaign_name\":\"Ưu đãi tháng 10\"}",
"created_at": "2026-10-20T20:15:00+07:00"
},
{
"_id": "6712a3b4c5d6e7f8a9b0c1d3",
"event": "TAG_ADDED",
"payload": "{\"tag\":\"Khách VIP\"}",
"created_at": "2026-10-18T09:30:00+07:00"
}
]
}
}scroll_id là null khi hết dữ liệu. items là bản ghi hoạt động ở dạng gốc, mỗi lần tối đa 10 bản ghi; payload là chuỗi JSON.
Lưu ý
- Hiện API này đang lỗi phía máy chủ và luôn trả lỗi 400 «Lỗi khi thực thi». Không nên công bố cho tới khi được sửa (xem
open_questions). - Nhân viên vai trò Người xem (VIEWER) không được dùng API này.
Liệt kê cuộc gọi của khách hàng Đọc
POST/2.0/api/lw-list-customer-calls
Lấy lịch sử cuộc gọi tổng đài với một khách hàng: chiều gọi, trạng thái, thời lượng, ghi âm, nhân viên xử lý. Chỉ có dữ liệu khi workspace dùng tích hợp tổng đài.
Tham số
| Tham số | Kiểu | Mô tả |
|---|---|---|
| store_id | string | Mã workspace lấy từ account-list-workspaces. Bắt buộc khi tài khoản có từ hai workspace trở lên. |
| customer_idbắt buộc | string | Id khách hàng (chuỗi 24 ký tự) lấy từ lw-search-customers hoặc lw-filter-customers. |
| page | number | Số trang, bắt đầu từ 1.Mặc định: 1 |
| limit | number | Số cuộc gọi mỗi trang, tối đa 50.Mặc định: 20 |
Ví dụ
curl -X POST https://api.ladipage.net/2.0/api/lw-list-customer-calls \
-H "api-key: $LADIPAGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"store_id": "5f8a3c2e9b1d4a7e6c0f1234",
"customer_id": "64b7e2f1a9c3d5e7f8a1b2c3",
"page": 1,
"limit": 20
}'Kết quả
{
"code": 200,
"message": "Success",
"data": {
"customer_id": "64b7e2f1a9c3d5e7f8a1b2c3",
"total": 2,
"page": 1,
"limit": 20,
"items": [
{
"id": "6713b1c2d3e4f5a6b7c8d9e0",
"direction": "Gọi đi",
"status": "Hoàn thành",
"duration": 185,
"from_number": "02873001234",
"to_number": "0912345678",
"recording_url": "https://recording.example.com/calls/6713b1c2d3e4f5a6b7c8d9e0.mp3",
"handler": "Lê Minh Hoàng",
"created_at": "2026-10-21T10:05:00+07:00"
},
{
"id": "6713b1c2d3e4f5a6b7c8d9e1",
"direction": "Gọi đến",
"status": "Cuộc gọi nhỡ",
"duration": 0,
"from_number": "0912345678",
"to_number": "02873001234",
"recording_url": null,
"handler": "Phạm Thu Trang",
"created_at": "2026-10-19T17:42:00+07:00"
}
]
}
}items sắp mới nhất trước. direction: Gọi đến | Gọi đi. status: Nghe máy, Hoàn thành, Không nghe máy, Máy bận, Đã hủy, Từ chối, Thất bại, Cuộc gọi nhỡ, Đang đổ chuông, hoặc giá trị gốc. duration tính bằng giây; handler là tên nhân viên.
Lưu ý
- Cuộc gọi được ghép với khách theo id khách hoặc theo số điện thoại chính/phụ của khách (khớp số gọi đi hoặc gọi đến).
from_numbervàto_numbertrả đầy đủ, không bị che.
Liệt kê giao dịch của khách hàng Đọc
POST/2.0/api/lw-list-customer-deals
Lấy các giao dịch bán hàng gắn với một khách hàng, kèm tên Space, giai đoạn và link chi tiết. Chỉ gồm giao dịch thuộc Space loại bán hàng; công việc xem bằng lw-list-customer-tasks.
Tham số
| Tham số | Kiểu | Mô tả |
|---|---|---|
| store_id | string | Mã workspace lấy từ account-list-workspaces. Bắt buộc khi tài khoản có từ hai workspace trở lên. |
| customer_idbắt buộc | string | Id khách hàng (chuỗi 24 ký tự) lấy từ lw-search-customers hoặc lw-filter-customers. |
| page | number | Số trang, bắt đầu từ 1.Mặc định: 1 |
| limit | number | Số giao dịch mỗi trang, tối đa 50.Mặc định: 20 |
Ví dụ
curl -X POST https://api.ladipage.net/2.0/api/lw-list-customer-deals \
-H "api-key: $LADIPAGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"store_id": "5f8a3c2e9b1d4a7e6c0f1234",
"customer_id": "64b7e2f1a9c3d5e7f8a1b2c3"
}'Kết quả
{
"code": 200,
"message": "Success",
"data": {
"customer_id": "64b7e2f1a9c3d5e7f8a1b2c3",
"total": 1,
"page": 1,
"limit": 20,
"items": [
{
"id": "6714c2d3e4f5a6b7c8d9e0f1",
"title": "Gói LadiPage Business 1 năm",
"total_value": 12000000,
"status": "OPEN",
"pipeline": {
"name": "Ký mới",
"url": "https://ladiwork.ladipage.com/space/6714c2d3e4f5a6b7c8d9e0aa"
},
"stage": {
"name": "Đã gửi báo giá"
},
"created_at": "2026-10-10T11:00:00+07:00",
"updated_at": "2026-10-22T15:30:00+07:00",
"detail_url": "https://ladiwork.ladipage.com/deal/6714c2d3e4f5a6b7c8d9e0f1"
}
]
}
}items sắp mới cập nhật trước; pipeline.url là link của Space.
Lưu ý
- Chỉ trả giao dịch trong các Space mà người cầm token được xem; nhân viên phải đã được thêm vào LadiWork của workspace.
Lấy danh sách trường lọc khách hàng Đọc
POST/2.0/api/lw-list-customer-fields
Lấy bộ từ vựng để dựng điều kiện cho lw-filter-customers và lw-count-customers: trường hệ thống, trường tuỳ chỉnh của workspace, cùng danh sách tag, tổ chức, phân khúc kèm id.
Tham số
| Tham số | Kiểu | Mô tả |
|---|---|---|
| store_id | string | Mã workspace lấy từ account-list-workspaces. Bắt buộc khi tài khoản có từ hai workspace trở lên. |
Ví dụ
curl -X POST https://api.ladipage.net/2.0/api/lw-list-customer-fields \
-H "api-key: $LADIPAGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"store_id": "5f8a3c2e9b1d4a7e6c0f1234"
}'Kết quả
{
"code": 200,
"message": "Success",
"data": {
"system_fields": [
{
"code": "name",
"label": "Họ tên",
"type": "TEXT"
},
{
"code": "total_order",
"label": "Tổng số đơn",
"type": "NUMBER"
},
{
"code": "created_at",
"label": "Ngày tạo",
"type": "DATE"
},
{
"code": "gender",
"label": "Giới tính",
"type": "SELECT"
}
],
"custom_fields": [
{
"code": "TEXT",
"name": "nhu_cau",
"label": "Nhu cầu",
"data_type": "TEXT",
"type": "TEXT"
},
{
"code": "OBJECT",
"name": "thong_tin_hoa_don",
"label": "Thông tin xuất hoá đơn",
"data_type": "OBJECT",
"type": "OBJECT",
"keys": [
{
"path": "ma_so_thue",
"label": "Mã số thuế",
"type": "TEXT"
},
{
"path": "ten_cong_ty",
"label": "Tên công ty",
"type": "TEXT"
}
]
}
],
"tags": [
{
"id": "65a1c3e5f7b9d1e3a5c7e9f1",
"name": "Khách VIP"
}
],
"organizations": [
{
"id": "65a1c3e5f7b9d1e3a5c7eb10",
"name": "Công ty TNHH Minh Phát"
}
],
"segments": [
{
"id": "65a1c3e5f7b9d1e3a5c7ec20",
"name": "Khách mua trên 1 lần"
}
]
}
}type của system_fields[]: TEXT | NUMBER | DATE | SELECT; của custom_fields[]: TEXT | NUMBER | DATE | SELECT | OBJECT. Với trường tuỳ chỉnh, code bằng kiểu dữ liệu; keys[] chỉ có ở trường Đối tượng.
Lưu ý
- Toán tử hợp lệ suy ra từ type (không có trong kết quả): TEXT → EQUAL, NOT_EQUAL, CONTAINS, NOT_CONTAIN, BEGIN_WITH, HAS_ANY_VALUE, IS_UNKNOWN; NUMBER → EQUAL, NOT_EQUAL, GREATER_THAN, LESS_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN_OR_EQUAL, HAS_ANY_VALUE, IS_UNKNOWN; DATE → ON, BEFORE, AFTER, GREATER_THAN, LESS_THAN, HAS_ANY_VALUE, IS_UNKNOWN; SELECT → EQUAL, NOT_EQUAL, HAS_ANY_VALUE, IS_UNKNOWN. Chi tiết xem
lw-filter-customers. - Khi dựng điều kiện trường tuỳ chỉnh: condition.code =
custom_fields[].code, condition.name =custom_fields[].name.
Liệt kê tương tác automation của khách hàng Đọc
POST/2.0/api/lw-list-customer-interactions
Lấy các flow, campaign hoặc sequence mà khách hàng đã tham gia, kèm tên, link và số liệu gửi/nhận/đọc/click. Tương ứng tab Tương tác trên trang khách hàng.
Tham số
| Tham số | Kiểu | Mô tả |
|---|---|---|
| store_id | string | Mã workspace lấy từ account-list-workspaces. Bắt buộc khi tài khoản có từ hai workspace trở lên. |
| customer_idbắt buộc | string | Id khách hàng (chuỗi 24 ký tự) lấy từ lw-search-customers hoặc lw-filter-customers. |
| type | string | Loại tương tác. Giá trị khác ba giá trị này được hiểu là flow.Giá trị: flow, campaign, sequenceMặc định: flow |
| page | number | Số trang, bắt đầu từ 1.Mặc định: 1 |
| limit | number | Số mục mỗi trang, tối đa 50.Mặc định: 20 |
Ví dụ
curl -X POST https://api.ladipage.net/2.0/api/lw-list-customer-interactions \
-H "api-key: $LADIPAGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"store_id": "5f8a3c2e9b1d4a7e6c0f1234",
"customer_id": "64b7e2f1a9c3d5e7f8a1b2c3",
"type": "campaign",
"page": 1,
"limit": 20
}'Kết quả
{
"code": 200,
"message": "Success",
"data": {
"customer_id": "64b7e2f1a9c3d5e7f8a1b2c3",
"type": "campaign",
"page": 1,
"limit": 20,
"items": [
{
"name": "Ưu đãi tháng 10",
"type": "EMAIL",
"total_send": 2,
"total_delivery": 2,
"total_read": 1,
"total_click": 1,
"last_interaction": "2026-10-20T20:15:00+07:00",
"detail_url": "https://ladiwork.ladipage.com/campaign/6715d3e4f5a6b7c8d9e0f1a2"
},
{
"name": "Nhắc gia hạn gói",
"type": "ZALO_ZNS",
"total_send": 1,
"total_delivery": 1,
"total_read": 1,
"total_click": 0,
"last_interaction": "2026-10-15T09:00:00+07:00",
"detail_url": "https://ladiwork.ladipage.com/campaign/6715d3e4f5a6b7c8d9e0f1a3"
}
],
"total": 2,
"total_send": 3,
"total_delivery": 3,
"total_read": 2,
"total_click": 1
}
}Ví dụ trên ứng với type = campaign. Với type = flow, items gồm name, total_subscribe, last_interaction, detail_url, kèm total và total_send. Với type = sequence, items gồm name, type, last_interaction, status, detail_url, kèm total, total_sub và status_done.
Liệt kê ghi chú của khách hàng Đọc
POST/2.0/api/lw-list-customer-notes
Lấy các ghi chú nội bộ về một khách hàng, kèm người tạo, mới nhất trước.
Tham số
| Tham số | Kiểu | Mô tả |
|---|---|---|
| store_id | string | Mã workspace lấy từ account-list-workspaces. Bắt buộc khi tài khoản có từ hai workspace trở lên. |
| customer_idbắt buộc | string | Id khách hàng (chuỗi 24 ký tự) lấy từ lw-search-customers hoặc lw-filter-customers. |
| page | number | Số trang, bắt đầu từ 1.Mặc định: 1 |
| limit | number | Số ghi chú mỗi trang, tối đa 50.Mặc định: 20 |
Ví dụ
curl -X POST https://api.ladipage.net/2.0/api/lw-list-customer-notes \
-H "api-key: $LADIPAGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"store_id": "5f8a3c2e9b1d4a7e6c0f1234",
"customer_id": "64b7e2f1a9c3d5e7f8a1b2c3"
}'Kết quả
{
"code": 200,
"message": "Success",
"data": {
"customer_id": "64b7e2f1a9c3d5e7f8a1b2c3",
"total": 2,
"page": 1,
"limit": 20,
"items": [
{
"id": "6716e4f5a6b7c8d9e0f1a2b3",
"note": "Khách quan tâm gói Business, hẹn gọi lại thứ Hai.",
"creator": "Lê Minh Hoàng",
"created_at": "2026-10-22T16:20:00+07:00"
},
{
"id": "6716e4f5a6b7c8d9e0f1a2b4",
"note": "Đã gửi báo giá qua email.",
"creator": "Phạm Thu Trang",
"created_at": "2026-10-18T10:45:00+07:00"
}
]
}
}note là nội dung ghi chú; creator là tên người tạo.
Liệt kê đơn hàng automation của khách hàng Đọc
POST/2.0/api/lw-list-customer-orders
Lấy các đơn hàng ghi nhận qua automation (flow) của một khách hàng, kèm tổng giá trị. Đơn hàng LadiSales xem bằng lw-list-customer-sale-orders.
Tham số
| Tham số | Kiểu | Mô tả |
|---|---|---|
| store_id | string | Mã workspace lấy từ account-list-workspaces. Bắt buộc khi tài khoản có từ hai workspace trở lên. |
| customer_idbắt buộc | string | Id khách hàng (chuỗi 24 ký tự) lấy từ lw-search-customers hoặc lw-filter-customers. |
| page | number | Số trang, bắt đầu từ 1.Mặc định: 1 |
| limit | number | Số đơn mỗi trang, tối đa 50.Mặc định: 20 |
Ví dụ
curl -X POST https://api.ladipage.net/2.0/api/lw-list-customer-orders \
-H "api-key: $LADIPAGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"store_id": "5f8a3c2e9b1d4a7e6c0f1234",
"customer_id": "64b7e2f1a9c3d5e7f8a1b2c3"
}'Kết quả
{
"code": 200,
"message": "Success",
"data": {
"customer_id": "64b7e2f1a9c3d5e7f8a1b2c3",
"total": 2,
"total_order_value": 4500000,
"page": 1,
"limit": 20,
"items": [
{
"id": "6717f5a6b7c8d9e0f1a2b3c4",
"order_id": "100235",
"value": 3000000,
"status": "PAID",
"channel": "LADIPAGE",
"created_at": "2026-10-20T11:30:00+07:00"
},
{
"id": "6717f5a6b7c8d9e0f1a2b3c5",
"order_id": "100198",
"value": 1500000,
"status": "PENDING",
"channel": "LADIPAGE",
"created_at": "2026-10-08T14:10:00+07:00"
}
]
}
}total_order_value là tổng giá trị mọi đơn của khách, không chỉ trang hiện tại. items sắp mới nhất trước.
Liệt kê đơn hàng LadiSales của khách hàng Đọc
POST/2.0/api/lw-list-customer-sale-orders
Lấy các đơn hàng LadiSales của một khách hàng: mã đơn, tổng tiền, trạng thái đơn, thanh toán, giao hàng. Chỉ có dữ liệu khi khách đã liên kết với khách hàng bên LadiSales.
Tham số
| Tham số | Kiểu | Mô tả |
|---|---|---|
| store_id | string | Mã workspace lấy từ account-list-workspaces. Bắt buộc khi tài khoản có từ hai workspace trở lên. |
| customer_idbắt buộc | string | Id khách hàng (chuỗi 24 ký tự) lấy từ lw-search-customers hoặc lw-filter-customers. |
| page | number | Số trang, bắt đầu từ 1.Mặc định: 1 |
| limit | number | Số đơn mỗi trang, tối đa 50.Mặc định: 20 |
Ví dụ
curl -X POST https://api.ladipage.net/2.0/api/lw-list-customer-sale-orders \
-H "api-key: $LADIPAGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"store_id": "5f8a3c2e9b1d4a7e6c0f1234",
"customer_id": "64b7e2f1a9c3d5e7f8a1b2c3"
}'Kết quả
{
"code": 200,
"message": "Success",
"data": {
"customer_id": "64b7e2f1a9c3d5e7f8a1b2c3",
"total": 2,
"page": 1,
"limit": 20,
"items": [
{
"code": "LS-100235",
"total": 3000000,
"status": "Open",
"payment_status": "Success",
"shipping_status": "Delivered",
"created_at": "2026-10-20T11:30:00+07:00"
},
{
"code": "LS-100198",
"total": 1500000,
"status": "Open",
"payment_status": "Pending",
"shipping_status": "Pending",
"created_at": "2026-10-08T14:10:00+07:00"
}
]
}
}items sắp theo mã đơn giảm dần; code là mã tham chiếu hoặc số đơn. Khách chưa liên kết LadiSales: total = 0, items rỗng, kèm note giải thích.
Lưu ý
- Đơn hàng ghi nhận qua automation xem bằng
lw-list-customer-orders. - Không kết nối được LadiSales thì trả lỗi «Không lấy được đơn hàng LadiSales của khách hàng lúc này».
Liệt kê phân khúc khách hàng Đọc
POST/2.0/api/lw-list-customer-segments
Lấy danh sách nhóm khách hàng (phân khúc) của workspace kèm id, có lọc theo tên. Dùng để lấy tên cho tham số group của lw-search-customers hoặc id cho điều kiện SEGMENT.
Tham số
| Tham số | Kiểu | Mô tả |
|---|---|---|
| store_id | string | Mã workspace lấy từ account-list-workspaces. Bắt buộc khi tài khoản có từ hai workspace trở lên. |
| keyword | string | Lọc theo tên phân khúc (chứa chuỗi, không phân biệt hoa thường). |
| limit | number | Số kết quả tối đa, tối đa 300. Không có phân trang.Mặc định: 100 |
Ví dụ
curl -X POST https://api.ladipage.net/2.0/api/lw-list-customer-segments \
-H "api-key: $LADIPAGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"store_id": "5f8a3c2e9b1d4a7e6c0f1234",
"keyword": "Subscribers"
}'Kết quả
{
"code": 200,
"message": "Success",
"data": {
"total": 2,
"count": 2,
"items": [
{
"id": "65a1c3e5f7b9d1e3a5c7ec21",
"name": "Khách mới tháng 10"
},
{
"id": "65a1c3e5f7b9d1e3a5c7ec20",
"name": "Khách mua trên 1 lần"
}
]
}
}total là số phân khúc khớp keyword, count là số mục trả về; items sắp mới tạo trước.
Liệt kê tag khách hàng Đọc
POST/2.0/api/lw-list-customer-tags
Lấy danh sách tag khách hàng của workspace kèm id, có lọc theo tên. Dùng để lấy tên cho tham số tags của lw-search-customers hoặc id cho điều kiện TAG.
Tham số
| Tham số | Kiểu | Mô tả |
|---|---|---|
| store_id | string | Mã workspace lấy từ account-list-workspaces. Bắt buộc khi tài khoản có từ hai workspace trở lên. |
| keyword | string | Lọc theo tên tag (chứa chuỗi, không phân biệt hoa thường). |
| limit | number | Số kết quả tối đa, tối đa 300. Không có phân trang.Mặc định: 100 |
Ví dụ
curl -X POST https://api.ladipage.net/2.0/api/lw-list-customer-tags \
-H "api-key: $LADIPAGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"store_id": "5f8a3c2e9b1d4a7e6c0f1234",
"keyword": "VIP"
}'Kết quả
{
"code": 200,
"message": "Success",
"data": {
"total": 2,
"count": 2,
"items": [
{
"id": "65a1c3e5f7b9d1e3a5c7e9f1",
"name": "Khách VIP"
},
{
"id": "65a1c3e5f7b9d1e3a5c7ea02",
"name": "Lead mới"
}
]
}
}total là số tag khớp keyword, count là số mục trả về.
Liệt kê công việc của khách hàng Đọc
POST/2.0/api/lw-list-customer-tasks
Lấy các công việc gắn với một khách hàng, tức các thẻ thuộc Space loại công việc, kèm trạng thái, giai đoạn và link chi tiết. Giao dịch bán hàng xem bằng lw-list-customer-deals.
Tham số
| Tham số | Kiểu | Mô tả |
|---|---|---|
| store_id | string | Mã workspace lấy từ account-list-workspaces. Bắt buộc khi tài khoản có từ hai workspace trở lên. |
| customer_idbắt buộc | string | Id khách hàng (chuỗi 24 ký tự) lấy từ lw-search-customers hoặc lw-filter-customers. |
| page | number | Số trang, bắt đầu từ 1.Mặc định: 1 |
| limit | number | Số công việc mỗi trang, tối đa 50.Mặc định: 20 |
Ví dụ
curl -X POST https://api.ladipage.net/2.0/api/lw-list-customer-tasks \
-H "api-key: $LADIPAGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"store_id": "5f8a3c2e9b1d4a7e6c0f1234",
"customer_id": "64b7e2f1a9c3d5e7f8a1b2c3"
}'Kết quả
{
"code": 200,
"message": "Success",
"data": {
"customer_id": "64b7e2f1a9c3d5e7f8a1b2c3",
"total": 1,
"page": 1,
"limit": 20,
"items": [
{
"id": "6718a6b7c8d9e0f1a2b3c4d5",
"title": "Gọi tư vấn gói Business",
"status": "IN_PROGRESS",
"pipeline": {
"name": "Chăm sóc khách hàng",
"url": "https://ladiwork.ladipage.com/space/6718a6b7c8d9e0f1a2b3c4aa"
},
"stage": {
"name": "Đang xử lý"
},
"created_at": "2026-10-21T09:00:00+07:00",
"updated_at": "2026-10-23T14:30:00+07:00",
"detail_url": "https://ladiwork.ladipage.com/task/6718a6b7c8d9e0f1a2b3c4d5"
}
]
}
}items sắp mới cập nhật trước; pipeline.url là link của Space.
Lưu ý
- Chỉ trả công việc trong các Space mà người cầm token được xem; nhân viên phải đã được thêm vào LadiWork của workspace.
Liệt kê công ty/tổ chức Đọc
POST/2.0/api/lw-list-organizations
Lấy danh sách công ty/tổ chức của workspace kèm id, có lọc theo tên. Dùng để lấy tên cho tham số company của lw-search-customers, id cho điều kiện ORGANIZATION, hoặc để gán tổ chức khi tạo giao dịch.
Tham số
| Tham số | Kiểu | Mô tả |
|---|---|---|
| store_id | string | Mã workspace lấy từ account-list-workspaces. Bắt buộc khi tài khoản có từ hai workspace trở lên. |
| keyword | string | Lọc theo tên công ty (chứa chuỗi, không phân biệt hoa thường). |
| limit | number | Số kết quả tối đa, tối đa 200. Không có phân trang.Mặc định: 50 |
Ví dụ
curl -X POST https://api.ladipage.net/2.0/api/lw-list-organizations \
-H "api-key: $LADIPAGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"store_id": "5f8a3c2e9b1d4a7e6c0f1234",
"keyword": "Công ty ABC"
}'Kết quả
{
"code": 200,
"message": "Success",
"data": {
"total": 2,
"count": 2,
"items": [
{
"id": "65a1c3e5f7b9d1e3a5c7eb10",
"name": "Công ty TNHH Minh Phát"
},
{
"id": "65a1c3e5f7b9d1e3a5c7eb11",
"name": "Công ty CP Sao Việt"
}
]
}
}total là số tổ chức khớp keyword, count là số mục trả về.
Lưu ý
- Nhân viên phải đã được thêm vào LadiWork của workspace.
Xuất danh sách khách hàng ra Excel Đọc
POST/2.0/api/lw-export-customers
Xuất toàn bộ khách hàng khớp bộ lọc ra file Excel (.xlsx). Từ 10.000 khách trở xuống: trả link tải ngay. Trên 10.000 khách: xử lý nền và gửi link qua email chủ workspace.
Tham số
| Tham số | Kiểu | Mô tả |
|---|---|---|
| store_id | string | Mã workspace lấy từ account-list-workspaces. Bắt buộc khi tài khoản có từ hai workspace trở lên. |
| keyword | string | Có trong danh sách tham số nhưng hiện KHÔNG được áp dụng khi xuất; muốn giới hạn tập khách hãy dùng company, group, tags, filters. |
| company | string | Tên công ty/tổ chức, cách khớp như lw-search-customers. |
| group | string | Tên nhóm khách hàng (phân khúc), cách khớp như lw-search-customers. |
| tags | array<string> | Danh sách tên tag, cách khớp như lw-search-customers. |
| filters | array<object> | Điều kiện lọc trên từng trường, cùng cấu trúc và toán tử với filters của lw-search-customers. |
| filters[].fieldbắt buộc | string | Tên trường hệ thống (vd total_order, created_at) hoặc tên trường tuỳ chỉnh. Danh sách như lw-search-customers. |
| filters[].operator | string | Toán tử; bỏ trống dùng mặc định theo kiểu trường. Danh sách như lw-search-customers. |
| filters[].value | string | Giá trị so sánh; bắt buộc trừ khi toán tử là HAS_ANY_VALUE hoặc IS_UNKNOWN. |
| match | string | Cách nối các điều kiện.Giá trị: AND, ORMặc định: AND |
Ví dụ
curl -X POST https://api.ladipage.net/2.0/api/lw-export-customers \
-H "api-key: $LADIPAGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"store_id": "5f8a3c2e9b1d4a7e6c0f1234",
"tags": [
"VIP"
],
"filters": [
{
"field": "created_at",
"operator": "after",
"value": "2026-01-01"
}
],
"match": "AND"
}'Kết quả
{
"code": 200,
"message": "Success",
"data": {
"status": "success",
"delivery": "link",
"download_url": "https://export.ladipage.com/files/khach-hang-20261029.xlsx",
"file_name": "khach-hang-20261029.xlsx",
"expires_in": "10 ngày",
"applied_filters": 1,
"match": "AND",
"message": "Đã xuất 1.250 khách hàng."
}
}Ví dụ trên là tập nhỏ (status = success, delivery = link; download_url là link tải file .xlsx, hết hạn sau 10 ngày). Tập trên 10.000 khách: status = queued, delivery = email, chỉ gồm message, applied_filters, match. Gọi lại cùng bộ lọc trong 60 giây: trả lại kết quả trước kèm deduped = true.
Lưu ý
- File gồm các cột name,
first_name,last_name, email, phone, tags, dob, gender, country, city, district, ward, address,address_2, company,job_title, vouchers, language,created_at,updated_at,utm_content,utm_campaign,utm_medium,utm_source,utm_termvà mỗi trường tuỳ chỉnh một cột cf.<tên trường>. Khách sắp theo ngày cập nhật giảm dần. - Trong file, email và số điện thoại đầy đủ (không che), trừ khách tạo sau thời điểm workspace vượt hạn mức khách hàng của gói.
- Link tải hết hạn sau 10 ngày. Với tập trên 10.000 khách, email chứa link được gửi tới email chủ workspace, không phải người gọi API.
- Gói STARTER, GLOBAL_STARTER và tài khoản demo không xuất được. Nhân viên cần quyền xuất khách hàng.
- Không truyền bộ lọc nào nghĩa là xuất toàn bộ khách hàng của workspace.
Tạo khách hàng Tạo
POST/2.0/api/lw-create-customer
Tạo mới một khách hàng với email (bắt buộc), họ tên và số điện thoại. Không tạo nếu email đã tồn tại trong workspace.
Tham số
| Tham số | Kiểu | Mô tả |
|---|---|---|
| store_id | string | Mã workspace lấy từ account-list-workspaces. Bắt buộc khi tài khoản có từ hai workspace trở lên. |
| emailbắt buộc | string | Email khách hàng, phải đúng định dạng và chưa có trong workspace. |
| name | string | Họ và tên khách hàng; được lưu vào cả họ tên và tên (first_name). |
| phone | string | Số điện thoại. Nếu truyền thì phải có đúng 10 chữ số (ký tự không phải số được bỏ qua khi đếm), nên dạng +84 với 11 chữ số bị từ chối. |
| idempotency_key | string | Khoá chống tạo lặp do phía bạn sinh. Gửi lại cùng khoá trong 60 giây thì nhận lại kết quả lần đầu thay vì tạo mới. Không truyền: hệ thống dùng tổ hợp name + email + phone làm khoá. |
Ví dụ
curl -X POST https://api.ladipage.net/2.0/api/lw-create-customer \
-H "api-key: $LADIPAGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"store_id": "5f8a3c2e9b1d4a7e6c0f1234",
"email": "nguyen.van.a@example.com",
"name": "Nguyễn Văn A",
"phone": "0912345678",
"idempotency_key": "crm-sync-000123"
}'Kết quả
{
"code": 200,
"message": "Success",
"data": {
"status": "success",
"id": "671a9b8c7d6e5f4a3b2c1d0e",
"name": "Nguyễn Văn An",
"email": "an***@example.com",
"phone": "******5678",
"detail_url": "https://ladiwork.ladipage.com/customer/671a9b8c7d6e5f4a3b2c1d0e",
"message": "Tạo khách hàng thành công."
}
}id là id khách mới; email và số điện thoại bị che một phần. Khi trùng yêu cầu trong 60 giây: trả kết quả lần đầu kèm deduped = true.
Lưu ý
- Chống trùng theo email: đã có khách cùng email (so chữ thường) trong workspace thì lỗi «Email đã tồn tại trong hệ thống». Không kiểm trùng theo số điện thoại.
- Chỉ nhận name, email, phone. Không truyền được tag, tổ chức, địa chỉ hay trường tuỳ chỉnh.
- Khách mới có trạng thái người đăng ký (SUBSCRIBER), đồng ý nhận email, kênh DASHBOARD, chưa có người phụ trách hay người theo dõi.
- Workspace đã đạt số khách tối đa của gói thì lỗi.
- Một yêu cầu giống hệt đang được xử lý thì lỗi «Yêu cầu tạo khách hàng đang được xử lý», thử lại sau vài giây.
- Sau khi tạo, khách được đưa vào luồng xử lý trigger giống như khi tạo khách trên ứng dụng, nên các automation khởi chạy theo phân khúc khách hàng có thể chạy với khách này. Lịch sử thay đổi của khách ghi nguồn là API.
- Nhân viên cần quyền tạo khách hàng.