流程、账号与托管

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

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

新建订阅

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

在设置 › API 复制 OData 地址（…/v1/odata）。
Power BI：获取数据 › OData 源；Excel：数据 › 获取数据 › 来自 OData 源。粘贴地址。
身份验证选「基本」：用户名随意，密码填你的 API 密钥。
可用的表有 Cases（事项）、CaseSteps（步骤）、Metrics（指标）和 MetricMonths（指标按月）。看到的只是这个密钥所属的人在员工端能看到的内容，最多 50,000 个事项，每页 1,000 行。
筛选和排序请在 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 请求头里。