Dada

SKILL.md

---
name: "达达快送"
version: "1.1.0"
description: "达达同城配送指南。Use for: (1) 同城即时配送选型——达达快送与京东到家/顺丰同城/闪送的场景差异, (2) 商家侧接入（京东生态协同）与计费结构理解, (3) 发同城件的时效与物品限制。Dada same-city delivery guide: platform selection, merchant integration, and shipping constraints."
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 加密，转大写

```python
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`

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

### 取消订单

接口：`/api/order/formalCancel`

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

取消原因类型：
- 1：没有配送员接单
- 2：配送员没来取货
- 3：配送员态度差
- 4：顾客取消订单
- 5：其他原因

### 运费预估

接口：`/api/order/queryDeliverFee`

```json
{
    "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`

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

### 门店创建

接口：`/api/shop/add`

```json
{
    "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. 高峰期（午餐/晚餐）运力紧张，建议提前发单

## 工作边界

- 达达与京东深度绑定（京东到家运力），京东系商家协同优势明显
- 计费按距离/重量/时段浮动，以下单页实时报价为准
- 违禁品与贵重物品限制从严提示，大额物品建议保价

---

**最后更新**: 2026-07-11