2018-09-28

该文档提供了找罐车与找油网TMS系统对接需要用到的接口，主要包括demand、carrier order相关接口。

Host

HOST: https://api.zhaoguanche.com/zyw/

Authentication

平台部分接口需要客户端认证，后续需要做认证的接口会在具体接口中标出

Authentication 模式

OAuth 2.0 协议标准 client credentials 模式

Client认证请求

POST:  /oauth2/token  
Content-Type:  application/x-www-form-urlencoded
Accept:  application/json

字段	描述	必须	数据类型	参数位置	备注
client_id	客户端ID	Y	String	@body	提前提供给企业客户
client_secret	客户端秘钥	Y	String	@body	提前提供给企业客户
grant_type	授权类型	Y	String	@body	目前紧支持客户端模式，强制设置该字段值为"client_credentials"

测试账号

client_id: d35e5379-b42a-4bd7-abe4-b0d981ee88d9
client_secret:33c737b514122ee8e6d65271cd7481b6ede62ea54419691705cc0e6cc56cb445
注：该账号仅供找油网测试使用

样例

curl -H "Accept: application/json"
https://api.zhaoguanche.com/zyw/oauth2/token 
-d "grant_type=client_credentials&client_id=${demoApp}&client_secret=${demoAppSecret}"

认证成功返回

{
 "token_type": "bearer", 
 "access_token": "W3xqSWKLJpZuzyPARZGEhGP9DuPYIufw", 
 "expires_in": 7200
}

认证失败返回

{
  "error": "invalid_client",
  "error_description": "Bad client credentials"
}

Token验证失败返回

{
"error": "invalid_token",
"error_description": "Invalid access token: W3xqSWKLJpZuzyPARZGEhGP9DuPYIufw"
}

Token过期返回

{
"error": "invalid_token",
"error_description": "Access token expired: W3xqSWKLJpZuzyPARZGEhGP9DuPYIufw"
}

请求响应

字段	描述	必须	数据类型	备注
code	返回码	是	int	具体看返回码定义
message	返回错误信息	是	String	必须携带该字段告知成功或错误信息
data	数据	否	String	当code为200，则该字段返回调用者想要的数据

返回码

字段	描述	备注
200	Success
500	Server Error	服务器发生的未知错误
530	Business Logic Error	业务逻辑错误，例如修改已经装货完毕运单的所属需求单装货地信息
431	Bad Request	包括参数缺失、参数验证失败等，具体错误看message信息
430	Operation Failed	未知失败原因的失败操作
440	Resources Not Found	没有发现要查询或者要修改的数据

Demand

该部分主要是提供给第三方企业（找油网）上传需求单使用的接口

POST /demand //上传新需求单

Content-Type: application/json
Accept: application/json
Authorization: Bearer ${token}

字段	描述	必须	数据类型	备注
orderId	订单ID	Y	String	该需求单的唯一标示
acceptTime	订单受理时间	N	String	受理该订单的时间
pickUpWay	提送方式	N	String
deliveringWay	装卸方式	N	String
warehouseManager	仓管员	N	String
businessInitiator	业务发起方	N	String
loadingAddrProvince	装货地省	Y	String
loadingAddrCity	装货地市	Y	String
loadingAddrDistrict	装货地区	Y	String
loadingAddrStreet	装货地详细地址	Y	String
loadingAddrCustom	装货地客户名称	N	String
loadingAddrContact	装货地联系人	Y	String
loadingAddrContactNumber	装货地联系电话	Y	String
scheduledLoadingTime	装货时间	Y	String	格式："yyyy-MM-dd'T'HH:mm:ss.SSSZ"
unloadingAddrProvince	卸货地省	Y	String
unloadingAddrCity	卸货地市	Y	String
unloadingAddrDistrict	卸货地区	Y	String
unloadingAddrStreet	卸货地详细地址	Y	String
unloadingAddrCustom	卸货地客户名称	N	String
unloadingAddrContact	卸货地联系人	Y	String
unloadingAddrContactNumber	卸货地联系电话	Y	String
scheduledUnloadingTime	卸货时间	Y	String	格式："yyyy-MM-dd'T'HH:mm:ss.SSSZ"
payloadName	货物名称	Y	String
itemNumber	货号	N	String
brand	品牌	N	String
category	标号	N	String
classification	级别	N	String
unitPrice	单价	Y	Decimal	单位:元/吨
packingSpecification	包装规格	N	String
weight	重量	Y	Decimal	单位:吨
volume	体积	N	Decimal	单位:立方米
collateralLoss	约定损耗	Y	Integer	例:千分之三,该值就为 3
compartment	隔舱	N	String
hasFlowMeter	流量计	N	String
requiredPortPositions	装卸口	N	String
payloadUnitPrice	约定货物单价	Y	Decimal	单位:吨
orderCreater	创建人	Y	String
remark	备注说明	N	String

