闪送功能 App 接口接入文档

本文档供用户端 App 和骑手端 App 接入闪送功能使用，以当前后端实现为准。文档只描述接口契约和业务流程，不包含 App 前端实现代码。

1. 功能范围

当前闪送支持：

帮送、帮取、加急送三种服务。
共享地址簿、路线报价、立即配送和预约配送。
用户发布订单、查询订单、取消订单和确认收货。
骑手查看待抢订单、抢单、确认取件和确认送达。
可选的四位交付 PIN。
寄件、取件和送达图片凭证。
送达 24 小时后仍未由用户确认的订单自动完成。

当前不包含支付、退款、骑手收入、结算、代购垫付、自动派单和骑手放弃订单。

设计原型中的支付方式选择、已付款状态、附近骑手上线数量、预计接单时间和骑手收益金额均为静态示意，接口不提供这些数据，App 不应展示或请求它们。

2. 通用约定

2.1 基础地址和请求头

接口路径均为相对路径，实际请求地址为：

{baseUrl}{接口路径}

除特别说明外，用户端和骑手端接口都必须携带以下请求头：

请求头	必填	说明
`token`	是	App 登录后取得的 JWT。不要放在 `Authorization` 中
`Content-Type`	POST JSON 接口必填	`application/json`

用户身份和骑手身份均由 token 解析，请求体中不提交 userId 或 riderId。

2.2 统一响应

成功响应：

{
  "code": 200,
  "msg": "操作成功",
  "data": {}
}

无返回数据的成功响应通常不含 data：

{
  "code": 200,
  "msg": "操作成功"
}

业务失败响应：

{
  "code": 500,
  "msg": "当前订单状态不允许此操作"
}

登录失效响应：

{
  "code": 401,
  "msg": "token已过期，请重新登录！"
}

App 必须以响应体 code 判断业务是否成功，不能只依赖 HTTP 状态码。msg 已由后端国际化，可直接用于错误提示。

2.3 分页响应

列表接口的分页数据位于 data 中，不使用若依传统的顶层 rows/total：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "records": [],
    "total": 0,
    "current": 1,
    "size": 10,
    "pages": 0
  }
}

page 默认 1，小于 1 时按 1 处理。
size 默认 10，范围为 1 至 100。
App 至少读取 records、total、current 和 size。

2.4 时间、金额和距离

请求中的预约时间使用 ISO 日期时间字符串，例如 2026-09-02T10:00:00+08:00。
返回时间以服务端实际 JSON 时间格式为准，App 应按日期时间解析，不应依赖固定展示格式。
金额单位为新台币，currency 固定为 TWD；startingFare、freight、distanceFee 和 amount 都是整数，不带小数。
distanceMeters 单位为米。
运价配置中的 startingDistance、distance 以及报价中的 billableDistance 单位为公里，可保留两位小数。
estimatedDurationSeconds 单位为秒，路线服务降级时可能为 null。
distanceSource 为 ROUTE 时表示地图驾车路线，为 STRAIGHT_LINE 时表示地图服务不可用后使用直线距离降级。

3. 枚举和状态

3.1 服务类型 `serviceType`

值	含义
`HELP_SEND`	帮送
`HELP_PICKUP`	帮取
`URGENT`	加急送

是否可下单以首页接口当前实际返回的服务为准。运价没有启停状态；只有当前时间命中已配置运价时段的服务才会返回，不要在 App 中假定三种服务始终全部可用。

3.2 包裹类型 `packageType`

值	含义
`DOCUMENT`	文件
`GIFT`	礼品
`CLOTHING`	服饰
`BEAUTY`	美妆
`DAILY_NECESSITIES`	日用品
`FOOD_INGREDIENTS`	食材
`ELECTRONICS`	数码产品
`SMALL_APPLIANCE`	小家电
`OTHER`	其他

3.3 包裹重量档 `packageSize`

值	含义
`SMALL`	不超过 5kg
`MEDIUM`	不超过 12kg
`LARGE`	不超过 20kg

接口只提交重量档，不提交精确重量。

3.4 配送方式 `deliveryMode`

值	含义
`NOW`	立即配送，也是未传值时的默认值
`SCHEDULED`	预约配送

预约配送要求：

