atlas-seller-kit/docs/api/category-commissions.md

# 类目佣金导入 API

> 2026-09-29。产品方案见 `docs/product/category-commission-import-plan.md`。所有金额与费率为十进制字符串；导入仅支持 Ozon / RU / rFBS / RUB。

## 管理端

全部 `/system/pricing/commissions` 接口要求实时有效的系统管理员授权，普通用户返回 403 `SYSTEM_ADMIN_REQUIRED`。

- `GET /system/pricing/commissions?platform_id={uuid}`：返回导入版本列表（不含原始文件），最近版本在前。
- `GET /system/pricing/commissions/:id`：版本详情，含解析后的类目、档位、异常、变更状态。
- `POST /system/pricing/commissions/preview`：只读预览。请求 `{platform_id,version,source_reference,captured_on,document}`，`document` 为来源 JSON 对象。返回 `{preview_hash,categories,summary,previous_import_id}`。分类结果为 eligible/excluded，差异为 added/changed/unchanged；summary 包含总类目、规则数、可用/排除类目、映射商品类型、移除类目数。格式不正确返回 422 `COMMISSION_IMPORT_INVALID`；允许预览全部无法映射的结果；没有可映射类目时禁止启用空版本。
- `POST /system/pricing/commissions/imports`：201，要求 UUID `Idempotency-Key`。请求在预览输入基础上增加 `{preview_hash,confirm_scope:true}`。确认适用范围表示管理员确认数据适用于 Ozon RU/rFBS 的 RUB 售价；目录异常和移除数量只在预览中提示，不要求额外勾选确认。只支持立即启用，完整替换本入口的前一版本，不修改非本入口规则；发生其他来源有效映射冲突时拒绝启用。

预览指纹覆盖完整输入、解析结果、可映射的商品类型及当前版本。启用时锁平台并重新核对，变化返回 409 `COMMISSION_PREVIEW_STALE`。同一来源内容不重复导入，同平台版本名称唯一，冲突返回 409 `COMMISSION_IMPORT_EXISTS`。旧导入的规则/映射结束有效期，新规则使用新行；禁止改写历史费率，历史报价保持不变。

最多 100 个一级类目、2,000 个二级类目，JSON 总大小最多 2 MiB。首版只接收三种固定区间的完整组合，校验叶子序号及 label/value 百分比一致、所有来源 cate_id 唯一；0% 是有效佣金，可正常导入；未匹配、父子关系不符、无有效类型的类目在预览中提示，并因无法建立商品类型映射而暂不参与算价。缺少或重叠档位不能发布。

## 卖家查询

`GET /pricing/commission-rules?store_id={uuid}&platform_product_category_id={uuid}`，也可用 `description_category_id={外部类目ID}` 替代内部类目 ID，两者必须且只能指定一个。当前固定 RU/rFBS，无需前端重复传入履约枚举。

需要门店属于当前工作空间。返回 `{data:{category_name,currency_code,bands,version,source,effective_from}}`；每档含 `{id,min_price,max_price,min_inclusive,max_inclusive,commission_rate}`。内部类目必须属于门店平台且有效；外部 ID 必须能唯一解析到同平台已核对佣金类目。没有可用规则返回 422 `PRICING_COMMISSION_UNAVAILABLE`，不能将缺失规则推定为 0% 佣金。

报价与此查询共用正式佣金解析器。现有 `PricingOption` 增加可选 `commission_details`（类目、区间、来源版本），以兼容已持久化的历史报价。规则换版会使待确认预览失效，已确认报价不重新计算。