搬运帮开放平台

1 接口规范概述

1.1 系统概述

接入方平台系统与搬运帮平台系统在不同业务请求中互为Client和Server，双方采用JSON over HTTPS进行通信。

搬运帮平台系统提供的业务类型：

消息格式说明：

• 所有请求，采用HTTPS+POST协议，遵循HTTPS 1.1协议规范
• 搬运帮与其他平台间使用IP白名单连接鉴权
• HTTPS鉴权采用请求签名鉴权
• 本规范中MD5,指rfc1321计算结果的可读的大写形式；即所有字母为大写
• 以下参数值，事先约定：Platformid、Secret
• Platformid：分配给第三方平台企业ID
• Secret：企业ID对应的密钥
• HTTPS消息体采用JSON格式， utf-8编码

2 鉴权接口

2.1 Ip白名单鉴权

服务端对客户端的IP进行白名单鉴权。

若IP白名单鉴权失败，则返回403 应答，表示鉴权未通过；若鉴权成功则继续下一步：签名鉴权。

2.2 HTTP签名鉴权

鉴权采用请求签名鉴权，即请求的HTTPS头域中携带Authorization头，填写相关信息，服务端进行鉴权验证。

2.2.1请求消息

格式为：

Authorization:EOPAUTH platformid={platformid-value},timestamp={timestamp-value},signature={signature-value}

例如：

Authorization:EOPAUTH platformid=350000100020003,timestamp=1630479002,signature=B35EB3AF4B198FE2EA2EA2F75F37D90B

其中，Authorization头相关参数说明：

2.2.2响应消息

如果签名鉴权未通过则返回401应答，表示鉴权未通过；如果签名鉴权通过，则返回业务处理结果。

3 全局状态码

当接入方调用服务时会返回请求状态码，不同的状态码对应不同的问题原因，可根据此状态码快速排查，请注意：全局状态码仅作为请求状态，不作为业务成功标志。

4 订单状态说明

当订单发生流转时，订单的状态会发生变化，平台方与接入方都将根据状态做出相应的处理，保障订单顺利完结

5 订单状态回传

当订单发生流转时，订单的状态会发生变化，平台方与接入方都将根据状态做出相应的处理，保障订单顺利完结

当订单状态发生变化时或订单需要接入方处理时将回传给接入方

6 回调事件类型说明

【requestType】当业务需要接入方知晓或处理时，平台会将数据通知到接入方（账户相关通知、订单相关通知）

7 订单事件类型说明

当事件推送类型requestType为订单相关通知时，可根据数据中的handleType字段与以下状态码进行判断，从而做出对应的处理动作

8 响应消息格式

服务端对客户端的请求会返回指定格式数据，一般由code、msg、data、requestId等组成。

响应消息示例：

{
	"code": 0,
	"msg": "处理成功",
	"data": {},
	"requestId": "b4f2afb1-6a48-4432-a1aa-3d5b9d2df917"
}

9 业务接口参数说明

以下针对说明的为HTTPS的消息体部分，其中HTTPS的头域部分参见2.2的章节。

9.1 获取账户信息接口

9.1.1接口说明

搬运帮为接入方开通了对应企业账户，可通过此接口查询账户状态以及余额等信息

9.1.2接口地址

GET /企业id/Account/AccountInfo

9.1.3请求消息

无请求参数

请求示例：

POST URL \
--header 'Authorization: EOPAUTH platformid="123",timestamp="789",signature="abc"'

9.1.4响应消息

响应消息示例：

{
	"code": 0,
	"msg": "ok",
	"data": {
		"name": "****",
		"balance": 10000.00,
		"balanceLimit": 3000.00,
		"availableBalance": 9000.00,
		"availableInvoiceAmount": 1000.00,
		"openWorkerTypes": [1,2,3]
	}
}

9.2 获取工种接口

9.2.1接口说明

搬运帮针对每个城市开通了不同工种，下单前需获取对应城市已开通的工种及每个工种对应的计时计量工时单位

9.2.2接口地址

POST /企业id/Worker/WorkerTypeList

9.2.3请求消息

请求示例：

POST URL \
--header 'Authorization: EOPAUTH platformid="123",timestamp="789",signature="abc"' \
--header 'Content-Type: application/json' \
--data-raw '{
	"City": "北京市"
}'

9.2.4响应消息

响应消息示例：

