terra-vantage

Terra API Vantage

Vantage API 是一个用于管理血液检测和 DNA 诊断产品、处理订单并交付检测结果的平台。它让医疗服务提供商、实验室和合作伙伴能够将诊断检测直接嵌入自己的应用中，同时由 Terra API 处理运营方面的复杂工作：试剂盒供应商集成（无最低订购量要求）、物流和配送、合规，以及将结果标准化为 FHIR 格式。

可用性与开通。 Vantage 在英国和美国提供服务，德国、西班牙和法国则标记为即将推出。开通需人工处理，并非自助服务：请联系 Terra API 启用您的凭证（参见账户设置）。访问权限从沙盒环境开始；正式上线时会另行启用生产环境。

从示例应用开始

对于新应用，请从已发布的诊断商店与运营控制台示例开始，并根据用户需求进行调整。运行 terra version，如果缺少 CLI，则可选择安装（见下文）。然后列出当前目录，并克隆最符合需求的示例：

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

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

账户工具：CLI 或 MCP

账户工具不会调用 Vantage 的订单、产品或结果端点：这些端点仍由你自己的客户端调用，而 terra data-api 没有 Vantage 路径。账户工具的作用是提供 Vantage 凭据，并设置环境的 Vantage API 版本。

凭据。 Vantage 使用与所有其他 Terra API 产品相同的 dev-id 和 API 密钥进行身份验证：

terra environments list                                # which dev-ids exist
terra environments retrieve-api-key --env <dev-id>     # dev-id and API key for Basic auth

这些就是下方 Authorization: Basic base64(DEV_ID:API_KEY) 中的 DEV_ID 和 API_KEY，因此 Agent 可以获取它们，而不必让人从控制面板中复制出来。Sandbox 和生产环境使用不同的 Vantage 主机，但共享同一组账户凭据。

retrieve-api-key 会打印密钥，而打印正是该命令的全部用途，因此只有在即将有程序使用该值时才运行它。它还会返回 webhook 签名密钥。在 CI 中，应将其通过管道传给使用方，而不要让它出现在作业日志中，并使用 --select 仅提取所需字段。通过 MCP 调用时，environments_read 配合 method: "retrieve_api_key" 会将同一对值返回到对话中，因此如果只需将值写入文件，优先使用 CLI。

API 版本。 Vantage 响应结构按日期进行版本管理，环境中固定的版本决定了所有未发送 X-Terra-Version 标头的请求的响应结构，以及每次 webhook 投递的响应结构（该标头对 webhook 从不适用）：

terra vantage api-version retrieve --env <dev-id>                          # pinned, latest, and every version you can move to
terra vantage api-version update --env <dev-id> --version <date> --dry-run # preview the change

更新会在环境的下一次 Vantage 请求时生效，无论新版本比当前固定版本更早还是更新，并且无法取消固定版本。由于此操作会改变 webhook 处理程序收到的结构，只有在处理程序同时接受两种结构后才应更改固定版本，并通过每次投递附带的 X-Terra-Version 标头区分两者。请阅读版本管理，了解各版本的变更内容。

在编码 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 调用。

身份验证

Vantage 使用标准的Terra API 凭据（Terra API 控制面板中的 dev-id 和 API 密钥——与所有其他 Terra API 产品使用的凭据相同），并在每个需要身份验证的端点上通过以下任一方式传递：

1. HTTP Basic（文档中的方式）：用户名 = dev-id，密码 = API 密钥，即 Authorization: Basic base64(DEV_ID:API_KEY)。旧版文档将它们称为 CLIENT_ID/CLIENT_SECRET，值相同。
2. 标头对：dev-id: <id> + x-api-key: <key>。

401 = 凭据错误或未知；403 = 账户已暂停、无权访问 Vantage、订购了目录中已禁用的产品，或在生产环境中调用 simulate 端点。

基础 URL（以下所有 API 路径均位于 /api/v1 下）：

环境	基础 URL
生产环境	https://vantage.tryterra.co
Sandbox	https://vantage-sandbox.tryterra.co

从下单到获取结果的工作流

一次集成会将检测从产品目录一路流转到结果确认。产品目录分为三级（产品类型包含产品，产品包含变体），变体是接收者实际收到的具体项目。