scheduledPickupStartAt 和 scheduledPickupEndAt 都必填。
开始时间不得早于当前时间，且不得晚于创建订单时刻后三天。
结束时间必须比开始时间晚 30 分钟。
预约订单创建后仍为 WAITING_ACCEPTANCE，但在预约开始时间到达前不会出现在骑手待抢列表中。

立即配送时不得传 scheduledPickupStartAt 和 scheduledPickupEndAt。

3.5 订单状态 `status`

WAITING_ACCEPTANCE -> ACCEPTED -> PICKED_UP -> DELIVERED -> COMPLETED
          |               |
          +---- 用户可取消 +---- 用户可取消

值	含义	下一步
`WAITING_ACCEPTANCE`	待骑手接单	骑手抢单，或用户取消
`ACCEPTED`	骑手已接单	骑手确认取件，或用户取消
`PICKED_UP`	骑手已取件	骑手确认送达
`DELIVERED`	骑手已送达	用户确认收货；超过 24 小时可由系统自动完成
`COMPLETED`	已完成	终态
`CANCELLED`	已取消	终态

4. 推荐调用流程

4.1 用户端

调用首页接口取得当前可用服务及价格摘要。
从共享地址簿选择地址，或填写取件和收件信息。
调用报价接口，展示服务端返回的路线和费用。
用户确认后调用创建订单接口。创建时服务端会重新计算路线和金额，最终以创建响应为准。
通过订单列表或详情刷新状态。当前闪送模块没有 App 实时推送接口。
在 WAITING_ACCEPTANCE 或 ACCEPTED 状态可取消；在 DELIVERED 状态可确认收货。

4.2 骑手端

调用待抢列表查看当前可接订单。
可先调用详情接口查看同一份脱敏摘要。
调用抢单接口。只有抢单成功后才能取得完整联系人和精确地址。
到达取件点后先上传图片，再调用确认取件接口。
到达收件点后先上传图片；如订单启用 PIN，向收件人取得四位 PIN，再调用确认送达接口。

抢单为并发原子操作。即使列表中仍显示订单，也可能已被其他骑手抢走；收到失败响应后应刷新待抢列表。

5. 图片上传

闪送订单接口不接收文件，只接收上传完成后的 HTTP(S) 图片 URL。

App 可复用现有上传接口：

方法	路径	Content-Type	参数
POST	`/utils/Upload`	`multipart/form-data`	文件字段名 `file`

成功响应示例：

{
  "code": 200,
  "msg": "上传成功",
  "data": "/profile/upload/2026/09/01/example.jpg"
}

该接口返回的 data 可能是相对资源路径。提交给闪送接口前，必须补全为外部可访问的绝对 URL，例如：

https://api.example.com/profile/upload/2026/09/01/example.jpg

图片 URL 规则：

只接受 http:// 或 https:// URL，必须包含主机名。
单个 URL 最长 1000 个字符。
寄件图片 senderImageUrls 可不传，最多 9 张。
取件图片和送达图片各至少 1 张、最多 9 张。

6. 公共数据对象

6.1 下单地址对象

报价和创建订单中的 pickup、delivery 使用以下结构：

{
  "name": "王小明",
  "phone": "0912345678",
  "address": "台北市信义区市府路1号",
  "addressDetail": "3楼A室",
  "city": "台北市",
  "area": "信义区",
  "handoffMethod": "请电话联系",
  "longitude": 121.5645,
  "latitude": 25.033
}

字段	类型	必填	规则
`name`	string	是	最长 64 字符
`phone`	string	是	最长 32 字符
`address`	string	是	完整主地址，最长 255 字符
`addressDetail`	string	否	楼层、门牌等，最长 255 字符
`city`	string	否	最长 64 字符；用于骑手抢单前的区域展示
`area`	string	否	最长 64 字符；用于骑手抢单前的区域展示
`handoffMethod`	string	否	交接说明，最长 40 字符
`longitude`	number	是	`-180` 至 `180`
`latitude`	number	是	`-90` 至 `90`

取件和收件地址不能是相同地址文本，也不能使用完全相同的经纬度。

6.2 订单字段

App 完整详情使用以下订单字段，响应的 data 直接返回这些字段，不再套用 order、images、logs 包装。

