快递鸟接口文档之预约取件

原创于 2025-12-19 15:54:20 发布 · 414 阅读

CC 4.0 BY-SA版权

文章标签：

在电商、ERP、打单工具或各类物流系统中，预约快递员上门揽件是常见的业务场景。快递鸟（KDNiao）提供了标准的 预约取件接口（RequestType: 1001），支持主流快递公司、快递柜及同城配送平台，帮助开发者快速实现“一键叫快递”功能。

本文将详细介绍如何对接快递鸟的 预约取件接口（OOrderService2），包括功能说明、接口信息、参数详解、请求示例及注意事项。

一、功能说明

核心作用：通知快递公司安排快递员在指定时间上门取件。
适用对象：
- 散客用户（未签约大客户账号）
- 已与快递网点签约并拥有大客户账号的企业用户（可结合电子面单接口使用）
业务流程：系统调用接口 → 快递公司接收订单 → 快递员按预约时间上门揽件 → 系统获取运单号

⚠️ 注意：该接口仅用于预约揽件，不生成电子面单。如需同时获取面单和单号，请使用电子面单接口（EOrderService，RequestType=1007）。

二、接口基本信息

项目	内容
接口指令（RequestType）	`1001`
接口地址	`https://api.kdniao.com/api/OOrderService2`
请求方式	`POST`
批量支持	❌ 不支持批量请求
并发限制	✅ 支持高并发（建议 ≤ 40 次/秒）
计费规则	按成功调用次数计费

📌 重要提示：
虽然文档中提到接口地址为 OOrderService2，但部分用户反馈该路径可能已调整或存在兼容性问题。若返回 404 或 “找不到资源”，请确认是否应使用 EOrderService 并设置 RequestType=1001，或联系快递鸟技术支持核实最新接口地址。

三、支持的快递与服务类型

1. 快递公司（部分）

顺丰速运（SF）
中通快递（ZTO）
圆通速递（YTO）
韵达速递（YD）
申通快递（STO）
EMS
宅急送
京东快递（JD）
德邦（DBL）
优速、品骏、承诺达、顺心捷达等

2. 快递柜

丰巢快递柜（ShipperCode = FCBOX）

3. 同城配送

闪送
达达（大马鹿）

✅ 具体支持列表请以快递鸟官方文档为准。

四、请求参数说明（应用级参数 RequestData）

以下为 JSON 格式的 RequestData 主要字段：

字段名	类型	必填	说明
`OrderCode`	String(30)	✅	自定义订单编号，不可重复
`ShipperCode`	String(20)	✅	快递公司编码（如 SF、ZTO）
`PayType`	Int(1)	✅	支付方式：1-现付，2-到付，3-月结
`ExpType`	Int(2)	❌	业务类型（如标准快递=1）
`StartDate` / `EndDate`	String(32)	✅	上门时间范围，格式：`2025-12-20 09:00:00`
`Sender`	Object	✅	发件人信息（姓名、手机、省市区、地址）
`Receiver`	Object	✅	收件人信息
`Weight`	Double	✅（部分快递）	包裹总重量（kg）
`Quantity`	Int(2)	✅	包裹数量（≥1）
`Commodity`	Array	❌	商品信息（名称、件数、重量等）
`Remark`	String(100)	❌	备注（如“易碎”、“需泡沫箱”）
`Callback`	String(50)	❌	自定义回传字段，原样返回

🔒 安全规范：
请求报文中禁止出现以下特殊字符：' " # & + < > % /

五、请求示例（JSON）

json编辑{
  "OrderCode": "ORDER_20251219_001",
  "ShipperCode": "SF",
  "PayType": 1,
  "ExpType": 1,
  "StartDate": "2025-12-20 09:00:00",
  "EndDate": "2025-12-20 18:00:00",
  "Sender": {
    "Name": "张三",
    "Mobile": "13800138000",
    "ProvinceName": "广东省",
    "CityName": "深圳市",
    "ExpAreaName": "南山区",
    "Address": "科技园南区腾讯大厦"
  },
  "Receiver": {
    "Name": "李四",
    "Mobile": "13900139000",
    "ProvinceName": "北京市",
    "CityName": "北京市",
    "ExpAreaName": "朝阳区",
    "Address": "三里屯太古里北区"
  },
  "Weight": 2.5,
  "Quantity": 1,
  "Commodity": [
    {
      "GoodsName": "蓝牙耳机",
      "Goodsquantity": 1,
      "GoodsWeight": 0.2
    }
  ],
  "Remark": "轻拿轻放",
  "Callback": "custom_12345"
}

六、返回参数说明

字段	类型	说明
`EBusinessID`	String	用户ID
`Success`	Bool	是否成功（true/false）
`ResultCode`	String	结果码（100=成功）
`Reason`	String	失败原因（如“缺少必填参数”）
`Order.OrderCode`	String	原始订单号
`Order.ShipperCode`	String	快递公司编码
`Order.LogisticCode`	String	生成的快递单号（关键！）
`UniquerRequestNumber`	String	唯一请求标识，用于排查问题

成功返回示例：

json编辑{
  "EBusinessID": "1237100",
  "Success": true,
  "Order": {
    "OrderCode": "ORDER_20251219_001",
    "ShipperCode": "SF",
    "LogisticCode": "SF123456789CN"
  },
  "ResultCode": "100",
  "Reason": "",
  "UniquerRequestNumber": "REQ20251219154900123"
}

七、常见问题与注意事项

接口返回 404？
确认是否使用了正确的接口地址。部分用户反馈 OOrderService2 可能已弃用，建议尝试使用 EOrderService 并设置 RequestType=1001，或联系快递鸟客服确认。
为何没有返回运单号？
预约取件成功后，快递公司通常会在快递员实际揽件时才分配单号。部分快递（如顺丰）支持预下单返回单号，其他快递可能仅返回预约成功状态。
时间格式错误？
StartDate 和 EndDate 必须为 yyyy-MM-dd HH:mm:ss 格式，且结束时间 > 开始时间。
重复 OrderCode？
使用相同 OrderCode 重复请求，系统会返回第一次的结果（幂等性设计）。
如何知道快递员是否已取件？
可配合快递鸟的 【在途监控】 服务，订阅物流轨迹推送，实时获取揽件、运输、签收等状态。