1  GET  /api/v1/products                       -> list product types (e.g. Blood Test)
2  GET  /api/v1/products/{product_type_id}     -> products within a type
3  GET  /api/v1/products/{product_id}/variants -> variants of a product
4  POST /api/v1/orders                         -> place order (variant_id + quantity + recipient)
5  (webhooks)                                  -> fulfillment + results status changes
6  GET  /api/v1/results/{order_item_id}?test_taker_id= -> presigned FHIR download URL
7  POST /api/v1/results/{order_item_id}/acknowledge?test_taker_id= -> MANDATORY, user-triggered

下单会返回 201，其中包含 order_id、recipient_id，以及每个商品对应的一个 order_item_id。新订单的 order_status: "order.payment_processing"（order.processing 是后续状态，只有付款完成后才会进入），每个商品的初始状态为 results_status: "results.awaiting_sample"。后续所有操作都应使用 order_item_id 进行跟踪，因为结果、激活和确认都是针对单个商品的。

references/api-reference.md 将各项目标对应到其端点（包括订单/结果索引、实验室查询、产品目录整理和监控端点），以及包含当前请求/响应架构的在线文档页面；实现任何端点调用前请先阅读，并在构造请求体时获取所链接的 .md 页面。

样本采集方式

每个订单都会设置一个 collection_type，用于确定如何采集样本以及适用的地址字段：

collection_type	含义	地址字段
AT_HOME	将试剂盒寄给接收者；接收者自行采集样本，并遵循试剂盒说明	shipping_address
GO_TO_LAB	在采血点（Patient Service Center）采集样本	requested_lab_address

对于 GO_TO_LAB，请求的实验室地址会用作代理信息，将订单分配到最近的可用实验室；GET /api/v1/labs?zip_code= 会列出附近的采血点（美国），供用户提前选择。要将订单绑定到用户选择的地点，请在 POST /orders 时将该行的 code + address.postal_code 作为 requested_lab 传入，响应随后会携带 confirmed_lab（完整地点详情）；如果代码未知，则会返回 400，且 invalid_fields 标签为 unknown_lab_code（重新获取 /labs 并重新选择）；如果查询暂时不可用，则会接受未绑定实验室的订单（confirmed_lab 为 null，GET 响应中会回显 requested_lab）。响应中的 confirmed_lab_address 是距离请求地址最近的采血点（尽力匹配，也可能为 null；仅供参考，不代表绑定预约）。变体会通过 available_collection_types（包含字符串 "AT_HOME"/"GO_TO_LAB" 的数组）声明其支持的采集方式，并通过 supported_ship_to_countries（ISO-3166 两字母国家代码；对于 AT_HOME，指收货目的地；对于 GO_TO_LAB，指所请求实验室所在国家）声明可下单的国家/地区；下单前应据此限制采集方式选择和地址表单。

试剂盒激活

部分供应商要求最终用户自行激活试剂盒（例如扫描包装上的 QR 码），实验室才会处理样本。QR 码中嵌入了 GET /api/v1/orders/activate?kit_id={supplier_item_id}，该地址会提供一个 HTML 激活表单；表单会提交到 POST /api/v1/orders/activate（JSON 请求体；如果你拥有 UI，也可以通过程序生成）。这两个激活路由均无需身份验证。激活成功后会发出 results.kit_activated webhook，其中包含新分配的 test_taker_id——请务必记录；每次查询结果都需要它。

确认结果（必需）

确认结果不是可选项。从低到高的所有临床升级级别的结果，都必须在患者能够查看之前得到明确确认；并且必须由最终用户在查看结果后通过按钮或复选框明确触发调用，绝不能在后端检索结果时自动触发。

POST /api/v1/results/{order_item_id}/acknowledge?test_taker_id={id}

结果未确认会导致以下两种后果：

• 责任将转移给你。 未能确认结果会“引发一连串责任转移，直接由你承担”；对于因结果延迟或未确认而导致的不良后果，你的组织将承担全部责任。
• 供应商可能直接联系患者。 升级结果带有 acknowledgment_due_by 截止时间；如果结果仍未确认，检测供应商和医疗团队有权直接联系患者。

FHIR 结果结构以及获取和确认端点的详细信息见 references/results.md；构建结果检索或确认步骤时请阅读该文档。

Webhook

Terra API 会将订单和结果进度发送到每个环境注册的 HTTPS webhook URL（PATCH /api/v1/clients/webhook-url；可通过 GET 读取）。event_type 分为两类：用于履约进度的 order.status_changed，以及用于单项结果进度的 order_item.results_status_change。Webhook 使用 X-Terra-Signature 标头进行 HMAC-SHA256 签名；在信任请求之前，请务必验证每个请求。投递采用至少一次机制，并会重试；请按 event_id 去重并尽快返回 2xx。

