README

达达配送--接口说明文档

感谢达达配送官方提供的SDK，本composer包基于达达配送官方SDK修改而来。本软件/插件包仅作为学习使用，如需商业使用，请根据自身业务需求进行修改。

官方链接：https://newopen.imdada.cn/

个人链接：http://www.youlongit.com

注意：

需要在项目根目录下config目录下新建dada.php文件，内容如下所示：

<?php
return[
    'app_key'   => '',
    'app_secret'   => '',
    'v'   => '1.0',
    'source_id'   => '',
    'host'   => 'http://newopen.qa.imdada.cn',
];

目录结构如下：

youlong
--dada
----src
------api
--------merchant
----------CityCode.php
----------MerchantAdd.php
----------ShopAdd.php
----------ShopDetail.php
----------ShopUpdate.php
--------message_inform
----------MessageInform.php
--------order
----------AddOrder.php
----------AddTip.php
----------AppendOrder.php
----------AppendTransporter.php
----------BaseOrder.php
----------CancelAppendOrder.php
----------CancelOrder.php
----------CancelReasons.php
----------ComplaintDada.php
----------ComplaintReasons.php
----------ConfirmAbnormalGoods.php
----------OrderDetails.php
----------ReAddOrder.php
--------recharge
----------BalanceQuery.php
----------Recharge.php
--------Base.php
--------client
----------DadaRequestClient.php
----------DadaResponse.php
--------config
----------Config.php
----------UrlConfig.php
------Dada.php
------composer.json

1、订单管理

1.1、新增订单

1.1.1、接口简介

在测试环境，使用统一商户和门店进行发单。其中，商户id：73753，门店编号：11047059

1.1.2、请求参数说明

1.1.2.1、product_list请求参数

1.1.3、返回结果

返回array格式，以下为参数说明

result业务参数

正确的返回结果如下：

[
  "status"	=> "success",
  "code"	=> 0,
  "msg"		=> "成功",
  "result"	=> [
    "distance"		=> 1762904.8573641,
    "fee"			=> 12,
    "deliverFee"	=> 12,
    "insuranceFee"	=> 0,
    "tips"			=> 0,
  ]
]

1.1.4、请求案例

<?php
    $data = new Dada();
    $addOrder = new AddOrder();
    $addOrder->setShopNo('11047059');
    $addOrder->setOriginId('20210416111032767383');
    $addOrder->setCityCode('2068');
    $addOrder->setCargoPrice(10.00);
    $addOrder->setIsPrepay(0);
    $addOrder->setReceiverName('测试');
    $addOrder->setReceiverPhone(13800138000);
    $addOrder->setReceiverDddress('中山市');
    $addOrder->setReceiverLat(22.51595);
    $addOrder->setReceiverLng(113.3926);
    $addOrder->setCargoWeight(5);
    $addOrder->setCargoNum(1);
    $addOrder->setCallback('http://krqx86.natappfree.cc/business.php?r=business/place/order');
    $req = new DadaRequestClient($data, $addOrder);
    var_dump($req->makeRequest());

1.2、重新发布订单

1.2.1、接口简介

在调用新增订单后，订单被取消、投递异常（妥投异常之物品返回完成=10）的情况下，调用此接口，可以在达达平台重新发布订单。

1.2.2、请求参数

1.2.2.1、product_list请求参数

1.2.3、返回结果

返回array格式，以下为参数说明

result业务参数

正确的返回结果如下：

[
  "status"	=> "success",
  "code"	=> 0,
  "msg"		=> "成功",
  "result"	=> [
    "distance"		=> 1762904.8573641,
    "fee"			=> 12,
    "deliverFee"	=> 12,
    "insuranceFee"	=> 0,
    "tips"			=> 0,
  ]
]

1.2.4、请求案例

<?php
    $data = new Dada();
    $addOrder = new ReAddOrder();
    $addOrder->setShopNo('11047059');
    $addOrder->setOriginId('20210416111032767383');
    $addOrder->setCityCode('2068');
    $addOrder->setCargoPrice(10.00);
    $addOrder->setIsPrepay(0);
    $addOrder->setReceiverName('测试');
    $addOrder->setReceiverPhone(13800138000);
    $addOrder->setReceiverDddress('中山市');
    $addOrder->setReceiverLat(22.51595);
    $addOrder->setReceiverLng(113.3926);
    $addOrder->setCargoWeight(5);
    $addOrder->setCargoNum(1);
    $addOrder->setCallback('http://krqx86.natappfree.cc/business.php?r=business/place/order');
    $req = new DadaRequestClient($data, $addOrder);
    var_dump($req->makeRequest());

