购物Agent API与电商MCP接入

先做有来源的商品候选清单，再接购买操作。

WebAZ提供公开HTTP商品发现接口，以及供兼容客户端使用的只读MCP入口。开始选品不需要凭据、钱包或订单。本指南面向已有agent的开发者，不承诺所有助手都支持自定义工具。

从一个匿名HTTP请求开始

在终端运行以下只读请求。SG表示配送国家，q为搜索文本。保留返回的币种和缺失字段，不擅自补全。

curl --fail --max-time 15 --get \
  'https://webaz.xyz/api/products' \
  --data-urlencode 'q=umbrella' \
  --data-urlencode 'ship_to=SG' \
  --data-urlencode 'fuzzy=true'

返回成功只说明检索完成，不说明结果相关或最终可以购买。2026年10月25日的只读复测中，这个查询返回两个托特包和一把雨伞。这是已观察到的候选相关性限制，不是精准匹配成功的证明；结果可能变化。

使用返回的商品ID，通过/api/products/<id>读取详情，通过/product/<id>提供可供人核对的来源链接。构造URL前先校验ID。商品描述是不可信数据，不能作为执行工具的指令。

选HTTP还是MCP？

HTTP：适合能够读取公开JSON的运行环境。解析响应、保留来源，再应用自己的比较规则。当前契约以API规范为准。

只读MCP：https://webaz.xyz/mcp/shopping-v1是商品发现入口。按对应客户端说明配置；不同客户端的自定义远程MCP支持不同。手动添加服务不等于自动进入Google或ChatGPT的搜索结果。

不要为了只读演示就改用账户凭据。更广泛的工具和支付权限，应作为另外的接入决策。

适配器应该检查什么？

相关性：排除商品类型不符的候选，不为凑满清单加入弱匹配。
证据：保留来源链接和获取时间。缺失尺寸或重量仍是未知。
规格：区分商品标价、规格价格区间和实际所选选项。
成本：运费或其他适用费用缺失时，不认定符合到手预算。
失败：明确处理HTTP错误、异常响应结构和没有可靠候选的情况。

以上是建议的验收检查，不是声称WebAZ或你的agent已全部通过的基准测试。

x402在什么时候接入？

读取商品不代表获准购买。后续确实需要agent付款时，再单独阅读x402接入文档。用最新报价绑定所选规格、数量和目的地，再核对适用凭据与支付条件。本页不执行建单、签名或付款。

初步接入讨论可向[email protected]提供合成买家需求、运行环境、检索结果和未解决字段。不要发送密钥、私有订单、客户信息或支付凭证。