# KK货源 (kk666.cn)

> 供应商 AI 员工 / ERP 与买家只读 Agent。规范以 https://kk666.cn/KK-openAi.md 为准（2026-10-13 v7.4）。

## Spec

- 摘要落地: https://kk666.cn/for-agent （/?for=agent 会转到这里）
- 完整规范（供应商写入）: https://kk666.cn/KK-openAi.md
- 买家只读: https://kk666.cn/kk-buyer-agent.md
- 字段速查: https://kk666.cn/kk-open-api.md
- HTML 文档: https://kk666.cn/api/open/docs
- 供应商接入话术: https://kk666.cn/ai-agent
- 开发者速查: https://kk666.cn/developer
- 发现文件: https://kk666.cn/llms.txt
- Agent 描述: https://kk666.cn/.well-known/agent.json

## API

- Base URL: https://kk666.cn/api
- 认证: Header `X-API-Key`（商户 Key；须登录后在 https://kk666.cn/supplier/api-keys 生成，明文仅一次）
- 密钥页须登录，且 robots.txt Disallow `/supplier/` `/console/`，不要靠爬虫发现 Key 能力
- 工作台别名 `/console/merchant/api-keys` 与 `/supplier/api-keys` 是同一页，不是第二套系统

## 公开只读（无需 Key）

- 列表: GET /api/public/products （默认 page_size=40，最大 200）
- 查询: keyword、code、category、town、tag、sort、focus=clearance|shop_featured
- 详情: GET /api/public/products/{code} ；code 是前台 slug（商品页 /product/{code}）；纯数字且 code 未命中时回落内部 id；含 skus[]
- 类目: GET /api/open/categories （可匿名）
- 上架政策: GET /api/public/policies/merchant-listing-rules

## 商户写入（必须 X-API-Key）

- 路径前缀: /api/open/*
- 写商品用内部 id: POST|PATCH /api/open/products 、 PATCH /api/open/products/{id}
- GET 开放接口会返回只读 `code`（前台 slug）；禁止 POST/PATCH 自定义 code
- 禁止把 API Key 打到 /api/products （那是商户后台 JWT）

## 约束

- 查询字符串必须 URL-encode（例如 `?keyword=%E7%AB%A5%E9%9E%8B`），不要把未编码中文直接放进 URL
- 仅导入商户自有或已授权货源；禁止未授权批量爬取公网商品后写入
- 主图/详情/白底/视频仅限 KK 图床（/kk_HSH/）；须先 POST /open/upload-image，禁止外站直链