pinkr-openapi-skill（Pinkr OpenAPI 技能）

pinkr_openapi 品氪 OpenApi 开放平台 Skill

本 Skill 由品氪提供 OpenApi 开放平台，支持门店管理、导购管理、会员管理、订单管理、退单管理、库存管理、商品管理、积分管理、储值管理、卡券管理、销售数据同步、营销数据分析、分销管理等全链路 CRM/SCRM 功能。通过调用品氪后端相关原生接口，实现第三方系统与品氪平台的数据互通，所有操作均通过安全认证的 API 接口完成。

tags: ["SCRM", "CRM", "openAPI", "api", "会员管理", "订单管理", "商品管理"]
use_when:
  - 用户需要同步门店、导购基础数据到品氪平台
  - 用户需要管理会员信息（查询/新增/更新会员）
  - 用户需要同步订单、退单、发货信息
  - 用户需要管理商品、库存数据
  - 用户需要同步积分、储值、卡券数据
  - 用户需要同步销售小票数据
  - 用户需要查询营销统计数据
  - 用户需要查询分销订单数据
not_for:
  - 非授权的第三方数据访问
  - 商业数据倒卖、非法数据爬取
# 环境变量配置
parameters:
  - name: PK_APPKEY
    description: 品氪开放平台分配的APPKEY
    required: true
    type: secret
    default: process.env.PK_APPKEY
  - name: PK_API_URL
    description: 品氪API基础地址
    required: false
    type: string
    default: process.env.PK_API_URL || "http://dev.openapi.pinkr.com"

功能说明

根据用户问句自动识别意图并调用对应接口，支持以下功能模块：

1. 门店管理：上传门店基础数据。
2. 导购管理：上传导购基础数据，支持所属门店绑定。
3. 会员标签：上传标签分类、标签、会员标签明细，获取标签资料。
4. 订单管理：获取订单列表及商品明细，更新发货信息，接收第三方订单，更新仓库发货状态。
5. 退单管理：获取退货退款单、退款单，更新退货退款状态和退款状态，接收第三方退货单。
6. 库存管理：获取仓库清单和商品清单，批量更新/获取商品库存。
7. 商品管理：上传商品尺码、颜色、SPU属性，上传商品，上传商品价格（千店千面），全量上传商品。
8. 会员管理：获取/更新会员信息，更新会员等级，新增会员卡，获取品氪会员信息，新增会员收货地址。
9. 积分管理：新增会员积分流水。
10. 储值管理：新增会员储值流水，绑定储值卡，储值卡变动消息推送。
11. 卡券管理：批量核销卡券。
12. 销售数据：接收小票（同步第三方订单明细）。
13. 营销数据：获取会员统计、目标管理、分组信息、标签会员等数据。
14. 分销管理：获取付费订单列表。
15. 订阅消息服务：接收品氪端推送的会员、积分、储值、卡券、商品、库存、订单等变更消息。

配置

• PK_APPKEY：品氪开放平台分配的 APPKEY，需保密。
• PK_API_URL：品氪 API 基础 URL，测试环境为 http://dev.openapi.pinkr.com。
• 正式环境每接口每秒并发数上限默认为 10。

在使用前，请确保已配置以下环境变量：

// 导出APPKEY和API地址
export PK_APPKEY= ${PK_APPKEY} || process.env.PK_APPKEY
export PK_API_URL= process.env.PK_API_URL || "http://dev.openapi.pinkr.com"

使用方式

1. 在品氪开放平台申请商户号和接口接入 IP 地址。
2. 开放平台分配接入的 APPKEY。
3. 使用 POST 请求接口，所有请求均使用 Content-Type: application/json。

数据请求格式

所有接口使用统一的 POST 表单方式提交：

{
  "method": "接口名称",
  "appid": "pinkr",
  "data": "请求数据实体(JSON格式字符串)",
  "v": "1"
}

公共响应参数

状态码

功能概览

前置要求

• 用户需在品氪开放平台申请商户号并获取 PK_APPKEY。
• 接入前需在品氪开放平台配置接口接入 IP 地址。
• 正式环境每接口每秒并发数上限默认为 10。
• 请求使用 POST 表单方式提交，appid 字段传 pinkr。

接口说明

1. 获取支持的快递列表

• 功能：获取支持的快递列表
• 接口名称：common.express.get
• 请求参数：无
• 返回数据：

