AC 商品知识库

如何通过 agent 采购

这个站点是只读的：没有购物车、没有结账按钮，也不处理支付。 它负责被搜到、被引用；下单这件由 agent 通过 AC 的交易接口完成， 并且必须你确认总价之后才会真的提交。

下单前的人工确认是我们这边的硬门槛，护栏在服务端的 do_* 逻辑层， 任何客户端都绕不过去：未确认的下单请求会被拒绝，服务端会把总价卡片带回来让你确认。

一、直接对 agent 说人话

把商品页里的「复制采购需求」粘给任意 agent，或者照下面这样说：

帮我买 apple-juice 这件商品 2 件，
送到 <城市+邮编>，预算不超过 <金额> default-channel 渠道的价格确认合规后下单。
下单前先把总价、运费、预计时效报给我，我点头再提交。

二、只读接口（查商品，不建单）

下面这些接口只做读取，不会创建 checkout，可以放心让第三方 agent 调。

分页商品索引 GET /agent/products.json?first=24&after=<cursor>&q=<关键词>
单商品机器副本 GET /agent/product/<slug 或 SKU>.json
接口自描述 GET /agent/openapi.json
MCP 端点（12 个工具） https://liferay.store/mcp

返回结构（节选）

{
  "slug": "apple-juice",
  "channel": "default-channel",
  "availability": "in_stock",
  "price_range": { "text": "1.99 USD", "min": { "amount": 1.99, "currency": "USD" } },
  "attributes": [{ "name": "Flavor", "value": "Apple" }],
  "variants": [{
    "sku": "...", "price": { "text": "1.99 USD" },
    "quantity_available": 50,
    "stocks": [{ "warehouse": "Oceania", "quantity": 209, "in_stock": true }]
  }],
  "purchase_request": "请用 AC 采购 agent 帮我完成下单：..."
}

金额一律是字符串 + 数值两份都给：text 用于展示（服务端给的原文）， amount/currency 用于机器判断。请不要在客户端自行计算总价。

三、下单（走交易侧，须人工确认）

本站点不提供结账入口。交易能力挂在这些地址上， 它们的护栏与本站说的完全一致（同一套 do_* 逻辑）：

ACP 结账会话 POST https://api.liferay.store/acp/checkout-session
MCP 工具调用 https://liferay.store/mcp
对话入口 https://api.liferay.store/chat

下单顺序（顺序不能改）

search_products → get_variants → create_or_update_checkout
  → set_address → list_delivery_options → set_delivery
  → request_payment_confirmation        # 先把总价给用户看
  → 用户明确确认
  → request_payment_confirmation(confirmed=true) → place_order（带幂等键）
两个坑（实测）：没设收货地址时服务端不报运费； 美国地址必填 postal_code 与 country_area。 金额一旦变化（改数量、换配送、用优惠码），之前的确认会自动失效，必须重新确认。

四、给抓取者的约定