> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clinkbill.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Catalog 与 UCP Checkout

> 商品搜索、结账、订单与数字交付的补充 MCP 接口参考。

这些工具是 [Wallet Service](/cn/guides/agent/wallet_service) 和 [Browser Pay](/cn/guides/agent/browser_pay) 之外的补充能力。已连接服务端的当前规则为用户请求选择 Catalog 或 UCP Checkout 时，使用对应工具。搜索结果不代表用户已授权购买。

本页介绍主要参数，完整 schema 通过 `tools/list` 获取；工具调用方式见 [MCP 连接与 OAuth](/cn/guides/agent/mcp_integration)。即使工具没有额外 Scope 要求，也需要正常的 MCP 认证连接。

## 搜索与商品详情

| 工具 | 主要参数 | Scope | 用途 |
| :- | :- | :- | :- |
| `discover_catalog` | `query`；可选 `catalogLanguage`、`limit` 及下述范围、分页字段 | `wallet:read` | 跨支持的目录搜索商品的主入口。 |
| `list_catalog_merchants` | `{}` | 无额外 Scope | 用户需要商户目录或限定具体商户时，查询已注册的 Catalog 商户。 |
| `get_product` | `productId`、`target`；可选 `selected`、`preferences`、`catalogLanguage` | `wallet:read` | 获取确定商品的详情和必选项，复用结果返回的 `target`。 |
| `parse_product_item` | `productUrl` | 无额外 Scope | 从支持的外部 HTTPS 商品链接取得已选 SKU 信息。 |
| `search_catalog` | `merchantId`、`query`；可选 `limit` | `wallet:read` | 已知注册商户的兼容搜索接口。新接入使用 `discover_catalog`。 |

### 搜索商品

`tools/call` 参数示例：

```json theme={null}
{
  "name": "discover_catalog",
  "arguments": {
    "query": "咖啡券",
    "catalogLanguage": "zh-Hans",
    "limit": 5
  }
}
```

| 参数 | 含义 |
| :- | :- |
| `query` | 必填，非空的用户搜索请求。 |
| `catalogLanguage` | 请求语言的 BCP 47 标签，例如 `en-US` 或 `zh-Hans`。 |
| `merchantId` | 限定为从 `list_catalog_merchants` 选出的已注册商户；广泛搜索时省略。 |
| `order_channel_id`、`storeId`、`channelType` | 已从权威结果取得的外部门店范围，不根据名称推测 ID。 |
| `sources` / `provider` | 明确的数据来源，或续查时的具体 provider，使用服务返回或支持的值。 |
| `cursor` | 不透明的续查游标。广泛搜索的续查需要且只能指定一个第三方来源，保留返回的来源与游标。 |
| `limit` | 正整数，最大 100。广泛搜索默认跨来源合计返回 10 个商品。 |

注册商户范围不能与外部门店或 provider 范围混用。结果可能包含 `groups`、`provider_results` 和精确的商品 `target` 对象。调用 `get_product` 时保留原始 target；门店 ID 不等于注册商户 ID。

纯搜索不创建购买授权，也不发起支付。结账前确定商品规格和必选项。按返回或解析结果注明的单位使用价格，已经是最小货币单位的金额不要再乘以 100。

## UCP Checkout

用户选择 UCP Checkout 购买后，先按已连接服务端的规则处理购买授权。如果指定预算需要预授权，在搜索前激活匹配的购买指令；未指定预算时，可先由结账返回实际总额，再完成授权。

1. 从 Catalog 获取确定的商品，或解析商品链接。
2. 确定 SKU、选项、数量和履约要求。
3. 调用 `create_checkout`，按 `next_action` 补充信息、授权消费或确认摘要。
4. 使用 `update_checkout` 修改当前结账支持的字段，重新查看并确认更新后的摘要。
5. 针对当前确认调用一次 `complete_checkout`。结果仍在等待或响应丢失时，读取 `get_operation`。
6. 查询返回的 UCP 订单；数字商品按需等待交付。

### 主要结账参数

| 工具 | 主要参数 | Scope |
| :- | :- | :- |
| `create_checkout` | `merchantId` / `merchantUrl` 二选一；`items` 与 `fulfillmentType`，或原生 `line_items` 与 `fulfillment`；可选 `buyer`、`shippingAddress`、`couponCode`、`buyerNote` | `wallet:read`、`payment:execute` |
| `update_checkout` | `operationId`、当前 `actionId`、`expectedRevision` 和要更新的字段 | `payment:execute`；恢复购买指令设置时还需要 `wallet:read` |
| `complete_checkout` | `operationId`、当前 `actionId`、`expectedRevision`；可选 `maxWaitSeconds`（0–60） | `payment:execute` |

使用 `create_checkout` 的 `items` 形式时：

* **注册商户**：使用返回的商户 ID、商品 ID、数量与已选选项。价格由 Catalog 提供，省略外部 `currency`、商品 `title` 和 `unitPriceMinor` 字段。
* **外部商品**：商品 URL 放入 `merchantUrl`，提供 `currency`，并填写每件商品的准确 `title` 与 `unitPriceMinor`。保留结果返回的 `order_channel_id`。缺失信息先通过 `get_product` 或 `parse_product_item` 获取，再创建结账。
* **履约**：需配送的实物使用 `PHYSICAL_GOODS_REQUIRES_SHIPPING` 并提供完整配送信息；不需配送时使用 `NO_SHIPPING_REQUIRED`。履约类型不明确时先向用户确认。

`create_checkout` 只准备结账，不完成支付。`update_checkout` 会使旧确认失效。`complete_checkout` 使用当前确认标识，不能在此替换金额或支付卡。兼容字段 `paymentInstrumentId` 在 Checkout 中被忽略，结账使用钱包默认卡。

购买授权工具及金额单位见 [Wallet Service 工具](/cn/api-reference/mcp/wallet)。Operation 标识、版本和恢复方式见 [Operation](/cn/api-reference/mcp/operations)。

## 订单与交付

| 工具 | 参数 | Scope | 结果 |
| :- | :- | :- | :- |
| `get_order` | `orderId`：使用结账 Operation 中的 `resources.ucp_order_id` | `payment:execute` | UCP 订单，包括履约、调整和数字交付状态。 |
| `wait_for_digital_delivery` | 同一 UCP `orderId`；可选 `maxWaitSeconds`（1–900） | `payment:execute` | 交付就绪、失败或有界等待超时。超时后沿用同一订单 ID 继续等待。 |

部分服务端版本将此 UCP 订单读取工具命名为 `get_ucp_order`。调用时使用当前连接的服务端 `tools/list` 返回的准确名称。

支付完成与交付完成是不同状态。查询订单或等待交付不会重试支付。

UCP 订单 ID 与 Clink 直接支付订单 ID 指向不同记录，不能互换，也不要假设 UCP 订单 ID 可以直接传给 Clink 退款工具。这组 UCP 工具没有提供通用的取消订单或退款操作。

## 区分支付流程

UCP Checkout 通过 `complete_checkout` 及其 Operation 完成。Browser Pay 获取凭证后，在商户网站付款，再通过 `confirm_result` 上报观察到的结果。UCP Checkout 完成后不要调用 Browser Pay 的 `confirm_result`。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.