接入指南

API文档最后更新: 2026-10-28

接入指南

完整文档下载：Markdown · OpenAPI YAML。

版本：1.0.0 · 契约修订：2026-10-28.2

本文用于店铺自有商品订单、供货订单及售后的经营对接。商品查询、采购下单等对接另见 采购 OpenAPI 文档；管理员接入见 后台管理 API。机器可读契约见 management-openapi-v1.yaml。

开始接入

接入需要三个参数：主站 HTTPS 域名、店主的前台用户 ID、该用户当前的 OpenAPI Key。店铺须具备经营权限、审核通过且处于启用状态。店铺身份由认证用户确定，不传 storeId。

基础地址：

https://{merchant-domain}/openapi/v1/seller

请求头：

X-KYS-User-Id: <USER_ID>
X-KYS-Key: <OPENAPI_KEY>
Content-Type: application/json

  • 仅使用主站域名。店铺可以获取在分站成交的本店订单，但经营接口不改用分站域名。

  • Key 与前台“接口管理”中的 Key 共用，支持 AK_ 加 16 位或 32 位小写十六进制字符。重置后旧 Key 立即失效。

  • 沿用该用户的 OpenAPI 开关、账户状态和 IP 白名单，不需要另申请供货密钥。

  • 不传 Cookie、登录密码、API Secret、时间戳或签名。密钥不得放入 URL、浏览器代码或日志。

订单范围与操作权限

可见订单包括：

  1. 该店铺销售的自有商品订单。

  2. 该店铺作为当前有效供货方的订单。

  3. 由该店铺人工供货、没有履约尝试记录的订单。

范围包括卡密、充值、实物及合法分站成交订单。历史上曾供货、现在已不由本店履约的订单，不因此获得供货权限。售后沿关联订单的店铺归属判断可见性。

返回信息

用途

isSeller / role

是否销售方；role=seller 或 supplier

canFulfill

是否由本店履约且已付款；具体动作还须符合当前状态

canProcessRecharge

当前能否处理人工充值

canUploadRechargeProof

当前是否具备人工充值凭证上传资格

canRefund / refundPending

是否可申请退款、是否正在退款

physical.canShip / canUpdateLogistics

实物发货、修改运单资格

canReply

当前是否可向买家回复或提交意见

canHandleExchange

当前是否由本店处理换货；还须匹配实物售后服务状态

销售方与实际履约方可能不同。销售方可按资格回复买家，供货方可查看相关售后，但供货身份本身不授予面向买家的回复或售后裁决权限。每次写入仍以服务端当时的状态和权限检查为准。

通用约定

  • HTTPS、UTF-8。除凭证上传外，请求体为 application/json。

  • 路径 {id} 为 1～10 位正整数，订单 ID、售后 ID 与其单号分别保存。

  • 时间是 Unix 秒级整数；金额单位为人民币元。totalPrice、refundedAmount 为两位金额，supplyAmount 可保留四位小数。

  • 列表 page 从 1 开始，pageSize 默认 20，范围 1～100。

  • GET 订单详情的 cards.list、GET 售后详情的 messages.list 返回全部记录；不要用 cardPage 或 messagePage 截断它们。

  • POST/PUT 返回的是操作后的详情快照，其中卡密、消息可能按每页 100/50 条返回；要获取完整记录，再调用对应 GET 详情。

成功响应：

{"code": 0, "message": "success", "data": {}, "requestId": "req_example"}

列表 data：

{"list": [], "total": 0, "page": 1, "pageSize": 20}

同时检查 HTTP 状态、code 及返回的业务状态。退款受理成功不表示资金已经退回。

接口清单

以下路径均接在 /openapi/v1/seller 后。

方法

路径

用途

GET

/orders

分页获取自有商品与供货订单

GET

/orders/{id}

获取订单完整详情

POST

/orders/{id}/recharge-result

处理人工充值，或上传充值凭证

POST

/orders/{id}/deliver

本地卡密出库、实物发货

PUT

/orders/{id}/logistics

更新实物运单

POST

/orders/{id}/refund

全额退还剩余可退金额

GET

/aftersales

分页获取可见售后

GET

/aftersales/{id}

获取售后完整详情

POST

/aftersales/{id}/messages

回复或举证

POST

/aftersales/{id}/decision

提交商家处理意见

POST

/aftersales/{id}/exchange

处理已批准换货的物流

错误、限流与重试

类别

配额

订单 GET 接口

每用户每分钟 120 次

售后 GET 接口

每用户每分钟 120 次

订单写接口

每用户每分钟 30 次

售后写接口

每用户每分钟 30 次

用户总额度

每用户每分钟 600 次，瞬时容量 30

认证尝试

同一商户、同一来源 IP 每分钟 200 次

店铺接口与该用户的采购 OpenAPI 共享账户和对应分组额度。响应可携带 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset，以 Retry-After 的秒数退避。

HTTP

常见 code

处理方式

400

400001

