运单信息综合查询与商家催单

验签、请求头、HMAC-SHA256 算法与通用开放对接一致，请先阅读基础约定。
本节接口除伙伴 AK/SK 外，还需携带主站登录用户身份（JWT、imAccount 或 workNo），详见端用户身份说明。

端用户身份

优先从请求中读取主站 JWT：X-Access-Token 请求头、Authorization: Bearer <token>，或 Query 参数 token。
其次若 token 缺失或无效，可使用请求体中的 imAccount（已注册的 IM 账号 ID）反查主账号维度用户。
最后若 token 和 imAccount 均无法识别，可使用请求体中的 workNo（会员号）查询对应主账号。
子账号 token 会在 ES 检索时归并到主账号数据范围。

运单信息综合查询

接口地址：/openapi/waybill/getWaybillInfo
请求方式：POST
说明：在登录用户可见范围内，按运单关键字或收货人信息检索运单；按开单时间 openDateTime 倒序最多返回 3 条。每条运单独立返回运单详情、轨迹（含签收）及催单历史（有记录时返回）。

与运单数据拉取的区别

getWaybillData 面向伙伴 AK 批量拉取、按数据过滤规则圈定范围；本接口面向已登录商家/物流端用户的白名单 ES 检索，且单条结果内嵌轨迹与催单历史。

检索条件

waybillKeyword、receiverMobile、receiverName、receiverAddress 至少传一项（可组合）：

字段	匹配说明
`waybillKeyword`	物流运单号或具语运单号（ES 两字段 OR）
`receiverMobile`	收货人手机号（11 位或虚拟号格式时按主机号前缀匹配，兼容 `138xxxx-分机`）
`receiverName`	收货人姓名
`receiverAddress`	收货地址

请求参数

参数名	类型	是否必填	说明
`waybillKeyword`	String	条件	运单关键字
`receiverMobile`	String	条件	收货人手机号
`receiverName`	String	条件	收货人姓名
`receiverAddress`	String	条件	收货地址
`imAccount`	String	否	IM 账号 ID；token 缺失时用于解析用户，有 token 时可省略
`workNo`	String	否	会员号；token 和 `imAccount` 均无法识别时用于定位用户

WARNING

请勿在 JSON 中传递 userId，由网关从 token / imAccount / workNo 自动注入。

请求示例

按运单号查询（携带 token）：

json

{
  "waybillKeyword": "WB202605120001"
}

按收货人手机号查询（token 不可用时传 imAccount 或 workNo）：

json

{
  "receiverMobile": "13800138000",
  "workNo": "101121"
}

组合条件：

json

{
  "waybillKeyword": "JY225051200001",
  "receiverName": "张三"
}

响应结构

成功时 result 为对象：

字段	类型	说明
`items`	Array	运单组合列表；未命中时为 `[]`
`items[].waybill`	Object	ES 运单文档，字段与主站查货库一致
`items[].track`	Object	轨迹与签收壳
`items[].track.signEntity`	Object	签收信息，`signName` / `signDate` / `signImg` 等
`items[].track.trackEntity`	Array	轨迹节点列表
`items[].businessReminderHistory`	Array	催单历史，按 `createTime` 倒序；无记录时不返回

轨迹节点 trackEntity[] 字段：

字段	类型	说明
`trackValue`	String	轨迹描述
`waybillNo`	String	物流运单号
`companyId`	String	物流公司 ID
`source`	String	数据来源
`trackDate`	String	轨迹时间

催单历史 businessReminderHistory[] 字段：

字段	类型	说明
`id`	Integer	记录 ID
`waybillNo`	String	物流运单号
`jyWaybillNo`	String	具语运单号
`type`	Integer	催单类型
`content`	String	催单内容
`pics`	String	催单图片
`status`	Integer	处理状态
`replyContent`	String	回复内容
`replyTime`	String	回复时间
`replyPics`	String	回复图片
`createTime`	String	创建时间
`createBy`	String	创建人

响应示例

命中 1 条：

json

{
  "code": 200,
  "message": "success",
  "result": {
    "items": [
      {
        "waybill": {
          "id": "5f4dcc3b5aa765d61d8327deb882cf99",
          "openDateTime": "2026-05-12 10:00:00",
          "status": "运输中",
          "source": "具语TMS",
          "jyWaybillNo": "JY225051200001",
          "waybillNo": "WB202605120001",
          "sendCompany": "某某物流",
          "companyId": "COMPANY-001",
          "receiverName": "张三",
          "receiverMobile": "13800138000",
          "receiverAddress": "上海市浦东新区XX路"
        },
        "track": {
          "signEntity": null,
          "trackEntity": [
            {
              "trackValue": "货物已从【深圳】发往【上海】",
              "waybillNo": "WB202605120001",
              "companyId": "16597",
              "source": "具语TMS",
              "trackDate": "2026-05-12 14:00:00"
            }
          ]
        },
        "businessReminderHistory": [
          {
            "id": 1001,
            "waybillNo": "WB202605120001",
            "jyWaybillNo": "JY225051200001",
            "type": 1,
            "content": "请尽快派送",
            "status": 0,
            "createTime": "2026-05-13 09:00:00",
            "createBy": "101121-张三"
          }
        ]
      }
    ]
  }
}

未命中：

json

{
  "code": 200,
  "message": "success",
  "result": {
    "items": []
  }
}

错误码

`code`	场景
200	成功（`items` 可能为空数组）
200	业务提示：`result` 为字符串如 `用户不存在`（`success=true`）
400	请求体缺失；或四项检索条件均为空
401	token、`imAccount` 与 `workNo` 均未解析到用户
500	ES 检索失败等业务异常

商家催单

接口地址：/openapi/waybill/businessReminder
请求方式：POST
说明：商家主账号或其子账号对指定运单发起催单。运单须在当前登录用户 ES 白名单范围内且唯一命中。

角色限制

仅商家（UserType_Delivery）主账号或子账号可调用；物流等其他角色返回业务错误。

请求参数

参数名	类型	是否必填	说明
`waybillId`	String	是	ES 运单文档主键 `id`
`type`	Integer	否	催单类型
`content`	String	否	催单内容
`pics`	String	否	催单图片 URL 等

请求示例

json

{
  "waybillId": "5f4dcc3b5aa765d61d8327deb882cf99",
  "type": 1,
  "content": "请尽快安排派送"
}

响应示例

成功：

json

{
  "code": 200,
  "message": "success",
  "result": "催单成功"
}

业务失败（示例）：

json

{
  "code": 500,
  "message": "该运单已催促",
  "result": null
}

错误码

`code`	场景
200	催单成功
400	请求体缺失或 `waybillId` 为空
401	未登录（token 缺失）
500	非商家角色、运单未唯一命中、重复催单等

运单信息综合查询与商家催单 ​

端用户身份 ​