{
	"code": 0,
	"msg": "ok",
	"data": [{
			"code": 2,
			"name": "装卸工",
			"specs": ["吨","方"]
		},
		{
			"code": 17,
			"name": "叉车工",
			"specs": ["小时","天","次"]
		}
	]
}

9.3 预览订单

9.3.1接口说明

在搬运帮平台下即时订单或预约订单时预览订单。

9.3.2接口地址

POST /企业id/Order/PreviewOrder

9.3.3请求消息

请求示例：

POST URL \
--header 'Authorization: EOPAUTH platformid="123",timestamp="789",signature="abc"' \
--header 'Content-Type: application/json' \
--data-raw '{
	"workerCode": 2,
	"serviceTime": 1704042061,
	"addressInfo": {
		"city": "北京市",
		"address": "东城区xx街道101号",
		"location": "116.405285,39.904989"
	},
	"servicePeopleCount": 1,
	"serviceSpec": "吨",
	"serviceSpecNum": 2,
	"amount": 100
}'

9.3.4响应消息

响应消息示例：

{
	"code": 0,
	"msg": "ok",
	"data": {
		"amount": 100.00
	}
}

9.4 下单接口

9.4.1接口说明

在搬运帮平台下即时订单或预约订单，若订单已取消，再次调用将修改订单信息(扩展序号为标识)。此接口在下单成功前会触发幂等校验：10秒内多次传入完全相同的数据，此时下单失败

9.4.2接口地址

POST /企业id/Order/CreateOrder

9.4.3请求消息

请求示例：

POST URL \
--header 'Authorization: EOPAUTH platformid="123",timestamp="789",signature="abc"' \
--header 'Content-Type: application/json' \
--data-raw '{
	"workerCode": 2,
	"serviceTime": 1704042061,
	"addressInfo": {
		"city": "北京市",
		"address": "东城区xx街道101号",
		"location": "116.405285,39.904989"
	},
	"servicePeopleCount": 1,
	"serviceSpec": "吨",
	"serviceSpecNum": 2,
	"notes": "2吨水泥需要装卸车",
	"noteImgUrls": ["https://abc.com/abc.jpg"],
	"telephone": "135****1234",
	"amount": 100,
	"extendNo": "abc123",
	"appointWorkerFromOrderNo": "2024010110011358389",
	"orderSource": 1,
	"majorRemark": "4.2米货车，200件矿泉水，200斤"
}'

9.4.4响应消息

响应消息示例：

{
	"code": 0,
	"msg": "ok",
	"data": {
		"addResult": "success",
		"orderNo": "2024010110011358389",
		"status": 0
	}
}

9.5 订单详情接口

9.5.1接口说明

下单成功后，可调用此接口获取订单信息，或订单状态流转时刷新此接口获取订单实时信息

9.5.2接口地址

POST /企业id/Order/OrderInfo

9.5.3请求消息

请求示例：

POST URL \
--header 'Authorization: EOPAUTH platformid="123",timestamp="789",signature="abc"' \
--header 'Content-Type: application/json' \
--data-raw '{
 "orderNo": "2024010110011358389"
}'

9.5.4响应消息

响应消息示例：

{
	"code": 0,
	"msg": "ok",
	"data": {
		"orderNo": "2024010110011358389",
		"orderStatus": 100,
		"workerCode": 2,
		"serviceTime": 1704042061,
		"addressInfo": {
			"city": "北京市",
			"address": "东城区xx街道101号",
			"location": "116.405285,39.904989"
		},
		"servicePeopleCount": 1,
		"serviceSpec": "吨",
		"serviceSpecNum": 2,
		"notes": "2吨水泥需要装卸车",
		"telephone": "135****1234",
		"amount": 100,
		"extendNo": "abc123"
	}
}

9.6 订单加价接口

9.6.1接口说明

订单已发布但未被接单时，可通过此接口修改订单价格，提高接单率

9.6.2接口地址

POST /企业id/Order/AddOrderPrice

9.6.3请求消息

请求示例：

POST URL \
--header 'Authorization: EOPAUTH platformid="123",timestamp="789",signature="abc"' \
--header 'Content-Type: application/json' \
--data-raw '{
 "orderNo": "2024010110011358389",
 "amount": 100
}'

9.6.4响应消息

响应消息示例：

{
	"code": 0,
	"msg": "ok",
	"data": {
		"orderNo": "2024010110011358389",
		"orderStatus": 0,
		"addPriceResult": "success",
		"msg": "加价成功"
	}
}

9.7 重置订单接口

9.7.1接口说明

