quote_cart - Clawdot虾点·文档中心

quote_cart

对一个购物车里已选的商品算价：校验店铺 / 购物车 / 商品，调用上游算价，返回价格明细、是否可结算，以及供下一步预览使用的 quote_id。

下单链路：search_shops 得 shop_id + cart_id（已封装店铺与配送坐标）→ get_shop_menu 选商品 → quote_cart 算价得 quote_id → select_address 得 address_id → preview_order（可回传 quote_id）得 preview_id + confirmation_token → create_order。shop_id / cart_id / address_id 与商品 item_id 均来自上游接口，原样回传，不要自造。

参数

参数	类型	必填	默认	说明
`consent_grant_id`	string	是	—	用户授权 ID（`cg_` 前缀，来自 `verify_user_bind`），标识已授权用户
`shop_id`	string	是	—	店铺 ID（来自 `search_shops`）
`cart_id`	string	是	—	购物车上下文 ID（来自 `search_shops`，已封装店铺与配送坐标，故算价无需再传经纬度）
`address_id`	string	是	—	网关地址 ID（字符串），原样使用 `select_address` 返回的 `address_id`
`items`	array	是	—	商品列表（见下，至少一项）
`items[].item_id`	string	是	—	商品 ID（来自 `get_shop_menu`）
`items[].sku_id`	string	否	`null`	SKU ID（来自菜单项的可选 SKU）
`items[].quantity`	integer	是	—	数量，≥ 1
`items[].ingredient_option_ids`	string[]	否	`[]`	配料 / 做法选项 ID 列表（来自菜单项的可选项；非默认规格用该规格 `sku_options[].ingredient_options` 的 option_id）
`items[].ingredient_quantities`	array	否	`[]`	为某个选项指定份数，如「浓缩份数 x3」，格式 `[{option_id, quantity}]`；仅 `max_quantity` 大于 1 的选项可用，超出会下单失败。列在这里即视同已选，不必再写进 `ingredient_option_ids`；不传则按各选项的 `default_quantity`（商家推荐份数）
`items[].remark`	string	否	`""`	单品备注
`lang`	string	否	—	本次返回内容使用的语言，枚举 `zh` / `en` / `ja` / `ko` / `ru` / `ms` / `es`；不传则用绑定时设定的语言（默认中文）
`include_chinese`	boolean	否	false	为 `true` 时响应同时返回中文原文（`<key>_zh`），见双语响应

返回

所有金额字段单位为分（整数），不是元。例如 payable_price: 1200 表示 ¥12.00。

字段	类型	说明
`quote_id`	string	报价 ID（`qt_`），传给 `preview_order` 校验报价上下文
`can_checkout`	boolean	是否可结算（有不可结算商品、缺店铺必选组、商品数量低于起购份数、购物车内商品均为「单点不送」商品、或上游禁止结算时为 `false`）
`blocking_reason`	string \| null	不可结算原因（`can_checkout` 为 `true` 时为 `null`）；例如「需从『必选好汤』补选必选项再下单（每组至少选 1 项）」或未达起送价。缺店铺必选组见 `get_shop_menu` 响应的 `required_groups`
`blocking_code`	integer	机器可读失败码：`1` = 单点不配送（购物车内商品均为「单点不送」商品，商家不接受单独配送；此时 `blocking_reason` 通常为「单点不配送」或「商品不可单独下单」，建议搭配正常商品重新算价；基于上游文案 best-effort 识别）；`2` = 未选满店铺必选组（缺该店必选商品组，需按 `get_shop_menu` 响应的 `required_groups` 补选后再下单；`blocking_reason` 形如「需从『必选好汤』补选必选项再下单」）；`0` = 其余所有情况（含可结算）。仅供程序化分流，是否可下单以 `can_checkout` 为准
`goods_price`	integer	商品小计（分）
`delivery_fee`	integer	配送费（分）
`packing_fee`	integer	打包费（分）
`original_price`	integer	优惠前总额（分）= 应付 + 优惠；满足 `original_price − discount = payable_price`
`discount`	integer	优惠金额（分）
`payable_price`	integer	应付金额（分）
`minimum_order_gap`	integer \| null	距起送差额（分）；不适用时为 `null`
`shop.lat`	number \| null	店铺纬度，与 `get_shop_menu` 的 `shop.lat` 同源同值（取自菜单阶段随 `cart_id` 保存的店铺坐标）；坐标系同请求 `lat` / `lng`（高德 GCJ-02）；菜单阶段未取到坐标、或 `get_shop_menu` 上线本字段前铸的 `cart_id` 时为 `null`
`shop.lng`	number \| null	店铺经度，其余同 `shop.lat`
`items`	array	算价商品明细
`items[].item_id`	string	商品 ID
`items[].name`	string	商品名
`items[].quantity`	integer	数量
`items[].price`	integer	单品价（分）
`items[].min_purchase`	integer \| null	起购份数回显（≥ 1，`1` 无约束），供对照 `quantity` 自查；极少数兜底路径无法回查时为 `null`
`items[].available_quantity`	integer \| null	库存余量回显（份，菜单快照）：正整数=剩余可购，`0` 售罄，`null` 充足或未知；仅供展示参考，实际以下单校验为准
`items[].image_url`	string \| null	商品图 URL，无图为 `null`
`items[].specs`	array	该项已选规格，`[{name, value}]`（如 `{"name":"规格","value":"大杯"}`）；无规格时为 `[]`
`items[].selected_ingredients`	array	该项已选配料/做法，`[{group_name, name, price_delta, quantity}]`；`group_name` 可为 `null`，`price_delta` 为选 1 份的加价（分），`quantity` 为生效份数（未指定时＝该选项的 `default_quantity`）。加多份不是 `price_delta × quantity`，分档价见 `get_item_options` 的 `price_steps`；无则为 `[]`

错误码

code	说明
`CONSENT_GRANT_REQUIRED`	缺少用户授权（未传 `consent_grant_id`）
`CONSENT_GRANT_INVALID`	用户授权无效
`CONSENT_GRANT_EXPIRED`	用户授权已过期，需重新授权
`CAP_NOT_BOUND`	该 Agent 未开通对应能力
`CONSENT_GRANT_WRONG_CAP`	授权属于其它能力 / 提供方
`PUBLIC_REFERENCE_INVALID`	`cart_id` 无效或过期、`shop_id` 与 `cart_id` 不匹配，或 `item_id` 不属于该 `cart_id`。`address_id` 仅在主算价（`cats_price`）失败、回退到 `render_quote` 分支时才会校验，无效时也归到此码
`CART_PRICE_INVALID`	`items[].quantity` 非整数或小于 1。MCP 传入原始 dict 绕过 pydantic，由 service 内部校验
`ELEME_ERROR`	上游算价接口异常

完整错误码见错误处理。

调用示例

{
  "name": "quote_cart",
  "arguments": {
    "consent_grant_id": "cg_your_consent_grant",
    "shop_id": "<来自 search_shops>",
    "cart_id": "<来自 search_shops>",
    "address_id": "<来自 select_address>",
    "items": [
      {"item_id": "670685166551", "sku_id": "5014584502270", "quantity": 1}
    ]
  }
}