Dureach API 参考：身份验证、端点、分页和 webhook

本页说明可安全用于客户集成的 Dureach API：API 密钥管理、webhook 和投递历史，以及独立版本的联系人获取端点。内容包括身份验证、请求字段、响应结构、游标分页、筛选器、限制和生产环境应处理的错误。

从受支持的范围开始

在 Settings -> Integrations 中创建最小权限的 API 密钥。将其保存在服务端，通过 Authorization 标头发送，并将每个请求限定到目标 workspace。浏览器应用、私有 runner 以及未记录的 /api/v1/ 或 /api/v2/ 路由不会自动成为客户 API。

示例使用 https://app.dureach.com。将 YOUR_OAUTH_ACCESS_TOKEN 和 UUID 换成自己的值。不要将真实密钥放入浏览器 bundle、URL、截图、日志或支持工单。

指南

• API authentication and quickstart
• Dureach API 访问限制
• 通过 MCP 连接 AI 客户端
• MCP 工具参考
• MCP 审批、策略与配额
• MCP SQL 读取器
• MCP 故障排查
• API webhooks
• Webhook setup and delivery monitoring

身份验证

在每个请求中将密钥作为 bearer token 发送：

curl --fail-with-body \
  'https://app.dureach.com/api/v2/webhooks?limit=25' \
  -H 'Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN' \
  -H 'Accept: application/json'

密钥属于创建它的活动 workspace，不能跨越 workspace 边界。如果请求返回 401，且密钥可能泄露，请撤销密钥、创建替代密钥并更新服务端 secret。

API 密钥端点

所有 API 密钥端点位于 /oauth/service-accounts 下，需要相应的 OAuth business scopes scope（或 all:*）。

POST /oauth/service-accounts

创建密钥。请求需要非空的 name（最多 255 个字符）和非空的 scopes 数组。scope 名称必须有效且不能重复。完整的 key 值只在此响应中返回。

{
  "name": "Reporting integration",
  "scopes": ["campaigns:read", "campaigns:create"]
}

{
  "id": "0199f372-efec-7c2d-af53-85ab8eab7c73",
  "name": "Reporting integration",
  "scopes": ["campaigns:read", "campaigns:create"],
  "key": "dureach_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "workspace_id": "0199f372-efef-73e5-b1ed-e2d1fbe4654d",
  "timestamp_created": "2025-10-17T18:33:40.079Z",
  "timestamp_updated": "2025-10-17T18:33:40.079Z"
}

GET /oauth/service-accounts

列出活动 workspace 中的密钥。查询参数：

响应包含 items，有下一页时还包含 next_starting_after。后续读取只返回安全的密钥前缀，不会返回原始 secret。

DELETE /oauth/service-accounts/{id}

撤销密钥。响应包含已删除密钥的元数据和安全前缀。将成功删除视为永久操作，并从 secret manager 中删除密钥。

Webhook 端点

Webhook 端点位于 /api/v2，需要 webhooks:*（或 all:*）以及包含 webhook 的套餐。

GET /api/v2/webhooks

列出 webhook 目标。支持的筛选器是 campaign（活动 UUID）和 event_type。使用 limit 和 starting_after 进行游标分页。页面大小为 1-100，默认为 25。响应为：

{
  "items": [
    {
      "id": "0199f372-efec-7c2d-af53-85ab8eab7c73",
      "campaign": "0199f372-efef-73e5-b1ed-e2d1fbe4654d",
      "name": "Interested lead receiver",
      "target_hook_url": "https://example.com/dureach-hook",
      "event_type": "lead.interested",
      "custom_interest_value": null,
      "timestamp_created": "2025-10-17T18:33:40.079Z"
    }
  ],
  "next_starting_after": "0199f372-efec-7c2d-af53-85ab8eab7c73"
}

POST /api/v2/webhooks

创建目标。发送 target_hook_url、name、event_type；如果事件是自定义兴趣标签，还要发送 custom_interest_value。接收 workspace 级事件时，campaign 可选。

GET /api/v2/webhooks/{id}, PATCH /api/v2/webhooks/{id}, DELETE /api/v2/webhooks/{id}

读取、更新或删除一个目标。PATCH 接受与创建相同的字段，只更改已提供的字段。更新后确认目标；删除目标不会删除历史投递事件。

GET /api/v2/webhooks/event-types

返回标准事件类型和活动 workspace 可用的自定义 lead 标签事件。将返回的 id 用作 event_type，不要硬编码可能改名的自定义标签。

POST /api/v2/webhooks/{id}/test