1.3、订单预发布

1.3.1、接口简介

预发布订单的操作流程是：使用【查询订单运费接口】获取平台订单编号，调用【查询运费后发单接口】即可发布订单。

【查询订单运费接口】经纬度为非必传参数，如果不传经纬度，系统会自动在city_code所在城市解析收货地址，所以此时接口中的city_code一定要传正确。

1.3.2、查询订单运费接口

传入订单相关参数可以查询到该时刻订单所需的运费，同时返回一个唯一的平台订单编号，注意：该平台订单编号有效期为3分钟。

1.3.2.1、请求参数说明

1.3.2.2、product_list请求参数

1.3.2.3、返回结果

返回array格式，以下为参数说明

result业务参数

正确的返回结果如下：

[
  "status"	=> "success",
  "code"	=> 0,
  "msg"		=> "成功",
  "result"	=> [
    "distance"		=> 1762904.8573641,
    "fee"			=> 12,
    "deliverFee"	=> 12,
    "insuranceFee"	=> 0,
    "tips"			=> 0,
  ]
]

1.3.3、查询运费后发单接口

根据【查询订单运费接口】返回的平台订单编号进行发单。只有新订单或者状态为已取消、已过期以及投递异常的情况下可以进行订单预发布。

1.3.3.1、请求参数说明

返回array格式，以下为参数说明

result业务参数

正确的返回结果如下：

1.3.4、请求案例

1.4、增加小费

1.4.1、接口简介

可以对待接单状态的订单增加小费。需要注意：订单的小费，以最新一次加小费动作的金额为准，故下一次增加小费额必须大于上一次小费额。

1.4.2、请求参数说明

返回array格式，以下为参数说明

1.4.3、请求案例

<?php    $data = new Dada();    $addTip = new AddTip();    $addTip->setOrderId('20210416111032767383');    $addTip->setCityCode('2068');    $addTip->setTips(1.5);    $req = new DadaRequestClient($data, $addTip);    var_dump($req->makeRequest());

1.5、订单回调

1.5.1、接口简介

每次订单状态发生变化时，会对添加订单接口中callback的URL进行回调。

已取消：包括配送员取消、商户取消、客服取消、系统取消（比如：骑士接单后一直未取货），此时订单的状态为5，可以通过“重新发单”来下发订单。
妥投异常：配送员在收货地，无法正常送到用户手中（包括用户电话打不通、客户暂时不方便收件、客户拒收、货物有问题等等）
状态1000：表示因为达达内部服务异常，导致下发订单失败。可以通过“新增订单”来下发订单。

接口测试链接：https://newopen.imdada.cn/#/quickStart/develop/apiTest

1.6、订单详情查询

1.6.1、接口简介

查询订单的相关信息以及骑手的相关信息，具体信息参见参数说明。

1.6.2、请求参数说明

1.6.3、返回结果

返回array格式，以下为参数说明

result业务参数

注：只有当订单被接单后才会有骑手信息，并且在待取货和配送中可以查询骑手实时的坐标信息。

1.6.4、请求案例

<?php    $data = new Dada();    $orderDetails =new OrderDetails();    $orderDetails->setOrderId('20210416111032767383');    $req = new DadaRequestClient($data, $orderDetails);    var_dump($req->makeRequest());

1.7、取消订单

1.7.1、接口简介

在订单待接单或待取货情况下，调用此接口可取消订单。

取消费用说明：

接单1 分钟以内取消不扣违约金；
接单后1－15分钟内取消订单，运费退回。同时扣除2元作为给配送员的违约金；
配送员接单后15 分钟未到店，商户取消不扣违约金；
系统取消订单说明：超过72小时未接单系统自动取消。每天凌晨2点，取消大于72小时未完成的订单。

1.7.2、请求参数说明

1.7.3、返回结果

返回array格式，以下为参数说明

result业务参数

1.7.4、取消原因列表

1.7.5、请求案例

<?php    $data = new Dada();    $cancelOrder = new CancelOrder();    $cancelOrder->setOrderId('20210416111032767384');    $cancelOrder->setCancelReasonId(4);    $req = new DadaRequestClient($data, $cancelOrder);    var_dump($req->makeRequest());

成功返回值：

[  "status" => "success",  "code" => 0,  "msg" => "成功",  "result" => [    "deduct_fee" => 0  ]]

1.8、追加订单

1.8.1、接口简介

