terra-unified-api

Terra API 最佳实践

经生产环境验证的 Terra API 开发指南，按影响分为 5 个类别。

从示例应用开始

对于新应用，请从已发布的示例开始，该示例涵盖可穿戴设备连接、Webhook 接收和健康仪表板，然后根据用户需求进行调整。运行 terra version；如果缺少 CLI，请提出安装建议（见下文）。然后列出当前目录并克隆最合适的示例：

terra examples list --select name,title,description
terra examples clone unified-api-web-app my-app

这两种方式都无需登录。阅读下载内容中的 README 和 AGENTS.md，并按照 next_steps 安装依赖、完成配置并运行应用，然后再基于它进行开发。克隆操作只会下载文件。对于现有应用，请将示例用作参考，并在原有位置调整相关部分。对于无法运行 CLI 的聊天助手，请提供这些命令，让用户在自己的终端中运行，或链接到源代码：https://github.com/tryterra/terra-examples/tree/main/examples/unified-api-web-app。

账户工具：CLI 或 MCP

对于以下规则，账户工具可用于核实 Terra API 实际执行的操作，而不只是你预期它执行的操作：

terra unified-api destinations list --env <dev-id>        # where webhooks go, and whether they are active
terra events list --env <dev-id> --outcome failed         # deliveries your endpoint rejected
terra events retrieve-payload <event_id> --env <dev-id>   # the exact body that was sent
terra users list --env <dev-id> --reference-id <ref>      # connection state, one row per provider
terra unified-api data scopes list --env <dev-id>         # which fields a payload will carry

其中有两项会改变你的测试方式。terra events retrieve-payload 是判断“载荷缺少某个字段”的事实依据：如果字段在这里不存在，原因就在于环境的数据权限范围，而不是你的处理程序。terra events resend --event-id <id> --event-type sleep --user-id <uuid> 会将真实存储的事件重新发送到你的端点，因此可以使用真实载荷测试处理程序，无需设备，也无需等待服务提供商同步。重新发送的事件可能会到达两次，因此处理程序必须具备去重能力（rules/webhooks-dedupe-terra-reference.md）。

这些规则验证所用的签名密钥由 terra unified-api destinations create 在创建时返回，且只返回一次。

通过 MCP 使用时，其中两项的行为有所不同。events_read 配合 method: "retrieve_payload" 需要 MCP 访问级别（仅有读取权限无法读取载荷正文），而且载荷属于用户的健康数据，会进入对话。unified_api_destinations_write 的 create 返回的 signing_secret 也会进入对话，因此应优先使用 CLI，让密钥直接进入处理程序的密钥存储区。

在编码 Agent（Claude Code、Codex、Cursor 等，无论是在用户的设备上还是云端）中，请使用 CLI；如果尚未安装，请提出安装建议：在 macOS 和 Linux 上运行 curl -fsSL https://cli.tryterra.co/install.sh | sh，在 Windows PowerShell 中运行 irm "https://cli.tryterra.co/install.ps1" | iex；如果用户已在使用 Homebrew 或 npm，也可以通过它们安装。在聊天助手（claude.ai、Claude Desktop、ChatGPT）中，请使用 Terra API 管理 MCP 服务，即使它能够运行代码也是如此：其沙盒无法安装 CLI 或登录。每条管理命令都对应一个工具，其名称和 method 表明命令的含义（terra users list 对应 users_read，且 method 为 "list"）。只有 CLI 支持 terra data-api、terra admin-api 和 terra examples；--select 和 --jq 则没有对应的 MCP 功能。terra-cli 和 terra-mcp 技能提供安全措施（确认更改、避免凭据进入对话记录）、错误说明，以及针对各项任务的操作指南。它们负责管理集成，但不能替代本技能所述的 API 调用。

按优先级划分的规则类别

优先级	类别	影响	前缀
1	Webhook 处理	严重	webhooks-
2	数据处理与幂等性	严重	data-
3	身份验证与连接生命周期	高	auth-
4	多设备数据	中	devices-
5	测试	低至中	testing-

