鲸予衣物护理 合作接口文档

上游平台接入指南 V1

上游平台将已付款的洗护订单提交给鲸予,保存鲸予返回的订单号,并通过订单查询或回调同步进度。鲸予返回 HTTP 202 时,订单已登记。服务商接单、实际取件和签收以订单进度为准。

接入前准备

双方确认接入范围与启用时间后,鲸予会提供对应环境的 HTTPS 接口地址、合作账号标识 partnerId、签名密钥和可以销售的服务编号 serviceCode。签名密钥通过双方约定的安全渠道交接。上游平台应提供可接收订单通知的 HTTPS 域名,使用标准 443 端口,开放 POST /v1/partner/order-events。

联调前确认可售商品、计量单位、件数或双数上限、服务区域与预约时间,以及改约、取消、退款、售后和结算责任。请使用双方确认的地址、编号及额度发起联调。本文示例中的编号、人名、地址、运单与时间均为虚构。

调用方向 方法与路径 成功响应
上游平台 → 鲸予 POST /v1/partner/orders HTTP 202,返回订单视图
上游平台 → 鲸予 GET /v1/partner/orders/{orderNo} HTTP 200,返回最新订单视图
鲸予 → 上游平台 POST /v1/partner/order-events 上游返回 HTTP 200 和 {"received":true}

请求签名

两个方向的请求都使用 HMAC-SHA256。POST 使用 Content-Type: application/json,请求体为未压缩的 UTF-8 JSON,最大 64 KiB。GET 请求体为空。

请求头 值
X-Partner-Id 联调时分配的合作账号标识,1–64 位字母、数字、下划线或短横线
X-Partner-Timestamp 十进制 Unix 时间戳,单位为秒。与接收方当前时间最多相差 300 秒
X-Partner-Signature HMAC-SHA256 结果,编码为 64 位小写十六进制字符

依次拼接时间戳、合作账号标识、大写 HTTP 方法、原始请求路径和请求体。每两个部分之间用一个 LF 换行符 \n 分隔。路径从 / 开始,保留实际发送的查询字符串。签名时使用实际发送的请求体字节。GET 签名字符串在路径后的 LF 结束。

timestamp + "\n" + partnerId + "\n" + METHOD + "\n" + pathAndQuery + "\n" + rawBody

以下 Node.js 示例可用于生成请求头。POST 生成请求体后,签名与实际发送都使用同一个 Buffer。验收回调时先对收到的原始字节校验签名,再解析 JSON。接收方应同时校验账号、时间戳和签名格式,并使用恒定时间比较。

import { createHmac } from 'node:crypto'

function signRequest({ partnerId, secret, method, pathAndQuery, rawBody = Buffer.alloc(0) }) {
  const timestamp = String(Math.floor(Date.now() / 1000))
  const prefix = [timestamp, partnerId, method.toUpperCase(), pathAndQuery].join('\n') + '\n'
  const signature = createHmac('sha256', secret)
    .update(prefix, 'utf8')
    .update(rawBody)
    .digest('hex')

  return {
    'X-Partner-Id': partnerId,
    'X-Partner-Timestamp': timestamp,
    'X-Partner-Signature': signature,
  }
}

提交订单

调用 POST /v1/partner/orders。以下字段均必填。

字段 格式与说明
externalOrderNo 上游订单号。在当前合作账号内唯一
items 1–50 条商品明细。每条含已分配的 serviceCode 与购买份数 quantity。份数为 1–10000 的整数,实际可购数量以商品规则为准
pickupWindow 含 startAt、endAt。时间须包含日期、秒与时区,支持 Z 或 +08:00 等偏移。结束时间须晚于开始时间,新订单的取件时段须尚未结束
pickupAddress 取件地址
returnAddress 返寄地址,填写最终收件信息
payment 含上游付款凭据 reference、实付金额 amountCent 和币种 currency。金额为 0–2147483647 的整数分,币种固定为 CNY,例如人民币 79 元填写 7900

订单号、服务编号与付款凭据最长 80 位,以 ASCII 字母或数字开头,其余可使用 ASCII 字母、数字、点、下划线、冒号或短横线。两个地址均填写 contactName、contactPhone、province、city、district、detail。这些字段为非空字符串,长度上限分别为 50、32、64、64、64、240。

quantity 按购买份数填写。若已确认的套餐每份包含 2 件,购买 1 份时填写 quantity: 1,鲸予按 2 件核对上限。专洗运动鞋按双计量,衣鞋任洗中一件衣服或一双鞋各按一件计量。同单可购买的商品组合与数量以双方确认的商品清单为准。

付款字段用于记录上游报送的付款信息。请按双方约定处理对账、退款及售后。

{
  "externalOrderNo": "PLATFORM-EXAMPLE-001",
  "items": [{ "serviceCode": "SERVICE-EXAMPLE", "quantity": 1 }],
  "pickupWindow": {
    "startAt": "2030-01-09T09:00:00+08:00",
    "endAt": "2030-01-09T10:00:00+08:00"
  },
  "pickupAddress": {
    "contactName": "示例取件人",
    "contactPhone": "00000000000",
    "province": "示例省",
    "city": "示例市",
    "district": "示例区",
    "detail": "示例路 1 号"
  },
  "returnAddress": {
    "contactName": "示例收件人",
    "contactPhone": "00000000000",
    "province": "示例省",
    "city": "示例市",
    "district": "示例区",
    "detail": "示例路 2 号"
  },
  "payment": { "reference": "PAY-EXAMPLE-001", "amountCent": 7900, "currency": "CNY" }
}