2. 上传门店

• 功能：上传门店基础数据，重复上传会覆盖上一次数据
• 接口名称：store.upload
• 请求参数：

3. 上传导购

• 功能：上传导购基础数据，重复上传会覆盖上一次数据
• 接口名称：guide.upload
• 请求参数：

4. 上传标签分类

• 功能：上传标签分类主数据
• 接口名称：tag.category.upload
• 请求参数：

5. 上传标签

• 功能：上传标签主数据
• 接口名称：tag.tag.upload
• 请求参数：

6. 上传会员标签明细

• 功能：更新品氪端会员的标签明细
• 接口名称：tag.memberTag.upload
• 请求参数：

7. 获取标签资料

• 功能：获取商户定义的标签基础资料
• 接口名称：tag.tag.get
• 请求参数：无
• 返回数据：

8. 获取订单列表（分页）

• 功能：获取线上订单列表，被拆单生成的新子订单不会显示
• 接口名称：order.order.get
• 请求参数：

返回数据主要字段：

订单金额计算逻辑：order_fact_money = order_money - customer_price - promotion_price - coupon_price - bonus_price + postage_price + wipe_off_price + change_price

9. 获取订单商品明细

• 功能：获取订单商品明细
• 接口名称：order.orderGoods.get
• 请求参数：

返回数据主要字段：

商品实付单价 = goods_fact_money / number

10. 更新订单发货信息

• 功能：更改线上订单发货状态
• 接口名称：order.delivery.update
• 请求参数：

delivery_goods 商品明细：

必须传商品『款 goods_sn、外部编码 sku_code』或『款 goods_sn、色 color_code、码 size_code』参数，两种方式二选一。

11. 接收第三方订单

• 功能：接收第三方商城订单到品氪端
• 接口名称：order.order.add
• 注意事项：

- 拆单后只传子单，但订单金额、优惠等都需要相应拆分 - 所属门店代码为第三方商城在品氪的虚拟门店代码 - 明细的合计金额必须等于主数据的金额，明细的合计数量必须等于主数据的数量 - 订单金额计算逻辑：order_fact_money = order_money - customer_price - promotion_price - coupon_price - bonus_price + postage_price

请求参数：

12. 更新订单仓库发货状态

• 功能：更改订单仓库提交状态
• 接口名称：order.storage.updateStatus
• 请求参数：

13. 获取退货退款单（分页）

• 功能：获取退货退款单列表
• 接口名称：refund.returnRefund.get
• 请求参数：

14. 更新退货退款单状态

• 功能：商家同意退货、商家已收货
• 接口名称：refund.returnRefund.status.update
• 请求参数：

15. 获取退款单（分页）

• 功能：获取申请退款（仅退款）、退款完成退款单列表
• 接口名称：refund.refund.get
• 请求参数：

16. 更新退款状态

• 功能：商家同意退款
• 接口名称：refund.status.update
• 请求参数：

17. 接收第三方退货单

• 功能：接收第三方退货单到品氪端
• 接口名称：refund.returnRefund.add
• 注意事项：明细的合计金额必须等于主数据的金额，明细的合计数量必须等于主数据的数量
• 请求参数：

18. 获取仓库清单

• 功能：获取需要同步商品库存的仓库清单
• 接口名称：stock.storageList.get
• 请求参数：无
• 返回数据：

19. 获取商品清单

• 功能：获取需要同步商品库存的商品清单
• 接口名称：stock.goodsList.get
• 请求参数：无
• 返回数据：

20. 批量更新商品库存

• 功能：批量同步商品库存到品氪端
• 接口名称：stock.goodsStock.batchUpdate
• 注意事项：goods_stocks 数组限制数量为 300
• 请求参数：

21. 批量获取商品库存（分页）

• 功能：获取品氪端商品库存
• 接口名称：warehouse.goodsStock.get
• 请求参数：参数都不传时不做筛选，全部返回

返回数据：

22. 上传商品尺码

• 功能：上传商品 SKU 绑定的尺码
• 接口名称：goods.size.upload
• 请求参数：

23. 上传商品颜色

• 功能：上传商品 SKU 绑定的颜色
• 接口名称：goods.color.upload
• 请求参数：

24. 上传商品 SPU 父级属性

• 功能：上传商品 SPU 父级属性
• 接口名称：goods.attributeName.upload
• 请求参数：

25. 上传商品 SPU 子属性

