onebound-api（onebound API 搜索）

Onebound API

Provides four e-commerce data capabilities through the Onebound platform gateway:

1. Taobao Keyword Search - Search Taobao and Tmall products by keyword
2. Taobao Item Detail - Fetch detailed Taobao product data by item ID
3. 1688 Keyword Search - Search 1688 products by keyword
4. 1688 Item Detail - Fetch detailed 1688 product data by item ID

Setup

Users should register on your Onebound platform, create a platform API key, and use that key with this skill.

Set these environment variables:

Workflow

Taobao Keyword Search

Use when the user asks to search Taobao or Tmall products by keyword.

Run:

bash {baseDir}/scripts/taobao-item-search.sh "<keyword>" "<page>" "<page_size>" "<sort>" "<cat>"

• keyword - Search keyword, required
• page - Page number, optional, defaults to 1
• page_size - Page size, optional, defaults to 10
• sort - Sort mode, optional
• cat - Category ID, optional, defaults to 0

Example:

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

Taobao Item Detail

Use when the user asks to fetch Taobao product details by item ID.

Run:

bash {baseDir}/scripts/taobao-item-detail.sh "<num_iid>" "<is_promotion>"

• num_iid - Taobao item ID, required
• is_promotion - Whether to request promotion info, optional, defaults to 1

Example:

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

1688 Keyword Search

Use when the user asks to search 1688 products by keyword.

Run:

bash {baseDir}/scripts/alibaba-1688-item-search.sh "<keyword>" "<page>" "<page_size>" "<sort>" "<cat>"

• keyword - Search keyword, required
• page - Page number, optional, defaults to 1
• page_size - Page size, optional, defaults to 40
• sort - Sort mode, optional
• cat - Category ID, optional, defaults to 0

Example:

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

1688 Item Detail

Use when the user asks to fetch 1688 product details by item ID.

Run:

bash {baseDir}/scripts/alibaba-1688-item-detail.sh "<num_iid>" "<sales_data>" "<agent>"

• num_iid - 1688 item ID, required
• sales_data - Whether to include recent sales data, optional, defaults to 0
• agent - Whether to include distribution pricing data, optional, defaults to 0

Example:

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

Output Format

Scripts output results in Markdown format. Present the output directly to the user.

OpenAPI Specification

For integration with OpenClaw, the gateway exposes the following OpenAPI Specification:

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

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

# 安全认证方式配置：要求用户提供 API Key (Bearer Token 格式)
security:
  - bearerAuth: []

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 Key 缺失或无效
        '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 Key 缺失或无效
        '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 (用于查询详情)
        gateway_request_id:
          type: string
          description: 网关请求流水号
        cost:
          type: number
          description: 本次调用扣费金额
        balance:
          type: number
          description: 账户剩余余额
          
    DetailResponse:
      type: object
      properties:
        item:
          type: object
          description: 商品详细信息
          properties:
            title:
              type: string
            price:
              type: number
            desc:
              type: string
              description: 图文详情 (HTML格式)
            skus:
              type: object
              description: 商品SKU信息与价格
        gateway_request_id:
          type: string
        cost:
          type: number
        balance:
          type: number

Guardrails

• Always check that ONEBOUND_API_KEY is set before calling any script. If missing, tell the user to set it.
• Default to https://onebound.vercel.app when ONEBOUND_BASE_URL is not set.
• Never ask the user for upstream credentials when using this skill.
• Never fabricate product search or detail results. Always call the platform gateway.
• If a script returns an error, show the error message to the user.
• Do not expose the API key in output.
• For keyword search, make sure the keyword is meaningful and not empty.
• For detail queries, require a valid item ID before making the call.

Failure Handling

• If the API returns a 401 error, the platform API key is invalid or expired. Ask the user to verify their credentials.
• If the API returns a 400 error, check the required parameters.
• If the API returns a 402 or a balance-related error, ask the user to recharge the platform balance.
• If the API returns a 500 error, it is a server-side issue. Suggest the user try again later.
• If the script exits with code 1, read the error message from stderr.