商户调用该接口将已发布的订单追加给指定的配送员,

追加的订单必须是该门店发出的处于待接单状态的订单
只能从符合条件的配送员列表选取配送员进行追加,参考查询追加配送员

1.8.2、请求参数说明

1.8.3、返回结果

返回array格式，以下为参数说明

正确的响应结果

[    "status" => "success",    "code" => 0,    "msg" => "成功"]

失败的响应结果

[    "status" => "fail",    "errorCode" => 2070,    "code" => 2070,    "msg" => "指派的订单已被接单"]

1.8.4、请求案例

<?php    $data = new Dada();    $appendOrder = new AppendOrder();    $appendOrder->setOrderId('20210416111032767384');    $appendOrder->setTransporterId('666');    $appendOrder->setShopNo('11047059');    $req = new DadaRequestClient($data, $appendOrder);    var_dump($req->makeRequest());

1.9、取消追加订单

1.9.1、接口简介

商户调用该接口取消已发布的追加订单

注：被取消的追加订单，状态变为待接单，其他配送员可见

1.9.2、请求参数说明

1.9.3、返回结果

返回array格式，以下为参数说明

正确的响应结果

[    "status" => "success",    "code" => 0,    "msg" => "成功"]

失败的响应结果

[    "status" => "fail",    "errorCode" => 2070,    "code" => 2070,    "msg" => "指派的订单已被接单"]

1.9.4、请求案例

<?php    $data = new Dada();    $cancelAppendOrder = new CancelAppendOrder();    $cancelAppendOrder->setOrderId('20210416111032767384');    $req = new DadaRequestClient($data, $cancelAppendOrder);    var_dump($req->makeRequest());

1.10、查询追加配送员

1.10.1、接口简介

商户调用该接口查询可追加订单的配送员列表

可追加的配送员需符合以下条件

配送员在1小时内接过此商户的订单,且订单未完成
配送员在当前商户接单数小于系统限定的指定商户接单总数
配送员在达达平台的接单数量未达上限

1.10.2、请求参数说明

1.10.3、返回结果

返回array格式，以下为参数说明

result业务参数：

正确的响应结果

[  "status" => "success",  "code" => 0,  "msg" => "成功",  "result" => [    [      "phone" => "13546670420",      "name" => "达达骑手",      "id" => 666,      "city_id" => 1    ]  ]]

1.10.4、请求案例

<?php    $data = new Dada();    $appendTransporter = new AppendTransporter();    $appendTransporter->setShopNo('11047059');    $req = new DadaRequestClient($data, $appendTransporter);    var_dump($req->makeRequest());

1.11、商家投诉达达

1.11.1、接口简介

达达配送员接单后，商家如果对达达服务不满意，均可以使用该接口对达达进行投诉。

1.11.2、请求参数说明

1.11.3、返回结果

返回array格式，以下为参数说明

正确的响应结果

[   "status" => "success",   "code" => 0,   "msg" => "成功",]

失败的响应结果

[   "status" => "fail",   "code" => 2134,   "errorCode" => 2134,   "msg" => "规定时间送达，投诉无效",]

1.11.4、请求案例

<?php    $data = new Dada();    $complaintDada = new ComplaintDada();    $complaintDada->setOrderId('20210416111032767384');    $complaintDada->setReasonId('4');    $req = new DadaRequestClient($data, $complaintDada);    var_dump($req->makeRequest());

1.12、妥投异常之物品返回完成

1.12.1、接口简介

订单妥投异常后，订单状态变为9，骑士将物品进行返还，如果商家确认收到物品后，可以使用该接口进行确认，订单状态变成10，同时订单终结。

1.12.2、请求参数说明

1.12.3、返回结果

返回array格式，以下为参数说明

1.12.4、请求案例

<?php    $data = new Dada();    $confirmAbnormalGoods = new ConfirmAbnormalGoods();    $confirmAbnormalGoods->setOrderId('20210416111032767384');    $req = new DadaRequestClient($data, $confirmAbnormalGoods);    var_dump($req->makeRequest());

2、商户管理

2.1、获取城市信息

2.1.1、接口简介

通过接口，获取城市信息列表

注：当没有业务参数的时候, body需要赋值为空字符串,即body:""。

2.1.2、请求参数说明

无

2.1.3、返回结果

返回array格式，以下为参数说明

2.1.4、result业务参数

2.1.5、请求案例

<?php    $data = new Dada();    $cityCode = new CityCode();    $req = new DadaRequestClient($data, $cityCode);    var_dump($req->makeRequest());

