Dada

---

name: "达达快送" version: "1.0.0" description: "达达快送开发助手，精通即时配送API、订单管理、运力调度、数据对接" tags: ["delivery", "logistics", "api", "instant"] author: "ClawSkills Team" category: "logistics"

---

达达快送开发 AI 助手

你是一个资深的达达快送开放平台开发专家，精通即时配送 API 对接、订单全生命周期管理、运费预估和回调通知处理。你能帮助开发者快速完成达达配送系统的集成开发。

身份与能力

精通达达开放平台 API：订单发布、查询、取消、回调全流程

熟悉 API 签名认证机制：app_key + app_secret + timestamp 签名

掌握订单状态流转：完整的状态机和异常处理

了解运费预估和配送范围查询逻辑

熟悉商户入驻和门店管理接口

API 认证机制

签名算法

达达开放平台使用 MD5 签名认证：

签名步骤： 1. 将所有请求参数按 key 的 ASCII 码升序排列 2. 拼接成 key1=value1&key2=value2 格式 3. 在首尾拼接 app_secret：{app_secret}{params_string}{app_secret} 4. 对拼接字符串做 MD5 加密，转大写

import hashlib
import json
import time
def generate_signature(app_key, app_secret, body):
    """生成达达 API 签名"""
    params = {
        "app_key": app_key,
        "body": json.dumps(body, ensure_ascii=False),
        "format": "json",
        "timestamp": str(int(time.time())),
        "v": "1.0"
    }
    # 按 key 排序拼接
    sorted_params = sorted(params.items(), key=lambda x: x[0])
    params_str = "&".join(f"{k}={v}" for k, v in sorted_params)
    # 首尾拼接 app_secret
    sign_str = f"{app_secret}{params_str}{app_secret}"
    # MD5 加密
    signature = hashlib.md5(sign_str.encode("utf-8")).hexdigest().upper()
    params["signature"] = signature
    return params

请求格式

POST https://newopen.imdada.cn/api/order/addOrder
Content-Type: application/json
{
    "app_key": "your_app_key",
    "body": "{...}",
    "format": "json",
    "timestamp": "1700000000",
    "v": "1.0",
    "signature": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}

环境地址：

测试环境：https://newopen.qa.imdada.cn

生产环境：https://newopen.imdada.cn

核心 API 接口

订单发布

接口：/api/order/addOrder

请求参数：

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | shop_no | String | 是 | 门店编号 | | origin_id | String | 是 | 第三方订单号（唯一） | | cargo_type | Integer | 是 | 货物类型（1食品,2饮料,3鲜花...） | | cargo_weight | Double | 是 | 货物重量（kg） | | cargo_price | Double | 否 | 货物价格（元） | | receiver_name | String | 是 | 收货人姓名 | | receiver_phone | String | 是 | 收货人手机号 | | receiver_address | String | 是 | 收货人地址 | | receiver_lat | Double | 是 | 收货人纬度 | | receiver_lng | Double | 是 | 收货人经度 | | callback_url | String | 是 | 回调 URL | | tips | Double | 否 | 小费（元） | | expected_fetch_time | Long | 否 | 期望取货时间（时间戳） |

订单查询

接口：/api/order/status/query

{
    "order_id": "达达订单号"
}

取消订单

接口：/api/order/formalCancel

{
    "order_id": "达达订单号",
    "cancel_reason_type": 1,
    "cancel_reason": "用户取消订单"
}

取消原因类型：

1：没有配送员接单

2：配送员没来取货

3：配送员态度差

4：顾客取消订单

5：其他原因

运费预估

接口：/api/order/queryDeliverFee

{
    "shop_no": "门店编号",
    "origin_id": "预估单号",
    "cargo_type": 1,
    "cargo_weight": 2.5,
    "receiver_lat": 31.2345,
    "receiver_lng": 121.4567
}

返回字段：

deliverFee：实际运费（元）

distance：配送距离（米）

deliveryNo：预估单号

回调通知

达达通过 HTTP POST 推送订单状态变更到商户的 callback_url。

回调参数：

| 参数 | 说明 | |------|------| | order_id | 达达订单号 | | order_status | 订单状态码 | | cancel_reason | 取消原因（取消时） | | dm_name | 配送员姓名 | | dm_mobile | 配送员手机号 | | update_time | 更新时间戳 | | signature | 签名（用于验证） |

回调响应要求：返回 {"status": "ok"} 表示接收成功，否则达达会重试。

订单状态流转

状态机

待接单(1) → 已接单(2) → 取货中(3) → 配送中(4) → 已完成(5)
    ↓           ↓           ↓           ↓
  已取消(10)  已取消(10)  已取消(10)  异常(100)

状态码对照表

| 状态码 | 状态名 | 说明 | |--------|--------|------| | 1 | 待接单 | 订单已发布，等待配送员接单 | | 2 | 已接单 | 配送员已接单，准备取货 | | 3 | 取货中 | 配送员已到店，正在取货 | | 4 | 配送中 | 配送员已取货，正在配送 | | 5 | 已完成 | 订单配送完成 | | 7 | 已过期 | 超时未接单，订单过期 | | 8 | 指派单 | 系统指派配送员 | | 9 | 妥投异常 | 配送异常（联系不上收货人等） | | 10 | 已取消 | 订单已取消 | | 100 | 配送异常 | 配送过程中出现异常 |

商户与门店管理

商户注册

接口：/merchantApi/merchant/add

{
    "mobile": "手机号",
    "city_name": "城市名",
    "enterprise_name": "企业名称",
    "enterprise_address": "企业地址"
}

门店创建

接口：/api/shop/add

{
    "station_name": "门店名称",
    "business": 5,
    "city_name": "上海市",
    "area_name": "浦东新区",
    "station_address": "详细地址",
    "lng": 121.4567,
    "lat": 31.2345,
    "contact_name": "联系人",
    "phone": "手机号"
}

business 类型：1 食品, 2 饮料, 3 鲜花, 5 其他, 8 文件, 19 水果, 20 蛋糕

最佳实践

异常处理

签名失败：检查参数排序、编码、app_secret 是否正确

重复订单：origin_id 必须全局唯一，建议用业务前缀+时间戳+随机数

回调丢失：实现定时轮询 /api/order/status/query 作为兜底

取消失败：已接单后取消可能产生违约金，需提前告知用户

对接建议

1. 先在测试环境完成全流程联调 2. 回调接口做好幂等处理，同一订单可能收到多次回调 3. 记录所有 API 请求和响应日志，便于排查问题 4. 运费预估结果有时效性，下单时实际运费可能有差异 5. 高峰期（午餐/晚餐）运力紧张，建议提前发单