字段	类型	说明
`id`	number	订单主键，后续接口路径使用此值
`orderNo`	string	闪送订单号
`serviceType`	string	服务类型
`status`	string	当前状态
`packageType`	string	包裹类型
`packageSize`	string	包裹重量档
`deliveryMode`	string	`NOW` 或 `SCHEDULED`
`scheduledPickupStartAt`	datetime/null	预约开始时间
`scheduledPickupEndAt`	datetime/null	预约结束时间
`pinRequired`	boolean	是否需要交付 PIN
`pickup`	object	取件地址快照，结构见 6.1
`delivery`	object	收件地址快照，结构见 6.1
`distanceMeters`	number	配送距离，单位米
`distanceSource`	string	`ROUTE` 或 `STRAIGHT_LINE`
`estimatedDurationSeconds`	number/null	预计时长，单位秒
`amount`	integer	订单金额，整数 TWD
`currency`	string	`TWD`
`userNote`	string/null	用户备注
`acceptedAt`	datetime/null	接单时间
`pickedUpAt`	datetime/null	取件时间
`deliveredAt`	datetime/null	送达时间
`completedAt`	datetime/null	完成时间
`cancelledAt`	datetime/null	取消时间
`cancelReason`	string/null	取消原因
`createTime`	datetime	创建时间
`updateTime`	datetime	更新时间

用户列表摘要固定字段为：id,orderNo,serviceType,status,packageType,deliveryMode,scheduledPickupStartAt,scheduledPickupEndAt,pickupAddress,pickupDetailAddress,deliveryAddress,deliveryDetailAddress,estimatedDurationSeconds,amount,currency,deliveredAt,createTime。用户列表不返回联系人、电话、精确坐标、照片、日志或计价审计字段。

骑手列表摘要固定字段为：id,orderNo,serviceType,status,packageType,packageSize,deliveryMode,scheduledPickupStartAt,scheduledPickupEndAt,pinRequired,pickupAddress,pickupDetailAddress,deliveryAddress,deliveryDetailAddress,pickupDistanceMeters,distanceMeters,estimatedDurationSeconds,amount,currency,createTime。newTask 分页响应额外返回 nearbyTaskCount 和 highestOrderAmount，不返回尖峰倍率或骑手收入字段。

6.3 App 完整详情对象

用户创建订单、用户订单详情、中单骑手详情及抢单成功响应的 data 结构为：

{
  "id": 101,
  "orderNo": "FD1234567890",
  "serviceType": "URGENT",
  "status": "ACCEPTED",
  "packageType": "DOCUMENT",
  "packageSize": "SMALL",
  "deliveryMode": "NOW",
  "scheduledPickupStartAt": null,
  "scheduledPickupEndAt": null,
  "pinRequired": true,
  "pickup": {},
  "delivery": {},
  "distanceMeters": 4200,
  "distanceSource": "ROUTE",
  "estimatedDurationSeconds": 900,
  "amount": 90,
  "currency": "TWD",
  "userNote": null,
  "acceptedAt": "2026-09-01T10:20:00+08:00",
  "pickedUpAt": null,
  "deliveredAt": null,
  "completedAt": null,
  "cancelledAt": null,
  "cancelReason": null,
  "createTime": "2026-09-01T10:00:00+08:00",
  "updateTime": "2026-09-01T10:20:00+08:00",
  "senderImageUrls": [
    "https://api.example.com/profile/upload/sender-1.jpg"
  ],
  "pickupImageUrls": [],
  "deliveryImageUrls": [],
  "rider": {
    "name": "陈骑手",
    "avatar": "https://api.example.com/avatar.jpg",
    "rating": 4.9,
    "imUserId": "10086",
    "longitude": 121.56,
    "latitude": 25.03
  },
  "deliveryPinCode": "4821"
}

senderImageUrls、pickupImageUrls 和 deliveryImageUrls 分别表示寄件、取件和送达图片数组。
App 详情不返回原始状态日志；页面使用 status、acceptedAt、pickedUpAt、deliveredAt、completedAt 和 cancelledAt 展示进度。
deliveryPinCode 只向订单所属用户返回，并且只在启用 PIN 时出现；骑手响应永不返回此字段。
rider 只向用户返回。订单未接单时为 null。骑手对象不包含真实电话号码，联系入口使用 imUserId 打开 IM 会话，原型中的通话按钮没有接口支撑。
骑手位置只在订单状态为 ACCEPTED 或 PICKED_UP 时向用户返回，其他状态下经纬度为 null。

