D黑奴背锅 文档中心

小递闪送 API

小递闪送字典、运费、订单与账单接口说明，并提供可编辑参数的在线请求测试器。

本项目通过 /xiaodi/* 接口调用小递开放平台。服务端负责补充 api、appId、version 和 sign，调用方只需传入业务参数。

基本说明

名称地址
本地服务http://localhost:8105
接口前缀http://localhost:8105/xiaodi

/xiaodi/* 不要求登录 Token。小递凭证支持以下两种来源：

  1. 请求使用 HTTP Basic Auth：用户名填写小递 App ID，密码填写小递 App Secret。凭证仅用于本次请求。
  2. 未使用 Basic Auth：自动使用后端 XIAODI_APP_ID 和 XIAODI_APP_SECRET 配置。

Basic Auth 必须同时填写 App ID 和 App Secret。生产环境必须使用 HTTPS，并建议在网关层增加访问控制。

  • GET 接口不需要 Body。
  • POST 接口的 Body 直接传参数对象。
  • 不要传 api、appId、version 或 sign，这些字段由服务端生成。

Apifox 设置：打开接口的“认证”，选择 Basic Auth，在 Username 填 App ID，在 Password 填 App Secret。

文档网站调用示例：

const authorization = `Basic ${btoa(`${appId}:${appSecret}`)}`;

await fetch("http://localhost:8105/xiaodi/get_address", {
  headers: { Authorization: authorization }
});

页面中的 App Secret 输入框使用 type="password"。凭证不会写入 localStorage、Cookie 或日志。

统一返回：

{
  "code": 0,
  "message": "操作成功",
  "data": {}
}

code=0 表示成功，code=1 表示失败。

接口测试

小递 API 请求测试器

请求由当前浏览器直接发送到目标服务。地址、参数和凭证不会被保存。

查看接口说明

请求配置

GET

本地服务默认为 http://localhost:8105

获取大厦和楼层字典。

两项留空时使用后端配置；填写后仅通过本次请求的 Basic Auth 发送。

GET 接口无需请求体，确认服务地址后即可发送。

响应

尚未发送请求

选择接口并填写参数后，响应状态和内容会显示在这里。

接口说明

方法路径用途
GET/xiaodi/get_address获取大厦和楼层字典
GET/xiaodi/get_express_type获取快递类型
GET/xiaodi/get_express_tags获取快递标签
GET/xiaodi/get_balance查询余额和授信
GET/xiaodi/get_coupon查询闪送券
POST/xiaodi/billing_fee下单试算运费
POST/xiaodi/create_order创建正式订单
POST/xiaodi/create_agent_order创建代理订单
POST/xiaodi/cancel_order取消订单
POST/xiaodi/query_order_logs查询订单操作轨迹
POST/xiaodi/query_account_details查询账单明细
POST/xiaodi/create_pre_order创建非标准地址预单
POST/xiaodi/query_pre_order_status查询预单状态

公共枚举

orderTypeId 订单方向

值说明
1拿货
2送货

sendTypeId 送货方式

值说明
21送货上门
22门市自提

fetchTypeId 拿货方式

值说明
11上门拿货
12送货门市，仅送货订单使用
13代收货物，仅拿货订单使用

paymentId 正式订单支付方式

值说明
1银联支付，订单创建后可能仍为未支付
11授信支付，需要账户已开通授信
12余额支付，需要运费余额充足

goodsCollection 是向客户代收的货款，goodsPayment 是代付货款，二者都不等于运费支付。运费支付方式由 paymentId 决定。

expressTypeId 和 expressTagIds 必须使用快递字典接口返回的值。多个标签按小递规则计算后传入 expressTagIds。

字典和账户接口

获取地址

GET /xiaodi/get_address

返回大厦和楼层 ID：

[
  {
    "mansionId": "大厦ID",
    "mansionName": "大厦名称",
    "floors": [
      {
        "floorId": "楼层ID",
        "floorName": "楼层名称"
      }
    ]
  }
]

获取快递类型

GET /xiaodi/get_express_type
[
  {
    "expressTypeId": "类型ID",
    "expressTypeName": "类型名称"
  }
]

获取快递标签

GET /xiaodi/get_express_tags
[
  {
    "expressTagId": "标签ID",
    "expressTagName": "标签名称"
  }
]

查询余额

GET /xiaodi/get_balance
字段说明
isCredit0 未开通授信，1 已开通
creditDays授信天数
creditAmount授信额度
creditBalance剩余授信额度
onlineBalance运费余额
proxyBalance货款余额

查询闪送券

GET /xiaodi/get_coupon

返回字段包括 couponId、validityBtime、validityEtime 和 couponAmount。

运费试算

POST /xiaodi/billing_fee

请求参数与正式下单基本一致。建议先试算，再正式下单。

{
  "orderTypeId": 2,
  "sendTypeId": 21,
  "fetchTypeId": 11,
  "paymentId": 12,
  "expressTypeId": 1,
  "expressTagIds": 0,
  "customerMansionId": 100,
  "customerFloorId": 200,
  "customerHouseNumber": "A01",
  "myMansionId": 101,
  "myFloorId": 201,
  "myHouseNumber": "B02",
  "goodsWeight": 1.5,
  "goodsCollection": 0,
  "goodsPayment": 0
}
字段说明
serviceCharge总运费
payAmount实际应付金额
fetchServiceCharge拿货费用
sendServiceCharge送货费用
overweightServiceCharge超重费用
surcharge增值服务明细
couponAmount优惠金额

正式下单

POST /xiaodi/create_order

参数

参数必填说明
orderTypeId是1 拿货，2 送货
sendTypeId是21 上门送货，22 门市自提
fetchTypeId是11 上门拿货，12 送货门市，13 代收货物
paymentId是1 银联，11 授信，12 余额
sellerOrderNo否ERP 唯一订单号，用于防重复下单
sellerQrcode否商家二维码或条码内容
createMemo否下单备注
expressTypeId是快递类型 ID
expressTagIds否快递标签 ID 计算值
customerCname是客户公司
customerContacts是客户联系人
customerMobileNumber是客户电话
customerMansionId是客户大厦 ID
customerFloorId是客户楼层 ID
customerHouseNumber是客户门牌号
myContacts是发货联系人
myMobileNumber是发货联系电话
myMansionId是发货方大厦 ID
myFloorId是发货方楼层 ID
myHouseNumber是发货方门牌号
goodsWeight是商品重量，KG
goodsCollection是代收金额，无代收传 0
goodsPayment是代付金额，无代付传 0
returnPrintImg否传 1 返回打印标签地址
goods否商品明细，传入时 goodsName 必填

请求示例

{
  "orderTypeId": 2,
  "sendTypeId": 21,
  "fetchTypeId": 11,
  "paymentId": 12,
  "sellerOrderNo": "ERP-20260721-001",
  "expressTypeId": 1,
  "expressTagIds": 0,
  "customerCname": "客户公司",
  "customerContacts": "张三",
  "customerMobileNumber": "13800000001",
  "customerMansionId": 100,
  "customerFloorId": 200,
  "customerHouseNumber": "A01",
  "myContacts": "李四",
  "myMobileNumber": "13900000001",
  "myMansionId": 101,
  "myFloorId": 201,
  "myHouseNumber": "B02",
  "goodsWeight": 1.5,
  "goodsCollection": 0,
  "goodsPayment": 0,
  "returnPrintImg": 1,
  "goods": [
    {
      "goodsName": "测试商品",
      "goodsNum": 1,
      "goodsAmount": 100,
      "goodsDesc": "测试订单"
    }
  ]
}

成功返回：

{
  "orderId": "小递订单ID",
  "companyId": "公司ID",
  "printImgUrl": "打印标签地址"
}

代理下单

POST /xiaodi/create_agent_order

参数与正式下单类似，但支付方式不同：

paymentId=1：支付宝
paymentId=2：微信

成功返回中包含 payInfo 支付二维码地址。

取消订单

POST /xiaodi/cancel_order
{
  "orderId": "小递订单ID",
  "pushCompanyId": "公司ID",
  "cancelMemo": "客户取消订单"
}

orderId 必填。

查询订单轨迹

POST /xiaodi/query_order_logs
{
  "orderId": "小递订单ID",
  "pushCompanyId": "公司ID",
  "sellerOrderNo": "ERP-20260721-001"
}

orderId 和 sellerOrderNo 至少传一个。返回字段包括 opId、opTypeName、opTime、opText、opImg、opName 和 opMobilePhone。

查询账单

POST /xiaodi/query_account_details
{
  "startDate": "2026-07-01",
  "endDate": "2026-07-31",
  "pushCompanyId": "公司ID",
  "orderId": "小递订单ID",
  "sellerOrderNo": "ERP-20260721-001"
}

返回 total、records 和 rows。账单行包括 orderId、feeTypeName、titleTypeName、costAmount 和 incomeAmount。

预单

创建预单

POST /xiaodi/create_pre_order
{
  "pushCompanyId": "公司ID",
  "orderTypeId": 2,
  "sellerOrderNo": "PRE-20260721-001",
  "expressTypeId": 1,
  "expressTagIds": 0,
  "customerCname": "客户公司",
  "customerContacts": "张三",
  "customerMobileNumber": "13800000001",
  "customerAddress": "深圳市福田区测试大厦8楼801",
  "myContacts": "李四",
  "myMobileNumber": "13900000001",
  "myAddress": "深圳市福田区供应商大厦3楼302",
  "goodsWeight": 2.5,
  "goodsPayment": 0,
  "offerAmount": 0,
  "returnPrintImg": 1
}

成功返回 preorderId。

查询预单状态

POST /xiaodi/query_pre_order_status
{
  "pushCompanyId": "公司ID",
  "preorderId": "预单ID"
}

状态：0 已取消，1 待确认，2 已下单。statusId=2 时使用返回的 orderId 继续查询正式订单轨迹。

推荐调用流程

get_address
→ get_express_type
→ get_express_tags
→ billing_fee
→ create_order
→ query_order_logs

地址无法转换为标准大厦、楼层 ID 时使用：

create_pre_order
→ query_pre_order_status

领取赛季奖励 POST

领取上赛季结算奖励。 ## 注意事项 - 无待领取奖励返回 code=1。

接口额度

了解 OpenAPI 的分钟、每日与每月额度，以及查询剩余额度的方法。

On this page

基本说明接口说明公共枚举orderTypeId 订单方向sendTypeId 送货方式fetchTypeId 拿货方式paymentId 正式订单支付方式字典和账户接口获取地址获取快递类型获取快递标签查询余额查询闪送券运费试算正式下单参数请求示例代理下单取消订单查询订单轨迹查询账单预单创建预单查询预单状态推荐调用流程