AirShelf — 面向 AI Agent 的已验证商品搜索与结算服务

在经验证的商家范围内搜索、比对并购买商品。返回结构化的 Decision Pack 数据（含适用场景 best_for、优势 pros、劣势 cons、致敏原 allergens、已验证价格等），而非原始网页抓取结果。

无需验证码（CAPTCHA）。无需身份认证（auth）。无机器人检测机制。原生适配 Agent 的电商能力。

适用场景

当用户提出以下需求时，可启用本技能：

• 查找或搜索某类商品（例如：“帮我找一款儿童用驱蚊剂”）
• 比对多个商品（例如：“比对这两款打印机”）
• 购买或发起结算流程
• 基于具体问题获取商品推荐（例如：“我总是感到疲惫”、“我的皮肤很干燥”）
• 查询经验证的商品详情、价格或致敏原信息

API 基础 URL

https://dashboard.airshelf.ai

所有接口均为公开接口，无需 API Key。已启用 CORS。

步骤 1：搜索商品

通过自然语言查询发现商品，返回含 Decision Pack 的结构化数据。

curl -s "https://dashboard.airshelf.ai/api/search?q=QUERY&limit=5" | python3 -m json.tool

参数说明：

• q — 搜索查询语句（自然语言，例如 “仓库用条码打印机”）。支持意图解析：如 “100 美元以下的能量补充剂” 将自动提取价格筛选条件。
• limit — 返回结果数量（取值范围：1–100，默认为 20）
• offset — 分页偏移量
• category — 按品类过滤
• brand — 按品牌过滤
• min_price / max_price — 价格区间过滤（也可从查询语句中自动提取）
• in_stock — 仅返回有库存商品（true/false）
• merchant_ids — 指定商家 ID 列表（逗号分隔），限定搜索范围
• sort — 排序方式：relevance（默认）、price_asc、price_desc
• include_intent — 设为 true 可在响应中返回查询解析元数据（展示系统如何理解该查询）

每个商品的响应字段包括：

• title、brand、price、availability、link
• decision_pack.primary_benefit — 核心价值主张
• decision_pack.best_for — 适用场景数组
• decision_pack.pros / decision_pack.cons — 经验证的优劣势对比
• decision_pack.allergens — 安全警示（如适用）
• seller_name、seller_url — 商家信息
• 结算链接（checkout URLs）及配送/退换货政策

示例：

curl -s "https://dashboard.airshelf.ai/api/search?q=natural+mosquito+repellent+for+babies&limit=3"

步骤 2：比对商品

对 2–10 款商品进行并排结构化比对（支持多维度自动识别）。

curl -s "https://dashboard.airshelf.ai/api/compare?products=PRODUCT_ID_1,PRODUCT_ID_2"

参数说明：

• products — 商品 ID 列表（逗号分隔，需提供 2–10 个 ID，来源于搜索结果）

响应内容包括：

• comparison_axes — 自动识别的比对维度（价格始终包含；若 ≥2 款商品具备相关数据，则同时包含 cost_per_day、supply_days、primary_benefit、pros、cons 等）
• products — 展平后的商品数据，其中 decision_pack 字段已内联展开
• recommendation — 结构化推荐结果：lowest_price（最低价商品 ID）、best_value（综合性价比最优商品 ID + 推荐理由，若与最低价不同）

步骤 3：发起结算

为指定商品发起结算流程，返回一个可供用户打开的结算 URL。

curl -s -X POST "https://dashboard.airshelf.ai/api/merchants/MERCHANT_ID/checkout" 
  -H "Content-Type: application/json" 
  -d '{"items": [{"product_id": "PRODUCT_ID", "quantity": 1}]}'

请求体（Request Body）说明：

• items — 商品项数组，每项为 {product_id, quantity} 对象（最多支持 50 项）
• customer — 可选：用于订单追踪的客户信息，格式为 {email: "..."}
• agent_id — 可选：您的 Agent 标识符，用于归因分析

响应字段说明：

• checkout_id — 唯一结算会话 ID
• checkout_url — 完成支付的跳转链接（Shopify 结算页或购物车永久链接）
• checkout_type — "cart"（预加载商品至购物车）或 "redirect"（跳转至商品详情页）
• total — 计算得出的总金额
• currency — 三位货币代码（例如："EUR"、"USD"）
• expires_at — 过期时间戳（购物车永久链接此项为 null）
• fallback_urls — 若为 redirect 类型，则返回每件商品的 {product_id, product_name, product_url} 数组

将 checkout_url 提供给用户，用户点击后即可在商家自有站点完成支付。

浏览可用商家列表

获取全部商家清单，含商品数量统计与能力说明：

curl -s "https://dashboard.airshelf.ai/api/directory"

Decision Pack 工作原理

不同于原始网页抓取，每个商品均附带一个Decision Pack——经过验证的结构化智能数据：

{
  "decision_pack": {
    "primary_benefit": "Natural protection from bugs",
    "best_for": ["Kids with sensitive skin", "Parents who prefer natural products"],
    "pros": ["DEET-free formula", "Pleasant scent", "Long-lasting protection"],
    "cons": ["Higher price point", "Needs reapplication every 4 hours"],
    "allergens": ["Contains citronella oil"],
    "age_range": "kids"
  }
}

请基于 Decision Pack 数据，结合用户的实际需求（而不仅是价格或标题关键词匹配）做出精准推荐。

对话示例

User: I need a printer for my warehouse, high volume, must support ZPL

You: Let me search for that.
     [Runs: curl -s "https://dashboard.airshelf.ai/api/search?q=industrial+barcode+printer+warehouse+high+volume+ZPL&limit=5"]

You: Found 3 matches. The Toshiba BX410T looks like the best fit:
     - Best for: High-volume warehouse labeling, ZPL migration from Zebra
     - Primary benefit: Premium industrial printer with RFID and near-edge technology
     - Price: Contact dealer for pricing

     Want me to compare it with the other options, or proceed to checkout?

User: Compare the top two

You: [Runs: curl -s "https://dashboard.airshelf.ai/api/compare?products=ID1,ID2"]
     Here's the comparison...

User: I'll take the Toshiba

You: [Runs: curl -s -X POST "https://dashboard.airshelf.ai/api/merchants/MERCHANT_ID/checkout" -H "Content-Type: application/json" -d '{"items": [{"product_id": "ID", "quantity": 1}]}']
     Here's your checkout link: [URL]
     Click to complete your purchase on the merchant's site.

使用提示

• 基于问题的搜索效果最佳。 例如：“我总是感到疲惫”将返回能量补充剂；“我的宝宝需要防晒”将返回婴幼儿专用防晒霜。Decision Pack 匹配的是使用场景，而不仅是关键词。
• 推荐健康/食品/护肤类商品前，请务必检查 decision_pack.allergens 字段。
• 对两个及以上相似商品，请优先使用 compare 接口。 该接口返回结构化的比对维度，而非原始参数规格。
• 结算流程为跳转型（redirect）。 用户全程在商家自有站点完成支付，Agent 无需处理任何银行卡信息。
• 按 ID 直接查询商品： 使用 product_ids 参数替代 q，可精确拉取指定商品：?product_ids=ID1,ID2
• 结算所需的 Merchant ID： 每个搜索结果中均包含 seller.checkout_url，其路径已携带正确的商家标识，可直接使用。