交易 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",
"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 是您流水线阶段之一的 ID — 使用 GET /pipelines 读取它们（请参阅下方的 流水线）。阶段 ID 在所有流水线中都是唯一的，因此 pipeline_id 派生自该阶段且为只读：default 是您的主流水线，当该阶段不再存在时，它将为 null。时间戳格式为 ISO 8601。
交易仅存储上述显示的字段。当您创建或更新交易时，任何其他字段都会被拒绝，并返回一个命名该字段的 400，因此您发送的任何内容都不会被静默丢弃。请将额外数据保留在关联联系人的自定义字段中。
列出交易
GET /deals — 返回您账户中的交易，按最新日期排序。
查询参数（均为可选）：stage（阶段 ID）、pipeline_id（仅限该流水线上的交易）、contact_id、limit（默认 50，最大 200）、cursor（来自上一页的 next_cursor）。
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"]
响应 (200)
{ "success": true, "deals": [{ "id": "deal_abc123", "title": "Annual plan – Jane's Clinic", "...": "..." }], "next_cursor": null }
获取交易
GET /deals/{dealId}
curl "https://api.youraiconnector.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.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" }'
响应 (201)
{ "success": true, "deal_id": "deal_abc123" }
更新交易
PUT /deals/{dealId} — 仅发送您想要更改的字段（title、description、notes、value、stage、status、priority、contact_id 等）。value 必须是一个数字。
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" }'
响应 (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.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 }'
响应 (200)：{ "success": true, "deal_id": "deal_abc123", "stage": "stage-3", "position": 0 }
删除交易
DELETE /deals/{dealId} — 移除该交易。此操作无法撤销。
curl -X DELETE "https://api.youraiconnector.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY"
响应 (200)：{ "success": true }
流水线
每个账户都有一个主流水线（id: "default"）；您可以额外添加最多九个流水线，每个都有其自己的阶段。阶段 ID 和触发标签在账户的所有流水线中必须是唯一的，并且每个流水线都可以将一个阶段标记为 won，将另一个阶段标记为 lost 结果。
列出流水线
GET /pipelines — 所有流水线，主流水线在前，每个流水线的阶段按位置排序。
curl "https://api.youraiconnector.com/v1/pipelines?apiKey=YOUR_API_KEY"
响应 (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" }
]
}
]
}
}
创建流水线
POST /pipelines — 正文 { "id"?, "name", "stages"?, "settings"? }。不填 id 将自动生成一个。每个阶段使用与“阶段”对话框相同的字段：id、name、color、position，可选的 trigger_tag（标签路径，users/{uid}/tags/{tagId}）、default_value、auto_move_after_days + auto_move_to_stage（同一流水线的阶段）以及 outcome（"won" 或 "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" }
]
}'
响应 (201)：{ "success": true, "data": { "pipeline": { ... } } }。如果阶段 ID 或触发标签已被其他流水线使用，则会返回 400 并指明该流水线；如果 ID 已存在，则返回 409。
更新流水线
PUT /pipelines/{pipelineId} — 正文 { "name"?, "stages"?, "settings"? }。stages 将替换整个列表，类似于“阶段”对话框。主流水线请使用 default。流水线 ID 本身无法更改。
删除流水线
DELETE /pipelines/{pipelineId} — 移除一个额外流水线（主流水线无法删除）。如果其阶段中仍有交易，调用将返回 409 并附带 deal_count；添加 ?delete_deals=true 可将这些交易与流水线一并删除。此操作无法撤销。
响应 (204)。