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.

APIViệc làmLoại
lw-list-dealsLiệt kê giao dịch, công việcĐọc
lw-get-dealXem chi tiết giao dịch, công việcĐọc
lw-get-deal-timelineXem lịch sử chỉnh sửa giao dịch, công việcĐọc
lw-list-deal-attachmentsLiệt kê tài liệu đính kèmĐọc
lw-list-deal-commentsLiệt kê bình luậnĐọc
lw-list-deal-fieldsLiệt kê trường lọc giao dịch, công việcĐọc
lw-list-deal-notesLiệt kê ghi chúĐọc
lw-list-deal-tasksLiệt kê việc con, hoạt độngĐọc
lw-list-pipelinesLiệt kê Space và giai đoạnĐọc
lw-create-dealTạo giao dịchTạo
lw-create-deal-commentViết bình luậnTạo
lw-create-deal-subtaskTạo việc conTạo
lw-create-deal-task-groupTạo hạng mục việc conTạo
lw-create-work-itemTạo công việcTạo
lw-list-ordersLiệt kê đơn hàngĐọc
lw-get-orderXem chi tiết đơn hàngĐọc

Quy ước chung

  • store_id là tham số chung của mọi API lw-*: giá trị store_id lấ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ếu store_id thì 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_context gồm store_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ểuMô tả
store_idstringID 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_idstringID 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.
typestringDù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_idstringID giai đoạn (lw-list-pipelines → items[].stages[].id).
keywordstringTì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_mebooleantrue = 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.
filtersarrayBộ 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ộcstringTê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[].operatorstringToá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[].valuestringGiá 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[].unitstringChỉ 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ờ
matchstringCá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
pagenumberSố trang, bắt đầu từ 1.Mặc định: 1
limitnumberSố 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
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ả

