具语开放接口

主题

订单接口 ​

创建订单 ​

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

请求参数 ​

参数名类型是否必填说明
pushTypeString否推送类型（历史兼容字段，创建接口可不传）
sourceNoString条件必填第三方来源单号；与 cusSelfOid 二选一，优先取 sourceNo 作为业务单号
cusSelfOidString条件必填客户自有单号；与 sourceNo 二选一
companyWorkNoString是公司会员号
sendPCompanyString否发货公司名称
sendPNameString建议发货人姓名
sendPPhoneString建议发货人手机
sendPTelString否发货人电话
sendSiteAddressTextString建议发货地址省市区，逗号分隔（如：广东省,广州市,天河区）
sendSiteAddressDetailsString建议发货完整地址（含门牌）
recePCompanyString否收货公司名称
recePNameString建议收货人姓名
recePPhoneString建议收货人手机
recePTelString否收货人电话
receSiteAddressTextString是收货地址省市区，逗号分隔；用于可配送区域校验
receSiteAddressDetailsString建议收货完整地址（含门牌）
deliveryTypeString否交货方式文本（服务端会尝试映射字典值）
distributionTypeString否配送方式 1、客户自提 2、送货到楼下 3、送货到家 4、送货到家并安装
izLiftString否是否有电梯
floorInteger否楼层数
sendRemarkString否发货备注
transportTypeString否运输方式
receipyTypeString否回单方式
collectionGoodsMoneyBigDecimal否代收货款
insuredMoneyBigDecimal否保价金额
writeOffOidString否核销单号
logisticsQuotationString否物流报价

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

参数名类型是否必填说明
goodsDescString否货物名称
goodsDetailString否商品详细名称
cargoPackString否货物包装
goodsModelString否商品型号
pieceInteger否套数
suitInteger否件数
installPriceInteger否安装件数
weightFloat否重量（kg）
volumeFloat否体积（m³）
goodsPhotoString否货物图片
colorString否颜色
lenthDouble否长度（字段名历史拼写，保持 lenth）
widthDouble否宽度
heightDouble否高度
dimensionString否尺寸文本

请求示例 ​

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

响应示例 ​

json
{
  "code": 200,
  "message": "success",
  "result": "JY225051200001"
}
字段类型说明
codeInteger业务状态码，200 表示成功
messageString返回消息
resultString具语运单号

修改订单 ​

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

与创建订单的核心差异 ​

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

对接建议

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

不可修改字段 ​

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

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

请求参数 ​

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

参数名类型修改时必填写入规则说明
jyWaybillNoString是—具语运单号，定位待修改订单
pushTypeString否保留原值历史兼容字段，可不传
sourceNoString否有值则更新第三方来源单号；传入时须与原单 cusSelfOid 一致，否则报未找到订单
cusSelfOidString否有值则更新客户自有单号；与 sourceNo 同时存在时，业务单号优先取 sourceNo
companyWorkNoString否有值则切换公司不传沿用原单公司；传入时按新公司做权限与区域校验
sendPCompanyString否有值则更新发货公司名称
sendPNameString否有值则更新发货人姓名
sendPPhoneString否有值则更新发货人手机
sendPTelString否有值则更新发货人电话
sendSiteAddressTextString否有值则更新发货地址省市区，逗号分隔
sendSiteAddressDetailsString否注意不传会写成空串，可能清空原发货明细
recePCompanyString否有值则更新收货公司名称
recePNameString否有值则更新收货人姓名
recePPhoneString否有值则更新收货人手机
recePTelString否有值则更新收货人电话
receSiteAddressTextString否有值则更新并校验收货省市区；传入时触发可配送区域校验，不传沿用原单区域
receSiteAddressDetailsString否注意不传会写成空串，可能清空原收货明细
deliveryTypeString否有值则更新交货方式文本（服务端映射字典）
distributionTypeString否注意不传时服务端默认 1，建议显式传入
izLiftString否有值则更新是否有电梯
floorInteger否有值则更新楼层数
sendRemarkString否有值则更新发货备注
transportTypeString否有值则更新运输方式：整车 / 汽运 / 空运 / 铁运（文本映射为字典值）
receipyTypeString否有值则更新回单方式
collectionGoodsMoneyBigDecimal否有值则更新代收货款
insuredMoneyBigDecimal否有值则更新保价金额
writeOffOidString否有值则更新核销单号
logisticsQuotationString否忽略当前版本仅接收，未落库

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

参数名类型修改时必填写入规则说明
goodsDescString否随列表整体替换货物名称
goodsDetailString否随列表整体替换商品详细名称
cargoPackString否随列表整体替换货物包装
goodsModelString否随列表整体替换商品型号
pieceInteger否随列表整体替换套数
suitInteger否随列表整体替换件数
installPriceInteger否随列表整体替换安装件数
weightFloat否随列表整体替换重量（kg）
volumeFloat否随列表整体替换体积（m³）
goodsPhotoString否随列表整体替换货物图片
colorString否随列表整体替换颜色
lenthDouble否随列表整体替换长度（字段名历史拼写，保持 lenth）
widthDouble否随列表整体替换宽度
heightDouble否随列表整体替换高度
dimensionString否随列表整体替换尺寸文本

常见错误 ​

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

请求示例 ​

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"
}
字段类型说明
codeInteger业务状态码，200 表示成功
messageString返回消息
resultString修改后的具语运单号（与请求中的 jyWaybillNo 一致）

取消订单 ​

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

请求参数 ​

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

请求示例 ​

json
{
  "jyWaybillNo": "JY225051200001"
}

响应示例 ​

json
{
  "code": 200,
  "message": "success",
  "result": "取消成功"
}
字段类型说明
codeInteger业务状态码，200 表示成功
messageString返回消息
resultString固定返回 取消成功

物流取消 ​

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

与「取消订单」的区别

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

请求参数 ​

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

请求示例 ​

json
{
  "jyWaybillNo": "JY225051200001"
}

响应示例 ​

json
{
  "code": 200,
  "message": "success",
  "result": "取消发货成功"
}
字段类型说明
codeInteger业务状态码，200 表示成功
messageString返回消息
resultString固定返回 取消发货成功

常见错误 ​

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

绑定物流运单 ​

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

请求参数 ​

参数名类型是否必填说明
jyWaybillNoString是具语运单号
waybillNoString是物流运单号
companyIdString是物流公司 ID（sys_config 主键）
openDateTimeString是开单时间，格式 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": "发货成功"
}
字段类型说明
codeInteger业务状态码，200 表示成功
messageString返回消息
resultString固定返回 发货成功

常见错误 ​

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

可发货公司列表 ​

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

请求参数 ​

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

请求示例 ​

json
{
  "destinationAddress": "福建省"
}

响应示例 ​

json
{
  "code": 200,
  "message": "",
  "result": [
    {
      "shortName": "具语物流",
      "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"
    }
  ]
}

响应字段 ​

字段类型说明
shortNameString公司简称
companyNameZhString公司中文名称
isExamineInteger是否已审核
companyAddressString公司地址
areaDescString区域描述
busiLinkmanString业务联系人
busiHotlineString业务热线
sortInteger排序值
companyLogoString公司 Logo URL
areaNameString覆盖区域名称（逗号拼接）
authenticationInteger是否已认证：1=已认证，0=未认证
legalPersonString法人
companyWorkNoString物流公司会员号

具语物流开放平台