请求样例
POST  /demand  HTTP/1.1
Accept: application/json
Authorization: Bearer 4ed0bf90-6e60-46e7-94d8-c21bd41bcd28
Payload:
{
"orderId":"1253625635",
"acceptTime":"2018-08-20T12:34:21.232+0800",
"pickUpWay":"auto",
"deliveringWay":"vehicle",
"warehouseManager":"张三",
"businessInitiator":"李四",
"loadingAddrProvince":"上海",
"loadingAddrCity":"上海市",
"loadingAddrDistrict":"闵行区",
"loadingAddrStreet":"田林路静安新城十区1000号楼",
"loadingAddrCustom":"蓁康电子",
"loadingAddrContact":"王凡",
"loadingAddrContactNumber":"18753932002",
"scheduledLoadingTime":"2018-08-20T12:34:21.232+0800",
"unloadingAddrProvince":"山东省",
"unloadingAddrCity":"临沂市",
"unloadingAddrDistrict":"兰山区",
"unloadingAddrStreet":"双岭路1000号",
"unloadingAddrCustom":"中国石化",
"unloadingAddrContact":"王五",
"unloadingAddrContactNumber":"18765434323",
"scheduledUnloadingTime":"2018-08-20T12:34:21.232+0800",
"payloadName":"汽油",
"itemNumber":"10021",
"brand":"中国石化",
"category":"100",
"classification":"2000",
"unitPrice":"8000",
"packingSpecification":"铁罐",
"weight":"10",
"volume":"50",
"collateralLoss":"1",
"compartment":"",
"hasFlowMeter":"1",
"requiredPortPositions":"02",
"payloadUnitPrice":"790",
"orderCreater":"Jack",
"remark":"下雨了"
}
成功返回样例
{
    "code":200,
    "message":"Success"
}
失败返回样例
{
    "code":431,
    "message":"参数有误",
    "detail":"类型解析异常，数据类型错误: 'payloadUnitPrice':'7000元'  "
}

PUT /demand //更新需求单

Content-Type: application/json
Accept: application/json
Authorization: Bearer ${token}

