订单接口

创建订单

接口地址：/openapi/order/createOrder
请求方式：POST
说明：创建新订单，成功后返回具语运单号。

物流公司标识（companyWorkNo / companyInfoId）

两者二选一即可，服务端都会解析为同一物流公司：

companyWorkNo：物流公司会员号。
companyInfoId：物流公司 ID，ERP 历史字段，ERP 对接方可直接沿用主站 deliverGoods 原值，无需先做 companyInfoId → companyWorkNo 转换。
两者同时传入时以 companyWorkNo 为准。

请求参数

参数名	类型	是否必填	说明
`pushType`	String	否	推送类型（历史兼容字段，创建接口可不传）
`sourceNo`	String	条件必填	第三方来源单号；与 `cusSelfOid` 二选一，优先取 `sourceNo` 作为业务单号
`cusSelfOid`	String	条件必填	客户自有单号；与 `sourceNo` 二选一
`companyWorkNo`	String	二选一	物流公司会员号；与 `companyInfoId` 二选一，同时传以本字段为准
`companyInfoId`	String	二选一	物流公司 ID（ERP 历史字段）；与 `companyWorkNo` 二选一，ERP 对接方可沿用原值
`sendPCompany`	String	否	发货公司名称
`sendPName`	String	建议	发货人姓名；未指定商家时用于匹配发货人绑定，自动补齐归属商家
`merchantWorkNo`	String	条件必填	商家会员号（兼容 `deliveryName`）；渠道优先级及姓名匹配兜底见下文
`sendPPhone`	String	建议	发货人手机
`sendPTel`	String	否	发货人电话
`sendSiteAddressText`	String	建议	发货地址省市区，逗号分隔（如：`广东省,广州市,天河区`）
`sendSiteAddressDetails`	String	建议	发货完整地址（含门牌）
`recePCompany`	String	否	收货公司名称
`recePName`	String	建议	收货人姓名
`recePPhone`	String	建议	收货人手机
`recePTel`	String	否	收货人电话
`receSiteAddressText`	String	是	收货地址省市区，逗号分隔；用于可配送区域校验
`receSiteAddressDetails`	String	建议	收货完整地址（含门牌）
`deliveryType`	String	否	货主交货方式：1、自送；2、需上门提货
`distributionType`	String	否	配送方式 1、客户自提 2、送货到楼下 3、送货到家 4、送货到家并安装
`izLift`	String	否	是否有电梯
`floor`	Integer	否	楼层数
`sendRemark`	String	否	发货备注
`transportType`	String	否	运输方式
`receipyType`	String	否	回单方式
`collectionGoodsMoney`	BigDecimal	否	代收货款
`insuredMoney`	BigDecimal	否	保价金额
`writeOffOid`	String	否	核销单号
`logisticsQuotation`	String	否	物流报价

货物列表 jyOnlieOrderGood（兼容别名字段 orderGoodList）：

参数名	类型	是否必填	说明
`goodsDesc`	String	否	货物名称
`goodsDetail`	String	否	商品详细名称
`cargoPack`	String	否	货物包装
`goodsModel`	String	否	商品型号
`piece`	Integer	否	套数
`suit`	Integer	否	件数
`installPrice`	Integer	否	安装件数
`weight`	Float	否	重量（kg）
`volume`	Float	否	体积（m³）
`goodsPhoto`	String	否	货物图片
`color`	String	否	颜色
`lenth`	Double	否	长度（字段名历史拼写，保持 `lenth`）
`width`	Double	否	宽度
`height`	Double	否	高度
`dimension`	String	否	尺寸文本

请求示例

json

{
  "companyWorkNo": "101121",
  "cusSelfOid": "ORDER-001",
  "sendPName": "发货人A",
  "sendPPhone": "13800000000",
  "sendSiteAddressText": "省,市,区",
  "sendSiteAddressDetails": "详细地址A",
  "recePName": "收货人B",
  "recePPhone": "13900000000",
  "receSiteAddressText": "省,市,区",
  "receSiteAddressDetails": "详细地址B",
  "jyOnlieOrderGood": [
    { "goodsDesc": "货物示例", "piece": 1 }
  ]
}