订单已被接单但未开始服务时，可通过此接口将订单重置为待接单状态，重新发布

9.7.2接口地址

POST /企业id/Order/ResetOrder

9.7.3请求消息

请求示例：

POST URL \
--header 'Authorization: EOPAUTH platformid="123",timestamp="789",signature="abc"' \
--header 'Content-Type: application/json' \
--data-raw '{
 "orderNo": "2024010110011358389",
 "reason": "师傅临时有事"
}'

9.7.4响应消息

响应消息示例：

{
	"code": 0,
	"msg": "ok",
	"data": {
		"orderNo": "2024010110011358389",
		"orderStatus": 0,
		"resetResult": "success",
		"msg": "重置成功"
	}
}

9.8 取消订单接口

9.8.1接口说明

预约订单后，发现订单下错了或长时间未接单，可取消订单。

取消说明：订单未开始服务前都可取消(接入方确认核对价格后才可开始服务)

注意：在工人师傅到达现场时，进行此操作可能会扣除费用

9.8.2接口地址

POST /企业id/Order/CancelOrder

9.8.3请求消息

请求示例：

POST URL \
--header 'Authorization: EOPAUTH platformid="123",timestamp="789",signature="abc"' \
--header 'Content-Type: application/json' \
--data-raw '{
 "orderNo": "2024010110011358389",
 "reason": "下错订单",
 "caultTypeEnum": 1
}'

9.8.4响应消息

响应消息示例：

{
	"code": 0,
	"msg": "ok",
	"data": {
		"orderNo": "2024010110011358389",
		"orderStatus": -1,
		"cancelResult": "success",
		"msg": "取消成功"
	}
}

9.9 核对订单接口

9.9.1接口说明

工人到达现场，与接入方现场人员沟通，发现作业量或工时需增加，此时需要添加附加费

9.9.2接口地址

POST /企业id/Order/CheckOrder

9.9.3请求消息

请求示例：

POST URL \
--header 'Authorization: EOPAUTH platformid="123",timestamp="789",signature="abc"' \
--header 'Content-Type: application/json' \
--data-raw '{
 "orderNo": "2024010110011358389",
 "checkStatus": 1
}'

9.9.4响应消息

响应消息示例：

{
	"code": 0,
	"msg": "ok",
	"data": {
		"orderNo": "2024010110011358389",
		"orderStatus": 500,
		"checkResult": "success",
		"msg": "核对成功"
	}
}

9.10 重新核对订单接口

9.10.1接口说明

服务前应核对订单，中途增加服务内容或货物情况发生变化，可通过此接口将订单回溯到未发起核对状态，师傅可修改订单重新发起核对。

回溯说明：订单状态为待核对或订单完结前可回溯，若订单已完结请协商或联系客服处理

9.10.2接口地址

POST /企业id/Order/ReCheckOrder

9.10.3请求消息

请求示例：

POST URL \
--header 'Authorization: EOPAUTH platformid="123",timestamp="789",signature="abc"' \
--header 'Content-Type: application/json' \
--data-raw '{
 "orderNo": "2024010110011358389",
 "reason": "增加服务内容",
 "amount": 100
}'

9.10.4响应消息

响应消息示例：

{
	"code": 0,
	"msg": "ok",
	"data": {
		"orderNo": "2024010110011358389",
		"orderStatus": 0,
		"resetResult": "success",
		"msg": "重置成功"
	}
}

9.11 确认服务完成接口

9.11.1接口说明

工人师傅服务完成后会发起核对请求，请确认服务是否完成，服务质量是否达标，物品是否损坏等，如有异常可拒绝确认。由于服务中可修改价格，所以此接口会受可用余额限制，当可用余额不足时无法确认服务完成

9.11.2接口地址

POST /企业id/Order/CheckComplete

9.11.3请求消息

请求示例：

POST URL \
--header 'Authorization: EOPAUTH platformid="123",timestamp="789",signature="abc"' \
--header 'Content-Type: application/json' \
--data-raw '{
 "orderNo": "2024010110011358389",
 "checkStatus": 1
}'

9.11.4响应消息

响应消息示例：

{
	"code": 0,
	"msg": "ok",
	"data": {
		"orderNo": "2024010110011358389",
		"orderStatus": 700,
		"checkResult": "success",
		"msg": "确认成功"
	}
}

9.12 补差价接口

9.12.1接口说明

