Onebound API

通过Onebound平台网关提供四种电商数据能力：

1. 1. 淘宝关键词搜索 - 按关键词搜索淘宝和天猫商品
2. 淘宝商品详情 - 按商品ID获取淘宝商品详细信息
3. 1688关键词搜索 - 按关键词搜索1688商品
4. 1688商品详情 - 按商品ID获取1688商品详细信息

设置

用户应在Onebound平台注册，创建平台API密钥，并将该密钥用于此技能。

设置以下环境变量：

工作流程

淘宝关键词搜索

当用户要求按关键词搜索淘宝或天猫商品时使用。

运行：

bash
bash {baseDir}/scripts/taobao-item-search.sh <关键词> <页码> <每页数量> <排序方式> <分类ID>

• - keyword - 搜索关键词，必填
• page - 页码，可选，默认为1
• page_size - 每页数量，可选，默认为10
• sort - 排序方式，可选
• cat - 分类ID，可选，默认为0

示例：

bash
bash {baseDir}/scripts/taobao-item-search.sh 女装
bash {baseDir}/scripts/taobao-item-search.sh 蓝牙耳机 1 20

淘宝商品详情

当用户要求按商品ID获取淘宝商品详情时使用。

运行：

bash
bash {baseDir}/scripts/taobao-item-detail.sh <商品ID> <是否获取促销信息>

• - numiid - 淘宝商品ID，必填
• ispromotion - 是否请求促销信息，可选，默认为1

示例：

bash
bash {baseDir}/scripts/taobao-item-detail.sh 652874751412

1688关键词搜索

当用户要求按关键词搜索1688商品时使用。

运行：

bash
bash {baseDir}/scripts/alibaba-1688-item-search.sh <关键词> <页码> <每页数量> <排序方式> <分类ID>

• - keyword - 搜索关键词，必填
• page - 页码，可选，默认为1
• page_size - 每页数量，可选，默认为40
• sort - 排序方式，可选
• cat - 分类ID，可选，默认为0

示例：

bash
bash {baseDir}/scripts/alibaba-1688-item-search.sh 女装
bash {baseDir}/scripts/alibaba-1688-item-search.sh 围巾 1 40

1688商品详情

当用户要求按商品ID获取1688商品详情时使用。

运行：

bash
bash {baseDir}/scripts/alibaba-1688-item-detail.sh <商品ID> <是否包含销售数据> <是否包含分销价格>

• - numiid - 1688商品ID，必填
• salesdata - 是否包含近期销售数据，可选，默认为0
• agent - 是否包含分销定价数据，可选，默认为0

示例：

bash
bash {baseDir}/scripts/alibaba-1688-item-detail.sh 610947572360

输出格式

脚本以Markdown格式输出结果。直接将输出呈现给用户。

OpenAPI规范

为与OpenClaw集成，网关暴露以下OpenAPI规范：

yaml
openapi: 3.0.3
info:
title: OneBound AI技能API
description: 提供淘宝(Taobao)和1688电商平台的商品数据检索与详情获取能力，专为AI Agent与OpenClaw技能设计。
version: 1.0.0
contact:
name: API支持
url: https://onebound.vercel.app

servers:
- url: https://onebound.vercel.app/api/v1/proxy
description: 生产环境网关

安全认证方式配置：要求用户提供API密钥（Bearer Token格式）

paths:
/taobao/item-search:
get:
summary: 淘宝商品关键词搜索
description: 通过关键词搜索淘宝平台上的商品，支持分页。返回商品列表、价格、销量、主图等基础信息。
operationId: searchTaobaoItems
tags:
- Taobao
parameters:
- name: q
in: query
description: 搜索关键词（例如：女装，iPhone 15）
required: true
schema:
type: string
maxLength: 100
- name: page
in: query
description: 页码（默认第1页）
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 1
responses:
200:
description: 搜索成功
content:
application/json:
schema:
$ref: #/components/schemas/SearchResponse
400:
description: 请求参数错误（例如缺少关键词）
401:
description: API密钥缺失或无效
402:
description: 账户余额不足
429:
description: 请求过于频繁（触发限流）

/taobao/item-detail:
get:
summary: 淘宝商品详情获取
description: 通过商品ID(num_iid)获取淘宝商品的详细信息，包括SKU属性、图文详情、库存状态等。
operationId: getTaobaoItemDetail
tags:
- Taobao
parameters:
- name: num_iid
in: query
description: 淘宝商品唯一数字ID（例如：652874751412）
required: true
schema:
type: string
pattern: ^\d+$
responses:
200:
description: 获取详情成功
content:
application/json:
schema:
$ref: #/components/schemas/DetailResponse
400:
description: 请求参数错误（例如ID不是纯数字）
401:
description: API密钥缺失或无效
402:
description: 账户余额不足

/1688/item-search:
get:
summary: 1688商品关键词搜索
description: 通过关键词搜索阿里巴巴1688平台上的商品，适用于B2B采购比价场景。
operationId: search1688Items
tags:
- 1688
parameters:
- name: q
in: query
description: 搜索关键词（例如：批发水杯，定制包装盒）
required: true
schema:
type: string
maxLength: 100
- name: page
in: query
description: 页码（默认第1页）
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 1
responses:
200:
description: 搜索成功
content:
application/json:
schema:
$ref: #/components/schemas/SearchResponse

/1688/item-detail:
get:
summary: 1688商品详情获取
description: 通过商品ID(num_iid)获取1688商品的详细信息，包括起批量、阶梯价格、供应商信息等。
operationId: get1688ItemDetail
tags:
- 1688
parameters:
- name: num_iid
in: query
description: 1688商品唯一数字ID（例如：610947572360）
required: true
schema:
type: string
pattern: ^\d+$
responses:
200:
description: 获取详情成功
content:
application/json:
schema:
$ref: #/components/schemas/DetailResponse

components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API_KEY

schemas:
SearchResponse:
type: object
properties:
items:
type: array
description: 搜索到的商品列表
items:
type: object
properties:
title:
type: string
description: 商品标题
price:
type: number
description: 商品价格
pic_url:
type: string
description: 商品主图链接
sales:
type: integer
description: 销量
num_iid:
type: string
description: 商品ID（用于查询详情）
gatewayrequestid:
type: string
description: 网关请求流水号
cost:
type