ERP 对接方也可直接传 companyInfoId（与主站 deliverGoods 一致）：

json

{
  "companyInfoId": "1834567890123456789",
  "merchantWorkNo": "101121",
  "cusSelfOid": "ORDER-001",
  "receSiteAddressText": "省,市,区"
}

响应示例

json

{
  "code": 200,
  "message": "success",
  "result": "JY225051200001"
}

字段	类型	说明
`code`	Integer	业务状态码，`200` 表示成功
`message`	String	返回消息
`result`	String	具语运单号

订单内容变更

修改订单接口已废弃，但暂未下线，历史对接可继续调用。新对接建议先取消订单，再按新内容创建订单。

取消后再以同一业务单号（sourceNo / cusSelfOid）重新下单时，会生成新的具语运单号，原单保持已取消，不参与创建幂等。

修改订单

已废弃（仍可用）

/openapi/order/updateOrder 已废弃，接口暂未下线，现有对接无需改造，可继续使用。

新对接或后续改造，建议走「取消后重新下单」：先取消订单，再创建订单。取消后再以同一 sourceNo / cusSelfOid 创建，会生成新的具语运单号，原单保持已取消状态。

接口地址：/openapi/order/updateOrder
请求方式：POST
说明：按具语运单号更新已有订单。请求体与「创建订单」共用同一套字段定义（OpenOrderDeliverDTO），但**必填规则、写入语义、可修改范围 **不同。
可修改状态：仅 待揽收（0）或 已取消（2）的订单可修改；原单为已取消时，修改成功后会恢复为待揽收。

与创建订单的核心差异

维度	创建订单	修改订单
定位字段	无	`jyWaybillNo` 必填
`companyWorkNo`	与 `companyInfoId` 二选一	可选；不传沿用原单公司，传入则切换并重新校验权限
`companyInfoId`	与 `companyWorkNo` 二选一	可选；与 `companyWorkNo` 语义一致，传入则切换公司；两者同时传以 `companyWorkNo` 为准
`sourceNo`	必填（当前网关校验）	可选；传入时作为附加匹配条件
`receSiteAddressText`	建议传（用于区域校验）	可选；不传沿用原单收货区域，传入则重新校验可配送
主表业务字段	按入参写入	未传 / 传 `null` 保留原值；传了具体值则更新
`jyOnlieOrderGood`	可选	整表替换：每次修改都会删旧货物再写入；不传、`null` 或 `[]` 会清空货物
`distributionType`	不传默认 `1`	不传时在服务端仍会按默认 `1` 处理，可能覆盖原值，建议显式传入
地址明细	按入参	`sendSiteAddressDetails` / `receSiteAddressDetails` 不传时会写成空串，可能清空原明细

对接建议

生产环境修改订单时，建议按「创建订单成功时的全量字段」组包提交，尤其注意 jyOnlieOrderGood 必须带完整货物列表，避免误清空。

不可修改字段

以下字段不会随修改接口变更（由系统保留或单独处理）：

字段 / 概念	说明
`jyWaybillNo`（`sn`）	仅用于定位，不会被改写
订单状态	非取消态保持不变；原单为已取消时修改后恢复为待揽收
创建信息	`createBy`、`createTime` 保留
商家归属	`deliveryId`（商家 ID）保留
码码高单号	`mmgOrderNo` 保留
订单来源	`orderSource` 由当前 AccessKey 决定，不接受请求体覆盖

请求参数

与创建订单字段名、类型完全一致；下表重点说明修改时的必填与写入规则。