首次登记返回 HTTP 202,上游应保存 orderNo。相同账号用相同的 externalOrderNo 和原订单内容再次提交时,仍返回原订单的当前视图。保持商品明细及其顺序一致。若使用相同订单号提交不同内容,返回 HTTP 409 EXTERNAL_ORDER_CONFLICT。已登记订单需要改约或取消时,请通过双方约定的渠道办理。

查询订单

调用 GET /v1/partner/orders/{orderNo},使用提交订单返回的鲸予订单号,仅查询当前合作账号的订单。新建和查询返回相同结构。

字段 含义
orderNo、externalOrderNo 鲸予订单号和上游原订单号
status、version 当前订单状态和订单视图版本。初始版本为 1,进度更新时递增
fulfillmentNo、providerOrderNo 承接任务参考编号和服务商预约参考编号。预约编号未确认时为 null
pickupWaybill、returnWaybill 去程和返寄运单,结构为 {carrierCode,waybillNo}。尚无运单时为 null
signedAt 客户实际签收时间,使用 UTC,签收前为 null
exceptionReason 待核实或无法承接时的业务提示,其他情况为 null

首次登记的响应示例。

{
  "orderNo": "JY-00000000-0000-4000-8000-000000000001",
  "externalOrderNo": "PLATFORM-EXAMPLE-001",
  "fulfillmentNo": "FT-00000000-0000-4000-8000-000000000001",
  "status": "pending_acceptance",
  "version": 1,
  "providerOrderNo": null,
  "pickupWaybill": null,
  "returnWaybill": null,
  "signedAt": null,
  "exceptionReason": null
}

订单状态

status 可展示给用户的含义
pending_acceptance 订单已登记,等待接单
acceptance_unknown 接单结果待核实
accepted 服务商已接单
pickup_booked 已预约取件,可查看去程运单
picked_up 已取件
received 衣物已到厂
washing 洗护中
return_shipped 已寄回,可查看返寄运单
signed 客户已签收
rejected 本次预约无法承接,可查看 exceptionReason
canceled 取件前已取消

signed、rejected 和 canceled 为当前订单的履约终态。后续售后事项按双方约定处理。

接收订单通知

鲸予通过 POST /v1/partner/order-events 发送状态通知,包含完整订单视图及 eventId、type 和 occurredAt。type 固定为 order.updated,occurredAt 为状态事件发生时间,使用 UTC。

{
  "eventId": "JY-00000000-0000-4000-8000-000000000001:8",
  "type": "order.updated",
  "occurredAt": "2030-01-10T07:20:00.000Z",
  "orderNo": "JY-00000000-0000-4000-8000-000000000001",
  "externalOrderNo": "PLATFORM-EXAMPLE-001",
  "fulfillmentNo": "FT-00000000-0000-4000-8000-000000000001",
  "status": "signed",
  "version": 8,
  "providerOrderNo": "APPT-EXAMPLE-001",
  "pickupWaybill": { "carrierCode": "EXAMPLE", "waybillNo": "PICKUP-EXAMPLE-001" },
  "returnWaybill": { "carrierCode": "EXAMPLE", "waybillNo": "RETURN-EXAMPLE-001" },
  "signedAt": "2030-01-10T07:20:00.000Z",
  "exceptionReason": null
}
  1. 验签、解析并保存事件,按 eventId 去重。创建订单的响应若尚未返回,可先按 externalOrderNo 关联。
  2. 按 orderNo 比较 version,只用更高版本更新本地订单。若先收到更高版本,可直接使用其中的完整订单视图,或查询最新进度。对重复事件或旧版本保留当前进度。
  3. 持久保存事件后返回 HTTP 200 和下列 JSON。已接收的重复事件及验签通过的旧版本也应确认收到。
{"received":true}

通知超时、返回其他 HTTP 状态或缺少 received: true 时,鲸予会用相同的 eventId 退避重投。上游可主动查询订单,核对最新状态。建议对通知和查询使用同一套版本更新规则。

错误处理与重试

鲸予返回的业务错误包含 code、message 和 requestId,响应头 X-Request-Id 含同一编号。反馈时提供请求编号和上游订单号即可。

HTTP 状态 含义与处理
400 JSON 无效或 GET 带请求体,修正请求
401 / 403 签名校验失败或合作账号角色不符,核对账号、路径、请求体与时钟
404 无法在当前合作账号下查询订单,或接口尚未开放。核对环境、账号与订单号
409 EXTERNAL_ORDER_CONFLICT 表示相同订单号用于不同内容,核对原单
413 / 415 请求体超过大小限制,或媒体类型、编码不符
422 字段或商品规则校验失败,按业务错误修正
429 入口限流,退避后沿用原订单号重试。此响应可能由网关直接返回
503 PARTNER_INTAKE_PAUSED 表示暂停接收新单,按 Retry-After 等待。已经登记的订单仍可查询或用原内容重提

常见 422 业务错误包括 VALIDATION_FAILED(字段格式不符)、SERVICE_UNAVAILABLE(账号未开放该服务编号)、INCOMPATIBLE_SERVICES(商品需要分开结算)、SERVICE_QUANTITY_EXCEEDED(超过商品数量上限)以及 APPOINTMENT_EXPIRED(取件时段已结束)。

提交时遇到网络超时或临时服务错误,使用当前时间重新签名,沿用同一 externalOrderNo 和原订单内容重试。取得 orderNo 后可用查询接口核对最新进度。