🔌 Open API · 开放平台

给商户和AI Agent的标准接口

通过API批量上传商品、管理库存和价格，让你的ERP、爬虫或AI Agent自动对接KK货源平台。

📅 文档更新：2026-06-13 v5 · AI员工一键接入 · 完整规范

接入要求

✅已完成实名认证的商户
🔑持有API Key（在商户后台 → API密钥 生成）
📖Key仅显示一次，丢了只能吊销重签

快速开始

1

获取API Key

登录供应商后台 → /supplier/api-keys → 生成新Key → 立即复制保存

2

上传商品图片（必做）

bulk/创建：不传 product_id；单张追加可传 ?product_id=（序号 DB max+1）。Bulk 禁止 product_id，须 temp+PATCH

curl -X POST https://kk.h-sh.com/api/open/upload-image \
-H "X-API-Key: kk_your_key" \
-F "file=@product.jpg"
# 创建商品前可不传 product_id，图片进临时目录
# → {"url": "https://cf.h-sh.com/kk_HSH/temp/...", "filename": "xxx.jpg"}
3

创建商品（含完整字段）

curl -X POST https://kk.h-sh.com/api/open/products \
-H "X-API-Key: kk_your_key" \
-H "Content-Type: application/json" \
-d '{
"product": {
"name": "夏季凉鞋",
"category": "women_shoes",
"price": 89.0,
"brand": "品牌名",
"origin_place": "温州",
"packaging": "盒装",
"unit": "双",
"min_order_qty": 2,
"tags": ["夏季", "新款"]
},
"main_images": ["https://cf.h-sh.com/kk_HSH/..."],
"main_video_url": "https://cf.h-sh.com/kk_HSH/temp/.../main.mp4",
"detail_images": ["https://cf.h-sh.com/kk_HSH/..."],
"detail_content": "<p>图文详情</p>",
"skus": [{"color":"黑色","size":"38","stock":50,"white_image_url":"https://cf.h-sh.com/kk_HSH/..."}]
}
4

日常改库存/价格（最高频）

curl -X PATCH https://kk.h-sh.com/api/open/products/{id}/skus \
-H "X-API-Key: kk_your_key" \
-H "Content-Type: application/json" \
-d '[{"color":"黑色","size":"38","stock":20,"white_image_url":"https://cf.h-sh.com/kk_HSH/..."}]'
5

更新商品信息/上下架/详情

curl -X PATCH https://kk.h-sh.com/api/open/products/{id} \
-H "X-API-Key: kk_your_key" \
-H "Content-Type: application/json" \
-d '{"name":"新名称","price":99,"is_active":false}'

📦 创建商品请求结构

注意：product、main_images、skus 在根层级并列，main_images 和 skus 不在 product 内

字段位置必填说明
nameproduct是商品名，最多200字
categoryproduct是平台 slug；先 GET /open/categories，有 subs 传子类
merchant_category_slugproduct否商户档口 Tab slug，须先创建
priceproduct是价格，必须>0
descriptionproduct否商品描述
brandproduct否品牌
origin_placeproduct否产地（温州/广州等）
packagingproduct否包装方式（盒装/袋装）
unitproduct否单位，默认"双"
min_order_qtyproduct否起订量，默认1
materialproduct否材质
tagsproduct否标签数组，每项最多4个汉字
main_images根层级是主图URL列表（须先 upload-image 到 KK OSS）
main_video_url根层级否主图视频；先 upload-video，勿放 main_images
detail_content根或 product否HTML 图文详情 ≤5000 字，根优先；GET 必返回
detail_images根或 product否详情图 URL 列表
source根层级否来源页 URL；货号用 product.art_no
skus根层级否SKU数组；含 color,size,stock,price,white_image_url?（创建时可传，POST响应返回）

🏷️ 标签规则

✅"夏季"2个汉字 — 通过
✅"新款上市"4个汉字 — 通过
❌"2024夏季新款"超过4个汉字 — 拒绝

每个标签最多4个汉字（或8个英文字符），超长返回 422 错误

🤖 AI Agent 接入

推荐使用 AI员工一键接入 页复制话术；完整规范见 KK-openAi.md。

Base URL：https://kk.h-sh.com/api/open
认证方式：Header: X-API-Key: kk_your_key
类目：先 GET /open/categories，有 subs 传子类 slug
白底图/视频：skus[].white_image_url 创建时可传；main_video_url 根层级；POST 响应即含 canonical URL
图片规则：须为 cf.h-sh.com/kk_HSH 或 kk.h-sh.com/kk_HSH 域名
标签规则：每项最多4个汉字，超长返回422

📚 完整API文档

开放 API 商品读写均限定本 Key 所属商户；浏览全平台公开商品请用 GET /api/public/products（无需 Key）。

POST
/open/upload-image
上传图片：bulk 不传 product_id；单张追加可传，序号 DB max+1
POST
/open/upload-video
上传主图视频 mp4/mov/webm/m4v → main_video_url
POST
/open/products
创建商品（含 SKU、白底图、主图视频）
GET
/open/products
查询本商户商品列表（分页、类目、上下架筛选）
GET
/open/products/:id
查询详情（含 skus[].white_image_url、main_video_url）
PATCH
/open/products/:id
更新商品信息（名称、价格、标签、上下架、视频）
PATCH
/open/products/:id/skus
批量更新 SKU 库存/价格/白底图
POST
/open/keys
生成新API Key（仅返回一次明文）
GET
/open/keys
列出我的API Key
DELETE
/open/keys/:id
吊销API Key

⚠️ 错误码

401API Key无效或已吊销
403商户未通过实名认证（请后台开启认证）
400参数错误，如类目非法、图片URL不在白名单
422校验失败，如标签过长、价格为0等

完整 Markdown 规范： KK-openAi.md · 在线 HTML： /open/docs