参数名	类型	修改时必填	写入规则	说明
`jyWaybillNo`	String	是	—	具语运单号，定位待修改订单
`pushType`	String	否	保留原值	历史兼容字段，可不传
`sourceNo`	String	否	有值则更新	第三方来源单号；传入时须与原单 `cusSelfOid` 一致，否则报未找到订单
`cusSelfOid`	String	否	有值则更新	客户自有单号；与 `sourceNo` 同时存在时，业务单号优先取 `sourceNo`
`companyWorkNo`	String	否	有值则切换公司	不传沿用原单公司；传入时按新公司做权限与区域校验；与 `companyInfoId` 二选一，同时传以本字段为准
`companyInfoId`	String	否	有值则切换公司	物流公司配置 ID（ERP 历史字段）；语义与 `companyWorkNo` 一致，传入则切换公司
`sendPCompany`	String	否	有值则更新	发货公司名称
`sendPName`	String	否	有值则更新	发货人姓名
`sendPPhone`	String	否	有值则更新	发货人手机
`sendPTel`	String	否	有值则更新	发货人电话
`sendSiteAddressText`	String	否	有值则更新	发货地址省市区，逗号分隔
`sendSiteAddressDetails`	String	否	注意	不传会写成空串，可能清空原发货明细
`recePCompany`	String	否	有值则更新	收货公司名称
`recePName`	String	否	有值则更新	收货人姓名
`recePPhone`	String	否	有值则更新	收货人手机
`recePTel`	String	否	有值则更新	收货人电话
`receSiteAddressText`	String	否	有值则更新并校验	收货省市区；传入时触发可配送区域校验，不传沿用原单区域
`receSiteAddressDetails`	String	否	注意	不传会写成空串，可能清空原收货明细
`deliveryType`	String	否	有值则更新	货主交货方式：1、自送；2、需上门提货
`distributionType`	String	否	注意	不传时服务端默认 `1`，建议显式传入
`izLift`	String	否	有值则更新	是否有电梯
`floor`	Integer	否	有值则更新	楼层数
`sendRemark`	String	否	有值则更新	发货备注
`transportType`	String	否	有值则更新	运输方式：`整车` / `汽运` / `空运` / `铁运`（文本映射为字典值）
`receipyType`	String	否	有值则更新	回单方式
`collectionGoodsMoney`	BigDecimal	否	有值则更新	代收货款
`insuredMoney`	BigDecimal	否	有值则更新	保价金额
`writeOffOid`	String	否	有值则更新	核销单号
`logisticsQuotation`	String	否	忽略	当前版本仅接收，未落库

货物列表 jyOnlieOrderGood（兼容别名 orderGoodList）——整表替换，每次必传完整列表：

参数名	类型	修改时必填	写入规则	说明
`goodsDesc`	String	否	随列表整体替换	货物名称
`goodsDetail`	String	否	随列表整体替换	商品详细名称
`cargoPack`	String	否	随列表整体替换	货物包装
`goodsModel`	String	否	随列表整体替换	商品型号
`piece`	Integer	否	随列表整体替换	套数
`suit`	Integer	否	随列表整体替换	件数
`installPrice`	Integer	否	随列表整体替换	安装件数
`weight`	Float	否	随列表整体替换	重量（kg）
`volume`	Float	否	随列表整体替换	体积（m³）
`goodsPhoto`	String	否	随列表整体替换	货物图片
`color`	String	否	随列表整体替换	颜色
`lenth`	Double	否	随列表整体替换	长度（字段名历史拼写，保持 `lenth`）
`width`	Double	否	随列表整体替换	宽度
`height`	Double	否	随列表整体替换	高度
`dimension`	String	否	随列表整体替换	尺寸文本

常见错误

场景	`message` 示例
未传 `jyWaybillNo`	请求体缺少必填字段
运单不存在或不属于本渠道	`未找到可操作的订单`
运单非待揽收/已取消	`当前订单状态不允许此操作`
传入的 `companyWorkNo` 无效	公司相关错误（如无对接权限）
`companyWorkNo` 与 `companyInfoId` 均未传且 AK 兜底失败	请求体缺少必填字段
传入的收货区域不可配送	区域不支持类错误

