下游服务商接入指南 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 也提供该追踪编号。联调求助请提供原履约编号、事件编号、响应状态和追踪编号,并省略密钥、签名及客户联系方式。
联调验收
- 使用虚构地址跑通派单、查询、取件、到厂、洗护、返寄和签收,核对两段运单与实际签收时间。
- 核对同一任务的重复派单以及首次响应丢失后的查证,确认只有一笔承接单。
- 验证明确拒单、回调重投、前置状态遗漏、重复事件编号改内容及返寄运单不一致的处理。
- 验证揽收前取消和已揽收订单的人工协调路径。