API v1
面向开发者与 AI Agent
API 调用说明
通过 RESTful API 管理商品、查询信息、对接 AI Agent。所有返回均为 JSON 格式。
🚀 快速开始
# 无需认证即可查询
curl https://xinxi.zxwsh.com/api/search?q=iPhone
# 需要认证的操作（获取 API Key 后）
curl -H "X-API-Key: YOUR_API_KEY" \
https://xinxi.zxwsh.com/api/products?page=1🔐 认证方式
| 方式 | 说明 |
|---|---|
X-API-Key Header |
推荐方式。在请求头中传递 API Key。 |
?api_key= 参数 |
备选方式。URL 中传递，适合浏览器直接测试。 |
| Session Cookie | 浏览器登录后自动携带，适合前端页面调用。 |
💡 API Key 在管理后台 → API 密钥管理生成。密钥仅在生成时显示一次，请妥善保存。
📡 API 端点
信息查询（无需认证）
GET
/api/search
搜索商品
| q | 搜索关键词 |
| category | 分类筛选 |
| page | 页码，默认1 |
GET
/api/product/<id>
获取商品详情，含卖家信息、图片、联系方式（需认证）
GET
/api/categories
获取所有商品分类列表
GET
/api/products
获取商品列表，支持分类筛选与分页
| category | 分类筛选 |
| page | 页码，默认1 |
GET
/api/v1/openapi.json
OpenAPI 3.0 规范文件，AI Agent 可直接解析调用
用户操作（需认证）
POST
/api/favorite/<id>
收藏/取消收藏商品
POST
/api/product/<id>/reveal-contact
查看卖家联系方式（消耗积分或需认证）
POST
/api/report/<id>
举报商品
POST
/api/upload
上传图片（multipart/form-data，字段名 file）
POST
/api/payment/create
创建支付订单（用于置顶/推广等付费服务）
🤖 AI Agent 接入指南
信息平台支持 AI Agent 直接通过 API 进行交互。推荐步骤：
- 获取 OpenAPI 规范文件，导入你的 AI 工具
- 从管理后台生成 API Key
- 在请求中携带
X-API-KeyHeader - 所有响应均为标准 JSON，Agent 可直接解析
🔑 API Key 管理
管理员可在 管理后台 → API 密钥 中：
- 创建新的 API Key（可设定名称、权限等级、速率限制）
- 启用/禁用已有 Key
- 删除不再使用的 Key
⚠️ API Key 通过 SHA256 哈希存储，原始 Key 仅在生成时显示一次。
📮 遇到问题？联系我们