请求示例

json

{
  "jyWaybillNo": "JY225051200001",
  "companyWorkNo": "101121",
  "cusSelfOid": "ORDER-001",
  "sendPName": "发货人A",
  "sendPPhone": "13800000000",
  "sendSiteAddressText": "广东省,深圳市,南山区",
  "sendSiteAddressDetails": "科技园路1号",
  "recePName": "收货人B-新",
  "recePPhone": "13900011111",
  "receSiteAddressText": "上海市,上海市,浦东新区",
  "receSiteAddressDetails": "世纪大道200号",
  "jyOnlieOrderGood": [
    { "goodsDesc": "电子配件", "piece": 1 }
  ]
}

响应示例

json

{
  "code": 200,
  "message": "success",
  "result": "JY225051200001"
}

字段	类型	说明
`code`	Integer	业务状态码，`200` 表示成功
`message`	String	返回消息
`result`	String	修改后的具语运单号（与请求中的 `jyWaybillNo` 一致）

取消订单

接口地址：/openapi/order/orderCancel
请求方式：POST
说明：按运单号取消订单。

请求参数

参数名	类型	是否必填	说明
`jyWaybillNo`	String	是	具语运单号

请求示例

json

{
  "jyWaybillNo": "JY225051200001"
}

响应示例

json

{
  "code": 200,
  "message": "success",
  "result": "取消成功"
}

字段	类型	说明
`code`	Integer	业务状态码，`200` 表示成功
`message`	String	返回消息
`result`	String	固定返回 `取消成功`

物流取消

接口地址：/openapi/order/logisticsCancel
请求方式：POST
说明：物流公司取消待揽收订单，将订单状态由「待揽收」（0）更新为「物流取消」（2）。仅当订单当前为待揽收时可操作。

与「取消订单」的区别

「取消订单」（/openapi/order/orderCancel）为商家侧取消；「物流取消」为物流侧在揽收前取消发货，状态流转不同。

请求参数

参数名	类型	是否必填	说明
`jyWaybillNo`	String	是	具语运单号

请求示例

json

{
  "jyWaybillNo": "JY225051200001"
}

响应示例

json

{
  "code": 200,
  "message": "success",
  "result": "取消发货成功"
}

字段	类型	说明
`code`	Integer	业务状态码，`200` 表示成功
`message`	String	返回消息
`result`	String	固定返回 `取消发货成功`

常见错误

场景	`message` 示例
订单不存在	`未找到可操作的订单`
订单非待揽收状态	`当前订单状态不允许此操作`
无对接权限	`该公司暂未开放对接权限`

绑定物流运单

接口地址：/openapi/order/bindWaybill
请求方式：POST
说明：物流公司回传运单号，绑定物流运单并同步轨迹；订单状态由「待揽收」（0）更新为「已揽收」（1）。绑定成功后会触发轨迹同步等后续处理。

请求参数

参数名	类型	是否必填	说明
`jyWaybillNo`	String	是	具语运单号
`waybillNo`	String	是	物流运单号
`companyId`	String	是	物流公司 ID
`openDateTime`	String	是	开单时间，格式 `yyyy-MM-dd HH:mm:ss`

请求示例

json

{
  "jyWaybillNo": "JY225051200001",
  "waybillNo": "SF1234567890",
  "companyId": "101121",
  "openDateTime": "2025-06-25 10:30:00"
}

响应示例

json

{
  "code": 200,
  "message": "success",
  "result": "发货成功"
}

字段	类型	说明
`code`	Integer	业务状态码，`200` 表示成功
`message`	String	返回消息
`result`	String	固定返回 `发货成功`

常见错误

场景	`message` 示例
必填字段缺失	`请求体缺少必填字段`
开单时间格式错误	`开单时间格式错误，要求 yyyy-MM-dd HH:mm:ss`
订单不存在	`未找到可操作的订单`
订单已绑定运单或非待揽收	`当前订单状态不允许此操作`
无对接权限	`该公司暂未开放对接权限`