字段	描述	必须	数据类型	备注
orderId	订单ID	Y	String	该需求单的唯一标示
acceptTime	订单受理时间	N	String	受理该订单的时间
pickUpWay	提送方式	N	String
deliveringWay	装卸方式	N	String
warehouseManager	仓管员	N	String
businessInitiator	业务发起方	N	String
loadingAddrProvince	装货地省	N	String
loadingAddrCity	装货地市	N	String
loadingAddrDistrict	装货地区	N	String
loadingAddrStreet	装货地详细地址	N	String
loadingAddrCustom	装货地客户名称	N	String
loadingAddrContact	装货地联系人	N	String
loadingAddrContactNumber	装货地联系电话	N	String
scheduledLoadingTime	装货时间	N	String	格式："yyyy-MM-dd'T'HH:mm:ss.SSSZ"
unloadingAddrProvince	卸货地省	N	String
unloadingAddrCity	卸货地市	N	String
unloadingAddrDistrict	卸货地区	N	String
unloadingAddrStreet	卸货地详细地址	N	String
unloadingAddrCustom	卸货地客户名称	N	String
unloadingAddrContact	卸货地联系人	N	String
unloadingAddrContactNumber	卸货地联系电话	N	String
scheduledUnloadingTime	卸货时间	N	String	格式："yyyy-MM-dd'T'HH:mm:ss.SSSZ"
payloadName	货物名称	N	String
itemNumber	货号	N	String
brand	品牌	N	String
category	标号	N	String
classification	级别	N	String
unitPrice	单价	N	Decimal	单位:吨
packingSpecification	包装规格	N	String
weight	重量	N	Decimal	单位:吨
volume	体积	N	Decimal	单位:立方米
collateralLoss	约定损耗	N	Integer	例:千分之三,该值就为 3
compartment	隔舱	N	String
hasFlowMeter	流量计	N	String
requiredPortPositions	装卸口	N	String
payloadUnitPrice	约定货物单价	N	Decimal	单位:吨
orderCreater	创建人	N	String
remark	备注说明	N	String

备注：除orderId以外，全部为可选字段，修改什么内容传什么字段

请求样例
PUT  /demand  HTTP/1.1
Accept: application/json
Authorization: Bearer 4ed0bf90-6e60-46e7-94d8-c21bd41bcd28
Payload:
{
   "orderId":"1253625635",
   "scheduledUnloadingTime":"2018-08-20T12:34:21.232+0800"
}
成功返回样例
{
    "code":200,
    "data":{
                  "orderId":"1253625635",
                  "scheduledUnloadingTime":"2018-08-20T12:34:21.232+0800"
           }
}
失败返回样例
{
    "code":440,
    "message":"参数错误",
    "detail":" 该订单不存在:1253625635"
}

DELETE /demand //取消需求单

Content-Type: application/json
Accept: application/json
Authorization: Bearer ${token}

字段	描述	必须	数据类型	备注
orderId	订单ID	Y	String	该需求单的唯一标示

请求样例
DELETE  /demand  HTTP/1.1
Accept: application/json
Authorization: Bearer 4ed0bf90-6e60-46e7-94d8-c21bd41bcd28
Payload:
{
   "orderId":"1253625635"
}
成功返回样例
{
    "code":200,
    "message":"Success"
}
失败返回样例
{
    "code":530,
    "message":"业务逻辑错误",
    "detail":" 该订单所属运单正在运输中，不能取消操作"
}

GET /tracks/{plate_num} //获取轨迹地址

Content-Type: application/json
Accept: application/json
Authorization: Bearer ${token}

字段	描述	必须	数据类型	备注
plate_num	路径参数，车牌号	Y	String	该需求单的唯一标示
from_address	起始地址	Y	String	xxx省xx市xxx区xxx
to_address	终点地址	Y	String	xxx省xx市xxx区xxx
start_at	开始时间	Y	Long	时间戳（毫秒数）
end_at	结束时间	Y	Long	时间戳（毫秒数）

请求样例

Authorization: Bearer 4ed0bf90-6e60-46e7-94d8-c21bd41bcd28
https://api.zhaoguanche.com/zyw/tracks/沪A12345?from_address=%E4%B8%8A%E6%B5%B7%E5%B8%82%E5%BE%90%E6%B1%87%E5%8C%BA%E4%BA%AC%E5%89%A7%E9%99%A2&to_address=%E5%8E%A6%E9%97%A8%E5%B8%82%E9%BC%93%E6%B5%AA%E5%B1%BF&start_at=1537848000&end_at=1537963200

返回结果
{
    "code":200,
    "data":"https://tools.useiov.net/tools/trace-addon.php?from_address=上海市徐汇区京剧院&to_address=厦门市鼓浪屿&start_at=1537848000&end_at=1537963200&plate_num=沪A12345"
}