参数错误、状态不允许、订单或售后不属于本店、店铺未通过审核或停用

401

401001

用户 ID、Key 不匹配，账户或 API 未启用

403

403001、403002

权限不足、IP 不在白名单或经营资格不满足

404

404001、404002

域名、路径或资源不存在

409

409001

请求编号与已有内容冲突，核对原请求

429

429001

请求频率超限，按 Retry-After 等待

503

503001

暂时不可用；读取可退避重试，写入先确认结果

500

500001

保存 requestId 联系商户；写入结果未知时先查详情

域名或入口直接被网关拒绝时，可能使用其他错误正文，先检查 HTTP 状态和响应类型。

重试规则：

  • GET 可在退避后重试，列表按订单 ID、消息 ID 去重。

  • 退款、回复、处理意见保留同一 requestNo 和相同内容重试。

  • requestNo 不是所有写接口的通用幂等参数。充值处理、运单、换货先查询当前状态及已有结果，再决定是否继续操作。

  • 微信投诉远端结果待确认时，先核对详情与消息，不换编号盲重发。

  • 本分组不新增管理事件订阅，订单与售后采集采用分页查询；涉及采购方的通知仍按原订单回调约定由平台发送。

返回字段

订单

字段

JSON 类型

说明

id / orderNo

integer / string

订单 ID、平台单号

goodsName / skuName / goodsImage

string 或 null

商品、规格显示信息

productType

string

card、recharge、physical

quantity / isPay

integer / boolean

数量、是否付款

status

string

pending、processing、success、canceled、partially_refunded、refunded

fulfillmentStatus

string

履约状态代码，用于辅助展示；最终交易结果仍读取 status

isSeller / role

boolean / string

是否销售方，角色 seller/supplier

totalPrice

number

销售方可见的买家实付金额

refundedAmount

number

销售方详情可见的累计退款金额

supplyAmount

number 或 null

纯供货方可见的本店供货金额，可能四位小数；无历史报价时为 null

createdAt / paymentTime / completedAt

integer

创建、付款、完成时间；未发生可为 0

remark / message

string 或 null

备注、处理说明，详情字段

processStart / processCurrent / processTarget

integer

处理进度，详情字段

canFulfill / canProcessRecharge / canUploadRechargeProof / canRefund / refundPending

boolean

详情的操作资格及退款进行状态

inputTemplateSnapshot

object 或 array

履约输入模板；无模板时可为 []

normalizedInputValues

array

履约资料，按模板 fieldKey 读取；仅按履约权限返回

verificationCodeRequired / verificationCodeInfo

boolean / object 或 null

验证码要求与当前状态；只返回履约所需信息

rechargeProof

object 或 null

凭证 url、uploadedAt、expiresAt

cards

object

list,total,page,pageSize；卡密项为 id,cardNumber,cardSecret,expireTime

physical

object

实物地址、物流、快递选项与可执行操作

非适用字段可能省略或为 null，未知附加字段请忽略。纯供货方不返回买家实付和退款金额，不用 supplyAmount 替代买家订单总额。

售后与物流

售后项字段：id、complainNo、orderId、orderNo、goodsName、productType、topic、status、serviceType、serviceStatus、createdAt、updatedAt、canReply。

售后 status：pending 待处理、processing 处理中、completed 已完成、terminated 已终止。

消息在 messages.list，包括 id、sender、senderLabel、content、messageFormat、timestamp。sender 为 user 或 service，展示时优先使用 senderLabel；messageFormat 常见 text、image。

实物售后的 serviceType 为 refund_only、return_refund、exchange，普通售后可为空。physical 包括 id、serviceType、serviceStatus、returnAddress、returnLogistics、replacementLogistics、carrierOptions。未形成的物流为 null，地址未提供时可为 []。

订单 physical 包括 shippingAddress、logistics、carrierOptions、canShip、canUpdateLogistics。地址及物流按返回内容展示，不自行拼接其他接口编号。

请求示例

curl --get "${KYS_BASE_URL}/openapi/v1/seller/orders" \
  -H "X-KYS-User-Id: ${KYS_USER_ID}" \
  -H "X-KYS-Key: ${KYS_OPENAPI_KEY}" \
  --data-urlencode 'page=1' \
  --data-urlencode 'pageSize=20' \
  --data-urlencode 'status=pending'
curl "${KYS_BASE_URL}/openapi/v1/seller/aftersales/5001/messages" \
  -H "X-KYS-User-Id: ${KYS_USER_ID}" \
  -H "X-KYS-Key: ${KYS_OPENAPI_KEY}" \
  -H 'Content-Type: application/json' \
  --data '{"content":"已收到，正在核实","attachments":[],"requestNo":"seller_reply_20261028_0001"}'

KYS_BASE_URL 形如 https://merchant.example.com，不包含 /openapi/v1。示例编号、卡密及凭证均为演示值；成功响应中的敏感资料也应按密钥同等要求保护。

上一篇下一篇