可发货公司列表

接口地址：/openapi/order/getCompanyList
请求方式：POST
说明：根据目的地省市区查询可配送至该地区的物流公司列表；不传目的地时返回全部启用状态的物流公司。

请求参数

参数名	类型	是否必填	说明
`destinationAddress`	String	否	目的地省文本，逗号分隔（如 `福建省` 或 `广东省`）；不传或为空时返回全部公司

请求示例

json

{
  "destinationAddress": "福建省"
}

响应示例

json

{
  "code": 200,
  "message": "",
  "result": [
    {
      "shortName": "具语物流",
      "companyInfoId": "1834567890123456789",
      "companyNameZh": "具语物流有限公司",
      "isExamine": 1,
      "companyAddress": "福建省福州市鼓楼区XX路100号",
      "areaDesc": "覆盖全省",
      "busiLinkman": "张三",
      "busiHotline": "0591-88888888",
      "sort": 1,
      "companyLogo": "https://example.com/logo.png",
      "areaName": "福建省",
      "authentication": 1,
      "legalPerson": "李四",
      "companyWorkNo": "101121"
    }
  ]
}

响应字段

字段	类型	说明
`shortName`	String	公司简称
`companyInfoId`	String	物流公司ID
`companyNameZh`	String	公司中文名称
`isExamine`	Integer	是否已审核
`companyAddress`	String	公司地址
`areaDesc`	String	区域描述
`busiLinkman`	String	业务联系人
`busiHotline`	String	业务热线
`sort`	Integer	排序值
`companyLogo`	String	公司 Logo URL
`areaName`	String	覆盖区域名称（逗号拼接）
`authentication`	Integer	是否已认证：`1`=已认证，`0`=未认证
`legalPerson`	String	法人
`companyWorkNo`	String	物流公司会员号

API 订阅配置列表（ERP）

接口地址：/openapi/order/getApiKeyList
请求方式：POST
说明：查询可推送的 API 订阅配置（push_type = 1），对齐主站 /callback/erp/getApiKeyList。须在伙伴密钥 owner_tag 中配置 company_work_nos 限定物流公司范围，未配置时拒绝返回。

请求参数

无业务字段，请求体可传空对象 {}。

前置条件

伙伴密钥 owner_tag 示例：

json

{
  "work_no": "商家会员号",
  "company_work_nos": [
    "300061",
    "300074"
  ]
}

响应示例

json

{
  "code": 200,
  "message": "",
  "result": [
    {
      "bindBy": "300061",
      "companyInfoId": "xxx",
      "companyInfoName": "某某物流",
      "subType": "平台标识",
      "appKey": "鉴权账号"
    }
  ]
}

响应字段

字段	类型	说明
`bindBy`	String	物流会员号
`companyInfoId`	String	物流公司配置 ID
`companyInfoName`	String	物流公司名称
`subType`	String	订阅平台
`appKey`	String	鉴权账号

ERP 接口迁移说明

