Giao dịch và công việc
Làm việc với các Space trên LadiWork: liệt kê và xem giao dịch, công việc, dòng thời gian, tài liệu, bình luận, ghi chú; tạo giao dịch, công việc, hạng mục, việc con và bình luận; xem đơn hàng LadiWork.
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-list-deals | Liệt kê giao dịch, công việc | Đọc |
lw-get-deal | Xem chi tiết giao dịch, công việc | Đọc |
lw-get-deal-timeline | Xem lịch sử chỉnh sửa giao dịch, công việc | Đọc |
lw-list-deal-attachments | Liệt kê tài liệu đính kèm | Đọc |
lw-list-deal-comments | Liệt kê bình luận | Đọc |
lw-list-deal-fields | Liệt kê trường lọc giao dịch, công việc | Đọc |
lw-list-deal-notes | Liệt kê ghi chú | Đọc |
lw-list-deal-tasks | Liệt kê việc con, hoạt động | Đọc |
lw-list-pipelines | Liệt kê Space và giai đoạn | Đọc |
lw-create-deal | Tạo giao dịch | Tạo |
lw-create-deal-comment | Viết bình luận | Tạo |
lw-create-deal-subtask | Tạo việc con | Tạo |
lw-create-deal-task-group | Tạo hạng mục việc con | Tạo |
lw-create-work-item | Tạo công việc | Tạo |
lw-list-orders | Liệt kê đơn hàng | Đọc |
lw-get-order | Xem chi tiết đơn hàng | Đọc |
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.
Liệt kê giao dịch, công việc Đọc
POST/2.0/api/lw-list-deals
Liệt kê giao dịch (Space Giao dịch) hoặc công việc (Space Công việc), lọc theo Space, giai đoạn, từ khoá và bộ lọc nâng cao giống chức năng Tạo bộ lọc trên LadiWork. Dùng để đồng bộ hoặc tìm thẻ trước khi xem chi tiết bằng lw-get-deal.
Tham số
| Tham số | Kiểu | Mô tả |
|---|---|---|
| store_id | string | ID workspace, lấy từ account-list-workspaces. Bắt buộc khi tài khoản có từ hai workspace trở lên; chỉ có một workspace thì bỏ qua được. |
| pipeline_id | string | ID Space (lw-list-pipelines → items[].id). Khi có, chỉ liệt kê trong Space này và loại Space (Giao dịch/Công việc) được tự xác định, không cần truyền type. |
| type | string | Dùng khi không truyền pipeline_id: SALES_PIPELINE = gộp mọi Space Giao dịch, WORK_PIPELINE = gộp mọi Space Công việc mà người gọi được xem. Bỏ trống cả pipeline_id và type = mọi Space.Giá trị: SALES_PIPELINE, WORK_PIPELINE |
| stage_id | string | ID giai đoạn (lw-list-pipelines → items[].stages[].id). |
| keyword | string | Tìm theo tên giao dịch/công việc, khớp một phần, không phân biệt hoa thường. |
| assigned_to_me | boolean | true = chỉ lấy giao dịch/công việc mà chính người sở hữu api-key đang phụ trách. Không cần truyền tên hay ID. |
| filters | array | Bộ lọc nâng cao, mỗi phần tử là một điều kiện. Bắt buộc có pipeline_id hoặc type để biết bộ trường. Lọc theo Giai đoạn hoặc trường tuỳ chỉnh bắt buộc có pipeline_id. Chỉ cần một điều kiện sai là cả yêu cầu lỗi, thông báo lỗi liệt kê giá trị hợp lệ. |
| filters[].fieldbắt buộc | string | Tên trường, không phân biệt hoa thường và dấu. Space Giao dịch: Tiêu đề giao dịch, Trạng thái giao dịch, Ngày dự kiến chốt, Thời gian thành công, Thời gian thất bại, Lý do thất bại, Ghi chú thất bại, Thời gian đóng, Thời gian tạo, Nhãn, Cờ bị đình trệ, Giai đoạn, Công ty, Người phụ trách. Space Công việc: Tên công việc, Trạng thái, Hạn xử lý, Thời gian thành công, Thời gian hoàn thành công việc, Thời gian đóng, Thời gian tạo, Nhãn, Giai đoạn, Công ty, Người phụ trách. Ngoài ra nhận tên hoặc nhãn trường tuỳ chỉnh của Space (lw-list-deal-fields → custom_fields[].name/label). |
| filters[].operator | string | Toán tử, nhận tên tiếng Việt, mã hoặc ký hiệu: Là (eq, =), Không là (neq, !=), Chứa (contains), Không chứa (notContains), Bắt đầu với (startWith), Không bắt đầu với (notStartWith), Lớn hơn (gt, >), Nhỏ hơn (lt, <), Lớn hơn hoặc bằng (gte, >=), Nhỏ hơn hoặc bằng (lte, <=), Là ngày (on), Không phải là ngày (notOn), Không có giá trị (isEmpty), Có giá trị bất kỳ (isNotEmpty). Toán tử hợp lệ theo trường: trường chữ (Tiêu đề/Tên công việc, Lý do thất bại, Ghi chú thất bại) = Là, Không là, Chứa, Không chứa, Bắt đầu với, Không bắt đầu với, Không có giá trị, Có giá trị bất kỳ (mặc định Chứa); Trạng thái = Là, Không là, Chứa, Không chứa (mặc định Là); trường ngày = chỉ Là ngày, Không phải là ngày (mặc định Là ngày); Nhãn, Cờ bị đình trệ, Giai đoạn, Công ty, Người phụ trách = Là, Không là, Không có giá trị, Có giá trị bất kỳ (mặc định Là); Thời gian hoàn thành công việc = Lớn hơn, Nhỏ hơn, Lớn hơn hoặc bằng, Nhỏ hơn hoặc bằng (mặc định Lớn hơn). Trường tuỳ chỉnh: xem operators trong lw-list-deal-fields. Bỏ trống = toán tử mặc định của trường. |
| filters[].value | string | Giá trị so sánh, bỏ trống khi dùng Không có giá trị/Có giá trị bất kỳ. Trạng thái: Đang mở, Thành công, Thua (hoặc OPEN, WON, LOST). Trường ngày: mốc có sẵn Hôm nay, Hôm qua, Tuần này, Tuần trước, Tháng này, Tháng trước, Quý này, Quý trước, Năm nay, Năm trước; hoặc một ngày yyyy-MM-dd; hoặc khoảng ngày yyyy-MM-dd,yyyy-MM-dd. Nhãn, Người phụ trách: tên, nhiều giá trị ngăn bằng dấu phẩy (Người phụ trách nhận cả email, hoặc một phần họ tên từ 2 ký tự). Giai đoạn, Công ty: tên đúng (không phân biệt dấu). Cờ bị đình trệ: Có/true = đang đình trệ, giá trị khác = không. Thời gian hoàn thành công việc: một số. Trường tuỳ chỉnh dạng chọn: nhãn hoặc giá trị lựa chọn; dạng có/không: Có/true. |
| filters[].unit | string | Chỉ dùng với Thời gian hoàn thành công việc: Phút, Giờ, Ngày, Tuần.Mặc định: Giờ |
| match | string | Cách nối các điều kiện trong filters: AND = thoả tất cả, OR = thoả ít nhất một.Giá trị: AND, ORMặc định: AND |
| page | number | Số trang, bắt đầu từ 1.Mặc định: 1 |
| limit | number | Số bản ghi mỗi trang, tối đa 50 (lớn hơn sẽ bị hạ về 50).Mặc định: 20 |
Ví dụ
curl -X POST https://api.ladipage.net/2.0/api/lw-list-deals \
-H "api-key: $LADIPAGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"store_id": "5f8c2a1b9d3e4f6a7b8c9d01",
"pipeline_id": "6650f1c2a9b3e4d5f6a7b8c9",
"filters": [
{
"field": "Trạng thái giao dịch",
"operator": "Là",
"value": "Đang mở"
},
{
"field": "Ngày dự kiến chốt",
"operator": "Là ngày",
"value": "2026-11-01,2026-11-30"
},
{
"field": "Người phụ trách",
"operator": "Là",
"value": "Nguyễn Văn An"
}
],
"match": "AND",
"page": 1,
"limit": 20
}'Kết quả
{
"code": 200,
"message": "Success",
"data": {
"total": 2,
"page": 1,
"limit": 20,
"scope": {
"pipeline_id": "6650f1c2a9b3e4d5f6a7b8c9",
"pipeline_name": "Bán hàng B2B",
"stage_id": null,
"stage_name": null,
"type": "SALES_PIPELINE",
"keyword": null,
"applied_filters": [
{
"field": "Trạng thái giao dịch",
"operator": "Là",
"value": "Đang mở"
},
{
"field": "Ngày dự kiến chốt",
"operator": "Là ngày",
"value": "2026-11-01,2026-11-30"
}
],
"match": "AND"
},
"items": [
{
"id": "66b2c3d4e5f6071829a3b4c5",
"code": "DEAL-1024",
"kind": "sale",
"title": "Gói Pro 12 tháng - Công ty An Phát",
"status": {
"code": "OPEN",
"name": "Đang mở"
},
"priority": {
"code": 3,
"name": "Cao"
},
"expected_close_date": "2026-11-30T17:00:00.000+07:00",
"pipeline": {
"name": "Bán hàng B2B",
"url": "https://work.ladipage.com/pipelines/6650f1c2a9b3e4d5f6a7b8c9"
},
"stage": {
"name": "Gửi báo giá"
},
"labels": [
{
"name": "Khách VIP",
"color": "#E5484D"
}
],
"customer": {
"name": "Nguyễn Văn An",
"email": "an***@example.com",
"phone": "0912***678",
"url": "https://work.ladipage.com/customers/6640a1b2c3d4e5f607182930"
},
"assignee": "Trần Thị Bình",
"followers": ["Lê Minh Châu"],
"detail_url": "https://work.ladipage.com/deals/66b2c3d4e5f6071829a3b4c5",
"total_value": 12000000,
"deal_probability": 60,
"weighted_value": 7200000
},
{
"id": "66b2c3d4e5f6071829a3b4d7",
"code": "DEAL-1019",
"kind": "sale",
"title": "Gói Business - Shop Mỹ phẩm Hoa Mai",
"status": {
"code": "LOST",
"name": "Thua"
},
"priority": {
"code": 2,
"name": "Trung bình"
},
"expected_close_date": "2026-11-30T17:00:00.000+07:00",
"pipeline": {
"name": "Bán hàng B2B",
"url": "https://work.ladipage.com/pipelines/6650f1c2a9b3e4d5f6a7b8c9"
},
"stage": {
"name": "Đàm phán"
},
"labels": [],
"customer": {
"name": "Hoàng Thị Mai",
"email": "ma***@gmail.com",
"phone": "0903***456",
"url": "https://work.ladipage.com/customers/6640a1b2c3d4e5f607182932"
},
"assignee": "Trần Thị Bình",
"followers": [],
"detail_url": "https://work.ladipage.com/deals/66b2c3d4e5f6071829a3b4d7",
"total_value": 5000000,
"deal_probability": 30,
"weighted_value": 1500000,
"lost_reason": "Giá cao hơn ngân sách",
"lost_comment": "Khách hẹn quay lại vào quý 1/2027",
"lost_time": "2026-10-27T15:20:00.000+07:00"
}
],
"store_context": {
"store_id": "5f8c2a1b9d3e4f6a7b8c9d01",
"store_name": "Công ty TNHH An Phát",
"you": "Trần Thị Bình"
}
}
}scope là phạm vi đang áp. code có dạng DEAL-<số> (Space Giao dịch) hoặc TASK-<số> (Space Công việc); kind là sale hoặc work. Chỉ Space Giao dịch có total_value, deal_probability, weighted_value; chỉ Space Công việc có start_date, processing_time; thẻ ở trạng thái Thua có thêm lost_reason, lost_comment, lost_time. store_context là workspace đang thao tác.
Lưu ý
- Sắp xếp theo thời gian cập nhật, mới nhất trước. Không trả thẻ đã xoá, kể cả thẻ đang nằm trong thùng rác.
- Phân trang bằng page/limit (tối đa 50 bản ghi/trang); dùng total để tính số trang.
- Dữ liệu theo quyền của người sở hữu api-key: chỉ các Space người đó được xem; trong Space Giao dịch không công khai, nhân viên có thể chỉ thấy giao dịch mình phụ trách.
pipeline_idngoài phạm vi quyền trả lỗi từ chối truy cập. - Email và số điện thoại khách hàng trong kết quả đã được che một phần (vd ma***@gmail.com, 0865***908).
- Ngày giờ trả về dạng ISO 8601 theo múi giờ của workspace (vd 2026-11-05T09:30:00.000+07:00).
- Trường hạn trong Space Giao dịch tên là Ngày dự kiến chốt, trong Space Công việc tên là Hạn xử lý; Lý do/Ghi chú/Thời gian thất bại và Cờ bị đình trệ chỉ có ở Space Giao dịch; Thời gian hoàn thành công việc chỉ có ở Space Công việc.
- Danh sách trường và toán tử hợp lệ của từng Space (kể cả trường tuỳ chỉnh) lấy bằng
lw-list-deal-fields.
Xem chi tiết giao dịch, công việc Đọc
POST/2.0/api/lw-get-deal
Lấy đầy đủ thông tin một giao dịch hoặc công việc theo ID: Space, giai đoạn, khách hàng, người phụ trách, nhãn, trường tuỳ chỉnh, tổng quan hoạt động và thẻ liên quan.
Tham số
| Tham số | Kiểu | Mô tả |
|---|---|---|
| store_id | string | ID workspace, lấy từ account-list-workspaces. Bắt buộc khi tài khoản có từ hai workspace trở lên. |
| deal_idbắt buộc | string | ID giao dịch/công việc (24 ký tự, từ lw-list-deals → items[].id) hoặc phần số của mã thẻ (vd 1024 với mã DEAL-1024 hoặc TASK-1024). |
Ví dụ
curl -X POST https://api.ladipage.net/2.0/api/lw-get-deal \
-H "api-key: $LADIPAGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"store_id": "5f8c2a1b9d3e4f6a7b8c9d01",
"deal_id": "66b2c3d4e5f6071829a3b4c5"
}'Kết quả
{
"code": 200,
"message": "Success",
"data": {
"id": "66b2c3d4e5f6071829a3b4c5",
"code": "DEAL-1024",
"kind": "sale",
"title": "Gói Pro 12 tháng - Công ty An Phát",
"status": {
"code": "OPEN",
"name": "Đang mở"
},
"priority": {
"code": 3,
"name": "Cao"
},
"expected_close_date": "2026-11-30T17:00:00.000+07:00",
"pipeline": {
"name": "Bán hàng B2B",
"url": "https://work.ladipage.com/pipelines/6650f1c2a9b3e4d5f6a7b8c9"
},
"stage": {
"name": "Gửi báo giá"
},
"labels": [
{
"name": "Khách VIP",
"color": "#E5484D"
}
],
"customer": {
"name": "Nguyễn Văn An",
"email": "an***@example.com",
"phone": "0912***678",
"url": "https://work.ladipage.com/customers/6640a1b2c3d4e5f607182930"
},
"assignee": "Trần Thị Bình",
"followers": ["Lê Minh Châu"],
"detail_url": "https://work.ladipage.com/deals/66b2c3d4e5f6071829a3b4c5",
"total_value": 12000000,
"deal_probability": 60,
"weighted_value": 7200000,
"description": "Khách cần 3 tài khoản, xuất hoá đơn VAT theo năm.",
"organization": {
"name": "Công ty TNHH An Phát"
},
"activity": {
"status": {
"code": "PLANNED",
"name": "Đã lên kế hoạch"
},
"last_activity_date": "2026-10-27T10:00:00.000+07:00",
"next_activity_date": "2026-10-30T09:30:00.000+07:00",
"next_activity_subject": "Gọi xác nhận báo giá",
"has_overdue": false,
"overdue_days": 0,
"undone_count": 2,
"done_count": 5
},
"created_at": "2026-10-15T09:12:00.000+07:00",
"updated_at": "2026-10-28T16:45:00.000+07:00",
"custom_fields": [
{
"name": "Nguồn khách",
"value": "Website"
},
{
"name": "Số tài khoản",
"value": 3
}
],
"related_deals": [
{
"title": "Gia hạn gói Pro 2025 - Công ty An Phát",
"url": "https://work.ladipage.com/deals/65a1b2c3d4e5f60718293a4b"
}
],
"related_info": [
{
"title": "Bình luận",
"api": "lw-list-deal-comments",
"params": {
"deal_id": "66b2c3d4e5f6071829a3b4c5"
}
},
{
"title": "Việc con, hoạt động",
"api": "lw-list-deal-tasks",
"params": {
"deal_id": "66b2c3d4e5f6071829a3b4c5"
}
}
],
"store_context": {
"store_id": "5f8c2a1b9d3e4f6a7b8c9d01",
"store_name": "Công ty TNHH An Phát",
"you": "Trần Thị Bình"
}
}
}Gồm mọi trường như một item của lw-list-deals, cộng thêm các trường chi tiết. custom_fields chỉ gồm trường có giá trị; related_info gợi ý các nhóm thông tin xem thêm kèm tham số gọi.
Lưu ý
- Thẻ nằm ngoài phạm vi quyền của người sở hữu api-key trả lỗi từ chối truy cập, không trả dữ liệu.
- Trả cả thẻ đang ở thùng rác (status.code = DELETED, nhãn Đã xóa).
- Trường tuỳ chỉnh dạng nhiều lựa chọn được gộp thành chuỗi ngăn bằng dấu phẩy.
- Email và số điện thoại khách hàng đã được che một phần.
- Xem thêm: việc con/hoạt động bằng
lw-list-deal-tasks, ghi chú bằnglw-list-deal-notes, bình luận bằnglw-list-deal-comments, tài liệu bằnglw-list-deal-attachments, lịch sử chỉnh sửa bằnglw-get-deal-timeline(đều nhận cùngdeal_id).
Xem lịch sử chỉnh sửa giao dịch, công việc Đọc
POST/2.0/api/lw-get-deal-timeline
Lấy lịch sử chỉnh sửa của một giao dịch/công việc (giống tab Lịch sử trên app): ai đổi trường nào, từ giá trị nào sang giá trị nào, lúc nào.
Tham số
| Tham số | Kiểu | Mô tả |
|---|---|---|
| store_id | string | ID workspace, lấy từ account-list-workspaces. Bắt buộc khi tài khoản có từ hai workspace trở lên. |
| deal_idbắt buộc | string | ID giao dịch/công việc (24 ký tự) hoặc phần số của mã thẻ (DEAL-<số>/TASK-<số>). |
| 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-get-deal-timeline \
-H "api-key: $LADIPAGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"store_id": "5f8c2a1b9d3e4f6a7b8c9d01",
"deal_id": "66b2c3d4e5f6071829a3b4c5",
"page": 1,
"limit": 20
}'Kết quả
{
"code": 200,
"message": "Success",
"data": {
"deal_id": "66b2c3d4e5f6071829a3b4c5",
"total": 2,
"page": 1,
"limit": 20,
"items": [
{
"field": "Giai đoạn",
"from": "Tiếp cận",
"to": "Gửi báo giá",
"by": "Trần Thị Bình",
"at": "2026-10-28T16:45:00.000+07:00"
},
{
"field": "Người phụ trách",
"from": null,
"to": "Trần Thị Bình",
"by": "Tự động",
"at": "2026-10-15T09:12:00.000+07:00"
}
],
"store_context": {
"store_id": "5f8c2a1b9d3e4f6a7b8c9d01",
"store_name": "Công ty TNHH An Phát",
"you": "Trần Thị Bình"
}
}
}deal_id là ID 24 ký tự. field là tên trường tiếng Việt (vd Giai đoạn, Người phụ trách, Trạng thái; trường tuỳ chỉnh dạng 'Trường tùy chỉnh: <tên>'). from, to là giá trị cũ/mới đã đổi sang tên, null nếu trống. by là tên người sửa, hoặc 'Tự động' với thay đổi do hệ thống.
Lưu ý
- Sắp xếp mới nhất trước. Gồm cả sự kiện tạo việc con, tải tài liệu, tạo ghi chú, tạo bình luận, gọi điện.
- Giá trị tham chiếu (giai đoạn, người, nhãn, khách hàng, công ty) chỉ hiện tên; không tra được tên thì để trống, không trả ID.
- Thẻ ngoài phạm vi quyền trả lỗi từ chối truy cập.
Liệt kê tài liệu đính kèm Đọc
POST/2.0/api/lw-list-deal-attachments
Liệt kê tệp đính kèm (tab Tài liệu) của một giao dịch/công việc, kèm link tải.
Tham số
| Tham số | Kiểu | Mô tả |
|---|---|---|
| store_id | string | ID workspace, lấy từ account-list-workspaces. Bắt buộc khi tài khoản có từ hai workspace trở lên. |
| deal_idbắt buộc | string | ID giao dịch/công việc, 24 ký tự (lw-list-deals → items[].id). Không nhận mã số DEAL-/TASK-. |
| page | number | Số trang, bắt đầu từ 1.Mặc định: 1 |
| limit | number | Số tệp 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-deal-attachments \
-H "api-key: $LADIPAGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"store_id": "5f8c2a1b9d3e4f6a7b8c9d01",
"deal_id": "66b2c3d4e5f6071829a3b4c5"
}'Kết quả
{
"code": 200,
"message": "Success",
"data": {
"deal_id": "66b2c3d4e5f6071829a3b4c5",
"total": 1,
"page": 1,
"limit": 20,
"items": [
{
"id": "66b5f6071829a3b4c5d6e7f8",
"name": "Bao-gia-An-Phat.pdf",
"url": "https://files.ladiwork.com/attachments/66b5f6071829a3b4c5d6e7f8/Bao-gia-An-Phat.pdf",
"file_type": "document",
"mime_type": "application/pdf",
"file_extension": "pdf",
"size": 245760,
"download_count": 3,
"description": "Báo giá gói Pro 12 tháng",
"by": "Trần Thị Bình",
"created_at": "2026-10-20T14:05:00.000+07:00"
}
],
"store_context": {
"store_id": "5f8c2a1b9d3e4f6a7b8c9d01",
"store_name": "Công ty TNHH An Phát",
"you": "Trần Thị Bình"
}
}
}url là link tải đầy đủ; by là tên người tải lên.
Lưu ý
- Sắp xếp mới tải lên trước.
- Thẻ ngoài phạm vi quyền trả lỗi từ chối truy cập.
Liệt kê bình luận Đọc
POST/2.0/api/lw-list-deal-comments
Liệt kê bình luận của một giao dịch/công việc, kèm tên người bình luận.
Tham số
| Tham số | Kiểu | Mô tả |
|---|---|---|
| store_id | string | ID workspace, lấy từ account-list-workspaces. Bắt buộc khi tài khoản có từ hai workspace trở lên. |
| deal_idbắt buộc | string | ID giao dịch/công việc, 24 ký tự (lw-list-deals → items[].id). Không nhận mã số DEAL-/TASK-. |
| page | number | Số trang, bắt đầu từ 1.Mặc định: 1 |
| limit | number | Số bình luậ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-deal-comments \
-H "api-key: $LADIPAGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"store_id": "5f8c2a1b9d3e4f6a7b8c9d01",
"deal_id": "66b2c3d4e5f6071829a3b4c5",
"limit": 50
}'Kết quả
{
"code": 200,
"message": "Success",
"data": {
"deal_id": "66b2c3d4e5f6071829a3b4c5",
"total": 2,
"page": 1,
"limit": 50,
"items": [
{
"id": "66b6071829a3b4c5d6e7f809",
"content": "Khách đã xác nhận báo giá, chuyển bộ phận kế toán xuất hoá đơn.",
"by": "Trần Thị Bình",
"is_reply": false,
"created_at": "2026-10-28T10:15:00.000+07:00"
},
{
"id": "66b6071829a3b4c5d6e7f80a",
"content": "@Trần Thị Bình đã nhận, chiều nay gửi hoá đơn.",
"by": "Lê Minh Châu",
"is_reply": true,
"created_at": "2026-10-28T11:02:00.000+07:00"
}
],
"store_context": {
"store_id": "5f8c2a1b9d3e4f6a7b8c9d01",
"store_name": "Công ty TNHH An Phát",
"you": "Trần Thị Bình"
}
}
}content là văn bản thuần, đã bỏ định dạng HTML (tên người được gắn thẻ vẫn giữ). by là tên người bình luận; is_reply = true nếu là trả lời một bình luận khác.
Lưu ý
- Sắp xếp mới nhất trước; bình luận và trả lời nằm chung một danh sách phẳng, phân biệt bằng
is_reply. - Thẻ ngoài phạm vi quyền trả lỗi từ chối truy cập.
Liệt kê trường lọc giao dịch, công việc Đọc
POST/2.0/api/lw-list-deal-fields
Trả danh sách Space, mỗi Space kèm các trường hệ thống và trường tuỳ chỉnh dùng được trong filters của lw-list-deals, cùng toán tử hợp lệ của từng trường. Gọi trước khi dựng bộ lọc nâng cao, đặc biệt khi lọc theo trường tuỳ chỉnh.
Tham số
| Tham số | Kiểu | Mô tả |
|---|---|---|
| store_id | string | ID workspace, lấy từ account-list-workspaces. Bắt buộc khi tài khoản có từ hai workspace trở lên. |
| pipeline | string | Tên (khớp đúng, không phân biệt hoa thường và dấu) hoặc ID của một Space để chỉ lấy Space đó. Bỏ trống = mọi Space. |
| type | string | Chỉ lấy Space Giao dịch (SALES_PIPELINE) hoặc Space Công việc (WORK_PIPELINE). Bỏ trống = cả hai.Giá trị: SALES_PIPELINE, WORK_PIPELINE |
Ví dụ
curl -X POST https://api.ladipage.net/2.0/api/lw-list-deal-fields \
-H "api-key: $LADIPAGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"store_id": "5f8c2a1b9d3e4f6a7b8c9d01",
"type": "SALES_PIPELINE"
}'Kết quả
{
"code": 200,
"message": "Success",
"data": {
"total_pipelines": 1,
"items": [
{
"pipeline": {
"id": "6650f1c2a9b3e4d5f6a7b8c9",
"name": "Bán hàng B2B",
"kind": "sale"
},
"system_fields": [
{
"label": "Tiêu đề giao dịch",
"operators": [
"eq",
"neq",
"contains",
"notContains",
"startWith",
"notStartWith",
"isEmpty",
"isNotEmpty"
]
},
{
"label": "Ngày dự kiến chốt",
"operators": ["on", "notOn"]
}
],
"custom_fields": [
{
"name": "nguon_khach",
"label": "Nguồn khách",
"type": "DROPDOWN",
"operators": ["eq", "neq", "isEmpty", "isNotEmpty"]
},
{
"name": "so_tai_khoan",
"label": "Số tài khoản",
"type": "NUMBER",
"operators": [
"eq",
"neq",
"gt",
"lt",
"gte",
"lte",
"isEmpty",
"isNotEmpty"
]
}
]
}
],
"store_context": {
"store_id": "5f8c2a1b9d3e4f6a7b8c9d01",
"store_name": "Công ty TNHH An Phát",
"you": "Trần Thị Bình"
}
}
}kind là sale hoặc work. system_fields là trường hệ thống theo loại Space. type của trường tuỳ chỉnh: TEXT, NUMBER, DATE, DROPDOWN, CHECK_BOX, LIST, BOOLEAN. operators là mã toán tử: eq, neq, contains, notContains, startWith, notStartWith, gt, lt, gte, lte, on, notOn, isEmpty, isNotEmpty.
Lưu ý
- Trường tuỳ chỉnh gắn theo từng Space, nên khi lọc theo trường tuỳ chỉnh phải gọi
lw-list-dealskèmpipeline_idcủa đúng Space đó. - Mã toán tử truyền thẳng được vào filters[].operator của
lw-list-deals. Trường ngày chỉ có on/notOn (đúng ngày/khoảng ngày hay không), không có trước/sau. - Space sắp xếp mới tạo trước. Không phân trang.
Liệt kê ghi chú Đọc
POST/2.0/api/lw-list-deal-notes
Liệt kê ghi chú của một giao dịch/công việc, kèm người tạo và trạng thái ghim.
Tham số
| Tham số | Kiểu | Mô tả |
|---|---|---|
| store_id | string | ID workspace, lấy từ account-list-workspaces. Bắt buộc khi tài khoản có từ hai workspace trở lên. |
| deal_idbắt buộc | string | ID giao dịch/công việc, 24 ký tự (lw-list-deals → items[].id). Không nhận mã số DEAL-/TASK-. |
| 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-deal-notes \
-H "api-key: $LADIPAGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"store_id": "5f8c2a1b9d3e4f6a7b8c9d01",
"deal_id": "66b2c3d4e5f6071829a3b4c5"
}'Kết quả
{
"code": 200,
"message": "Success",
"data": {
"deal_id": "66b2c3d4e5f6071829a3b4c5",
"total": 1,
"page": 1,
"limit": 20,
"items": [
{
"id": "66b71829a3b4c5d6e7f8091a",
"content": "Khách ưu tiên thanh toán chuyển khoản trước ngày 30/11.",
"by": "Trần Thị Bình",
"pinned": true,
"attachment_count": 1,
"created_at": "2026-10-22T09:40:00.000+07:00"
}
],
"store_context": {
"store_id": "5f8c2a1b9d3e4f6a7b8c9d01",
"store_name": "Công ty TNHH An Phát",
"you": "Trần Thị Bình"
}
}
}content là văn bản thuần, đã bỏ định dạng HTML. by là tên người tạo; attachment_count là số tệp đính kèm trong ghi chú.
Lưu ý
- Ghi chú được ghim đứng đầu, sau đó mới nhất trước.
- Thẻ ngoài phạm vi quyền trả lỗi từ chối truy cập.
Liệt kê việc con, hoạt động Đọc
POST/2.0/api/lw-list-deal-tasks
Liệt kê hoạt động (của giao dịch) hoặc việc con (của công việc), lọc theo thẻ, Space, trạng thái, ưu tiên, thời hạn, người được giao, khách hàng, từ khoá. Dùng cho danh sách việc cần làm hoặc báo cáo tiến độ.
Tham số
| Tham số | Kiểu | Mô tả |
|---|---|---|
| store_id | string | ID workspace, lấy từ account-list-workspaces. Bắt buộc khi tài khoản có từ hai workspace trở lên. |
| deal_id | string | Chỉ lấy việc con của một giao dịch/công việc (ID 24 ký tự). |
| pipeline_id | string | Chỉ lấy việc con trong một Space (lw-list-pipelines → items[].id). Không truyền deal_id lẫn pipeline_id = mọi Space người gọi được xem. |
| status | string | Hoàn thành hoặc Chưa hoàn thành (cũng nhận done/completed, not_done/open). Giá trị khác trả lỗi. |
| priority | string | Cao, Trung bình hoặc Thấp (cũng nhận HIGH, MEDIUM, LOW). |
| deadline | string | Lọc theo thời điểm kết thúc: Quá hạn (đã qua hôm nay và chưa hoàn thành), Hôm nay, Tuần này (thứ Hai đến Chủ nhật), Sau đó (từ tuần sau), Chưa lên kế hoạch (không có thời điểm kết thúc). Mốc ngày tính theo giờ Việt Nam (UTC+7). |
| assignee | string | Tên, email hoặc một phần họ tên (từ 2 ký tự) của nhân viên được giao. Không tìm thấy nhân viên thì trả lỗi. |
| customer_id | string | Chỉ lấy việc con gắn với khách hàng này. |
| assigned_to_me | boolean | true = chỉ lấy việc giao cho chính người sở hữu api-key. |
| keyword | string | Tìm theo tên việc con/hoạt động, khớp một phần, không phân biệt hoa thường. |
| page | number | Số trang, bắt đầu từ 1.Mặc định: 1 |
| limit | number | Số bản ghi mỗi trang, tối đa 100.Mặc định: 50 |
Ví dụ
curl -X POST https://api.ladipage.net/2.0/api/lw-list-deal-tasks \
-H "api-key: $LADIPAGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"store_id": "5f8c2a1b9d3e4f6a7b8c9d01",
"pipeline_id": "6651a2b3c4d5e6f708192a3b",
"deadline": "Quá hạn",
"assigned_to_me": true
}'Kết quả
{
"code": 200,
"message": "Success",
"data": {
"total": 1,
"page": 1,
"limit": 50,
"filters": {
"pipeline_id": "6651a2b3c4d5e6f708192a3b",
"deadline": "Quá hạn",
"assigned_to_me": true
},
"items": [
{
"id": "66b829a3b4c5d6e7f8091a2b",
"name": "Gửi bản phác thảo banner",
"done": false,
"status": {
"code": "WORKING",
"name": "Chưa hoàn thành"
},
"priority": {
"code": "HIGH",
"name": "Cao"
},
"start_time": "2026-10-24T08:00:00.000+07:00",
"end_time": "2026-10-27T17:00:00.000+07:00",
"group": "Thiết kế",
"assignees": ["Lê Minh Châu"],
"created_at": "2026-10-23T15:30:00.000+07:00",
"deal": {
"title": "Thiết kế banner chiến dịch Black Friday",
"url": "https://work.ladipage.com/deals/66b3d4e5f6071829a3b4c5d6"
},
"customer": {
"name": "Phạm Thu Hà",
"url": "https://work.ladipage.com/customers/6640a1b2c3d4e5f607182931"
}
}
],
"store_context": {
"store_id": "5f8c2a1b9d3e4f6a7b8c9d01",
"store_name": "Công ty TNHH An Phát",
"you": "Trần Thị Bình"
}
}
}filters là bộ lọc đã nhận. status.code là DONE hoặc WORKING; priority.code là HIGH, MEDIUM hoặc LOW, priority = null khi chưa đặt. group là tên hạng mục; assignees là tên người được giao.
Lưu ý
- Sắp xếp theo thứ tự trong thẻ, rồi theo thời gian tạo cũ trước.
- Phân trang bằng page/limit (tối đa 100 bản ghi/trang).
- Quyền: lọc theo
deal_idthì thẻ đó phải xem được; lọc theopipeline_idthì Space đó phải xem được; không lọc thì giới hạn trong các Space người gọi được xem. - Nên giới hạn theo
deal_idhoặcpipeline_id; bỏ cả hai sẽ quét toàn bộ việc con của workspace.
Liệt kê Space và giai đoạn Đọc
POST/2.0/api/lw-list-pipelines
Liệt kê các Space (Giao dịch và Công việc) người gọi được xem, kèm danh sách giai đoạn. Dùng để lấy pipeline_id và stage_id trước khi lọc hoặc tạo giao dịch/công việc.
Tham số
| Tham số | Kiểu | Mô tả |
|---|---|---|
| store_id | string | ID workspace, lấy từ account-list-workspaces. Bắt buộc khi tài khoản có từ hai workspace trở lên. |
| type | string | SALES_PIPELINE = chỉ Space Giao dịch, WORK_PIPELINE = chỉ Space Công việc. Bỏ trống = tất cả.Giá trị: SALES_PIPELINE, WORK_PIPELINE |
Ví dụ
curl -X POST https://api.ladipage.net/2.0/api/lw-list-pipelines \
-H "api-key: $LADIPAGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"store_id": "5f8c2a1b9d3e4f6a7b8c9d01",
"type": "WORK_PIPELINE"
}'Kết quả
{
"code": 200,
"message": "Success",
"data": {
"total": 1,
"items": [
{
"id": "6651a2b3c4d5e6f708192a3b",
"name": "Marketing",
"type": "WORK_PIPELINE",
"kind": "work",
"url": "https://work.ladipage.com/pipelines/6651a2b3c4d5e6f708192a3b",
"stages": [
{
"id": "6651a2b3c4d5e6f708192a3f",
"name": "Cần làm",
"order_number": 1
},
{
"id": "6651a2b3c4d5e6f708192a40",
"name": "Đang thực hiện",
"order_number": 2
},
{
"id": "6651a2b3c4d5e6f708192a41",
"name": "Hoàn thành",
"order_number": 3
}
]
}
],
"store_context": {
"store_id": "5f8c2a1b9d3e4f6a7b8c9d01",
"store_name": "Công ty TNHH An Phát",
"you": "Trần Thị Bình"
}
}
}id là pipeline_id, stages[].id là stage_id. type là SALES_PIPELINE hoặc WORK_PIPELINE, kind là sale hoặc work; url là link bảng trên app. stages xếp theo thứ tự cột.
Lưu ý
- Chủ workspace và quản lý thấy mọi Space; thành viên chỉ thấy Space mình tạo, Space mình là thành viên và Space công khai.
- Space sắp xếp mới tạo trước. Không phân trang.
Tạo giao dịch Tạo
POST/2.0/api/lw-create-deal
Tạo một giao dịch mới trong một Space Giao dịch, tại giai đoạn chỉ định. Dùng khi đẩy cơ hội bán hàng từ hệ thống khác vào LadiWork.
Tham số
| Tham số | Kiểu | Mô tả |
|---|---|---|
| store_id | string | ID workspace, lấy từ account-list-workspaces. Bắt buộc khi tài khoản có từ hai workspace trở lên. |
| titlebắt buộc | string | Tên giao dịch. |
| pipeline_idbắt buộc | string | ID Space Giao dịch (lw-list-pipelines với type=SALES_PIPELINE). Truyền ID Space Công việc sẽ bị từ chối, dùng lw-create-work-item. |
| stage_idbắt buộc | string | ID giai đoạn thuộc đúng Space trên (items[].stages[].id). Thiếu stage_id thì API không tạo mà trả danh sách giai đoạn để chọn (status = need_stage). |
| total_value | number | Giá trị giao dịch.Mặc định: 0 |
| customer_id | string | ID khách hàng có sẵn (từ lw-search-customers, lw-get-customer). |
| customer_email | string | Email khách hàng có sẵn, dùng khi không có customer_id. Không tìm thấy khách hàng thì báo lỗi, API không tự tạo khách hàng mới (tạo trước bằng lw-create-customer). |
| deal_probability | number | Xác suất thành công, 0–100. |
| expected_close_date | string | Ngày dự kiến chốt, ISO 8601. Nên kèm múi giờ (vd 2026-11-30T17:00:00+07:00). |
| priority | number | Ưu tiên: 1 = Thấp, 2 = Trung bình, 3 = Cao.Giá trị: 1, 2, 3 |
| labels | array | Mảng ID nhãn giao dịch (chuỗi). |
| sub_owner_id | string | ID tài khoản (24 ký tự) của nhân viên phụ trách. Bỏ trống thì hệ thống áp quy tắc phân bổ tự động của Space; Space không có quy tắc thì người sở hữu api-key là người phụ trách. |
| organization_id | string | ID công ty (từ lw-list-organizations). |
| description | string | Mô tả giao dịch. |
| idempotency_key | string | Khoá chống tạo trùng do bên gọi tự đặt (vd mã đơn ở hệ thống của bạn). Có hiệu lực 60 giây. |
Ví dụ
curl -X POST https://api.ladipage.net/2.0/api/lw-create-deal \
-H "api-key: $LADIPAGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"store_id": "5f8c2a1b9d3e4f6a7b8c9d01",
"title": "Gói Pro 12 tháng - Công ty An Phát",
"pipeline_id": "6650f1c2a9b3e4d5f6a7b8c9",
"stage_id": "6650f1c2a9b3e4d5f6a7b8d4",
"total_value": 12000000,
"customer_email": "lienhe@anphat.vn",
"priority": 3,
"idempotency_key": "crm-order-58213"
}'Kết quả
{
"code": 200,
"message": "Success",
"data": {
"status": "success",
"message": "Đã tạo giao dịch DEAL-1031",
"id": "66bb2c3d4e5f6071829a3b4c",
"code": "DEAL-1031",
"kind": "sale",
"title": "Gói Pro 12 tháng - Công ty An Phát",
"priority": {
"code": 3,
"name": "Cao"
},
"expected_close_date": "2026-11-30T17:00:00.000+07:00",
"pipeline": {
"name": "Bán hàng B2B",
"url": "https://work.ladipage.com/pipelines/6650f1c2a9b3e4d5f6a7b8c9"
},
"stage": {
"name": "Gửi báo giá"
},
"labels": [],
"customer": {
"name": "Công ty TNHH An Phát",
"email": "li***@anphat.vn",
"phone": "0283***789",
"url": "https://work.ladipage.com/customers/6640a1b2c3d4e5f607182933"
},
"assignee": "Trần Thị Bình",
"followers": [],
"detail_url": "https://work.ladipage.com/deals/66bb2c3d4e5f6071829a3b4c",
"total_value": 12000000,
"deal_probability": 0,
"weighted_value": 0,
"store_context": {
"store_id": "5f8c2a1b9d3e4f6a7b8c9d01",
"store_name": "Công ty TNHH An Phát",
"you": "Trần Thị Bình"
}
}
}Các trường còn lại là thông tin giao dịch vừa tạo, có dạng như một item của lw-list-deals với kind = sale; status ở đây là kết quả gọi (success), giao dịch mới luôn ở trạng thái Đang mở. Thiếu stage_id: status = need_stage, kèm pipeline (tên Space) và stages [{id, name, order_number}]. Yêu cầu trùng trong 60 giây: trả lại kết quả lần trước kèm deduped = true.
Lưu ý
- Tạo ngay khi gọi, không có bước xác nhận. Trạng thái giao dịch mới luôn là Đang mở; người tạo là người sở hữu api-key.
- Tác dụng phụ giống tạo trên app: gửi thông báo giao việc cho người phụ trách (và trưởng nhóm/quản lý nếu cấu hình), phát sự kiện Giao dịch được tạo cho kịch bản tự động (Automation) và webhook của workspace, ghi lịch sử thẻ, áp quy tắc phân bổ và quy tắc đình trệ của Space.
- Chống trùng: cùng
idempotency_key, hoặc khi không có khoá thì cùng title +pipeline_id+stage_id+ khách hàng, trong vòng 60 giây sẽ trả lại kết quả lần trước (deduped = true) thay vì tạo mới. Hai yêu cầu giống hệt gửi đồng thời: yêu cầu sau báo lỗi đang được xử lý. - Giới hạn: tổng số giao dịch và công việc của workspace không vượt hạn mức gói; quá hạn mức trả lỗi.
- Quyền: vai trò phải có quyền tạo giao dịch và người gọi phải xem được Space; Space có quy tắc theo giai đoạn có thể chặn tạo thẻ ở một số giai đoạn.
- Nếu workspace bật quy tắc gán khách hàng và khách đã có người phụ trách, chỉ người đó (hoặc chủ/quản lý/người có quyền gán) tạo được giao dịch cho khách này.
- Khác
lw-create-work-item: chỉ nhận Space Giao dịch, cótotal_value,deal_probability,customer_email,organization_id; không nhậnstart_date,processing_time,custom_fields.
Viết bình luận Tạo
POST/2.0/api/lw-create-deal-comment
Viết một bình luận mới vào giao dịch/công việc, vd báo kết quả xử lý hoặc ghi lý do duyệt/trả lại.
Tham số
| Tham số | Kiểu | Mô tả |
|---|---|---|
| store_id | string | ID workspace, lấy từ account-list-workspaces. Bắt buộc khi tài khoản có từ hai workspace trở lên. |
| deal_idbắt buộc | string | ID giao dịch/công việc, 24 ký tự (lw-list-deals → items[].id). |
| messagebắt buộc | string | Nội dung bình luận, tối đa 10.000 ký tự. Văn bản thuần hoặc HTML; nội dung được lưu nguyên văn và hiển thị dạng văn bản có định dạng trên app. |
| idempotency_key | string | Khoá chống tạo trùng do bên gọi tự đặt. Có hiệu lực 60 giây. |
Ví dụ
curl -X POST https://api.ladipage.net/2.0/api/lw-create-deal-comment \
-H "api-key: $LADIPAGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"store_id": "5f8c2a1b9d3e4f6a7b8c9d01",
"deal_id": "66b2c3d4e5f6071829a3b4c5",
"message": "Khách đã xác nhận báo giá, chuyển bộ phận kế toán xuất hoá đơn."
}'Kết quả
{
"code": 200,
"message": "Success",
"data": {
"status": "success",
"message": "Đã thêm bình luận",
"deal": "Gói Pro 12 tháng - Công ty An Phát",
"store_context": {
"store_id": "5f8c2a1b9d3e4f6a7b8c9d01",
"store_name": "Công ty TNHH An Phát",
"you": "Trần Thị Bình"
}
}
}deal là tên thẻ. Không trả ID bình luận; muốn lấy thì gọi lw-list-deal-comments. Yêu cầu trùng trong 60 giây: trả lại kết quả lần trước kèm deduped = true.
Lưu ý
- Tạo ngay khi gọi. Người bình luận là người sở hữu api-key. Chỉ tạo bình luận gốc, không trả lời một bình luận có sẵn.
- Tác dụng phụ: gửi thông báo bình luận mới cho những người liên quan đến thẻ, phát sự kiện bình luận mới cho kịch bản tự động (Automation) và webhook, đánh dấu chưa đọc cho thành viên, ghi lịch sử thẻ.
- Gắn thẻ (mention) nhân viên: hệ thống chỉ nhận dạng thẻ HTML <span class='comment-mention-tag' comment-staff-id='ID tài khoản nhân viên'>@Tên</span>, người được gắn thẻ sẽ nhận thông báo. Hiện chưa có API công khai nào trả ID tài khoản nhân viên. Viết @Tên dạng chữ thường không gửi thông báo.
- Chống trùng: cùng
deal_id+ message (hoặc cùngidempotency_key) trong 60 giây trả lại kết quả lần trước, không tạo bình luận thứ hai. - Quyền: vai trò phải có quyền tạo bình luận và xem được thẻ; Space có quy tắc theo giai đoạn có thể chặn bình luận ở một số giai đoạn.
Tạo việc con Tạo
POST/2.0/api/lw-create-deal-subtask
Tạo một việc con (hoạt động) gắn vào giao dịch/công việc, có thể đặt vào một hạng mục. Dùng để giao việc cụ thể trong một thẻ.
Tham số
| Tham số | Kiểu | Mô tả |
|---|---|---|
| store_id | string | ID workspace, lấy từ account-list-workspaces. Bắt buộc khi tài khoản có từ hai workspace trở lên. |
| namebắt buộc | string | Tên việc con. |
| deal_idbắt buộc | string | ID giao dịch/công việc chứa việc con, 24 ký tự (lw-list-deals → items[].id). |
| description | string | Mô tả việc con. |
| start_time | string | Thời điểm bắt đầu, ISO 8601, nên kèm múi giờ. |
| end_time | string | Thời điểm kết thúc (hạn), ISO 8601, nên kèm múi giờ. Dùng cho bộ lọc deadline của lw-list-deal-tasks. |
| priority | string | Ưu tiên: HIGH, MEDIUM hoặc LOW (viết hoa). Giá trị được lưu nguyên văn; viết khác sẽ không lọc và không hiển thị đúng nhãn ưu tiên. |
| scope_users | array | Mảng ID tài khoản (24 ký tự) của nhân viên được giao. Phần tử không đúng định dạng bị bỏ qua. Bỏ trống = việc con không có người được giao. |
| done | boolean | true = tạo ở trạng thái đã hoàn thành.Mặc định: false |
| deal_task_group_id | string | ID hạng mục (từ lw-create-deal-task-group → deal_task_group_id) để đặt việc con vào hạng mục đó. Không bắt buộc; bỏ trống thì việc con nằm ngoài hạng mục. |
| idempotency_key | string | Khoá chống tạo trùng do bên gọi tự đặt. Có hiệu lực 60 giây. |
Ví dụ
curl -X POST https://api.ladipage.net/2.0/api/lw-create-deal-subtask \
-H "api-key: $LADIPAGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"store_id": "5f8c2a1b9d3e4f6a7b8c9d01",
"deal_id": "66b2c3d4e5f6071829a3b4c5",
"name": "Gửi hợp đồng bản ký",
"end_time": "2026-11-05T17:00:00+07:00",
"priority": "HIGH"
}'Kết quả
{
"code": 200,
"message": "Success",
"data": {
"status": "success",
"message": "Đã tạo việc con",
"id": "66b9a3b4c5d6e7f8091a2b3c",
"name": "Gửi bản phác thảo banner",
"done": false,
"deal_id": "66b3d4e5f6071829a3b4c5d6",
"store_context": {
"store_id": "5f8c2a1b9d3e4f6a7b8c9d01",
"store_name": "Công ty TNHH An Phát",
"you": "Trần Thị Bình"
}
}
}id là ID việc con. Yêu cầu trùng trong 60 giây: trả lại kết quả lần trước kèm deduped = true.
Lưu ý
- Tạo ngay khi gọi. Người tạo là người sở hữu api-key. Việc con được xếp cuối danh sách (hoặc cuối hạng mục nếu có
deal_task_group_id). - Không cần hạng mục:
deal_task_group_idlà tuỳ chọn. Hệ thống không kiểm tra hạng mục có thuộc đúng thẻ không, nên chỉ dùng ID hạng mục của chính thẻ đó. - Tác dụng phụ: gửi thông báo việc mới, cập nhật số hoạt động và hoạt động kế tiếp của thẻ, ghi lịch sử thẻ.
- Chống trùng: cùng name +
deal_id(hoặc cùngidempotency_key) trong 60 giây trả lại kết quả lần trước. - Quyền: vai trò phải có quyền tạo việc con và xem được thẻ; Space có quy tắc theo giai đoạn có thể chặn thêm hoạt động ở một số giai đoạn.
Tạo hạng mục việc con Tạo
POST/2.0/api/lw-create-deal-task-group
Tạo một hạng mục (nhóm việc con, vd Thiết kế, Nghiệm thu) trong giao dịch/công việc. Sau đó dùng lw-create-deal-subtask với deal_task_group_id trả về để thêm việc con vào hạng mục.
Tham số
| Tham số | Kiểu | Mô tả |
|---|---|---|
| store_id | string | ID workspace, lấy từ account-list-workspaces. Bắt buộc khi tài khoản có từ hai workspace trở lên. |
| deal_idbắt buộc | string | ID giao dịch/công việc, 24 ký tự (lw-list-deals → items[].id). |
| namebắt buộc | string | Tên hạng mục. |
| idempotency_key | string | Khoá chống tạo trùng do bên gọi tự đặt. Có hiệu lực 60 giây. |
Ví dụ
curl -X POST https://api.ladipage.net/2.0/api/lw-create-deal-task-group \
-H "api-key: $LADIPAGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"store_id": "5f8c2a1b9d3e4f6a7b8c9d01",
"deal_id": "66b2c3d4e5f6071829a3b4c5",
"name": "Thiết kế"
}'Kết quả
{
"code": 200,
"message": "Success",
"data": {
"status": "success",
"message": "Đã tạo hạng mục",
"deal_task_group_id": "66baa3b4c5d6e7f8091a2b3d",
"name": "Thiết kế",
"deal": "Thiết kế banner chiến dịch Black Friday",
"store_context": {
"store_id": "5f8c2a1b9d3e4f6a7b8c9d01",
"store_name": "Công ty TNHH An Phát",
"you": "Trần Thị Bình"
}
}
}deal_task_group_id là ID hạng mục vừa tạo; deal là tên thẻ. Yêu cầu trùng trong 60 giây: trả lại kết quả lần trước kèm deduped = true.
Lưu ý
- Tạo ngay khi gọi; hạng mục mới xếp cuối danh sách hạng mục của thẻ. Ghi lịch sử thẻ, không gửi thông báo.
- Chống trùng: cùng
deal_id+ name (hoặc cùngidempotency_key) trong 60 giây trả lại kết quả lần trước. - Quyền: vai trò phải có quyền tạo hạng mục và xem được thẻ.
Tạo công việc Tạo
POST/2.0/api/lw-create-work-item
Tạo một công việc mới trong một Space Công việc, tại giai đoạn chỉ định, có thể ghi luôn trường tuỳ chỉnh của Space. Dùng khi đẩy yêu cầu/việc từ hệ thống khác vào LadiWork.
Tham số
| Tham số | Kiểu | Mô tả |
|---|---|---|
| store_id | string | ID workspace, lấy từ account-list-workspaces. Bắt buộc khi tài khoản có từ hai workspace trở lên. |
| titlebắt buộc | string | Tên công việc. |
| pipeline_idbắt buộc | string | ID Space Công việc (lw-list-pipelines với type=WORK_PIPELINE). Truyền ID Space Giao dịch sẽ bị từ chối, dùng lw-create-deal. |
| stage_idbắt buộc | string | ID giai đoạn thuộc đúng Space trên. Thiếu stage_id thì API không tạo mà trả danh sách giai đoạn (status = need_stage). |
| start_date | string | Ngày bắt đầu, ISO 8601, nên kèm múi giờ. |
| expected_close_date | string | Hạn xử lý, ISO 8601, nên kèm múi giờ (vd 2026-11-30T17:00:00+07:00). |
| processing_time | object | Thời gian xử lý ước lượng. Phải có đủ value và unit. |
| processing_time.valuebắt buộc | number | Số lượng thời gian. |
| processing_time.unitbắt buộc | string | Đơn vị. Đơn vị khác trả lỗi.Giá trị: hours, days, weeks, months |
| priority | number | Ưu tiên: 1 = Thấp, 2 = Trung bình, 3 = Cao.Giá trị: 1, 2, 3 |
| customer_id | string | ID khách hàng liên quan (từ lw-search-customers). |
| labels | array | Mảng ID nhãn (chuỗi). |
| sub_owner_id | string | ID tài khoản (24 ký tự) của nhân viên phụ trách. Bỏ trống thì áp quy tắc phân bổ tự động của Space; không có quy tắc thì người sở hữu api-key là người phụ trách. |
| description | string | Mô tả công việc. |
| custom_fields | object | Trường tuỳ chỉnh của Space, dạng { tên trường: giá trị }. Tên trường là name hoặc label lấy từ lw-list-deal-fields của đúng Space này. Trường không thuộc Space, hoặc trường dạng chọn mà giá trị không có trong danh sách lựa chọn, trả lỗi và không tạo. |
| custom_fields.<tên trường> | string|number|boolean | Giá trị của trường. Trường dạng chọn nhận nhãn hoặc giá trị lựa chọn; kiểu dữ liệu các trường khác được kiểm theo định nghĩa trường. |
| idempotency_key | string | Khoá chống tạo trùng do bên gọi tự đặt. Có hiệu lực 60 giây. |
Ví dụ
curl -X POST https://api.ladipage.net/2.0/api/lw-create-work-item \
-H "api-key: $LADIPAGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"store_id": "5f8c2a1b9d3e4f6a7b8c9d01",
"title": "Thiết kế banner chiến dịch Black Friday",
"pipeline_id": "6651a2b3c4d5e6f708192a3b",
"stage_id": "6651a2b3c4d5e6f708192a40",
"expected_close_date": "2026-11-20T17:00:00+07:00",
"processing_time": {
"value": 2,
"unit": "days"
},
"priority": 2,
"custom_fields": {
"Kênh": "Facebook"
}
}'Kết quả
{
"code": 200,
"message": "Success",
"data": {
"status": "success",
"message": "Đã tạo công việc TASK-2058",
"id": "66bc4d5e6f7081929a3b4c5d",
"code": "TASK-2058",
"kind": "work",
"title": "Thiết kế banner chiến dịch Black Friday",
"priority": {
"code": 2,
"name": "Trung bình"
},
"expected_close_date": "2026-11-20T17:00:00.000+07:00",
"pipeline": {
"name": "Marketing",
"url": "https://work.ladipage.com/pipelines/6651a2b3c4d5e6f708192a3b"
},
"stage": {
"name": "Đang thực hiện"
},
"labels": [],
"customer": null,
"assignee": "Lê Minh Châu",
"followers": [],
"detail_url": "https://work.ladipage.com/deals/66bc4d5e6f7081929a3b4c5d",
"start_date": null,
"processing_time": {
"value": 2,
"unit": "days",
"unit_name": "Ngày"
},
"store_context": {
"store_id": "5f8c2a1b9d3e4f6a7b8c9d01",
"store_name": "Công ty TNHH An Phát",
"you": "Trần Thị Bình"
}
}
}Các trường còn lại là thông tin công việc vừa tạo, có dạng như một item của lw-list-deals với code TASK-<số> và kind = work; status ở đây là kết quả gọi (success). Thiếu stage_id: status = need_stage kèm stages. Yêu cầu trùng trong 60 giây: trả lại kết quả lần trước kèm deduped = true.
Lưu ý
- Tạo ngay khi gọi, không có bước xác nhận. Trạng thái mặc định Đang mở; nếu giai đoạn chọn thuộc nhóm Hoàn thành thì công việc được tạo ở trạng thái Thành công. Người tạo là người sở hữu api-key.
- Tác dụng phụ giống tạo trên app: gửi thông báo giao việc, phát sự kiện tạo thẻ cho kịch bản tự động (Automation) và webhook, ghi lịch sử thẻ, áp quy tắc phân bổ của Space.
- Chống trùng: cùng
idempotency_key, hoặc khi không có khoá thì cùng title +pipeline_id+stage_id, trong 60 giây trả lại kết quả lần trước (deduped = true). Muốn tạo nhiều công việc cùng tên liên tiếp thì truyềnidempotency_keykhác nhau. - Giới hạn: dùng chung hạn mức số giao dịch và công việc theo gói của workspace.
- Quyền: vai trò phải có quyền tạo thẻ và người gọi phải xem được Space; quy tắc theo giai đoạn của Space có thể chặn tạo thẻ ở một số giai đoạn.
- Khác
lw-create-deal: chỉ nhận Space Công việc, cóstart_date,processing_time,custom_fields; không nhậntotal_value,deal_probability,customer_email,organization_id; không áp quy tắc gán khách hàng.
Liệt kê đơn hàng Đọc
POST/2.0/api/lw-list-orders
Liệt kê lịch sử đơn hàng gắn với khách hàng trong dữ liệu khách hàng LadiWork (đồng bộ từ LadiSales, LadiPage, Haravan, Sapo, Shopify, nhập tay...), kèm tổng số đơn và tổng doanh thu theo bộ lọc. Khác shop-list-orders là đơn của cửa hàng LadiSales.
Tham số
| Tham số | Kiểu | Mô tả |
|---|---|---|
| store_id | string | ID 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 một phần, không phân biệt hoa thường, trong mã đơn, tên, email, số điện thoại, địa chỉ khách hàng và kênh bán. |
| status | string | ALL = tất cả, PAID = đã thanh toán, NOT_PAID = chưa thanh toán (mọi trạng thái trừ đã thanh toán và đã huỷ), CANCEL = đã huỷ.Giá trị: ALL, PAID, NOT_PAID, CANCELMặc định: ALL |
| from_date | string | Từ thời điểm (ISO 8601), lọc theo ngày tạo đơn. Phải truyền cùng to_date; thiếu một trong hai thì dùng mặc định 12 tháng gần nhất. |
| to_date | string | Đến thời điểm (ISO 8601), tính cả mốc này. Phải truyền cùng from_date. |
| 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-orders \
-H "api-key: $LADIPAGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"store_id": "5f8c2a1b9d3e4f6a7b8c9d01",
"status": "PAID",
"from_date": "2026-10-01T00:00:00+07:00",
"to_date": "2026-10-31T23:59:59+07:00",
"page": 1,
"limit": 50
}'Kết quả
{
"code": 200,
"message": "Success",
"data": {
"from_date": "2026-10-01T00:00:00.000+07:00",
"to_date": "2026-10-31T23:59:59.000+07:00",
"status": "PAID",
"page": 1,
"limit": 50,
"total": 2,
"count": 2,
"summary": {
"total_orders": 2,
"total_revenue": 1840000
},
"summary_labels": {
"total_orders": "Tổng số đơn",
"total_revenue": "Tổng doanh thu"
},
"field_labels": {
"order_id": "Mã đơn",
"customer_name": "Tên khách hàng",
"customer_email": "Email",
"customer_phone": "Số điện thoại",
"source": "Nguồn",
"channel": "Kênh bán",
"status": "Trạng thái",
"value": "Giá trị đơn",
"created_at": "Ngày tạo"
},
"items": [
{
"id": "6703a4b5c6d7e8f90a1b2c3d",
"order_id": "LS10258",
"customer_name": "Nguyễn Văn An",
"customer_email": "an***@example.com",
"customer_phone": "0912***678",
"source": "LADISALES",
"source_label": "LadiSales",
"channel": "Landing page",
"status": "PAYMENT_SUCCESS",
"status_label": "Đã thanh toán",
"value": 1250000,
"currency": "VND",
"created_at": "2026-10-25T20:14:00.000+07:00"
},
{
"id": "6703a4b5c6d7e8f90a1b2c3e",
"order_id": "#1042",
"customer_name": "Phạm Thu Hà",
"customer_email": "ha***@gmail.com",
"customer_phone": "0987***321",
"source": "HARAVAN",
"source_label": "Haravan",
"channel": "Website",
"status": "PAYMENT_SUCCESS",
"status_label": "Đã thanh toán",
"value": 590000,
"currency": "VND",
"created_at": "2026-10-12T11:03:00.000+07:00"
}
],
"store_context": {
"store_id": "5f8c2a1b9d3e4f6a7b8c9d01",
"store_name": "Công ty TNHH An Phát",
"you": "Trần Thị Bình"
}
}
}from_date, to_date là khoảng ngày thực tế đã áp; count là số đơn trong trang. field_labels là nhãn tiếng Việt của các trường. id dùng cho lw-get-order; order_id là mã đơn.
Lưu ý
- Sắp xếp mới tạo trước. Phân trang bằng page/limit (tối đa 50 đơn/trang).
- Chỉ gồm đơn đã gắn với một khách hàng.
total_revenuecộng giá trị mọi đơn khớp bộ lọc trên tất cả các trang; với status = ALL con số này gồm cả đơn chưa thanh toán và đã huỷ. Lấy doanh thu thực thu thì dùng status = PAID.- Mã trạng thái gốc: PAYMENT_SUCCESS = đã thanh toán, CANCEL = đã huỷ, các mã còn lại hiển thị là chưa thanh toán (riêng PAYMENT_FAIL là thanh toán thất bại).
- Email và số điện thoại khách hàng đã được che một phần.
- keyword được dùng như biểu thức tìm kiếm; tránh các ký tự đặc biệt như ( ) [ ] * + ? \.
- Quyền: vai trò của người sở hữu api-key phải được xem danh sách đơn hàng.
Xem chi tiết đơn hàng Đọc
POST/2.0/api/lw-get-order
Lấy chi tiết một đơn hàng trong dữ liệu khách hàng LadiWork: thông tin đơn, sản phẩm, chiến dịch, khuyến mãi, nguồn, chi nhánh, thương hiệu, địa chỉ và UTM.
Tham số
| Tham số | Kiểu | Mô tả |
|---|---|---|
| store_id | string | ID workspace, lấy từ account-list-workspaces. Bắt buộc khi tài khoản có từ hai workspace trở lên. |
| idbắt buộc | string | ID đơn hàng, 24 ký tự hex, lấy từ lw-list-orders → items[].id (không phải mã đơn order_id). |
Ví dụ
curl -X POST https://api.ladipage.net/2.0/api/lw-get-order \
-H "api-key: $LADIPAGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"store_id": "5f8c2a1b9d3e4f6a7b8c9d01",
"id": "6703a4b5c6d7e8f90a1b2c3d"
}'Kết quả
{
"code": 200,
"message": "Success",
"data": {
"id": "6703a4b5c6d7e8f90a1b2c3d",
"order_id": "LS10258",
"status": "PAYMENT_SUCCESS",
"status_label": "Đã thanh toán",
"source": "LADISALES",
"source_label": "LadiSales",
"channel": "Landing page",
"value": 1250000,
"currency": "VND",
"discount_value": 50000,
"customer_name": "Nguyễn Văn An",
"customer_email": "an***@example.com",
"customer_phone": "0912***678",
"customer_address": "12 Nguyễn Trãi, Phường Bến Thành, TP. Hồ Chí Minh",
"campaign_name": "Khuyến mãi tháng 10",
"sequence_name": "Chăm sóc sau mua",
"flow_name": "Cảm ơn khách mua hàng",
"voucher_campaigns": ["Giảm 50K đơn đầu"],
"discount_codes": ["CHAO50K"],
"branch_name": "Chi nhánh Quận 1",
"brand_name": "An Phát Cosmetics",
"utm": {
"source": "facebook",
"campaign": "oct_sale",
"term": "serum",
"content": "video_01",
"medium": "cpc"
},
"created_at": "2026-10-25T20:14:00.000+07:00",
"updated_at": "2026-10-25T20:30:00.000+07:00",
"field_labels": {
"order_id": "Mã đơn",
"status": "Trạng thái",
"value": "Giá trị đơn",
"discount_value": "Giảm giá",
"customer_name": "Tên khách hàng",
"customer_address": "Địa chỉ"
},
"item_field_labels": {
"product_name": "Tên sản phẩm",
"variant": "Phân loại",
"quantity": "Số lượng",
"price": "Đơn giá",
"total_price": "Thành tiền"
},
"items": [
{
"product_name": "Serum dưỡng ẩm Hoa Hồng",
"variant": "30ml",
"product_type": "Physical",
"quantity": 2,
"price": 650000,
"discount_value": 50000,
"total_price": 1250000,
"category_name": "Chăm sóc da"
}
],
"store_context": {
"store_id": "5f8c2a1b9d3e4f6a7b8c9d01",
"store_name": "Công ty TNHH An Phát",
"you": "Trần Thị Bình"
}
}
}voucher_campaigns là tên chương trình khuyến mãi; items là danh sách sản phẩm trong đơn.
Lưu ý
- ID sai định dạng hoặc không thuộc workspace trả lỗi.
- Email và số điện thoại khách hàng đã được che một phần.
- Quyền: vai trò của người sở hữu api-key phải được xem chi tiết đơn hàng.