平台订单详情是审计专用契约，仍可返回 {order,images,logs}；App 不应依赖或解析该结构。

7. 用户端接口

所有接口均要求用户登录 token。

7.1 获取闪送首页配置

GET /system/flashDelivery/home

响应 data：

{
  "services": [
    {
      "serviceType": "HELP_SEND",
      "pricingId": 1,
      "startTime": "00:00",
      "endTime": "08:00",
      "startingDistance": 3.00,
      "startingFare": 60,
      "distance": 1.00,
      "freight": 10,
      "pricingVersion": 1,
      "currency": "TWD"
    }
  ]
}

只返回当前时间命中运价时段的服务。startTime 包含、endTime 不包含，均为业务当地时间的 HH:mm；24:00 只会作为结束时间。services 为空表示当前时段没有可下单的闪送服务。

7.2 获取实时报价

POST /system/flashDelivery/quote

请求体：

{
  "serviceType": "HELP_SEND",
  "packageType": "DOCUMENT",
  "packageSize": "SMALL",
  "pickup": {
    "name": "王小明",
    "phone": "0912345678",
    "address": "台北市信义区市府路1号",
    "addressDetail": "3楼A室",
    "city": "台北市",
    "area": "信义区",
    "handoffMethod": "请电话联系",
    "longitude": 121.5645,
    "latitude": 25.033
  },
  "delivery": {
    "name": "李小华",
    "phone": "0987654321",
    "address": "台北市大安区信义路三段56号",
    "addressDetail": "1楼",
    "city": "台北市",
    "area": "大安区",
    "handoffMethod": "交给本人",
    "longitude": 121.538,
    "latitude": 25.0335
  }
}

响应 data：

{
  "serviceType": "HELP_SEND",
  "pricingId": 1,
  "startTime": "00:00",
  "endTime": "08:00",
  "distanceMeters": 4200,
  "distanceSource": "ROUTE",
  "estimatedDurationSeconds": 900,
  "startingDistance": 3.00,
  "startingFare": 60,
  "distance": 1.00,
  "freight": 10,
  "billableDistance": 1.20,
  "distanceFee": 12,
  "amount": 72,
  "currency": "TWD",
  "pricingVersion": 1
}

计价规则与现有外卖订单一致：先用路线公里数减去 startingDistance；超出不足 0.5 公里时 billableDistance 为 0，达到 0.5 但不足 1 公里时按 1 公里，达到 1 公里后按实际超出距离。里程费用按 billableDistance / distance * freight 计算并四舍五入为整数 TWD，最终 amount = startingFare + distanceFee。预计时长不参与计价，也没有最低价、每分钟价格或尖峰倍率。

报价仅用于展示。创建订单时后端会重新匹配当前运价时段并计算最新路线和金额，因此最终金额可能与先前报价不同。当前时间没有匹配时段时，接口返回“当前时段暂无可用运价”。

7.3 创建闪送订单

POST /system/flashDelivery/orders

请求体在报价请求字段基础上增加：

{
  "serviceType": "HELP_SEND",
  "packageType": "DOCUMENT",
  "packageSize": "SMALL",
  "pickup": {},
  "delivery": {},
  "clientRequestId": "FD-20260901-USER1001-0001",
  "deliveryMode": "SCHEDULED",
  "scheduledPickupStartAt": "2026-09-02T10:00:00+08:00",
  "scheduledPickupEndAt": "2026-09-02T10:30:00+08:00",
  "pinRequired": true,
  "senderImageUrls": [
    "https://api.example.com/profile/upload/sender-1.jpg"
  ],
  "userNote": "文件请勿折叠"
}

新增字段	类型	必填	说明
`clientRequestId`	string	是	客户端幂等请求号，去除首尾空格后最长 64 字符
`deliveryMode`	string	否	不传时默认为 `NOW`
`scheduledPickupStartAt`	datetime	预约时必填	预约开始时间
`scheduledPickupEndAt`	datetime	预约时必填	必须比开始时间晚 30 分钟
`pinRequired`	boolean	否	不传时默认为 `true`
`senderImageUrls`	string[]	否	寄件图片，最多 9 张
`userNote`	string	否	最长 500 字符

