交易 API
交易是您销售渠道看板上的一个销售机会——包含标题、价值、所处阶段，以及可选的所属联系人和分配的团队成员。本指南涵盖了如何通过 API 读取和管理交易。
以下所有示例均展示了 cURL 中的 ?apiKey= 查询形式，以及 JavaScript 和 Python 中的 X-API-Key 标头——两者均适用于所有端点。
交易对象
{
"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 是您某个渠道阶段的 ID——请从您的渠道设置 (GET /users/me/pipeline-settings) 中读取它们。时间戳采用 ISO 8601 格式。
列出交易
GET /deals — 返回您账户中的交易，按最新日期排序。
查询参数（均为可选）：stage（阶段 ID）、contact_id、limit（默认 50，最大 200）、cursor（来自上一页的 next_cursor）。
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"]
响应 (200)
{ "success": true, "deals": [{ "id": "deal_abc123", "title": "Annual plan – Jane's Clinic", "...": "..." }], "next_cursor": null }
获取交易
GET /deals/{dealId}
curl "https://api.dmchamp.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY"
响应 (200)
{ "success": true, "deal": { "id": "deal_abc123", "title": "Annual plan – Jane's Clinic", "...": "..." } }
如果交易不存在或属于其他账户，将返回 404。
创建交易
POST /deals — title 和 stage 为必填项；stage 必须是您渠道中某个阶段的 ID。
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" }'
响应 (201)
{ "success": true, "deal_id": "deal_abc123" }
更新交易
PUT /deals/{dealId} — 仅发送您想要更改的字段（title、description、value、stage、status、priority、contact_id 等）。value 必须是一个数字。
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" }'
响应 (200)：{ "success": true, "deal_id": "deal_abc123" }
将交易移动到另一个阶段
POST /deals/{dealId}/move — 正文 { "new_stage_id": "stage-3", "new_position": 0 }。位置 0 将卡片置于列的最上方。
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 }'
响应 (200)：{ "success": true, "deal_id": "deal_abc123", "stage": "stage-3", "position": 0 }
删除交易
DELETE /deals/{dealId} — 移除该交易。此操作无法撤销。
curl -X DELETE "https://api.dmchamp.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY"
响应 (200)：{ "success": true }