接入指南

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

接入指南

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

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

本文面向需要读取、处理本站本地订单及售后的管理系统。可导入 Apifox、Swagger 等工具的契约见 management-openapi-v1.yaml，店铺经营对接见 店铺供货 API。

接入信息

接入方保存以下三个参数：

参数

说明

商户域名

商户提供的主站 HTTPS 域名

管理员账户

后台管理员的登录账户名

管理员 API Key

绑定该管理员的独立密钥，仅接受 ADM_ 加 16 位小写十六进制字符，共 20 个字符

主管理员在“后台用户”中生成并启用密钥。重置后旧密钥立即失效；管理员停用、API 停用或角色撤权后，相关请求不再允许。密钥只在生成时展示，请保存在服务端密钥配置中，不写入浏览器代码、URL 或日志。

基础地址：

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

该分组只使用主站域名。管理员仍受原订单、售后权限和商户身份要求约束；有订单权限不代表有售后权限。

请求头

X-KYS-Admin-Account: <ADMIN_ACCOUNT>
X-KYS-Key: <ADMIN_API_KEY>
Content-Type: application/json

使用管理员登录账户和独立 API Key 验证，不传登录密码、Cookie、API Secret、时间戳或签名。请求头名称不区分大小写。

数据范围

订单列表、订单详情和订单处理覆盖本站所有已付款的以下订单，包括分站成交订单：

  1. 本地货源卡密订单。

  2. 本地货源充值订单。

  3. 无货源的人工充值订单。

不按创建入口或管理员本人限定订单。售后列表、详情和处理覆盖所有来源的售后，包括其他渠道和远程货源订单的售后；售后读取关联订单不受上述本地订单范围限制。

通用约定

  • 使用 HTTPS、UTF-8。除注明外，请求体和响应为 application/json。

  • 路径 {id} 是订单或售后的整数 ID，1～10 位正整数；它与 orderNo、complainNo 不同。

  • 时间字段为 Unix 秒级整数；列表日期筛选为 YYYY-MM-DD，按北京时间自然日计算。

  • 金额单位为人民币元。实付及退款金额一般保留两位小数，单价、成本、利润可保留四位小数。后台部分十进制字段返回字符串，应按字段类型读取并用十进制方式计算。

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

  • 列表不附带全站汇总统计。GET 订单详情返回全部卡密，GET 售后详情返回全部消息。

  • 资源或权限检查在每次操作时执行；收到详情后，订单状态仍可能因其他操作者而变化。

统一响应

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

code=0 表示接口调用成功。批量处理还必须检查 data 内每一项的 result，不能将外层成功当作所有订单处理成功。问题排查请保存 requestId，不要记录密钥或完整卡密。

分页 data：

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

接口清单

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

方法

路径

用途

GET

/orders

分页获取本地订单

GET

/orders/{id}

获取订单完整详情

POST

/orders/process

单个或批量处理订单

GET

/aftersales

分页获取所有来源售后

GET

/aftersales/{id}

获取售后完整详情

POST

/aftersales/{id}/process

回复、处理售后

限流、错误和同步

类别

配额

订单 GET 接口

每管理员每分钟 120 次

售后 GET 接口

每管理员每分钟 120 次

订单处理

每管理员每分钟 30 次

售后处理

每管理员每分钟 30 次

账户总额度

每管理员每分钟 600 次，瞬时容量 30

认证尝试

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

额度由同一管理员的请求共同消耗。响应可携带 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset；Reset 为 Unix 秒级时间，收到 429/503 时按 Retry-After 秒数等待。

HTTP

常见 code

处理方式

400

400001

检查参数、操作资格及当前状态

401

401001

检查管理员账户、Key、账户及 API 开关

403

403001

检查角色权限、商户身份要求及账户限制

404

404001、404002

检查主站域名、完整路径、资源 ID 和本地订单范围

409

409001

请求编号内容冲突或操作冲突，先核对原请求

429

429001

按 Retry-After 退避

503

503001

暂时不可用，读取可退避重试，写入先核对结果

500

500001

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

域名、入口或网关直接拒绝的请求可能不使用上述 JSON 格式，先检查 HTTP 状态和响应类型。

订单及售后采集使用分页列表和详情查询，按 id 关联，重复读取按状态、消息 ID 去重。本分组不新增管理事件订阅。订单处理引发的采购方回调由平台按原订单通知约定发送；管理员对接以订单详情确认处理或退款结果，不需要自行重发采购方通知。

字段与状态

订单

字段

JSON 类型

说明

id / orderNo

integer / string

订单 ID、平台订单号