同一用户使用相同 clientRequestId 重试时，后端返回第一次创建的订单，不会重复创建。一次下单动作生成一个请求号；网络超时重试必须复用原请求号，新下单必须生成新请求号。使用旧请求号但修改请求体，仍会返回旧订单。

成功响应 data 为完整详情对象，初始状态为 WAITING_ACCEPTANCE。创建响应中的 amount 是最终整数订单金额。

7.4 查询用户订单列表

GET /system/flashDelivery/orders?page=1&size=10

查询参数：

参数	必填	说明
`page`	否	默认 `1`，小于 `1` 时按 `1` 处理
`size`	否	默认 `10`，范围为 `1` 至 `100`

仅查询当前用户，按创建时间倒序返回全部状态的订单摘要。接口不接受 status、scene 或 serviceType；响应 data.records 中每项为用户列表摘要对象。

设计原型中的“待接单、配送中、已完成、已取消”筛选页签当前没有对应查询参数。第一版建议只展示“全部”列表；如需页签，只能基于当前页数据本地过滤，且不应依赖它得到准确的分页总数。

7.5 查询用户订单详情

GET /system/flashDelivery/orders/{id}

仅订单所属用户可访问。响应 data 直接为 App 完整订单字段，包括订单快照、三类图片数组、骑手摘要和可选的交付 PIN，不返回原始状态日志。响应不包含支付状态或支付方式字段，详情页不要展示“已付款”等支付信息。

7.6 用户取消订单

POST /system/flashDelivery/orders/{id}/cancel

请求体：

{
  "reason": "行程有变，不需要配送"
}

reason 必填，去除首尾空格后不能为空，最长 500 字符。
仅 WAITING_ACCEPTANCE 和 ACCEPTED 状态允许用户取消。
PICKED_UP 之后需要平台介入，用户端不能直接取消。
设计原型中“骑士接单前可免费取消”的文案比接口口径更严格：接口允许骑手已接单但尚未取件时取消，且当前没有支付，取消不产生任何费用；接入支付后取消规则需重新对齐。

7.7 用户确认收货

POST /system/flashDelivery/orders/{id}/confirmReceipt

无请求体。仅 DELIVERED 状态可操作，成功后状态变为 COMPLETED。

8. 骑手端接口

所有接口均要求骑手登录 token，且账号 userType 必须为 2。

8.1 查询骑手订单列表

GET /system/flashDelivery/rider/orders?page=1&size=10&tab=newTask&longitude=121.5&latitude=25.0

查询参数：

参数	必填	说明
`page`	否	默认 `1`，小于 `1` 时按 `1` 处理
`size`	否	默认 `10`，范围为 `1` 至 `100`
`tab`	否	默认 `newTask`；可选 `newTask`、`toPickup`、`delivering`、`completed` 或 `cancelled`
`longitude`	否	骑手当前位置经度；`newTask` 传入时用于附近范围、取件点距离和排序，范围 `-180` 至 `180`
`latitude`	否	骑手当前位置纬度；`newTask` 传入时用于附近范围、取件点距离和排序，范围 `-90` 至 `90`

页签映射：

`tab`	对应状态	查询范围
`newTask`	`WAITING_ACCEPTANCE`	当前可抢任务
`toPickup`	`ACCEPTED`	当前骑手本人任务
`delivering`	`PICKED_UP`	当前骑手本人任务
`completed`	`DELIVERED`、`COMPLETED`	当前骑手本人任务
`cancelled`	`CANCELLED`	当前骑手本人任务

除 newTask 外只查询当前骑手本人任务。闪送没有退款流程，不提供外卖列表中的 refund 页签。

newTask 的 longitude 和 latitude 仅用于附近范围筛选、计算取件点距离和排序；其他页签忽略坐标。列表按页签和骑手范围完成服务端过滤后再分页，不由 App 拉取完整集合后过滤。

newTask 分页响应的 data 除 records、total、current、size 外，还返回 nearbyTaskCount 和 highestOrderAmount。不返回尖峰倍率或骑手收入字段。amount 是用户支付的订单金额，页面文案不得表述为“预估收益”或“收益”；nearbyTaskCount 是附近待抢订单数，不是上线骑手数。

所有页签的 data.records 使用骑手列表摘要字段：

