bee-inquiry-read

版本: 2.0.2

简介

通过小蜜蜂（Bee）建站开放 API，读取询盘数据并生成结构化分析报告。

支持全字段读取、按需选取字段（fields）、多语言筛选、分页查询。

---

输入参数

api_key (string, 必填)

API 身份认证密钥，用于调用方身份识别和接口权限控制。

• 获取地址: https://open.tradew.com
• 推荐配置方式: 通过 skills.entries.env.BEE_API_KEY 注入，避免每次调用明文传参。

---

language (string, 可选)

站点语言筛选。

⚠️ 约束： 如果提供此参数，必须通过 bee-languages-get skill 返回的列表人工选择，不允许 AI 系统推断。

---

recent_days (integer, 可选)

站点语言筛选。

⚠️ 约束： 指定返回最近多少天内的询盘数据，范围0-36500。默认值为 0，表示不限制时间范围，返回所有询盘。

---

fields (array of strings, 可选)

字段白名单。指定返回哪些询盘字段，不传则返回全部字段。

可选值：

| 字段 | 说明 | | --------------- | ---------------- | | inquiry_id | 询盘唯一编号 | | language | 语言 | | is_read | 是否已读 | | title | 询盘标题 | | content | 询盘内容 | | country_code | 国家代码 | | ip | IP 地址 | | contact | 联系人信息对象 | | source | 来源渠道 | | target_products | 关联产品列表 | | create_time | 创建时间 |

---

pagination (object, 必填)

分页配置参数。

current_page (integer)

• 默认值: 1
• 最小值: 1
• 分页规则：
  • 必须依赖 data.pagination.has_next_page
  • 使用 data.pagination.next_page 作为下一页页码
  • 禁止基于 total_page 或手动递增推算
  • has_next_page=false 时必须停止请求

page_size (integer)

• 默认值: 10
• 范围: 10 ~ 50

---

输出结构

顶层字段

| 字段 | 类型 | 说明 | | -------- | ----------------- | -------------------------------- | | status | boolean | 请求状态，true 成功 / false 失败 | | msg | string | 返回消息 | | data | object | null | 返回结果数据，失败时为 null |

data.pagination

| 字段 | 类型 | 说明 | | ------------ | ------- | ------------ | | current_page | integer | 当前页码 | | page_size | integer | 每页数量 | | total_page | integer | 总页数 | | total_count | integer | 总记录数 |

data.list[] (array of objects)

每条询盘数据包含以下字段：

| 字段 | 类型 | 说明 | | --------------- | ----------------- | ----------------------------------------- | | inquiry_id | integer | 询盘唯一编号 | | language | string | 站点语言 | | is_read | boolean | 是否已读 | | title | string | 询盘标题 | | content | string | 询盘内容（可能包含 HTML 表单） | | country_code | string | 国家代码（ISO 3166-1） | | ip | string | IPv4 或 IPv6 地址 | | contact | object | 联系人信息 | | source | string | 询盘来源渠道 | | target_products | array of objects | 关联产品列表 | | create_time | string (datetime) | 创建时间（ISO 8601 格式） |

contact 对象

| 字段 | 类型 | 说明 | | ------- | ------ | -------- | | name | string | 联系人姓名 | | email | string | 邮箱地址 | | tel | string | 联系电话 | | address | string | 联系地址 |

target_products[] 对象

| 字段 | 类型 | 说明 | | ------------ | ------- | -------- | | products_id | integer | 产品 ID | | product_name | string | 产品名称 | | product_url | string | 产品链接 |

---

依赖

| 参数 | 依赖 skill | 关联字段 | 模式 | | -------- | -------------------- | ------------------- | ------ | | language | bee-languages-get | list[].language | select |

language 参数的值必须从 bee-languages-get 的返回列表中人工选择。

---

使用示例

基础查询（第一页，每页 10 条）

{
  "api_key": "your-api-key",
  "pagination": {
    "current_page": 1,
    "page_size": 10
  }
}

带语言筛选 + 字段限制

{
  "api_key": "your-api-key",
  "language": "en",
  "fields": ["inquiry_id", "country_code", "source", "contact", "create_time"],
  "pagination": {
    "current_page": 1,
    "page_size": 50
  }
}

返回最近7天内的询盘数据

{
  "api_key": "your-api-key",
  "recent_days": 7,
  "fields": ["inquiry_id", "country_code", "source", "contact", "create_time"],
  "pagination": {
    "current_page": 1,
    "page_size": 50
  }
}

---

注意事项

1. api_key 必填，从 https://open.tradew.com 获取
2. pagination 必须符合范围限制（page_size 10~50，current_page ≥ 1）
3. language 必须人工从 bee-languages-get 选择，不得系统推断
4. 翻页规则： data.pagination.has_next_page，是否存在下一页；data.pagination.next_page，下一页页码，没有下一页时为 null；是否继续由用户决定
5. fields 可选，不传则返回全部字段；传了则只返回指定字段

---

适用场景

• 外贸询盘数据拉取
• 客户来源渠道统计
• 产品热门度/转化分析
• 客户画像与身份标签分析
• 分页导出与 CRM 数据同步