由于某些原因，导致在核对订单时订单金额与最终金额不一致，经接入方人员核实后可调用此接口为订单增加差价，只能在订单完结后调用，多次调用会多次扣费，若未收到响应结果，确保不重复调用，可稍后通过订单详情功能查看总金额是否为最终服务金额

9.12.2接口地址

POST /企业id/Order/AddOrderAmount

9.12.3请求消息

请求示例：

POST URL \
--header 'Authorization: EOPAUTH platformid="123",timestamp="789",signature="abc"' \
--header 'Content-Type: application/json' \
--data-raw '{
 "orderNo": "2024010110011358389",
 "amount": 30
}'

9.12.4响应消息

响应消息示例：

{
	"code": 0,
	"msg": "ok",
	"data": {
		"orderNo": "2025052611404364678",
		"addResult": "success",
		"msg": "补差价成功"
	}
}

9.13 附近工人数量接口

9.13.1接口说明

由于某些原因，在下单前，需要得知服务地址周边的工人数量，以便提升接单时间以及接单率，可通过此接口进行查询

9.13.2接口地址

POST /企业id/Worker/VicinityWorkerCount

9.13.3请求消息

请求示例：

POST URL \
--header 'Authorization: EOPAUTH platformid="123",timestamp="789",signature="abc"' \
--header 'Content-Type: application/json' \
--data-raw '{
 "workerCode": 3,
 "location": "116.405285,39.904989"
}'

9.13.4响应消息

响应消息示例：

{
	"code": 0,
	"msg": "ok",
	"data": 100
}

10 余额预警通知说明

当接入方账户余额低于设置预警额度后，每次确认服务完成后都将触发余额预警通知，若可用余额不足将无法下单与验收服务，接入方需在收到通知后返回指定格式数据，如未返回响应示例数据或网络超时将触发重试机制，详见重试机制说明

10.1 接口地址

POST 接入方提供的余额预警地址

10.1.1请求消息

请求示例：

POST URL \
--header 'Content-Type: application/json' \
--data-raw '{
	"requestId": "abc123def",
	"requestType": 100,
	"data": {
		"balance": 3000.00,
		"availableBalance": 1000.00
	}
}'

10.1.2响应消息

响应消息示例：

{
	"code": 0,
	"msg": "处理成功"
}

11 状态回调参数说明

当订单状态发生变化时，搬运帮会将订单状态通知到接入方提供的回调地址。有的状态时间间隔很短，加上网络延时，接入方可能会同时或逆序收到状态通知，接入方在收到回调时需正确处理并发和顺序问题，响应消息需按要求返回，如未返回响应示例数据或网络超时将触发重试机制，详见重试机制说明

11.1 订单取消通知

11.1.1接口说明

订单由于某些原因导致无法服务且由平台操作取消后，向接入方推送此状态，接入方收到此通知后应将内部订单也更新为已取消

11.1.2接口地址

POST 接入方提供的回调地址

11.1.3请求消息

请求示例：

POST URL \
--header 'Content-Type: application/json' \
--data-raw '{
	"requestId": "abc123def",
	"requestType": 200,
	"data": {
		"orderNo": "2024010110011358389",
		"status": -1,
		"handleType": -1
	}
}'

11.1.4响应消息

响应消息示例：

{
	"code": 0,
	"msg": "处理成功"
}

11.2 订单待接单通知

11.2.1接口说明

订单由平台操作重置状态后（师傅不能服务等原因）向接入方推送待接单，此时将会由平台其他师傅参与接单

11.2.2接口地址

POST 接入方提供的回调地址

11.2.3请求消息

请求示例：

POST URL \
--header 'Content-Type: application/json' \
--data-raw '{
	"requestId": "abc123def",
	"requestType": 200,
	"data": {
		"orderNo": "2024010110011358389",
		"status": 0,
		"handleType": 0
	}
}'

11.2.4响应消息

响应消息示例：

{
	"code": 0,
	"msg": "处理成功"
}

11.3 订单已接单通知

11.3.1接口说明

此订单由师傅接单后，向接入方推送此通知，接入方收到此通知后可同步相关信息给现场人员，注意接听师傅电话

11.3.2接口地址

POST 接入方提供的回调地址

11.3.3请求消息

请求示例：

POST URL \
--header 'Content-Type: application/json' \
--data-raw '{
	"requestId": "abc123def",
	"requestType": 200,
	"data": {
		"orderNo": "2024010110011358389",
		"status": 100,
		"handleType": 100,
		"workerInfo": {
			"workerName": "张三",
			"workerMobile": "13011112222"
		}
	}
}'

