KK货源平台 开放API

📅 文档更新：2026-06-13 v5 · Base URL: https://kk.h-sh.com/api · 完整规范 · 字段速查

供 AI Agent、ERP、爬虫通过 API Key 批量管理商品、SKU 库存与图片。请先读层级约定，避免 400。

请求体层级（POST 创建）

{
  "product": {"name":"...", "category":"women_shoes", "price":89, "art_no":"厂家款号"},
  "main_images": ["https://cf.h-sh.com/kk_HSH/..."],
  "source": "https://来源页可选",
  "skus": [{"color":"黑色","size":"38","stock":50}]
}

PATCH /open/products/{id} 为扁平 JSON（无 product 包装），可含 art_no、source、is_active 等。

商品标识

平台内部另有前台编码（如 W0、K10），开放 API 不返回，对接请以 id 为准。

认证方式

X-API-Key: kk_your_api_key

端点总览

快速开始

1. 上传图片（bulk/创建：不传 product_id）

curl -X POST https://kk.h-sh.com/api/open/upload-image \
  -H "X-API-Key: $KK_API_KEY" \
  -F "file=@product.jpg"
# 单张追加（非 bulk）：?product_id=123，写入 {merchant_id}/products/{product_id}/{uuid}.jpg
# bulk 禁止 product_id，须 temp upload → 立刻 PATCH

2. 创建商品

product / main_images / source / skus 在根层级并列

curl -X POST https://kk.h-sh.com/api/open/products \
  -H "X-API-Key: $KK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product":{"name":"夏季凉鞋","category":"women_shoes","price":89.0,"art_no":"X001","tags":["夏季","新款"]},"main_images":["https://cf.h-sh.com/kk_HSH/..."],"source":"https://example.com/item","skus":[{"color":"黑色","size":"38","stock":50,"white_image_url":"https://cf.h-sh.com/kk_HSH/..."}]}'

2b. 上传主图视频（选填）

curl -X POST https://kk.h-sh.com/api/open/upload-video \
  -H "X-API-Key: $KK_API_KEY" \
  -F "file=@main.mp4"
# 将返回 url 写入创建 JSON 根层级 main_video_url（勿放入 main_images）

3. 更新SKU库存/价格/白底图

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

4. 更新商品信息/上下架/货号/来源

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

创建商品字段

SKU字段

标签规则

分类体系（必读）

平台类目示例

GET /open/categories
{
  "data": [
    {"slug":"women_shoes","name":"女鞋","requires_subcategory":true,
     "subs":[{"slug":"sandals","name":"凉鞋"}, {"slug":"boots","name":"靴子"}]},
    {"slug":"hats","name":"帽子","requires_subcategory":false,"subs":[]}
  ]
}
# 女鞋有子类 → product.category 传 "sandals"，不能传 "women_shoes"
# 帽子无子类 → product.category 传 "hats"

类目

子类 slug 以 /open/categories 返回为准；编码前缀按所属大类 W/K/H/B 生成。

图片 URL 归属（Bulk 必读）

错误码

创建响应

注意事项

• 对接以 id 标识商品；平台内部前台编码不在 API 中返回
• 库存只写 skus[].stock；商品 stock 为 SKU 之和，只读
• 白底图 skus[].white_image_url：创建时可传；未传可用 PATCH skus 补图
• 主图视频写根层级 main_video_url，禁止放入 main_images
• source 响应字段名；入库为 source_url；误传 url | 货号 会截断
• auto_approve=true 的 Key 创建商品自动上架（status=active）
• SKU 更新按 color+size 匹配：存在则更新，不存在则新增
• Key 明文只返回一次，丢了只能吊销重签
• SKU 请求体支持数组或 {"items":[...]}/{"skus":[...]}