快速参考

1. Webhook 处理（关键）

• webhooks-verify-raw-body – 在解析 JSON 之前，基于未经修改的原始请求体验证签名标头 HMAC（terra-signature / X-Terra-Signature，读取时不区分大小写）
• webhooks-ack-within-timeout – 在超时时间内（默认 8s）返回 200，并异步处理
• webhooks-dedupe-terra-reference – 根据 X-Terra-Trace-Id 对投递进行去重；大型请求的所有分块共用 terra-reference
• webhooks-archive-raw-payloads – 将原始载荷归档到对象存储，并通过载荷键关联数据行
• webhooks-handle-informational-events – 明确路由非数据事件，解包 s3_payload 投递，并确保遇到未知类型时不会崩溃

2. 数据处理与幂等性（关键）

• data-natural-keys – 活动/睡眠数据以 summary_id 为键，每日类型数据以（连接、日期）为键，激素数据以时间戳为键
• data-date-part-only – 在进行任何时区转换之前，从 ISO 字符串中截取日期部分
• data-superset-overwrite – 标准字段遵循超集保证；当 X-Terra-Ordering-Timestamp 更新或相等时覆盖
• data-coalesce-enrichment-scores – 增强评分不遵循超集保证，使用 COALESCE，确保 null 不会覆盖现有值
• data-columns-over-blobs – 将指标提取到类型化列中，并将原始载荷保留在对象存储中
• data-timestamp-localization – 遵循 timestamp_localization 标志，并有意识地选择一种存储策略

3. 身份验证与连接生命周期（高）

• auth-reference-id – 将用户 ID 作为 reference_id 传递；它是每个 webhook 中的关联键
• auth-handle-all-events – 通过幂等 upsert 处理全部七种身份验证事件类型
• auth-reauth-id-swap – user_reauth 会签发新的 Terra API 用户 ID，请将旧 ID 替换为新 ID
• auth-parse-scopes – 解析逗号分隔的 scope 字符串；在 permission_change 时应用 scopes_added/scopes_removed
• auth-reconcile-connections – 在页面挂载、身份验证重定向和定时任务中，根据 Terra API 状态核对连接
• auth-integrations-endpoint-headers – 向公开集成目录发送 dev-id；否则会获取所有提供商，而不是已启用的提供商

4. 多设备数据（中）

• devices-expect-cross-device-duplicates – 同一会话会按设备分别到达，且 summary_ids 不同；合并策略由你的应用负责
• devices-enrichment-provider-agnostic – 增强评分与提供商无关且可比较，但仅在评分权重启用时才会提供

5. 测试（低至中）

• testing-mock-boundaries – 模拟 SDK、数据库和后台任务；让异步处理立即执行
• testing-cover-event-edge-cases – 测试重放、空数据数组、未知用户、type 0、增强评分为 null、重新身份验证时的 ID 替换

使用方法

处理某个领域时，请阅读 rules/ 中对应的规则文件。例如，编写 webhook 端点前，请先阅读 rules/webhooks-verify-raw-body.md 及其相关文件。每条规则都包含错误/正确的代码示例，以及相关的 docs.tryterra.co 页面链接。获取页面前，请先运行 terra docs ask（或通过 MCP 使用 docs_ask）：它会根据文档回答并注明来源。为任何文档 URL 添加 .md，即可获取 Markdown 格式。

相关技能

此技能涵盖 Unified API 集成的核心内容。其他 Terra API 产品各有自己的技能：terra-mobile-sdk（Apple Health、Samsung Health、Health Connect）、terra-streaming（通过 WebSocket 传输实时数据）、terra-planned-workouts 和 terra-routes（写入设备）、terra-lab-reports、terra-vantage（诊断测试下单）以及 terra-models。处理账户相关工作时，请使用 terra-cli 或 terra-mcp。AI Interface 则是独立的：它是一个 MCP 服务，可让你应用自己的 Agent 读取已连接用户的健康数据；而上文的管理 MCP 服务用于管理账户。