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

下游服务商接入指南 V1

本文供承接鲸予洗护订单的合作服务商使用。鲸予发送派单并查询接单结果,服务商负责保存承接结果,并在取件、洗护和返寄过程中回传进度。

联调地址与调用方向

表中的域名为示例占位。联调前,双方确认各自的 HTTPS 地址、合作账号编号、签名密钥、服务编码、计量单位和承运商代码。密钥通过双方约定的安全渠道交接。

调用方向 方法和路径 用途
鲸予 → 服务商 POST https://provider.example.org/v1/assignments 接收派单并返回承接结果。
鲸予 → 服务商 GET https://provider.example.org/v1/assignments/{fulfillmentNo} 用鲸予原履约编号查询承接结果。
服务商 → 鲸予 POST https://jingyu.example.org/v1/fulfillment/events 回传取件、洗护、返寄或取消的实际进度。

服务商接口使用 HTTPS 标准 443 端口、可信证书和公网 IPv4 DNS 解析。请在配置的地址直接响应。POST 请求与成功响应使用未压缩的 UTF-8 JSON,设置 Content-Type: application/json。GET 请求体为空。请求和成功响应请控制在 64 KiB 以内。

请求签名

两个方向的 HTTP 请求均按约定账号使用同一签名规则。每次请求都将以下请求头各发送一次。

请求头 取值
X-Partner-Id 双方约定的合作账号编号,1–64 位,仅含英文字母、数字、下划线或短横线。
X-Partner-Timestamp 本次发送时的十进制 Unix 秒,1–12 位数字。接收方接受与当前时间相差不超过 300 秒的请求。
X-Partner-Signature HMAC-SHA256 输出的 64 位小写十六进制文本。

将时间戳、合作账号编号、大写 HTTP 方法、原始路径按顺序以单个 LF 字符 \n 连接,再追加一个 LF 和实际发送的请求体字节。路径从 / 开始,保留原有百分号编码、查询参数及其顺序。GET 也保留路径后的 LF,其后没有请求体字节。接收方用收到的原始字节验签,随后解析 JSON。

timestamp + "\n" + partnerId + "\n" + uppercaseMethod + "\n" + rawPathWithQuery + "\n" + rawBodyBytes

以下 Node.js 示例演示如何生成三个请求头。POST 先确定要实际发送的 UTF-8 字节,并将同一份字节传给签名函数和 HTTP 客户端。GET 可省略 body。

import { createHmac } from 'node:crypto'

function partnerHeaders({ partnerId, sharedKey, method, path, body = Buffer.alloc(0) }) {
  const timestamp = String(Math.floor(Date.now() / 1000))
  const prefix = `${timestamp}\n${partnerId}\n${method.toUpperCase()}\n${path}\n`
  const signature = createHmac('sha256', sharedKey)
    .update(prefix, 'utf8')
    .update(body)
    .digest('hex')
  return {
    'X-Partner-Id': partnerId,
    'X-Partner-Timestamp': timestamp,
    'X-Partner-Signature': signature,
  }
}

请求 HMAC 由请求方生成,签名范围到请求体为止。接单响应、查询响应及回调确认由原 HTTPS 请求返回,按该连接的 HTTP 状态码和响应 JSON 判定结果。重试时以当前发送时间重新签名,沿用原业务编号和业务内容。

接收派单

POST /v1/assignments 的请求字段如下。示例数据均为虚构。

字段 类型 含义
orderNo 字符串 鲸予订单号,用于沟通和核对。
fulfillmentNo 字符串 鲸予履约编号,用于接单去重、结果查询及后续回调。
items 非空数组 本次服务明细。每项含 serviceCode、quantity、unitCount 和 unit。
items[].serviceCode 字符串 双方约定的服务代码。
items[].quantity 正整数 购买数量,例如购买一套填 1。
items[].unitCount 正整数 实际交洗数量,例如一套两件填 2。
items[].unit 字符串 item 为件,pair 为双。请用 unitCount 和 unit 核对交洗数量。
pickupWindow 对象 startAt、endAt 为带时区的预约取件起止时间,结束晚于开始。
pickupAddress 对象 上门取件地址。
returnAddress 对象 洗护完成后的返寄地址。

