# 交易 API

交易是您[销售渠道](../deals/sales-pipeline.md)看板上的一个销售机会——包含标题、价值、所处阶段，以及可选的所属联系人和分配的团队成员。本指南涵盖了如何通过 API 读取和管理交易。

- **基础 URL** — `https://api.youraiconnector.com/v1`
- **身份验证** — 您的 API 密钥（请参阅 [身份验证](authentication.md)）
- **错误与分页** — 请参阅 [错误与分页](errors-and-pagination.md)

以下所有示例均展示了 cURL 中的 `?apiKey=` 查询形式，以及 JavaScript 和 Python 中的 `X-API-Key` 标头——两者均适用于所有端点。

---

## 交易对象

```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` 是您流水线阶段之一的 ID — 使用 `GET /pipelines` 读取它们（请参阅下方的 [流水线](#pipelines)）。阶段 ID 在所有流水线中都是唯一的，因此 `pipeline_id` 派生自该阶段且为只读：`default` 是您的主流水线，当该阶段不再存在时，它将为 `null`。时间戳格式为 ISO 8601。

交易仅存储上述显示的字段。当您创建或更新交易时，任何其他字段都会被拒绝，并返回一个命名该字段的 `400`，因此您发送的任何内容都不会被静默丢弃。请将额外数据保留在关联联系人的自定义字段中。

---

## 列出交易

`GET /deals` — 返回您账户中的交易，按最新日期排序。

**查询参数**（均为可选）：`stage`（阶段 ID）、`pipeline_id`（仅限该流水线上的交易）、`contact_id`、`limit`（默认 50，最大 200）、`cursor`（来自上一页的 `next_cursor`）。

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

**响应** (`200`)

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

---

## 获取交易

`GET /deals/{dealId}`

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

**响应** (`200`)

```json
{ "success": true, "deal": { "id": "deal_abc123", "title": "Annual plan – Jane's Clinic", "...": "..." } }
```

如果交易不存在或属于其他账户，将返回 `404`。

---

## 创建交易

`POST /deals` — `title` 和 `stage` 为必填项；`stage` 必须是您渠道中某个阶段的 ID。

```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" }'
```

**响应** (`201`)

```json
{ "success": true, "deal_id": "deal_abc123" }
```

---

## 更新交易

`PUT /deals/{dealId}` — 仅发送您想要更改的字段（`title`、`description`、`notes`、`value`、`stage`、`status`、`priority`、`contact_id` 等）。`value` 必须是一个数字。

```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" }'
```

**响应** (`200`)：`{ "success": true, "deal_id": "deal_abc123" }`

---

## 将交易移动到另一个阶段

`POST /deals/{dealId}/move` — 正文 `{ "new_stage_id": "stage-3", "new_position": 0 }`。位置 `0` 将卡片置于列的最上方。

```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 }'
```

**响应** (`200`)：`{ "success": true, "deal_id": "deal_abc123", "stage": "stage-3", "position": 0 }`

---

## 删除交易

`DELETE /deals/{dealId}` — 移除该交易。**此操作无法撤销。**

```bash
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` — 所有流水线，主流水线在前，每个流水线的阶段按位置排序。

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

**响应** (`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" }
        ]
      }
    ]
  }
}
```

### 创建流水线

`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"`）。

```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" }
    ]
  }'
```

**响应** (`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`)。

---

## 后续步骤

- [销售漏斗](../deals/sales-pipeline.md) — 介绍阶段、阶段标签、多个漏斗以及看板的工作方式。
- [任务 API](tasks.md) — 任务可以通过 `deal_id` 与交易关联。
- [自动化](../automations/automations.md) — **查找交易 (Find deals)** 和 **查找交易 (Find deal)** 步骤在工作流中读取相同的数据。