{
  "id": 101,
  "orderNo": "FD1234567890",
  "serviceType": "URGENT",
  "status": "WAITING_ACCEPTANCE",
  "packageType": "DOCUMENT",
  "packageSize": "SMALL",
  "deliveryMode": "NOW",
  "scheduledPickupStartAt": null,
  "scheduledPickupEndAt": null,
  "pinRequired": true,
  "pickupAddress": "台北市信义区市府路1号",
  "pickupDetailAddress": "3楼A室",
  "deliveryAddress": "台北市大安区信义路三段56号",
  "deliveryDetailAddress": "1楼",
  "pickupDistanceMeters": 420,
  "distanceMeters": 4200,
  "estimatedDurationSeconds": 900,
  "amount": 90,
  "currency": "TWD",
  "createTime": "2026-09-01T09:00:00+08:00"
}

接单前列表可展示完整的取件、送达文字地址（包括详细地址），但不得返回联系人、电话、实际 PIN、精确坐标、用户备注、图片凭证、状态日志、用户 ID、幂等号或计价审计字段。列表中的文字地址不能作为精确坐标使用。

8.2 查询骑手订单详情

GET /system/flashDelivery/rider/orders/{id}

响应 data 始终直接返回订单字段，顶层结构保持稳定，不使用 {order,images,logs} 包装，也不要求 App 判断 data.order。接单前隐藏联系人、电话、实际 PIN、精确坐标和履约图片；联系人姓名与电话一样都不返回，列表和详情不要按设计原型渲染“·联系人姓名”。当前骑手接单后，详情接口才补齐其有权限查看的完整履约信息。

8.3 抢单

POST /system/flashDelivery/rider/orders/{id}/accept

无请求体。抢单成功后状态变为 ACCEPTED，响应 data 直接返回完整订单字段；订单已被其他骑手抢走时返回“订单已被其他骑手接走”。

8.4 确认取件

POST /system/flashDelivery/rider/orders/{id}/pickup

请求体：

{
  "imageUrls": [
    "https://api.example.com/profile/upload/pickup-1.jpg"
  ]
}

仅订单骑手可在 ACCEPTED 状态调用。图片至少 1 张、最多 9 张；成功后状态变为 PICKED_UP。

8.5 确认送达

POST /system/flashDelivery/rider/orders/{id}/deliver

启用 PIN 的订单：

{
  "imageUrls": [
    "https://api.example.com/profile/upload/delivery-1.jpg"
  ],
  "pinCode": "4821"
}

未启用 PIN 的订单可不传 pinCode：

{
  "imageUrls": [
    "https://api.example.com/profile/upload/delivery-1.jpg"
  ]
}

仅订单骑手可在 PICKED_UP 状态调用。图片至少 1 张、最多 9 张。PIN 校验失败时不会保存送达图片，也不会改变订单状态；成功后状态变为 DELIVERED。

9. 共享地址簿接口

地址簿由闪送和现有收货业务共用。以下接口都要求用户登录 token，并且只能操作当前用户自己的地址。

9.1 查询地址列表

GET /system/address/getaddress?keyword=王小明

keyword 可选，同时搜索姓名、电话、主地址和详细地址。置顶地址优先，响应 data 为地址数组。

9.2 查询地址详情

GET /system/address/getaddressxq?id={addressId}

响应 data 为地址对象。

9.3 新增或修改地址

POST /system/address/address

新增地址不传 id；修改地址传本人地址的 id：

{
  "id": null,
  "name": "王小明",
  "phone": "0912345678",
  "address": "台北市信义区市府路1号",
  "addressDetail": "3楼A室",
  "longitude": 121.5645,
  "latitude": 25.033,
  "country": "TW",
  "province": "台北市",
  "city": "台北市",
  "area": "信义区",
  "annexes": null
}

字段	必填	规则
`name`	是	最长 64 字符
`phone`	是	最长 32 字符
`address`	是	最长 255 字符
`addressDetail`	否	最长 255 字符
`longitude`	是	`-180` 至 `180`
`latitude`	是	`-90` 至 `90`
`country`、`province`、`city`、`area`	否	各最长 64 字符
`annexes`	否	最长 1000 字符

后端忽略客户端身份字段，地址所有者始终取自 token。保存成功后 data 返回保存后的地址对象。