两个地址各含六个非空字符串。contactName 为联系人(最多 50 字符),contactPhone 为联系电话(最多 32 字符),province、city、district 分别为省、市和区县(各最多 64 字符),detail 为详细地址(最多 240 字符)。两处地址可以不同。日期时间精确到秒,支持 Z 或数字时区偏移,可附最多三位毫秒。

{
  "orderNo": "JY-DEMO-ORDER-001",
  "fulfillmentNo": "FT-DEMO-001",
  "items": [
    { "serviceCode": "DEMO-WASH-2", "quantity": 1, "unitCount": 2, "unit": "item" }
  ],
  "pickupWindow": {
    "startAt": "2030-08-15T09:00:00+08:00",
    "endAt": "2030-08-15T10:00:00+08:00"
  },
  "pickupAddress": {
    "contactName": "示例取件联系人",
    "contactPhone": "00000000000",
    "province": "示例省",
    "city": "示例市",
    "district": "示例区",
    "detail": "示例取件路 1 号"
  },
  "returnAddress": {
    "contactName": "示例收件联系人",
    "contactPhone": "00000000000",
    "province": "示例省",
    "city": "示例市",
    "district": "示例区",
    "detail": "示例返寄路 2 号"
  }
}

服务商先按 fulfillmentNo 原子保存承接决定,再响应 HTTP 200。成功接单时,providerOrderNo 是服务商对该履约任务生成的唯一承接单号,在同一合作账号内保持稳定。该编号为 1–80 位,以英文字母或数字开头,后续可使用英文字母、数字、点、下划线、冒号或短横线。

{ "status": "accepted", "providerOrderNo": "CARE-DEMO-001" }

确认无法承接时,同样响应 HTTP 200。字段 reason 为 1–200 字符的实际拒单原因,可填写地区、预约时段或承接范围等原因,请省略联系人、电话和详细地址。

{ "status": "rejected", "reason": "该预约时段已满" }

按同一 fulfillmentNo 重复收到内容一致的派单时,服务商返回原决定及原承接单号。若同一编号的派单内容发生冲突,应保护已保存的结果并联系鲸予核对,建议返回 HTTP 409。派单和查询的 HTTPS 请求超时为 8 秒。网络超时、非 200 响应或不符合协议的响应会进入查证流程,鲸予使用原 fulfillmentNo 查证接单结果。

查询承接结果

GET /v1/assignments/{fulfillmentNo} 的路径参数是派单中的原履约编号。查询已保存的接单或拒单决定时,返回 HTTP 200,响应 JSON 与派单的结果格式一致。仍在处理或尚未查到决定时,返回 HTTP 404,鲸予会按结果待核实处理。查证只读取已保存的决定。验证幂等性时,可并发提交同一任务并模拟首次响应丢失,再通过查询确认只有一笔承接单及一次预约。

回传履约进度

服务商完成实际操作后,调用 POST /v1/fulfillment/events。请在已通过派单响应或查询返回接单结果后开始上报。每个履约任务按下表顺序推进,逐条收到确认再发送下一条。

status 业务含义 可接续的状态 运单要求
pickup_booked 取件预约已受理 已接单 accepted 提供取件运单。
picked_up 快递已实际揽收 pickup_booked 可省略。
received 洗护点已收货 picked_up 可省略。
washing 已开始洗护 received 可省略。
return_shipped 已发出返寄包裹 washing 提供返寄运单,承运商代码与运单号的组合须有别于取件运单。
signed 返寄包裹已实际签收 return_shipped 承运商代码及运单号须与已登记的返寄运单一致。
canceled 揽收前取消已确认 accepted 或 pickup_booked 可省略。

