# 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.youraiconnector.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", "notes": "Prefers a call after 5pm.", "stage": "stage-2", "pipeline_id": "default", "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 bằng `GET /pipelines` (xem [Quy trình](#pipelines) bên dưới). Id giai đoạn là duy nhất trên tất cả các quy trình của bạn, vì vậy `pipeline_id` được bắt nguồn từ giai đoạn và là chỉ đọc: `default` là quy trình chính của bạn và nó là `null` khi giai đoạn đó không còn tồn tại. Dấu thời gian tuân theo chuẩn ISO 8601. Một giao dịch chỉ lưu trữ các trường được hiển thị ở trên. Khi bạn tạo hoặc cập nhật một giao dịch, bất kỳ trường nào khác đều sẽ bị từ chối kèm theo một `400` nêu tên trường đó, vì vậy không có dữ liệu nào bạn gửi bị mất đi mà không được thông báo. Hãy lưu trữ dữ liệu bổ sung vào các trường tùy chỉnh của liên hệ được liên kết. --- ## 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), `pipeline_id` (chỉ các giao dịch trên quy trình đó), `contact_id`, `limit` (mặc định 50, tối đa 200), `cursor` (từ `next_cursor` của trang trước). **cURL** ```bash curl "https://api.youraiconnector.com/v1/deals?apiKey=YOUR_API_KEY&stage=stage-2&limit=50" ``` **JavaScript** ```javascript const res = await fetch("https://api.youraiconnector.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.youraiconnector.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.youraiconnector.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.youraiconnector.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`, `notes`, `value`, `stage`, `status`, `priority`, `contact_id`, …). `value` phải là một số. ```bash curl -X PUT "https://api.youraiconnector.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.youraiconnector.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.youraiconnector.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY" ``` **Phản hồi** (`200`): `{ "success": true }` --- ## Quy trình Mỗi tài khoản có một quy trình chính (`id: "default"`); bạn có thể thêm tối đa chín quy trình nữa, mỗi quy trình có các giai đoạn riêng. Id giai đoạn và thẻ kích hoạt phải là duy nhất trên tất cả các quy trình trong tài khoản, và mỗi quy trình có thể đánh dấu một giai đoạn là kết quả `won` và một giai đoạn là kết quả `lost`. ### Liệt kê các quy trình `GET /pipelines` — mọi quy trình, quy trình chính đứng đầu, mỗi quy trình có các giai đoạn được sắp xếp theo vị trí. ```bash curl "https://api.youraiconnector.com/v1/pipelines?apiKey=YOUR_API_KEY" ``` **Phản hồi** (`200`): ```json { "success": true, "data": { "pipelines": [ { "id": "default", "name": "Sales", "position": 0, "is_default": true, "settings": { "sync_stage_tags": false }, "stages": [ { "id": "stage-1", "name": "New lead", "color": "#3B82F6", "position": 0, "trigger_tag": null }, { "id": "won", "name": "Won", "color": "#10B981", "position": 1, "outcome": "won" } ] } ] } } ``` ### Tạo một quy trình `POST /pipelines` — phần thân `{ "id"?, "name", "stages"?, "settings"? }`. Để trống `id` để hệ thống tự tạo. Mỗi giai đoạn sử dụng các trường tương tự như hộp thoại Giai đoạn: `id`, `name`, `color`, `position`, tùy chọn `trigger_tag` (đường dẫn thẻ, `users/{uid}/tags/{tagId}`), `default_value`, `auto_move_after_days` + `auto_move_to_stage` (một giai đoạn của cùng quy trình) và `outcome` (`"won"` hoặc `"lost"`). ```bash curl -X POST "https://api.youraiconnector.com/v1/pipelines?apiKey=YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "id": "reviews", "name": "Review requests", "stages": [ { "id": "rv_asked", "name": "Asked", "color": "#3B82F6", "position": 0 }, { "id": "rv_done", "name": "Review posted", "color": "#10B981", "position": 1, "outcome": "won" } ] }' ``` **Phản hồi** (`201`): `{ "success": true, "data": { "pipeline": { ... } } }`. Một id giai đoạn hoặc thẻ kích hoạt đã được sử dụng bởi một quy trình khác sẽ là `400` nêu tên quy trình đó; một id đã tồn tại sẽ là `409`. ### Cập nhật một quy trình `PUT /pipelines/{pipelineId}` — phần thân `{ "name"?, "stages"?, "settings"? }`. `stages` thay thế toàn bộ danh sách, giống như hộp thoại Giai đoạn. Sử dụng `default` cho quy trình chính. Bản thân id quy trình không thể thay đổi. ### Xóa một quy trình `DELETE /pipelines/{pipelineId}` — xóa một quy trình bổ sung (quy trình chính không thể bị xóa). Nếu các giao dịch vẫn nằm trong các giai đoạn của nó, lệnh gọi sẽ trả về `409` với `deal_count`; thêm `?delete_deals=true` để xóa các giao dịch đó cùng với quy trình. **Hành động này không thể hoàn tác.** **Phản hồi** (`204`). --- ## 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, nhiều quy trình 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 một quy trình làm việc.