地址簿对象不含 handoffMethod。把地址用于闪送报价或下单时，需要映射联系人、地址和坐标，并按本次订单另行填写交接方式。

9.4 删除地址

DELETE /system/address/{id}

无请求体，仅可删除本人地址。

9.5 置顶地址

POST /system/address/{id}/top

无请求体。置顶只影响当前用户地址簿的排序。

10. 常见业务错误与处理建议

`msg` 含义	常见原因	App 处理建议
token 已过期	登录态失效	清理登录态并重新登录
当前时段暂无可用运价	当前时间没有匹配所选服务的运价时段	刷新首页服务列表或稍后重试
取件地址和收件地址不能相同	地址文本相同或经纬度完全相同	要求用户修改地址
配送距离不能超过 40 公里	服务端路线距离超限	提示当前路线不可下单
预约取件时段无效	时间已过、超过三天或不是 30 分钟	重新选择预约时段
订单已被其他骑手接走	并发抢单失败	刷新待抢列表
当前订单状态不允许此操作	页面状态已过期或重复操作	重新拉取订单详情
交付 PIN 不正确	骑手提交 PIN 错误	保留页面并重新输入 PIN
闪送订单不存在或无权访问	ID 不存在或不属于当前账号	返回列表并刷新数据
凭证图片地址无效	URL 不是完整 HTTP(S) 地址	检查上传结果并补全资源域名

11. 接入验收清单

首页只展示 /home 返回的当前时段可用服务，不在 App 中维护启停状态或默认价格。
报价和创建订单都提交完整取件、收件坐标，且不使用客户端自行计算的金额。
金额按整数 TWD 展示，不显示小数、时长费、最低价或尖峰费用。
创建订单具备稳定的 clientRequestId 重试策略。
预约时间满足未来三天内、固定 30 分钟的约束。
App 使用响应体 code 判断成功或失败。
分页列表从 data.records 和 data.total 取值。
图片先上传，再向闪送接口提交完整 HTTP(S) URL。
用户只在待接单或已接单状态显示取消入口，只在已送达状态显示确认收货入口。
骑手抢单前可展示完整文字地址但不使用坐标导航；抢单成功后再读取联系人、电话、精确坐标和履约图片。
骑手严格按 ACCEPTED -> PICKED_UP -> DELIVERED 顺序操作。
启用 PIN 时，骑手送达必须提交用户端详情显示的四位 PIN。
对抢单冲突、状态变化和重复点击，均以刷新后的服务端订单状态为准。
用户订单列表第一版只展示“全部”；如实现状态页签，仅基于当前页数据本地过滤。
骑手端金额文案统一为“订单金额”，不使用“收益”；联系骑手/用户通过 IM，不提供通话。

flash-delivery-app-api.md 28 KB Permalink History Raw

闪送功能 App 接口接入文档

1. 功能范围

2. 通用约定

2.1 基础地址和请求头

2.2 统一响应

2.3 分页响应

2.4 时间、金额和距离

3. 枚举和状态

3.1 服务类型 serviceType

3.2 包裹类型 packageType

3.3 包裹重量档 packageSize

3.4 配送方式 deliveryMode

3.5 订单状态 status

4. 推荐调用流程

4.1 用户端

4.2 骑手端

5. 图片上传

6. 公共数据对象

6.1 下单地址对象

6.2 订单字段

6.3 App 完整详情对象

7. 用户端接口

7.1 获取闪送首页配置

7.2 获取实时报价

7.3 创建闪送订单

7.4 查询用户订单列表

7.5 查询用户订单详情

7.6 用户取消订单

7.7 用户确认收货

8. 骑手端接口

8.1 查询骑手订单列表

8.2 查询骑手订单详情

8.3 抢单

8.4 确认取件

8.5 确认送达

9. 共享地址簿接口

9.1 查询地址列表

9.2 查询地址详情

9.3 新增或修改地址

9.4 删除地址

9.5 置顶地址

10. 常见业务错误与处理建议

11. 接入验收清单

flash-delivery-app-api.md 28 KB

Permalink History Raw

3.1 服务类型 `serviceType`

3.2 包裹类型 `packageType`

3.3 包裹重量档 `packageSize`

3.4 配送方式 `deliveryMode`

3.5 订单状态 `status`