Phản hồi mẫu · JSON
{
  "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_id ngoà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ểuMô tả
store_idstringID 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ộcstringID 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
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ả

Phản hồi mẫu · JSON
{
  "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ằng lw-list-deal-notes, bình luận bằng lw-list-deal-comments, tài liệu bằng lw-list-deal-attachments, lịch sử chỉnh sửa bằng lw-get-deal-timeline (đều nhận cùng deal_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ểuMô tả
store_idstringID 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ộcstringID giao dịch/công việc (24 ký tự) hoặc phần số của mã thẻ (DEAL-<số>/TASK-<số>).
pagenumberSố trang, bắt đầu từ 1.Mặc định: 1
limitnumberSố mục mỗi trang, tối đa 50.Mặc định: 20

Ví dụ

cURL
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ả

Phản hồi mẫu · JSON
{
  "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ểuMô tả
store_idstringID 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ộcstringID giao dịch/công việc, 24 ký tự (lw-list-deals → items[].id). Không nhận mã số DEAL-/TASK-.
pagenumberSố trang, bắt đầu từ 1.Mặc định: 1
limitnumberSố tệp mỗi trang, tối đa 50.Mặc định: 20

Ví dụ

cURL
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ả

Phản hồi mẫu · JSON
{
  "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ểuMô tả
store_idstringID 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ộcstringID giao dịch/công việc, 24 ký tự (lw-list-deals → items[].id). Không nhận mã số DEAL-/TASK-.
pagenumberSố trang, bắt đầu từ 1.Mặc định: 1
limitnumberSố bình luận mỗi trang, tối đa 50.Mặc định: 20

Ví dụ

cURL
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ả

Phản hồi mẫu · JSON
{
  "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ểuMô tả
store_idstringID workspace, lấy từ account-list-workspaces. Bắt buộc khi tài khoản có từ hai workspace trở lên.
pipelinestringTê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.
typestringChỉ 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
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ả

Phản hồi mẫu · JSON
{
  "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-deals kèm pipeline_id củ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ểuMô tả
store_idstringID 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ộcstringID giao dịch/công việc, 24 ký tự (lw-list-deals → items[].id). Không nhận mã số DEAL-/TASK-.
pagenumberSố trang, bắt đầu từ 1.Mặc định: 1
limitnumberSố ghi chú mỗi trang, tối đa 50.Mặc định: 20

Ví dụ

cURL
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ả

Phản hồi mẫu · JSON
{
  "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ểuMô tả
store_idstringID workspace, lấy từ account-list-workspaces. Bắt buộc khi tài khoản có từ hai workspace trở lên.
deal_idstringChỉ lấy việc con của một giao dịch/công việc (ID 24 ký tự).
pipeline_idstringChỉ 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.
statusstringHoà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.
prioritystringCao, Trung bình hoặc Thấp (cũng nhận HIGH, MEDIUM, LOW).
deadlinestringLọ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).
assigneestringTê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_idstringChỉ lấy việc con gắn với khách hàng này.
assigned_to_mebooleantrue = chỉ lấy việc giao cho chính người sở hữu api-key.
keywordstringTì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.
pagenumberSố trang, bắt đầu từ 1.Mặc định: 1
limitnumberSố bản ghi mỗi trang, tối đa 100.Mặc định: 50

Ví dụ

cURL
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ả

Phản hồi mẫu · JSON
{
  "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_id thì thẻ đó phải xem được; lọc theo pipeline_id thì 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_id hoặc pipeline_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ểuMô tả
store_idstringID workspace, lấy từ account-list-workspaces. Bắt buộc khi tài khoản có từ hai workspace trở lên.
typestringSALES_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
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ả

Phản hồi mẫu · JSON
{
  "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ểuMô tả
store_idstringID 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ộcstringTên giao dịch.
pipeline_idbắt buộcstringID 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ộcstringID 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_valuenumberGiá trị giao dịch.Mặc định: 0
customer_idstringID khách hàng có sẵn (từ lw-search-customers, lw-get-customer).
customer_emailstringEmail 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_probabilitynumberXác suất thành công, 0–100.
expected_close_datestringNgày dự kiến chốt, ISO 8601. Nên kèm múi giờ (vd 2026-11-30T17:00:00+07:00).
prioritynumberƯu tiên: 1 = Thấp, 2 = Trung bình, 3 = Cao.Giá trị: 1, 2, 3
labelsarrayMảng ID nhãn giao dịch (chuỗi).
sub_owner_idstringID 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_idstringID công ty (từ lw-list-organizations).
descriptionstringMô tả giao dịch.
idempotency_keystringKhoá 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
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ả

Phản hồi mẫu · JSON
{
  "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ận start_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ểuMô tả
store_idstringID 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ộcstringID giao dịch/công việc, 24 ký tự (lw-list-deals → items[].id).
messagebắt buộcstringNộ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_keystringKhoá chống tạo trùng do bên gọi tự đặt. Có hiệu lực 60 giây.

Ví dụ

cURL
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ả

Phản hồi mẫu · JSON
{
  "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ùng idempotency_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ểuMô tả
store_idstringID 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ộcstringTên việc con.
deal_idbắt buộcstringID giao dịch/công việc chứa việc con, 24 ký tự (lw-list-deals → items[].id).
descriptionstringMô tả việc con.
start_timestringThời điểm bắt đầu, ISO 8601, nên kèm múi giờ.
end_timestringThờ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.
prioritystringƯ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_usersarrayMả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.
donebooleantrue = tạo ở trạng thái đã hoàn thành.Mặc định: false
deal_task_group_idstringID 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_keystringKhoá chống tạo trùng do bên gọi tự đặt. Có hiệu lực 60 giây.

Ví dụ

cURL
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ả

Phản hồi mẫu · JSON
{
  "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_id là 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ùng idempotency_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ểuMô tả
store_idstringID 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ộcstringID giao dịch/công việc, 24 ký tự (lw-list-deals → items[].id).
namebắt buộcstringTên hạng mục.
idempotency_keystringKhoá chống tạo trùng do bên gọi tự đặt. Có hiệu lực 60 giây.

Ví dụ

cURL
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ả

Phản hồi mẫu · JSON
{
  "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ùng idempotency_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ểuMô tả
store_idstringID 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ộcstringTên công việc.
pipeline_idbắt buộcstringID 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ộcstringID 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_datestringNgày bắt đầu, ISO 8601, nên kèm múi giờ.
expected_close_datestringHạn xử lý, ISO 8601, nên kèm múi giờ (vd 2026-11-30T17:00:00+07:00).
processing_timeobjectThời gian xử lý ước lượng. Phải có đủ value và unit.
processing_time.valuebắt buộcnumberSố lượng thời gian.
processing_time.unitbắt buộcstringĐơn vị. Đơn vị khác trả lỗi.Giá trị: hours, days, weeks, months
prioritynumberƯu tiên: 1 = Thấp, 2 = Trung bình, 3 = Cao.Giá trị: 1, 2, 3
customer_idstringID khách hàng liên quan (từ lw-search-customers).
labelsarrayMảng ID nhãn (chuỗi).
sub_owner_idstringID 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.
descriptionstringMô tả công việc.
custom_fieldsobjectTrườ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|booleanGiá 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_keystringKhoá chống tạo trùng do bên gọi tự đặt. Có hiệu lực 60 giây.

Ví dụ

cURL
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ả

Phản hồi mẫu · JSON
{
  "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ền idempotency_key khá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ận total_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ểuMô tả
store_idstringID workspace, lấy từ account-list-workspaces. Bắt buộc khi tài khoản có từ hai workspace trở lên.
keywordstringTì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.
statusstringALL = 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_datestringTừ 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_datestringĐến thời điểm (ISO 8601), tính cả mốc này. Phải truyền cùng from_date.
pagenumberSố trang, bắt đầu từ 1.Mặc định: 1
limitnumberSố đơn mỗi trang, tối đa 50.Mặc định: 20

Ví dụ

cURL
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ả

Phản hồi mẫu · JSON
{
  "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_revenue cộ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ểuMô tả
store_idstringID 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ộcstringID đơ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
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ả

Phản hồi mẫu · JSON
{
  "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.