发送测试投递。成功响应包含 success: true、status_code: 200、response_time_ms 和 error: null。先对非生产接收器进行测试。

GET /api/v2/webhook-events

列出投递尝试。使用 success=true|false 或 webhook_url 筛选。使用 limit（1-100，默认为 25）和 starting_after。事件包含 payload、status_code、success、retry_count、will_retry、timestamp_next_retry、error_message、retry_successful、lead_email 和 response_time_ms。写入应用日志前脱敏 payload 和 lead_email。

GET /api/v2/webhook-events/{id}

按 UUID 读取一次投递尝试。

GET /api/v2/webhook-events/summary 和 GET /api/v2/webhook-events/summary-by-date

返回聚合投递状态。摘要包含 total_events、successful_events、failed_events、success_rate 和 failure_rate。日期摘要返回 items 数组，每天一条记录。用于监控，不用于重放事件。

联系人获取端点

联系人获取服务目前在 /api/v1/leadbank 下提供独立计量的旧版端点。可用性取决于 workspace 权限：

搜索和列表响应可能很大。始终发送文档规定的页面或 limit 参数，并在没有下一页时停止。空结果只表示该查询没有匹配项，不能证明不存在某个人或公司。

请求规范

使用文档规定的方法和路径，发送前验证字段，遵循游标或页面限制，并分别处理 401、403、验证、速率和服务器错误。让 webhook consumer 幂等：确认前保存事件 ID，临时失败后安全重试。

错误

API 密钥管理返回包含 statusCode、error 和 message 的 JSON；较新的端点还可能包含机器可读的 code。将 400 视为输入无效，401 视为缺少、无效或已撤销的身份验证，403 视为 scope、角色、workspace 或套餐失败，404 视为未知资源，409 视为状态冲突，429 视为速率或用量限制。只在临时 5xx 失败后重试有界且幂等的请求；不要盲目重试 4xx。

故障排查清单

1. 确认基础 URL https://app.dureach.com 和正确的路径版本。
2. 发送 Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN；不要使用查询字符串密钥。
3. 检查密钥 scope 和活动 workspace，然后确认套餐包含该端点。
4. 验证 UUID、必填字段、limit 范围和 starting_after 游标。
5. 记录状态、已脱敏的 message 或 code、请求时间和端点，以便支持。
6. 如果密钥暴露，请撤销并更换。不要发送密钥或未脱敏的 webhook payload。

端点工作流

1. 在 Settings → Integrations 中创建 API 密钥，并选择最小 scope。
2. 使用 Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN 和 Accept: application/json 发送只读请求。
3. 编写集成前验证响应结构，保留 items、UUID、enum 和 next_starting_after。
4. 严格按返回值使用游标分页，游标缺失时停止。
5. 通过在确认投递前保存事件 ID，让 webhook consumer 保持幂等。

请求字段规则

使用有界的正数 limit、有效 UUID、文档规定的事件类型和完整的必填 JSON 字段。不要将密钥放入查询字符串、浏览器 bundle、截图或日志。

Campaign 和 lead API

以下是使用 workspace 范围 OAuth service account 可调用的 campaign 和 lead 操作。在 Settings -> Integrations 创建 key，仅在首次显示时保存，并存放在服务端。Workspace 套餐必须包含 API 访问权限。以下请求使用 https://api.dureach.com。

先发送只读请求：

curl --fail-with-body 'https://api.dureach.com/api/v2/campaigns?limit=10' \
  -H 'Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN' \
  -H 'Accept: application/json'

Campaign 列表返回 items，也可能返回 next_starting_after。下一页请求原样传入该游标。limit 最大为 100。读取或更新单条记录时使用响应中的 UUID。

添加 lead 时，向 POST /api/v2/lead/add 发送以下 JSON：

{
  "campaign_id": "CAMPAIGN_UUID",
  "leads": [{"email": "[email protected]", "first_name": "Jane"}]
}

使用 GET /api/v2/lead/get?email=jane%40example.com&campaign_id=CAMPAIGN_UUID 查找 lead。修改状态时，向 POST /api/v2/lead/update/status 发送 campaign_id、email 和 new_status。创建和更新 campaign 使用 JSON；日程和序列必填字段见 OpenAPI schema。

Key 绑定到创建它的 workspace。不同的 X-Workspace-ID 会被拒绝。缺失或无效 key 返回 401；权限不足或 workspace 不匹配返回 403。分别处理验证错误和速率限制。不要把 key 放在 URL、浏览器 bundle、截图或日志中。

OpenAPI 规范列出了这七项操作的请求字段、响应和 bearer 认证方式。