2.2、注册商户

2.2.1、接口简介

商户注册接口,并完成与该商户的绑定.生成的初始化密码会以短信形式发送给注册手机号

2.2.2、请求参数说明

2.2.3、返回结果

返回array格式，以下为参数说明

正确响应的结果

[    "status" => "success",    "result" => 73767,    "code" => 0,    "msg" => "成功"]

2.2.4、请求案例

<?php    $data = new Dada();    $merchantAdd = new MerchantAdd();    $merchantAdd->setMobile('13800138000');    $merchantAdd->setCityName('上海');    $merchantAdd->setEnterpriseName('优雅谷');    $merchantAdd->setEnterpriseDddress('上海街');    $merchantAdd->setContactName('张三1');    $merchantAdd->setContactPhone('13800138000');    $merchantAdd->setEmail('123456.gd@163.com');    $req = new DadaRequestClient($data, $merchantAdd);    var_dump($req->makeRequest());

注：把 source_id 的值设置为空

2.3、新增门店

2.3.1、接口简介

门店编码可自定义，但必须唯一，若不填写，则系统自动生成。发单时用于确认发单门店
如果需要使用达达商家App发单，请设置登陆达达商家App的账号（必须手机号）和密码
该接口为批量接口,业务参数为数组

2.3.2、请求参数说明

2.3.3、返回结果

返回array格式，以下为参数说明

2.3.4、result业务参数

2.3.5、请求案例

<?php    $data = new Dada();    $shopAdd = new ShopAdd();    $shopAdd->setStationName('优雅谷');    $shopAdd->setBusiness(1);    $shopAdd->setCityName('上海');    $shopAdd->setAreaName('浦东新区');    $shopAdd->setStationAddress('浦东新区');    $shopAdd->setLng(113.403081);    $shopAdd->setLat(22.51043);    $shopAdd->setContactName('游龙');    $shopAdd->setPhone('13800138000');    $req = new DadaRequestClient($data, $shopAdd);    var_dump($req->makeRequest());

2.4、编辑门店

2.4.1、接口简介

门店编码是必传参数。其他参数，需要更新则传，且不能为空。

2.4.2、请求参数说明

2.4.3、返回结果

返回array格式，以下为参数说明

正确的响应结果

[    "status" => "success",    "code" => 0,    "msg" => "成功"]

失败的响应结果

[    "status" => "fail",    "errorCode" => 2406,    "code" => 2406,    "msg" => "没有可以更新的参数,请重新核对"]

2.4.4、请求案例

<?php    $data = new Dada();    $shopUpdate = new ShopUpdate();    $shopUpdate->setOriginShopId('shop001');    $shopUpdate->setStationName('优雅谷');    $shopUpdate->setBusiness(1);    $shopUpdate->setCityName('上海');    $shopUpdate->setAreaName('浦东新区');    $shopUpdate->setStationAddress('浦东新区');    $shopUpdate->setLng(113.403081);    $shopUpdate->setLat(22.51043);    $shopUpdate->setContactName('游龙');    $shopUpdate->setPhone('13800138000');    $req = new DadaRequestClient($data, $shopUpdate);    var_dump($req->makeRequest());

2.5、门店详情

2.5.1、接口简介

查询门店详情接口

2.5.2、请求参数说明

2.5.3、返回结果

返回array格式，以下为参数说明

2.5.4、result业务参数

2.5.5、请求案例

<?php    $data = new Dada();    $shopDetail = new ShopDetail();    $shopDetail->setOriginShopId('shop001');    $req = new DadaRequestClient($data, $shopDetail);    var_dump($req->makeRequest());

3、消息通知

3.1、消息通知简介

3.1.1、简介

1.登录开发者账号，在【属性设置】里配置【接收消息URL地址】。

2.当产生对应类型的消息时，达达开放平台会将消息推送至配置的URL地址。

3.1.2、推送消息参数说明

3.1.3、消息地址应返回的结果

返回JSON格式，以下为返回结果说明

正确的响应结果（JSON格式）

{"status":"ok"}

错误的响应结果（JSON格式）

{"status":"fail"}

注：

不同的messageType决定不同的messageBody。
不同的messageType需要不同的处理方式。
如果返回失败(status='fail')或者请求超时，达达侧会重试3次。

3.2、消息确认

3.2.1、接口简介

1.商家接受到消息后，根据不同的messageType作不同的操作。

2.当产生对应类型的消息时，达达开放平台会将消息推送至配置的URL地址。

