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.

URL cơ sở — https://api.youraiconnector.com/v1
Xác thực — khóa API của bạn (xem Xác thực)
Lỗi & phân trang — xem Lỗi & Phân trang

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",
  "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 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

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

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

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)

{ "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.youraiconnector.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.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)

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

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.

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.

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í.

curl "https://api.youraiconnector.com/v1/pipelines?apiKey=YOUR_API_KEY"

Phản hồi (200):

{
  "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").

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 — 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ụ — 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 một quy trình làm việc.

API Giao dịch #

Đối tượng giao dịch #

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

Lấy một deal #

Tạo một deal #

Cập nhật một deal #

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

Xóa một giao dịch #

Quy trình #

Liệt kê các quy trình #

Tạo một quy trình #

Cập nhật một quy trình #

Xóa một quy trình #

Các bước tiếp theo #