• 功能：上传商品 SPU 子属性
• 接口名称：goods.attributeValue.upload
• 请求参数：

26. 上传商品

• 功能：上传商品
• 接口名称：goods.goods.upload
• 请求参数：

27. 上传商品价格（千店千面）

• 功能：上传商品价格作为千店千面商品价格调价单
• 接口名称：goods.price.upload
• 请求参数：

28. 全量上传商品

• 功能：全量上传商品，含颜色、尺码、属性基础资料自动创建
• 接口名称：goods.goods.fullUpload
• 请求参数：

29. 获取会员信息

• 功能：获取品氪端的会员信息
• 接口名称：member.info.get
• 请求参数：

返回数据：

30. 更新会员等级

• 功能：更新品氪端会员等级
• 接口名称：member.level.update
• 请求参数：

31. 更新会员信息

• 功能：更新品氪端会员信息
• 接口名称：member.info.update
• 请求参数：

32. 新增会员卡

• 功能：第三方会员开卡后同步至品氪
• 接口名称：member.add
• 注意事项：该会员卡对应积分、储值、小票需通过对应接口上传到品氪
• 请求参数：

返回数据：

33. 获取品氪会员信息

• 功能：获取品氪端的会员信息，缓存 60 秒更新一次
• 接口名称：pinkrMember.info.get
• 请求参数：

返回数据：

34. 新增会员收货地址

• 功能：新增会员收货地址
• 接口名称：member.address.add
• 请求参数：

35. 新增会员积分流水

• 功能：新增会员积分流水
• 接口名称：integral.add
• 请求参数：

积分来源代码：

36. 新增会员储值流水

• 功能：新增会员储值流水
• 接口名称：deposit.add
• 请求参数：

储值金额说明：类型为 0、2、3、5 时为正数，类型为 1、4 时为负数。

37. 新增储值卡绑定

• 功能：线下售卡绑定，传递储值卡与会员的绑定信息到品氪
• 接口名称：deposit.card.bind
• 请求参数：

38. 批量核销卡券

• 功能：批量更改品氪端会员卡券状态
• 接口名称：coupon.status.batchUse
• 请求参数：

39. 接收小票

• 功能：同步第三方订单明细到品氪端
• 接口名称：sale.order.add
• 请求参数：

40. 获取会员统计数据

• 功能：获取会员相关统计数据，默认缓存两个小时
• 接口名称：data.member.count
• 请求参数：无
• 返回数据：

41. 获取商户目标管理

• 功能：获取商户目标管理，包括销售目标和开卡目标，默认缓存两个小时
• 接口名称：data.target.get
• 请求参数：

42. 获取会员分组基础资料

• 功能：获取会员分组基础资料，缓存时间 1 小时
• 接口名称：data.member.group.groupInfo.get
• 请求参数：

43. 获取预设会员分组类型

• 功能：获取预设会员分组类型
• 接口名称：data.member.group.config.get
• 请求参数：无

44. 获取对应会员分组下的会员

• 功能：获取对应会员分组下的会员
• 接口名称：data.member.group.get
• 请求参数：

45. 获取标签基础资料

• 功能：获取商户标签基础资料，缓存时间 1 小时
• 接口名称：data.Tag.get
• 请求参数：

46. 获取标签下的会员

• 功能：获取商户标签下的会员
• 接口名称：data.Tag.Member.get
• 请求参数：

返回数据：

47. 获取付费订单（分页）

• 功能：获取分销付费订单列表
• 接口名称：distribution.paidOrder.get
• 请求参数：

订阅消息服务

品氪开放平台提供主动推送服务，包括会员信息、积分、储值、卡券等消息订阅类型。第三方订阅后无需手动轮询调用。

验签算法

1. 将 appid、appkey、data、method、nonce、timestamp 根据参数名称 ASCII 码表顺序排序，拼接成 query string
2. 以 MD5(32) 算法计算签名字符串
3. 对签名字符串所有字符大写化
4. 将 sign 字段与其他参数一同放在请求中

重推机制

品氪开放平台对推送消息提供每 10 秒 1 次，共三次的重推机制。

订阅消息接口列表

错误处理

配置要求

• PK_APPKEY：品氪开放平台分配的 APPKEY，需保密。
• PK_API_URL：品氪 API 基础 URL。
• 依赖工具：curl（用于发起请求）、jq（用于解析 JSON 响应）。