references/webhooks.md 中介绍了每种事件类型及其完整载荷、状态枚举、签名验证以及重试和调试机制。构建或验证 webhook 处理程序，或遇到投递似乎丢失的情况时，请阅读该文档。

使用 Sandbox

有两种方式可推动 sandbox 订单完成其生命周期：

• simulate 端点（测试首选）。 使用 {"event": "...", "order_item_id": "..."} 调用 POST /api/v1/orders/{orderID}/simulate，即可应用一个生命周期事件，其效果与供应商更新完全一致——记录状态历史，并发送已签名的 webhook。事件包括：payment_complete、payment_failed、processing、delayed、cancelled、delivery_fulfilled、completed、kit_activated、sample_processing_in_lab、sample_rejected、partial_results_ready、results_ready、lab_processing_error、escalation_raised。只接受有效的向前状态转换（否则返回 422）；results_ready 还会存储样本结果，以便端到端测试下载和确认流程。在生产环境中会返回 403。
• 模拟供应商流程。 sandbox 供应商会按计时器推进订单：运输 webhook 通常会在约一分钟内到达；激活试剂盒后，结果 webhook 会以 1–2 分钟的间隔陆续到达。激活需要通过浏览器完成：打开 https://vantage-sandbox.tryterra.co/api/v1/orders/activate?kit_id={supplier_item_id}（supplier_item_id 会随 sandbox webhook 一起发送）并完成表单。顺利流程是确定性的（results_ready）；如需测试拒收情况，请使用 simulate。

Sandbox webhook 会在 order.status_changed 载荷中添加 supplier_item_id；生产环境的载荷不包含该字段（可从 GET /api/v1/orders/{orderID} → items[].supplier_item_id 中获取）。

易踩问题

• ID 是 JSON 字符串。 订单响应和 Webhook 中的 order_id、order_item_id、recipient_id、test_taker_id、variant_id 和 event_id 都是以字符串序列化的 64 位雪花 ID，切勿将其解析为数字（JavaScript 会导致数据损坏）。目录读取（/products*）仍会返回数值型 id 字段；订单请求中的 variant_id 则必须是字符串。
• 两种场景使用同一套术语。 REST 读取和 Webhook 负载使用相同的 order.* 履约状态（支付失败 = order.payment_failed）和相同的 results.* 状态：Webhook 状态与 REST 读取中的状态完全一致。（历史情况：Webhook 曾使用 fulfillment.*，REST 曾使用 order.failed；两者现已废弃。）
• 签名时间戳的单位是 Unix 秒。 X-Terra-Signature: t=<unix_seconds>,v1=<hex>；如果将 t 当成毫秒处理，每次验证都会失败。请基于原始请求体进行签名校验。
• 读取或确认结果时必须提供 test_taker_id。 两个端点都将其作为查询参数；该参数最早出现在 results.kit_activated Webhook 中。
• 创建订单时请发送 Idempotency-Key 标头（每次尝试使用唯一值）：使用相同键和请求体重试会重放原始结果，而不会重复下单；相同键搭配不同请求体会返回 409。如果不带该标头，服务器不会进行去重（client_order_reference_id 仅用于对账）：遇到结果不明的失败时，请先列出近期订单并根据你的引用进行匹配，再重试。
• 预签名结果 URL 会在 15 分钟后过期。 请重新获取以生成新 URL，不要缓存该 URL。
• 目录筛选会阻止下单。 PUT /api/v1/products/selection 是全量写入；从筛选结果中移除的产品不会出现在读取结果中，对其下单会返回 403。
• Sandbox 和生产环境使用不同的 Webhook URL，并且需要分别在每个环境中启用访问权限（先启用 Sandbox）。
• 固定的 API 版本决定 Webhook 的结构，请求标头无法覆盖 Webhook 所用版本。 请求中的 X-Terra-Version 只会改变该请求的响应；Webhook 投递始终使用环境固定的版本。在编写解析器前，请通过 terra vantage api-version retrieve 检查版本，并将每次投递的 X-Terra-Version 标头与请求体一起保存。

在线文档

references/api-reference.md 将每个端点对应到其参考页面。以下指南值得完整阅读：

• 什么是 Vantage API？
• 账户设置与身份验证
• 版本控制
• 使用 Sandbox
• 确认结果
• 最佳实践
• 上线生产环境

获取页面前，请先运行 terra docs ask（或通过 MCP 运行 docs_ask）：它会根据文档作答并注明来源。任何文档 URL 后面都可以加上 .md，以获取 Markdown 格式。