3.2.2、推送消息参数说明

3.2.3、返回结果

返回array格式，以下为参数说明

3.2.4、请求案例

<?php    $data = new Dada();    $messageInform = new MessageInform();    $messageInform->setMessageType(1);    $messageInform->setMessageBody([        'orderId'   => '20210416111032767384', // 消息类型（1：骑士取消订单推送消息）        'dadaOrderId'   => '277073797294677', // 达达订单号，选填        'isConfirm'   => 1, // 0:不同意，1:表示同意    ]);    $req = new DadaRequestClient($data, $messageInform);    var_dump($req->makeRequest());

3.3、骑士取消订单

3.3.1、接口交互简介

1.骑士取消订单后，达达开放平台推送消息至商家配置的URL。

2.商家接收到消息后，进行确认操作。

注：

商户接收到消息，返回ok或者success

3.3.2、推送消息的请求参数说明

3.3.3、接收到消息后的确认参数说明

4、充值管理

4.1、获取充值链接

4.1.1、请求参数说明

4.1.2、返回结果

返回array格式，以下为参数说明

4.1.3、请求案例

<?php    $data = new Dada();    $recharge = new Recharge();    $recharge->setAmount(1);    $recharge->setCategory('PC');    $req = new DadaRequestClient($data, $recharge);    var_dump($req->makeRequest());

返回值：

[  "status" => "success",  "code" => 0,  "msg" => "成功",  "result" => "达达收银台URL地址"]

4.2、查询账户余额

4.2.1、接口简介

使用此接口可以查询运费账户或红包账户的余额。

4.2.2、请求参数说明

4.2.3、返回结果

返回array格式，以下为参数说明

4.2.4、请求案例

<?php    $data = new Dada();    $balanceQuery = new BalanceQuery();    $balanceQuery->setCategory(3); // 查询运费账户类型（1：运费账户；2：红包账户，3：所有），默认查询运费账户余额    $req = new DadaRequestClient($data, $balanceQuery);    var_dump($req->makeRequest());

返回值

[  "status" => "success",  "code" => 0,  "msg" => "成功",  ["result"]=> [     "deliverBalance" => 9974854.9,    "redPacketBalance" => 1000000  ]]

xiulong / dada

维护者

详细信息

README

1、订单管理

1.1、新增订单

1.1.1、接口简介

1.1.2、请求参数说明

1.1.2.1、product_list请求参数

1.1.3、返回结果

1.1.4、请求案例

1.2、重新发布订单

1.2.1、接口简介

1.2.2、请求参数

1.2.2.1、product_list请求参数

1.2.3、返回结果

1.2.4、请求案例

1.3、订单预发布

1.3.1、接口简介

1.3.2、查询订单运费接口

1.3.2.1、请求参数说明

1.3.2.2、product_list请求参数

1.3.2.3、返回结果

1.3.3、查询运费后发单接口

1.3.3.1、请求参数说明

1.3.4、请求案例

1.4、增加小费

1.4.1、接口简介

1.4.2、请求参数说明

1.4.3、请求案例

1.5、订单回调

1.5.1、接口简介

1.6、订单详情查询

1.6.1、接口简介

1.6.2、请求参数说明

1.6.3、返回结果

1.6.4、请求案例

1.7、取消订单

1.7.1、接口简介

1.7.2、请求参数说明

1.7.3、返回结果

1.7.4、取消原因列表

1.7.5、请求案例

1.8、追加订单

1.8.1、接口简介

1.8.2、请求参数说明

1.8.3、返回结果

1.8.4、请求案例

1.9、取消追加订单

1.9.1、接口简介

1.9.2、请求参数说明

1.9.3、返回结果

1.9.4、请求案例

1.10、查询追加配送员

1.10.1、接口简介

1.10.2、请求参数说明

1.10.3、返回结果

1.10.4、请求案例

1.11、商家投诉达达

1.11.1、接口简介

1.11.2、请求参数说明

1.11.3、返回结果

1.11.4、请求案例

1.12、妥投异常之物品返回完成

1.12.1、接口简介

1.12.2、请求参数说明

1.12.3、返回结果

1.12.4、请求案例

2、商户管理

2.1、获取城市信息

2.1.1、接口简介

2.1.2、请求参数说明

2.1.3、返回结果

2.1.4、result业务参数

2.1.5、请求案例

2.2、注册商户

2.2.1、接口简介

2.2.2、请求参数说明

2.2.3、返回结果

2.2.4、请求案例