上游平台接入指南 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
}
- 验签、解析并保存事件,按
eventId去重。创建订单的响应若尚未返回,可先按externalOrderNo关联。 - 按
orderNo比较version,只用更高版本更新本地订单。若先收到更高版本,可直接使用其中的完整订单视图,或查询最新进度。对重复事件或旧版本保留当前进度。 - 持久保存事件后返回 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 后可用查询接口核对最新进度。