淘宝/天猫/1688 商品素材拉取

概述

淘宝 / 天猫 / 1688 商品素材提取（Pay Skill）

适用场景

当用户提供淘宝、天猫或 1688 商品链接，并希望提取商品标题、主图、SKU、详情图、视频或卖点时调用本 Skill。

付费前置检查（必须执行）

1. 检查当前 Agent 是否提供 weixinpay 插件及 weixinpay_pay 支付工具。
2. 已提供：继续执行下面的付费流程。
3. 未提供：明确提示“当前 Agent 暂不支持微信支付付费能力”，然后终止；不得绕过支付直接请求商品素材。
4. 本 Skill 单次调用价格为人民币 0.02 元。支付必须通过微信支付授权界面由用户本人确认；用户取消或支付失败时立即停止。
5. 用户不需要、也不应提供万邦 API Key、微信支付密钥或 SkillHub 开发者私钥；这些凭证只保存在商家服务端。

工作流程

第一步：请求资源

正式服务地址已经固定，用户无需配置环境变量。先保存下面 JSON 的原始序列化内容，后续重试必须原样复用：

POST https://sxsai.cn/skill/taobao-fetcher/api/resource
Content-Type: application/json

{"url":"https://detail.1688.com/offer/123456789.html"}

第二步：处理 402 响应

服务首次响应为 HTTP 402 Payment Required，并同时返回：

• Header WeixinPay-Required：本次支付码。
• Header X-Out-Trade-No：本次调用的商户订单号。
• Body WeixinPay["WeixinPay-Required"]：支付码的兼容读取位置。
• Body out_trade_no：订单号的兼容读取位置。
• Body amount / currency：本次订单金额和币种。

优先读取 Header；宿主无法读取 Header 时才使用上述 Body 兼容字段。只有支付码和订单号均为非空、且 amount="0.02"、currency="CNY" 时才能继续。任一字段缺失或金额不一致时立即停止并报告服务异常。

支付码和订单号只允许交给宿主的 weixinpay_pay 以及固定商家接口 https://sxsai.cn/skill/taobao-fetcher/api/resource，不得向用户展示、写入日志或发送给其他地址。

第三步：发起微信支付授权

将 WeixinPay-Required 的完整值作为 paymentCode，调用：

weixinpay_pay(paymentCode=<WeixinPay-Required 的完整值>)

等待用户在微信支付授权界面中本人确认。用户取消或明确支付失败时停止。若支付工具超时或结果不确定，不得再次发起支付或创建新订单；可以直接执行第四步，用同一订单向商家服务查询实际支付状态。

第四步：支付成功后重新获取资源（必须执行）

weixinpay_pay 明确成功后，或需要查询超时/不确定的支付结果时，必须再次请求第一步的同一接口：

• 必须复用第一步保存的原始 JSON 请求体，不得重新拼装或改变任何字符。
• 将第一次响应的 WeixinPay-Required 和 X-Out-Trade-No 原样放入请求 Header。
• 禁止跟随到其他来源的重定向；目标必须仍为原 HTTPS 域名 sxsai.cn。

POST https://sxsai.cn/skill/taobao-fetcher/api/resource
Content-Type: application/json
WeixinPay-Required: <payment_code>
X-Out-Trade-No: <out_trade_no>

{"url":"https://detail.1688.com/offer/123456789.html"}

只有服务端通过微信支付查单确认 trade_state=SUCCESS 后，才会返回商品素材。

结果处理

以下名称均指响应 JSON 的 code 字段：

• SUCCESS：向用户展示 content 中的商品素材。
• NOT_PAID：支付尚未确认；只使用同一请求体、支付码和订单号重新查询，不得新建订单或再次支付。
• FULFILLING：另一请求正在履约；只重试同一订单，不得新建订单。
• REFUNDED：告知用户服务失败且已发起全额退款，不要再次支付。
• FULFILL_AND_REFUND_FAILED：停止自动重试，提示用户联系商家客服。
• REQUEST_MISMATCH：支付后的请求体发生变化，必须恢复第一步保存的原始请求体。

支付后的网络超时、连接中断、非 JSON 或 5xx 响应都不得触发新订单或第二次支付；保留原支付码、订单号和请求体，稍后仅查询同一订单。

成功结果中的 content 字段包含：

• title
• main_images / sku_images / detail_images
• video
• sku_list
• selling_points
• source_platform
• product_id / source_url

安全要求

• 只接受 https:// 的淘宝、天猫和 1688 真实域名及其子域名。
• 不记录 SkillHub 私钥、微信支付证书、APIv3 密钥或支付凭证。
• 同一 out_trade_no 只履约一次；重复调用返回已缓存结果。
• SKILL.md 中的 pricing.amount_fen: 2、SkillHub 发布页的 ¥0.02 / 次 和服务端实际下单金额必须始终一致。

非支付连通性测试（仅开发排障）

仅当用户明确要求进行不付款的 402 连通性测试时，才可以运行本 Skill 目录中的脚本：

node "<本 Skill 目录>/scripts/preflight.mjs" "<商品链接>"

该脚本只验证首次响应是否包含非空的标准支付字段，随后立即停止；它不能替代 weixinpay_pay，不得用于真实履约。