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（类目、区间、来源版本），以兼容已持久化的历史报价。规则换版会使待确认预览失效，已确认报价不重新计算。