DM Champ Docs

API Giao dịch

Một giao dịch là một cơ hội bán hàng trên bảng Quy trình Bán hàng của bạn — bao gồm tiêu đề, giá trị, giai đoạn hiện tại, và tùy chọn liên hệ đi kèm cũng như thành viên nhóm được chỉ định. Hướng dẫn này bao gồm cách đọc và quản lý các giao dịch thông qua API.

Tất cả các ví dụ dưới đây đều hiển thị dạng truy vấn ?apiKey= trong cURL và tiêu đề X-API-Key trong JavaScript và Python — cả hai đều hoạt động trên mọi endpoint.

Đối tượng giao dịch 

{
  "id": "deal_abc123",
  "title": "Annual plan – Jane's Clinic",
  "description": "Asked for pricing on the annual plan.",
  "company": "Jane's Clinic",
  "stage": "stage-2",
  "value": 4800,
  "probability": 60,
  "priority": "high",
  "status": "open",
  "source": "whatsapp",
  "position": 0,
  "contact_id": "ctc_9f8e7d",
  "assigned_to": "usr_4a2b",
  "tags": ["clinic"],
  "close_date": "2026-10-01T00:00:00.000Z",
  "created_at": "2026-09-05T09:12:00.000Z",
  "updated_at": "2026-09-05T09:40:00.000Z",
  "stage_entered_at": "2026-09-05T09:40:00.000Z"
}

stage là id của một trong các giai đoạn quy trình của bạn — hãy đọc chúng từ cài đặt quy trình (GET /users/me/pipeline-settings). Các dấu thời gian tuân theo chuẩn ISO 8601.

Liệt kê các giao dịch

GET /deals — trả về các giao dịch trong tài khoản của bạn, giao dịch mới nhất hiển thị trước.

Tham số truy vấn (tất cả đều tùy chọn): stage (một id giai đoạn), contact_id, limit (mặc định là 50, tối đa 200), cursor (từ next_cursor của trang trước).

cURL

curl "https://api.dmchamp.com/v1/deals?apiKey=YOUR_API_KEY&stage=stage-2&limit=50"

JavaScript

const res = await fetch("https://api.dmchamp.com/v1/deals?stage=stage-2&limit=50", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { deals, next_cursor } = await res.json();

Python

res = requests.get(
    "https://api.dmchamp.com/v1/deals",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"stage": "stage-2", "limit": 50},
)
deals = res.json()["deals"]

Phản hồi (200)

{ "success": true, "deals": [{ "id": "deal_abc123", "title": "Annual plan – Jane's Clinic", "...": "..." }], "next_cursor": null }

Lấy một deal

GET /deals/{dealId}

curl "https://api.dmchamp.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY"

Phản hồi (200)

{ "success": true, "deal": { "id": "deal_abc123", "title": "Annual plan – Jane's Clinic", "...": "..." } }

Một deal không tồn tại, hoặc thuộc về một tài khoản khác, sẽ trả về 404.

Tạo một deal

POST /deals — title và stage là bắt buộc; stage phải là một trong các id giai đoạn trong pipeline của bạn.

curl -X POST "https://api.dmchamp.com/v1/deals?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Annual plan – Jane'"'"'s Clinic", "stage": "stage-1", "value": 4800, "contact_id": "ctc_9f8e7d" }'

Phản hồi (201)

{ "success": true, "deal_id": "deal_abc123" }

Cập nhật một deal

PUT /deals/{dealId} — chỉ gửi các trường bạn muốn thay đổi (title, description, value, stage, status, priority, contact_id, …). value phải là một số.

curl -X PUT "https://api.dmchamp.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "value": 5200, "priority": "high" }'

Phản hồi (200): { "success": true, "deal_id": "deal_abc123" }

Di chuyển giao dịch sang giai đoạn khác

POST /deals/{dealId}/move — nội dung { "new_stage_id": "stage-3", "new_position": 0 }. Vị trí 0 đặt thẻ ở đầu cột.

curl -X POST "https://api.dmchamp.com/v1/deals/deal_abc123/move?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "new_stage_id": "stage-3", "new_position": 0 }'

Phản hồi (200): { "success": true, "deal_id": "deal_abc123", "stage": "stage-3", "position": 0 }

Xóa một giao dịch

DELETE /deals/{dealId} — xóa giao dịch. Thao tác này không thể hoàn tác.

curl -X DELETE "https://api.dmchamp.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY"

Phản hồi (200): { "success": true }

Các bước tiếp theo

  • Quy trình bán hàng — cách thức hoạt động của các giai đoạn, thẻ giai đoạn và bảng.
  • API Tác vụ — các tác vụ có thể được liên kết với một giao dịch bằng deal_id.
  • Tự động hóa — các bước Tìm giao dịch và Tìm giao dịch đọc cùng một dữ liệu bên trong quy trình làm việc.