# 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](../deals/sales-pipeline.md) 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.

- **URL cơ sở** — `https://api.dmchamp.com/v1`
- **Xác thực** — khóa API của bạn (xem [Xác thực](authentication.md))
- **Lỗi & phân trang** — xem [Lỗi & Phân trang](errors-and-pagination.md)

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

```json
{
  "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**

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

**JavaScript**

```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**

```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`)

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

---

## Lấy một deal

`GET /deals/{dealId}`

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

**Phản hồi** (`200`)

```json
{ "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.

```bash
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`)

```json
{ "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ố.

```bash
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.

```bash
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.**

```bash
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](../deals/sales-pipeline.md) — 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ụ](tasks.md) — 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](../automations/automations.md) — 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.