原主站 /callback/erp/* 对接方请改调开放网关，验签使用 HTTP Header（accessKey / timestamp / sign / nonce ），请求体为扁平 JSON，不再在 body 中传 appKey / secret / sign / timestamp。

原主站接口	开放网关接口	说明
`getCompanyList`	`/openapi/order/getCompanyList`	原 `data.mdzArr` → `destinationAddress`
`deliverGoods`	`/openapi/order/createOrder`	见下表字段映射
`getApiKeyList`	`/openapi/order/getApiKeyList`	须配置 `owner_tag.company_work_nos`

deliverGoods → createOrder 字段映射

ERP 旧字段	OpenAPI 字段	说明
`companyInfoId`	`companyInfoId` 或 `companyWorkNo`（二选一）	可直接沿用原 `companyInfoId`，无需转换；改传 `companyWorkNo`（物流公司会员号）亦可；两者同时传以 `companyWorkNo` 为准
`deliveryName`	`merchantWorkNo`（ERP 条件必填，别名 `deliveryName`）	商家会员号；ERP 优先按单传，未传时尝试发货人绑定；和谐等固定商家见下
`orderSource`	（不传）	由伙伴密钥 `order_source` 决定（客易=7、尚夏=8、聚水潭=15、和谐=18、快麦=19 等）
`cusSelfOid`	`cusSelfOid` 或 `sourceNo`	幂等键，二选一

商家会员号（`merchantWorkNo`）如何传

ERP 开单（order_source = 7 / 8 / 15 / 19）：优先使用每单传入的 merchantWorkNo，一个 AK 可对应多个商家，不读取伙伴密钥的 owner_tag.work_no。未传会员号时才按 sendPName 匹配发货人绑定；传入值和姓名匹配均未得到会员号时，返回缺少商家会员号错误。

直接沿用 ERP 原 companyInfoId（推荐，零改动迁移）：

json

{
  "merchantWorkNo": "101121",
  "companyInfoId": "1834567890123456789",
  "cusSelfOid": "..."
}

或改传 companyWorkNo（物流公司会员号，与 companyInfoId 二选一）：

json

{
  "merchantWorkNo": "101121",
  "companyWorkNo": "101121",
  "cusSelfOid": "..."
}

老 ERP 字段名仍可用：deliveryName 等价于 merchantWorkNo。

和谐开单（order_source = 18）：有请求传入的 merchantWorkNo 时优先使用；未传入时使用伙伴密钥的 owner_tag.work_no，两者均未提供时才尝试按 sendPName 匹配发货人绑定；仍未命中返回“伙伴密钥未配置商家会员号”。

其他来源（非 7 / 8 / 15 / 18 / 19）：商家会员号可选；未配置且未传入时尝试发货人绑定，未命中可继续创建订单，不关联商家。

发货人绑定匹配：仅在请求未传入 merchantWorkNo 且没有更高优先级的固定商家配置时，用 sendPName 匹配已配置的发货人姓名，支持精确、名称%（前缀）、%名称（后缀）和 %名称%（包含）规则。命中多个商家时取绑定更新时间/创建时间较晚的一条，时间相同按会员号字典序取较大值。匹配结果用于订单商家关联、供应链配置和幂等判断。绑定对应商家不存在时返回商家不存在错误。

订单接口 ​

创建订单 ​

请求参数 ​

请求示例 ​

响应示例 ​

修改订单 ​

与创建订单的核心差异 ​

不可修改字段 ​

请求参数 ​

常见错误 ​

请求示例 ​

响应示例 ​

取消订单 ​

请求参数 ​

请求示例 ​

响应示例 ​

物流取消 ​

请求参数 ​

请求示例 ​

响应示例 ​

常见错误 ​

绑定物流运单 ​

请求参数 ​

请求示例 ​

响应示例 ​

常见错误 ​

可发货公司列表 ​

请求参数 ​

请求示例 ​

响应示例 ​

响应字段 ​

API 订阅配置列表（ERP） ​

请求参数 ​

前置条件 ​

响应示例 ​

响应字段 ​

ERP 接口迁移说明 ​

deliverGoods → createOrder 字段映射 ​

商家会员号（merchantWorkNo）如何传 ​

订单接口

创建订单

请求参数

请求示例

响应示例

修改订单

与创建订单的核心差异

不可修改字段

请求参数

常见错误

请求示例

响应示例

取消订单

请求参数

请求示例

响应示例

物流取消

请求参数

请求示例

响应示例

常见错误

绑定物流运单

请求参数

请求示例

响应示例

常见错误

可发货公司列表

请求参数

请求示例

响应示例

响应字段

API 订阅配置列表（ERP）

请求参数

前置条件

响应示例

响应字段

ERP 接口迁移说明

deliverGoods → createOrder 字段映射

商家会员号（`merchantWorkNo`）如何传