11.3.4响应消息

响应消息示例：

{
	"code": 0,
	"msg": "处理成功"
}

11.4 到达现场通知

11.4.1接口说明

师傅到达服务地址后推送此通知，接入方收到通知后可通知现场人员接洽服务事宜

11.4.2接口地址

POST 接入方提供的回调地址

11.4.3请求消息

请求示例：

POST URL \
--header 'Content-Type: application/json' \
--data-raw '{
	"requestId": "abc123def",
	"requestType": 200,
	"data": {
		"orderNo": "2024010110011358389",
		"status": 200,
		"handleType": 200
	}
}'

11.4.4响应消息

响应消息示例：

{
	"code": 0,
	"msg": "处理成功"
}

11.5 订单待核对通知

11.5.1接口说明

订单处于待核对状态时向接入方推送此通知，接入方需进行核对价格，若未及时核对订单无法进入服务环节，若无需增加费用也应进行核对确认

11.5.2接口地址

POST 接入方提供的回调地址

11.5.3请求消息

请求示例：

POST URL \
--header 'Content-Type: application/json' \
--data-raw '{
	"requestId": "abc123def",
	"requestType": 200,
	"data": {
		"orderNo": "2024010110011358389",
		"status": 300,
		"handleType": 300,
		"orderAmount": 200.00,
		"addType": 1
	}
}'

11.5.4响应消息

响应消息示例：

{
	"code": 0,
	"msg": "处理成功"
}

11.6 开始服务通知

11.6.1接口说明

接入方核对价格或接入方通过订单详情页确认服务开始，无需返回数据

11.6.2接口地址

POST 接入方提供的回调地址

11.6.3请求消息

请求示例：

POST URL \
--header 'Content-Type: application/json' \
--data-raw '{
	"requestId": "abc123def",
	"requestType": 200,
	"data": {
		"orderNo": "2024010110011358389",
		"status": 500,
		"handleType": 500
	}
}'

11.6.4响应消息

响应消息示例：

{
	"code": 0,
	"msg": "处理成功"
}

11.7 确认服务完成通知

11.7.1接口说明

订单服务结束后向接入方推送此通知，接入方需确认服务结束，若未确认服务则订单无法完结，请谨慎确认

11.7.2接口地址

POST 接入方提供的回调地址

11.7.3请求消息

请求示例：

POST URL \
--header 'Content-Type: application/json' \
--data-raw '{
	"requestId": "abc123def",
	"requestType": 200,
	"data": {
		"orderNo": "2024010110011358389",
		"status": 600,
		"handleType": 600,
		"orderAmount": 200.00,
		"addType": 1,
		"orderImgUrls": ["https://abc.com/abc.jpg"]
	}
}'

11.7.4响应消息

响应消息示例：

{
	"code": 0,
	"msg": "处理成功"
}

11.8 订单完结通知

11.8.1接口说明

订单在平台完结后，向接入方推送此通知，接入方收到此通知后将内部订单也更新为完结

11.8.2接口地址

POST 接入方提供的回调地址

11.8.3请求消息

请求示例：

POST URL \
--header 'Content-Type: application/json' \
--data-raw '{
	"requestId": "abc123def",
	"requestType": 200,
	"data": {
		"orderNo": "2024010110011358389",
		"status": 700,
		"handleType": 700,
		"orderAmount": 200.00
	}
}'

11.8.4响应消息

响应消息示例：

{
	"code": 0,
	"msg": "处理成功"
}

12 重试机制说明

腾讯云服务器响应异常或网络不稳定时，为避免接入方无法收到通知而影响业务，搬运帮平台将对每条通知进行多次重试，请接入方在收到相同通知时根据requestId判断是否已经处理，保证通知处理的幂等性。

重试顺序和机制请参考以下说明。

12.1.1 正确响应示例

接入方在收到请求时，需要对请求进行验签，验签通过后需要进行业务处理，处理完成后返回如下数据，表示处理成功，平台将判定此条通知处理完成，并将重试次数清零。

{
	"code": 0,
	"msg": "处理成功"
}

12.1.2 重试请求

如果接入方返回处理成功以外的数据或未限定时间内返回，平台将判定此条通知处理失败，此时平台将对此条通知进行重试，重试时请求参数相同。接入方需合理设计接口幂等性，以便应对重复通知。

12.1.3 重试次数与间隔

平台对每条通知的重试次数与间隔如下：

以上重试超时后，平台将放弃推送，请注意排查。