京东快递/快运2025物流开放平台与快递鸟对接指南

快递鸟
139 阅读5分钟

文档前言

随着京东物流业务体系的持续扩展和升级，现有参数标准中的字段配置已无法完全满足日益丰富的业务场景需求。为此，快递鸟平台对下单接口参数进行了重要更新，特别针对冷链等新兴业务场景进行了深度优化。

本文档详细介绍了京东快递/快运2025版物流开放平台与快递鸟的对接标准。自2025年初起，新对接项目建议直接采用本文档规范，原有2024版接口仍可继续使用但将不再更新维护。

重要提示：为方便开发者快速识别变更内容，本文档中所有新增或修改的参数均以​​#E0F9FB​​底色标注。

一、前期准备工作

1.1 京东平台参数获取

在开始对接前，需首先联系京东销售支持团队创建应用，并获取以下关键参数：

京东参数名称

说明

必须性

对应快递鸟参数

customerCode

客户编码

例：020K6***02

快递类必传

（京东标快、京东特快、生鲜标快、生鲜特快、函速达、特惠包裹、电商标快、京东特惠）

Param1

businessUnitCode

事业部编码

例：EBU4418*****0002

快运类必传

（特快零担、特惠重货、特快重货、快运零担、特惠专配）

Param2

AppKey

应用密钥

例：B4EF1D69ED**********5E60A4A00FA9

必传

Param3

AppSecret

应用密钥

例：fec4a78e48***************0f44d3d

必传

Param4

AccessToken

访问令牌

例：93e387e***********************8nlmz

必传

Param5

1.2 参数获取路径

京东开放平台操作步骤：

  1. 访问 ​京东开放平台​
  2. 进入"应用管理"，选择"对接方案"
  3. 新建两个对接方案：
  • 京东快递快运
  • 京东云打印
  1. 确保两个方案均保持上线状态

参数获取方法：

  • AppKey和AppSecret：在应用管理页面生成获取
  • AccessToken：参照京东官方文档的令牌获取流程

二、接口核心规范

2.1 基础接口信息

项目

规格

接口URL

​​https://api.kdniao.com/api/EOrderService​​

内容类型

​​x-www-form-urlencoded​​

批量请求

不支持，并发限制≤20次/秒

计费规则

按成功请求次数计算

温馨提示：如您首次使用快递鸟接口，建议先参考API参数示意图了解基本调用流程。

三、请求与响应示例

3.1 请求参数示例（京东快递）

json

{
  "OrderCode": "TAN951324222372",
  "ShipperCode": "JD",
  "LogisticsRouteCode": "OPEN",
  "CustomerMap": {
    "Param2": "020K2311100",
    "Param3": "0a3abb77fc3c4a439c95dc4c83529900",
    "Param4": "67ad2c16ae194a07a2f00598c837d20c",
    "Param5": "c312d533280a40648afca9fc5cafc0bf"
  },
  "PayType": 3,
  "ExpType": 17,
  "Remark": "小心破损",
  "Sender": {
    "Name": "哈哈",
    "Mobile": "1840****905",
    "ProvinceName": "广东省",
    "CityName": "深圳市",
    "ExpAreaName": "福田区",
    "Address": "北环大道6018号华强科创广场1栋17层"
  },
  "TemplateSize": "P1303",
  "Receiver": {
    "Name": "雅雅",
    "Mobile": "178****7360",
    "ProvinceName": "广东省",
    "CityName": "深圳市",
    "ExpAreaName": "南山区",
    "Address": "桃源街道平山村40栋菜鸟驿站"
  },
  "Commodity": [{
    "GoodsName": "日用品",
    "Goodsquantity": 20,
    "GoodsWeight": 1.0
  }],
  "IsReturnPrintTemplate": 1
}

3.2 成功响应示例

json

{
  "Order": {
    "MarkDestination": "D-武汉",
    "OriginName": "长春集货分拣中心",
    "LogisticCode": "JDVF02543099355",
    "ShipperCode": "JD",
    "PackageName": "2-K33",
    "OrderCode": "WBM2311480",
    "KDNOrderCode": "KDN2311231150028110",
    "DestinatioName": "长沙望城散货分拣中心",
    "SortingCode": "JDVF02543099355-1-1-"
  },
  "EBusinessID": "1000000",
  "UniquerRequestNumber": "69ecd9cd-baa8-4ecf-a66d-f4456cb60e5c",
  "ResultCode": 100,
  "Reason": "成功",
  "Success": true
}

3.3 失败响应示例

json

{
  "EBusinessID": "1237100",
  "ResultCode": "105",
  "Reason": "上门收件时间不能为空",
  "UniquerRequestNumber": "5e66486b-8fbc-4131-b875-9b13d2ad1354"
}

四、常见问题排查指南

4.1 基础配置问题

问题1：返回"下单失败|B2C订单接单的基本信息-配送信息的揽收方式为空"

  • 解决方案：检查 PickupMethod 字段是否正确赋值1或2

问题2：返回"客户配置信息校验失败，余额小于等于停用金额"

  • 解决方案：该提示表明商家编码账户余额不足，需联系京东销售进行充值

问题3：返回"不存在订阅关系"

  • 解决方案：确认已在京东物流开放平台正确创建"京东快递"及"京东云打印"应用，并确保应用处于上线状态

4.2 面单模板配置

京东物流提供多种标准面单模板样式，开发者可根据实际业务需求选择合适的模板尺寸和布局。

五、注意事项

  1. 参数映射准确性：确保京东参数与快递鸟参数的映射关系正确无误
  2. 并发控制：严格遵守20次/秒的并发限制，避免请求被拒绝
  3. 令牌管理：AccessToken具有时效性，需建立有效的刷新机制
  4. 环境验证：上线前务必在测试环境完成全流程验证

本指南将随着双方平台的升级而持续更新，建议开发者定期关注最新版本，以确保对接的顺畅和稳定。

avatar
文章
阅读
粉丝