> For the complete documentation index, see [llms.txt](https://doc.duaer.com/zh/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.duaer.com/zh/api/process-signals.md).

# 把流程信号推送到其他系统：订阅、OData 和流程 API

让其他系统接收 Duaer 的流程信号：指标未达标、新的流程发现、新卡片和卡片拍板。Power BI 和 Excel 可以通过 OData 读取事项和指标，外部的智能体可以通过 API 了解每个指标的含义并触发数据来源刷新。
## 新建订阅

1. 打开设置 › API，在「流程信号订阅」里点「新建订阅」。只有组织的所有者和管理员能看到。
2. 填名称和接收地址。地址必须是 https，不能带用户名密码，也不能是内网或本机地址。
3. 勾选要接收的事件：指标未达标、新的流程发现、新卡片、卡片已拍板。
4. 设每日上限（1 到 100,000，默认 1,000），点「保存」。
5. 复制显示的签名密钥。它只显示这一次。每个组织最多 20 个订阅。

## 接收到什么

每个事件发一次 POST，正文是 JSON。请求头带 x-duaer-event、x-duaer-delivery、x-duaer-sequence 和 x-duaer-signature。正文只有编号、名称和数字，从不包含事项的列（客户名、金额等）。

```
{
  "id": "b3f1…",
  "sequence": 42,
  "event": "card.decided",
  "occurredAt": "2026-10-19T08:15:02.000Z",
  "organizationId": "…",
  "data": {
    "projectId": "…",
    "cardId": 318,
    "ruleId": "r-…",
    "caseId": "INV-1024",
    "title": "Invoice INV-1024 is overdue",
    "choice": "o1",
    "choiceLabel": "Paid",
    "decidedBy": "ana@example.com"
  }
}
```

## 校验签名

x-duaer-signature 的格式是 t=<时间戳>,v1=<签名>：签名是用订阅密钥对「时间戳.原始正文」做的 HMAC-SHA256。

```
// Node.js: check the x-duaer-signature header with the subscription's secret.
import { createHmac, timingSafeEqual } from 'node:crypto';

function verified(secret, rawBody, header) {
  const t = /(?:^|,)t=(\d+)/.exec(header)?.[1];
  const v1 = /(?:^|,)v1=([0-9a-f]{64})/.exec(header)?.[1];
  if (!t || !v1) return false;
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest();
  const given = Buffer.from(v1, 'hex');
  return given.length === expected.length && timingSafeEqual(given, expected);
}
```

## 重试、暂停和重发

- 接收方返回非 2xx 或连接失败时，分别在 1、5、30、120 分钟后重试，共 5 次，之后记为失败。
- 暂停期间的事件先保留，恢复后按编号发送；超过当天上限的，留到第二天（按 UTC 计）。
- 投递记录保留 30 天。可以「重发失败的」，也可以「从此编号起重发」。重试的事件可能晚于后面的事件送达，请按 x-duaer-sequence 排序。
- 新建、修改、删除和重发都记入审计日志，不记录密钥。

## 用 Power BI 或 Excel 读取（OData）

1. 在设置 › API 复制 OData 地址（…/v1/odata）。
2. Power BI：获取数据 › OData 源；Excel：数据 › 获取数据 › 来自 OData 源。粘贴地址。
3. 身份验证选「基本」：用户名随意，密码填你的 API 密钥。
4. 可用的表有 Cases（事项）、CaseSteps（步骤）、Metrics（指标）和 MetricMonths（指标按月）。看到的只是这个密钥所属的人在员工端能看到的内容，最多 50,000 个事项，每页 1,000 行。
5. 筛选和排序请在 Power Query 里读完后再做：这个源不支持 $filter 和 $orderby。

```
GET <DUAER_HOST>/v1/odata/Cases?$top=100&$count=true
Authorization: Basic base64("any:<your-api-key>")
```

## 流程 API

- GET /v1/process/metrics：这个人能看到的指标，带一句话含义、说明、单位、当前值、最近一个月和目标。
- POST /v1/process/sources/{id}/refresh：立即读取一次数据来源，和「立即运行」一样，返回 202。只有所有者和管理员的密钥能用。
- 密钥放在 Authorization: Bearer 或 X-DUAER-API-KEY 请求头里。
## Questions

### 能连 Power Automate、Logic Apps 或 Copilot Studio 吗？

专用连接器在下一步提供。现在可以用 HTTP 请求触发器接收订阅，或用 HTTP 操作调用流程 API。

### 为什么正文里没有事项的详细信息？

为了不把事项的列发到 Duaer 以外。需要详细信息时，用 API 密钥通过 OData 读取，只能读到这个人有权看的内容。

### 接收方停机一天会丢事件吗？

不会。5 次重试结束后记为失败，30 天内可以重发；暂停订阅也能先把事件留着。

## 相关

- [Duaer 公开 API 的身份验证](https://doc.duaer.com/zh/api/authentication.md)
- [Duaer 公开 API 端点参考](https://doc.duaer.com/zh/api/api-reference.md)
- [在 Duaer 里用一张指标表管指标](https://doc.duaer.com/zh/build/duaer-metrics.md)
- [在 Duaer 里看流程发现和 SOP 符合度](https://doc.duaer.com/zh/build/process-findings.md)
- [卡片的分派与升级：按部门或金额派给负责人，超期升级给主管](https://doc.duaer.com/zh/build/card-assignment.md)