签收和取消为终态。已实际揽收后发生拒洗、包裹异常或售后时,请与鲸予运营联系人核对实际情况和后续安排。需要留件或改址时,双方先确认处理方式。

字段 类型 含义
eventId 字符串 在同一合作账号下唯一的事件编号,跨订单也须唯一。重试沿用原编号。
sequence 正整数 在同一履约任务内严格递增,最大值 9007199254740991,建议从 1 开始逐条加一。
fulfillmentNo 字符串 原派单中的鲸予履约编号。
providerOrderNo 字符串 服务商已确认的原承接单号。
status 字符串 上表列出的一个回调状态。
occurredAt 字符串 事件实际发生时间,带时区且精确到秒,可附最多三位毫秒。按已应用事件时间向前推进,允许相同时间。签收时填写实际签收时间。
waybill 对象 按上表提供,包含双方约定的承运商代码 carrierCode 和运单号 waybillNo。

回调中的各编号、承运商代码和运单号使用 1–80 位字符串。首位为英文字母或数字,后续可使用英文字母、数字、点、下划线、冒号或短横线。省略非必需对象或字段。事件发生时间须早于或等于鲸予接收时间。

下面是第六个履约事件的示例。联调时填写实际发生的时间。

{
  "eventId": "DEMO-EVENT-006",
  "sequence": 6,
  "fulfillmentNo": "FT-DEMO-001",
  "providerOrderNo": "CARE-DEMO-001",
  "status": "signed",
  "occurredAt": "2030-08-18T16:28:00+08:00",
  "waybill": { "carrierCode": "DEMO-CARRIER", "waybillNo": "DEMO-RETURN-001" }
}

回调确认与重试

鲸予以 HTTP 200 确认已处理事件,正文返回 applied、duplicate、当前 status 和整数 version。版本用于反馈鲸予记录的当前履约进度。

{ "applied": true, "duplicate": false, "status": "signed", "version": 8 }
HTTP 200 正文字段 含义和处理
applied: true, duplicate: false 新事件已推进履约,服务商可发送下一条。
applied: false, duplicate: true 相同事件已收到,服务商可停止重试。
applied: false, duplicate: false 已确认收到较旧的序号,当前履约状态维持在较新进度。服务商可停止重试。

遇网络中断、超时或 HTTP 5xx 时,可退避重投同一事件。沿用 eventId、sequence、occurredAt 与原字段,更新请求签名的发出时间。若响应带 Retry-After,请至少等待指定时间。同一事件编号对应不同内容,或用另一事件编号复用本任务当前序号,均返回 HTTP 409。遇 HTTP 409 时先核对原始事件、接单编号和前置状态。确有遗漏的先补发前置事件,再提交待处理的事件。

HTTP 状态 回调处理
400、413、415 检查 JSON、请求体大小和媒体类型。
401、403 检查合作账号、签名、两端时钟和接口权限。
404 用原履约编号核对任务及联调环境。
409 检查编号内容、事件序号、状态顺序、前后时间和运单是否一致。若接单结果尚未被鲸予记录,先核实接单。常见错误码有 EVENT_CONFLICT、EVENT_SEQUENCE_CONFLICT、INVALID_STATUS_TRANSITION 和 WAYBILL_MISMATCH。
422 检查字段格式、必需运单及事件发生时间。

鲸予的回调错误正文包含 code、message 和 requestId,响应头 X-Request-Id 也提供该追踪编号。联调求助请提供原履约编号、事件编号、响应状态和追踪编号,并省略密钥、签名及客户联系方式。

联调验收

  1. 使用虚构地址跑通派单、查询、取件、到厂、洗护、返寄和签收,核对两段运单与实际签收时间。
  2. 核对同一任务的重复派单以及首次响应丢失后的查证,确认只有一笔承接单。
  3. 验证明确拒单、回调重投、前置状态遗漏、重复事件编号改内容及返寄运单不一致的处理。
  4. 验证揽收前取消和已揽收订单的人工协调路径。