status

string

pending 待处理、processing 处理中、success 成功、canceled 已取消、partially_refunded 部分退款、refunded 已退款

orderType

string

订单记录的类型代码，常见 local、platform、partner、supplier、sales_channel、redemption；与列表查询参数的来源分类不同，例如 orderType=platform 筛选结果可返回 local

source

string

详情中的创建入口代码，例如 front、openapi

sourceType

string

货源类型；本订单分组返回 local

productType

string

card 卡密、recharge 充值

goodsId / skuId

integer

商品、规格 ID；无规格时 skuId 为 0

goodsName / skuName / goodsImage

string 或 null

商品、规格显示信息

quantity

integer

购买数量

salePrice / costPrice / profit

number 或 string

单价、成本、利润，十进制字段可能为字符串，最多四位小数

totalPrice / refundedAmount

number

实付、累计已退金额

taxType / taxRate / taxAmount / refundedTaxAmount

string / number

计价类型为 exclusive 不含税、personal 个人含税、enterprise 企业含税；其余为税率、税额和已退税额

paymentChannel / paymentNo / paymentTime

string 或 null / string 或 null / integer

支付渠道、支付单号、支付时间

createdAt / updatedAt / completedAt

integer

创建、更新、完成时间；未发生可为 0；updatedAt 在详情中返回

processingTime

integer

处理耗时，秒

user

object

买家 id、nickname、可选 avatar、isGuest

processMessage

string 或 null

按订单返回的处理进度展示信息；进度写入参数见处理订单

message / remark / adminRemark

string 或 null

处理说明、订单备注、后台备注；详情返回

orderParams / normalizedInputValues

array

充值资料；数据字段按该订单模板读取

inputTemplateSnapshot

object 或 array

输入模板；无模板时可为 []，字段定义在 fields 中

currentFulfillmentAttemptId / finalFulfillmentAttemptId

integer 或 null

当前、最终履约记录 ID；尚无履约记录或历史人工处理订单可为 null

cardSecrets

array

详情的完整卡密数组，项字段见获取订单详情；卡密项 id 可能是数字字符串

rechargeProof

object 或 null

充值凭证：url、uploadedAt、expiresAt，按有效期访问，URL 应保密

verificationCodeRequired / verificationCodeInfo

boolean / object 或 null

是否需要验证码及当前验证码状态

refundHistory / refundFailure

array / object 或 null

退款历史、退款失败信息，主要在详情返回

storeInfo / subsiteInfo / salesChannelInfo / openApiInfo

object

按订单来源返回的归属或渠道信息，可能省略

字段会随订单类型和可用信息省略或为 null。请忽略未知附加字段，不把展示字段当作操作凭据；不要使用履约内部状态代替 status 判断订单最终结果。

售后与实物服务

售后基础字段：id、userId、complainNo、topic、orderNo、status、source、serviceType、serviceStatus、createdAt、updatedAt、order。详情增加完整 messages 和按需返回的 physical。

消息字段：id、complainId、sender、content、messageFormat、timestamp；部分消息带 senderLabel。messageFormat 常见 text、image，按返回类型展示。

serviceType 为空表示普通售后或微信投诉；实物为 refund_only 仅退款、return_refund 退货退款、exchange 换货。serviceStatus 常见 pending、awaiting_return、return_shipped、refunding、awaiting_replacement、completed、rejected、canceled，具体允许动作由当前服务状态决定。

物流对象为空时为 null，非空时包括 carrierCode、carrierName、trackingNo、status、shippedAt。快递选项包含 code、name 及对应要求。

请求示例

通过环境变量提供凭据：

curl --get "${KYS_BASE_URL}/openapi/v1/admin/orders" \
  -H "X-KYS-Admin-Account: ${KYS_ADMIN_ACCOUNT}" \
  -H "X-KYS-Key: ${KYS_ADMIN_API_KEY}" \
  --data-urlencode 'status=pending' \
  --data-urlencode 'page=1' \
  --data-urlencode 'pageSize=20'
curl "${KYS_BASE_URL}/openapi/v1/admin/orders/process" \
  -H "X-KYS-Admin-Account: ${KYS_ADMIN_ACCOUNT}" \
  -H "X-KYS-Key: ${KYS_ADMIN_API_KEY}" \
  -H 'Content-Type: application/json' \
  --data '{"orderIds":[12345],"status":"success","message":"处理完成"}'

其中 KYS_BASE_URL 形如 https://merchant.example.com，不包含 /openapi/v1；示例中的订单、卡密和请求编号均为演示值。

上一篇下一篇