神州专车开放平台

相关文章推荐

纯真的羽毛球 · constexpr （C++） | ...· 5 月前 ·

打盹的斑马 · 中国对南海问题的立场_中华人民共和国驻加拿大大使馆· 10 月前 ·

活泼的香槟 · 销售桶装饮用水,小规模的增值税税率是多少-百度经验· 10 月前 ·

机灵的小熊猫 · 北京师范大学统计学院· 1 年前 ·

憨厚的瀑布 · 束之高閣 [正文] - 成語檢視 - ...· 1 年前 ·

#### 第二步：进行授权认证在【应用管理】模块里应用详情中获得客户端ID和客户端秘钥用于请求授权服务器进行授权，[步骤参考授权认证](doc?r=guide/content#授权认证)，授权后获取access_token #### 第三步：请求API 授权认证后根据授权后获取的Access Token尝试请求以下API。请求各环境[接入域名](doc?r=guide/content#域名)，响应报文请参考[请求与响应](doc?r=guide/content#请求与响应) + [/v1/resource/common/getCityService](doc?r=api/content#产品总类) + [/v1/resource/common/getNearbyCarInfo](doc?r=api/content#附近车辆) + [/v1/resource/common/estimate/price](doc?r=api/content#费用预估（无优惠券）) #### 关于订单状态回调通知订单状态发生变化时，神州服务器会主动请求用户配置的订单状态变化回调url。目前回调状态有两个版本，于2017年9月15号及以后创建的应用都是V2版本回调，之前的应用都是V1版本的回调。如果想由V1切到V2版本回调，可以联系神州工作人员。注意：回调状态与订单状态不完全一致。收到回调状态后，再通过订单详情接口获取订单详细信息，来完成您的业务操作 ###### 回调数据 https://你的订单变化回调url?q={"content":{"status":"compleled", "orderId":"6265131711686377123","eventExplanation":"","dOrderId":"123"},"operation":"statusChanged"} ###### 回调数据说明 | 参数名称 | 类型 | 可选 | 说明 | ------ | --- | --- | --- | status | string | 否 | 订单回调状态 | orderId | string | 否 | 订单ID | operation | string | 否 | 固定值statusChanged | eventExplanation | string | 是 | 对事件的解释说明，例如为何取消，无效，调账等 | dOrderId | string | 是 | 渠道订单id，当创建订单的请求参数customData中有传dOrderId时才返回 #### 关于发票状态回调通知发票状态发生变化时，神州服务器会主动请求用户配置的发票状态变化回调url。目前只有在发票状态为已开票、已邮寄（纸质发票才有此状态）、已红冲（电子发票才有此状态）才会回调给开发者。收到回调状态后，您可以根据自身需要做相应的业务操作 ###### 回调数据 https://你的发票变化回调url?q={"content":{"status":"invoiced", "receiptId":"1"},"operation":"invoiceStatusChanged"} ###### 回调数据说明 | 参数名称 | 类型 | 可选 | 说明 | ------ | --- | --- | --- | status | string | 否 | 发票回调状态 | receiptId | string | 否 | 开票记录主键 | operation | string | 否 | 固定值invoiceStatusChanged | eventExplanation | string | 是 | 对事件的解释说明 #### 关于接机礼宾订单状态回调通知接机礼宾订单状态发生变化时，神州服务器会主动请求用户配置的接机礼宾订单状态回调url。收到回调状态后，您可以根据自身需要做相应的业务操作 ###### 回调数据 https://你的接机礼宾订单状态变化回调url?q={"content":{"status":"waitConfirm", "orderId":"6656565677008158723","eventExplanation":""},"operation":"pickupServiceStatusChanged"} ###### 回调数据说明 | 参数名称 | 类型 | 可选 | 说明 | ------ | --- | --- | --- | status | string | 否 | 接机礼宾订单回调状态 | orderId | string | 否 | 关联用车订单id | operation | string | 否 | 固定值pickupServiceStatusChanged | eventExplanation | string | 是 | 对事件的解释说明 #### 关于反馈单回调通知反馈单发送处理情况时，神州服务器会主动请求用户配置的反馈单回调url。收到回调，您可以根据自身需要做相应的业务操作 ###### 回调数据 https://你的反馈单回调url?q={"content":{"orderId":"666666","sourceType":1,"feedbackType":1,"description":"用户取消订单失败", "processResult":"已为用户退款","refundAmount":"15.0","isFinish":1,"isSupportReopen":1},"operation":"feedbackOrderChanged"} ###### 回调数据说明 | 参数名称 | 类型 | 可选 | 说明 | ------ | --- | --- | --- | orderId | string | 否 | 关联订单id | sourceType | Integer | 否 | 来源类型(1:第三方,2:神州) | feedbackType | Integer | 否 | 反馈类型 | description | string | 否 | 事件描述 | processResult | string | 否 | 处理结果 | refundAmount | string | 否 | 退款金额 | isFinish | Integer | 否 | 是否完结(0:未完结,1:完结) | isSupportReopen | Integer | 否 | 是否支持再次开启(0:不支持,1:支持) #### 关于支付用户在开发者应用中叫车后订单服务完成，且司机提交完费用后，系统会立即自动在用户神州专车的账户上扣取自身余额。 #### 关于时间戳所有接口涉及到时间均采用unix时间戳，unix时间戳-百度百科、unix时间戳-维基百科。 ## API快速接入指南 + API模式快速接入 ## 授权认证神州专车开发平台API授权认证采用 `OAuth 2.0` 目前支持 + [授权码模式（Authorization Code）](#auth_code) + [客户端模式（Client Credentials Grant）](#auth_client) + [密码模式（Resource Owner Password CredentialsGrant）](#auth_password) 注意：客户端模式只允许访问与用户信息无关API，如[基础信息（product）](doc?r=api/content#基础信息)权限范围下的API。测试环境和正式环境使用域名不同，请使用正确[域名](doc?r=guide/content#域名)。 #### 授权码模式授权（Authorization Code） ###### 授权流程 1. 完成接入准备 2. 拼接授权地址，请求授权地址会引导用户进行登录和授权 3. 用户授权成功后，在重定向url中获取授权`code` 4. 通过接口，使用`code `获取`access_token` 5. 使用`access_token`代替用户发送接口请求 ##### 第一步：请求授权地址按照下面规则拼接请求授权地址，将会引导用户进行神州专车账户登录。登录后跳转到授权页面进行授权。授权地址后追加`mobile=手机号`可限制授权登录的用户手机号。
注意测试环境和正式环境[域名](doc?r=guide/content#域名)不同，下面示例为正式环境域名 [HTTP/GET] https://oauth.10101111.com/oauth/authorize?client_id=你的客户端ID&redirect_uri=你的重定向url&response_type=code&scope=read&state=客户端状态&mobile=手机号 ###### 请求参数 | 参数名称 | 类型 | 可选 | 说明 | ------ | --- | --- | --- | client_id | string | 否 | 客户端ID，我的应用中查看 | redirect_uri | string | 否 | 重定向url,授权成功后回调的url
必须与创建应用时配置的值一致。 | response_type | string | 否 | 固定值code | scope | string | 否 | 目前固定值read | state | string | 是 | 可以指定任意值。授权成功回调时，这个值会被原样返回 ##### 第二步：获取code 应用程序通过授权服务器授权成功后将会重定向到 `redirect_uri` 地址上并追加 `code `参数。此`code`只能使用一次，有效期为10分钟。如果在第一步传入了`state`参数授权服务器会直接将`&state=参数`追加到重定向地址上。 [Example] http://你的重定向URL?code=dDV68&state=state ##### 第三步：根据code获取Access Token 获取授权 `access_token` ，用于请求开放平台API。默认有效期`12小时`。有效期可以从应用中修改。注意测试环境和正式环境[域名](doc?r=guide/content#域名)不同，下面示例为正式环境域名 [HTTP/POST] https://oauth.10101111.com/oauth/token?client_id=你的客户端ID&client_secret=你的客户端密钥&grant_type=authorization_code&code=授权code&redirect_uri=你的重定向url ###### 请求参数 | 参数名称 | 类型 | 可选 | 说明 | ------ | --- | --- | --- | client_id | string | 否 | 客户端ID，我的应用中查看 | client_secret | string | 否 | 客户端秘钥，我的应用中查看 | grant_type | string | 否 | 固定值authorization_code | code | string | 否 | 授权code | redirect_uri | string | 否 | 重定向url，我的应用中配置的 ###### 响应数据 > 数据仅供参考 "access_token": "0f541eec-67f9-4831-8af6-8e5330290bc5", "token_type": "bearer", "refresh_token": "3e86c0e7-ff8f-4abc-a4f8-0624365f3aa9", "expires_in": 599, "scope": "read" ###### 响应数据说明 | 参数名称 | 类型 | 可选 | 说明 | ------ | --- | --- | --- | access_token | string | 否 | 访问令牌 | token_type | string | 否 | 令牌类型默认:bearer | refresh_token | string | 否 | 刷新令牌 | expires_in | string | 否 | 访问令牌有效期，单位秒 | scope | string | 否 | 客户端scope ##### 第四步：更新Access Token 如果用户的`access_token`过期了,可以通过`refresh_token`获得新的`access_token`，`refresh_token`有效期默认`30天`。注意测试环境和正式环境域名不同，下面示例为正式环境域名 [HTTP/POST] https://oauth.10101111.com/oauth/token?client_id=你的客户端ID&client_secret=你的客户端秘钥&grant_type=refresh_token&refresh_token=刷新令牌 ###### 请求参数 | 参数名称 | 类型 | 可选 | 说明 | ------ | --- | --- | --- | client_id | string | 否 | 客户端ID，我的应用中查看 | client_secret | string | 否 | 客户端秘钥，我的应用中查看 | grant_type | string | 否 | 固定值refresh_token | refresh_token | string | 否 | 刷新令牌 ###### 响应数据 > 数据仅供参考与第三步获取的数据结构一致 "access_token": "0f541eec-67f9-4831-8af6-8e5330290bc5", "token_type": "bearer", "refresh_token": "3e86c0e7-ff8f-4abc-a4f8-0624365f3aa9", "expires_in": 599, "scope": "read" ###### 示意图

#### 客户端模式授权（Client Credentials Grant）应用程序可以直接向授权服务器获取`Access Token `授权，该授权只允许访问与用户信息无关API，如[基础信息（product）](doc?r=api/content#基础信息)权限范围下的API。 ##### 请求地址 [HTTP/POST] https://oauth.10101111.com/oauth/token?client_id=你的客户端ID&client_secret=你的客户端密钥&grant_type=client_credentials ##### 请求参数 | 参数名称 | 类型 | 可选 | 说明 | ------ | --- | --- | --- | client_id | string | 否 | 客户端ID，我的应用中查看 | client_secret | string | 否 | 客户端秘钥，我的应用中查看 | grant_type | string | 否 | 固定值client_credentials ##### 响应数据 > 数据仅供参考 "access_token": "e7a2b42f-c607-47dc-8b65-16ead82278b9", "token_type": "bearer", "expires_in": 599, "scope": "read" ##### 响应数据说明 | 参数名称 | 类型 | 可选 | 说明 | ------ | --- | --- | --- | access_token | string | 否 | 访问令牌 | token_type | string | 否 | 令牌类型默认:bearer | expires_in | string | 否 | 访问令牌有效期，单位秒 | scope | string | 否 | 客户端scope #### 密码模式授权（ Resource Owner Password CredentialsGrant）应用程序可以使用企业超级管理员账号直接向授权服务器获取`Access Token`授权。该模式可以用来实现替他人叫车，无需用户登录神州账户用车。企业超级管理员账号信息请联系神州商务人员。 ##### 请求地址 [HTTP/POST] https://oauth.10101111.com/oauth/token?client_id=你的客户端ID&client_secret=你的客户端密钥&grant_type=password&username=XXX&password=XXX ##### 请求参数 | 参数名称 | 类型 | 可选 | 说明 | ------ | --- | --- | --- | client_id | string | 否 | 客户端ID，我的应用中查看 | client_secret | string | 否 | 客户端秘钥，我的应用中查看 | grant_type | string | 否 | 固定值password | username | string | 否 | 企业超级管理员账户 | password | string | 否 | 企业超级管理员密码备注：企业超级管理员账户及密码可联系神州商务进行开通。 ##### 响应数据 > 数据仅供参考 "access_token": "1bbdd5be7-6309-4861-900e-4a33a7dde7c9", "token_type": "bearer", "refresh_token": "87b5514b-9216-43ab-97c6-5e673sdf82de", "expires_in": 46399, "scope": "read" ##### 响应数据说明 | 参数名称 | 类型 | 可选 | 说明 | ------ | --- | --- | --- | access_token | string | 否 | 访问令牌 | token_type | string | 否 | 令牌类型默认:bearer | refresh_token | string | 否 | 刷新令牌 | expires_in | string | 否 | 访问令牌有效期，单位秒 | scope | string | 否 | 客户端scope ## 域名所有服务器通信均采用 `https://` 访问。 #### 测试环境域名 | 名称 | 域名 | ------ | --- | 授权认证 | https://sandboxoauth.10101111.com | API | https://sandboxapi.10101111.com #### 正式环境域名 | 名称 | 域名 | ------ | --- | 授权认证 | https://oauth.10101111.com | API | https://openapi.10101111.com ## 接口调试参考 [接入域名 > 测试环境域名](doc?r=guide/content#域名) 指向测试环境为便捷开发者能够跑完完整流程，提供以下测试接口（正式环境不支持这些接口） #### 1. 账户充值 [HTTP/POST] /v1/action/user/recharge ###### 请求参数 | 参数名称 | 类型 | 可选 | 说明 | ------ | --- | --- | --- | access_token | string | 否 | 授权后的access token | amount | integer | 否 | 充值金额 | mobile | string | 是 | 待充值用户手机号
如果只传入该参数，表示给个人账户充值 | companyId | integer | 是 | 企业Id
如果只传入该参数，表示给公司账户充值(企业支付)
如果mobile和companyId都传了，且企业支付类型为员工垫付，表示给员工账户充值(员工垫付) ###### 响应数据 > 数据仅供参考 "busiCode": "BASE000", "code": 1, "content": "SUCCESS", "msg": "成功", "status": "SUCCESS", "uid": "b9339eb4-0845-4673-b3ea-2eb2e857b3061455521954623", "version": "200" #### 2. 变更订单状态接口和工具（模拟司机接单）为方便开发者能够走通整个订单流程，开放平台提供了订单状态接口和工具。 ##### （1）订单调试接口调用此接口可变更[订单状态](doc?r=guide/content#状态定义)，变更顺序如下(必须按此顺序变更) > created > dispatched > arriving > arrived > serviceStarted > serviceFinished > feeSubmitted > paid > completed [HTTP/POST] /v1/action/order/changeStatus ###### 请求参数 | 参数名称 | 类型 | 可选 | 说明 | ------ | --- | --- | --- | access_token | string | 否 | 授权后的access token | orderId | string | 否 | 订单id | driverId | long | 否 | 接单司机id | status | string | 否 | 订单状态 | clng | double | 是 | 司机当前经度(开始和结束服务时必填) | clat | double | 是 | 司机当前纬度(开始和结束服务时必填) | actualKiloLength | double | 是 | 实际里程数(司机提交费用时必填) | highwayAmount | double | 是 | 路桥费 | airportServiceAmount | double | 是 | 机场服务费 | parkingAmount | double | 是 | 停车费 | cleanAmount | double | 是 | 清洁费 | otherAmount | double | 是 | 其他费用 | otherAmountRemark | string | 是 | 其他费用描述 ###### 响应数据 > 数据仅供参考 "busiCode": "BASE000", "code": 1, "content": { "code": 1, "message": "订单状态修改成功" "msg": "成功", "status": "SUCCESS", "uid": "2358e4e5-219c-4492-9827-4f8eb957a8dc1458107714834", "version": "200" ##### （2）订单调试工具在开放平台网站—>应用管理—>测试环境—>操作—>调试，如下图：

点击调试，可以对该应用的订单进行调试，如下图：

订单状态流转图如下：

订单状态流转图

#### 3. 测试环境司机信息 | 车型 | 测试环境司机Id | ------ | --- | 商务7座 | 43851,49842,49860,49875,49893,49908 | 公务轿车 | 42393,49848,49851,49854,49866,49869,
49872,49881,49884,49887,49899,49902,
49905,49914,49917,49920 | 豪华轿车 | 44118,49845,49863,49878,49896,49911 ## 请求与响应每个开放平台API都需要附带以下参数 ##### 通用请求参数 | 参数名称 | 类型 | 可选 | 说明 | ------ | --- | --- | --- | access_token | string | 否 | 授权后的access token ##### 响应报文每个开放平台API的HTTP请求的响应结果，都以JSON格式包含以下内容： | 参数名称 | 类型 | 可选 | 说明 | ------ | --- | --- | --- | code| integer | 否 | 调用结果状态，详见下表>状态值 | status | string | 否 | 调用结果状态英文标识，详见下表>英文标识 | busiCode | integer | 否 | 业务状态。BASE000代表无业务错误，BASE001代表通用业务错误，BASE002代表无业务结果，其他的字符串代表具体业务错误。 | msg | string | 否 | 调用结果描述信息，详见下表>描述 | uid | string | 否 | 唯一标示 | version | string | 否 | 请求的版本号 | content | json/string/array... | 否 | API返回的结果,由API定义 ##### 调用结果状态 | 状态值 | 英文标识 | 描述 | ------ | --- | --- | 1 | SUCCESS | 成功 | 2 | API_NOT_FIND | API不存在或者此版本API已下线 | 3 | LIMIT_ERROR | 调用频率超过限制 | 4 | NO_AUTH | 客户端的API权限不足 | 6 | MAPI_ERROR | 服务器内部错误 | 7 | BASE_ERROR | 业务处理错误 | 9 | PARAM_ERROR | 参数错误 | 10 | INVOKER_INIT_FAIL | 客户端身份初始化失败 | 12 | PROTOCOL_ERROR | 请求协议错误 | 13 | SECRETKEY_EXPIRED | 秘钥过期 | 14 | PERMISSION_DENIED | 权限不足 | 15 | TOKEN_INVALID | TOKEN失效 ## 状态定义 #### 1. 订单状态 | 状态值 | 描述 | ------ | --- | created | 新建 | invalid | 无效 | dispatched | 已派单 | arriving | 已出发 | arrived | 已到达 | canceled | 已取消 | serviceStarted | 已开始服务 | serviceFinished | 已结束服务 | feeSubmitted | 已提交费用 | paid | 已支付待评价 | completed | 已完成 #### 2. 订单回调状态V1（待废弃） | 回调值 | 描述 | ------ | --- | created | 新建 | invalid | 无效 | dispatched | 已派单 | recharged | 订单充值（下单余额不足5分钟内进行充值并满足订单金额后进行回调） | arriving | 已出发 | arrived | 已到达 | canceled | 已取消 | serviceStarted | 已开始服务 | serviceFinished | 已结束服务 | feeSubmitted | 已提交费用 | partPaid | 部分支付（包括违约金） | paid | 全部支付（包括违约金） | completed | 已完成 #### 3. 订单回调状态V2 | 回调值 | 描述 | ------ | --- | created | 新建 | balanceNotEnough| 订单新建成功后，发现用户余额不足，需要在五分钟内充值，否则后台自动取消订单。需要用户主动拉取订单详情接口，以获取差多少钱 | rechargedInTime | 余额不足订单发生充值，需要用户主动拉取订单详情接口，以获取还差多少钱，如果欠费金额为0，则表明该单不欠费，可以进行后续流程 | canRetryInvalid | 订单无效，再次下单可能下单成功。例如超接单上线，无空驶车辆。有无效备注 | noRetryInvalid | 订单无效，再次下单也不可能下单成功。例如超服务范围，无司机。有无效备注 | dispatched | 已派单，订单详情可查到司机信息 | redispatched | 订单改派，司机和车辆信息有变化。需要用户主动拉取订单详情接口，以获得最新的司机和车辆信息 | arriving | 已出发 | arrived | 已到达 | canceled | 已取消。可能会产生违约金，需要用户主动拉取订单详情接口，以获得目前订单正确价格。有取消原因备注 | serviceStarted | 已开始服务 | serviceFinished | 已结束服务 | feeSubmitted | 已提交费用 | partPaid | 部分支付（包括违约金） | paid | 全部支付（包括违约金） | priceUp | 客服调账，上调。订单价钱增加，需要用户主动拉取订单详情接口，以获得目前订单正确价格。有调账备注 | priceDown | 客服调账，下调。订单价钱减少，需要用户主动拉取订单详情接口，以获得目前订单正确价格。有调账备注 | completed | 已完成。此状态下订单信息不会再发生变化，订单信息应以此状态为准 #### 4. 支付状态 | 状态值 | 描述 | ------ | --- | unpaid | 未支付 | paying | 支付处理中 | paymentFailure | 支付失败 | partPayment | 部分支付 | paid | 已支付 #### 5. 订单创建状态 | 状态值 | 描述 | ------ | --- | hasUnpaidOrder | 有未完成支付订单 | createSuccess | 创建成功 | createFailed | 创建失败 | orderAreaError | 超服务范围 | orderLimitError | 超接单上限，运力不足 | orderCarError | 无空驶车辆 | memberError | 会员状态无效 | couponError | 代金券已被使用 | departureTimeError | 用车时间小于当前时间 | frozenMoneyNotEnough | 可冻结金额不足 | passengerMoreThanThreeOrder | 乘车人未结算订单达到三个 | outOfDayError | 预定时间超过系统规定天数 | blackListMemberPermanent | 订车人在永久黑名单中 | blackListMemberTemp | 订车人在临时黑名单中 | blackListPassengerPermanent | 乘车人在永久黑名单中 | blackListPassengerTemp | 乘车人在临时黑名单中 | couponIsNotBelongToMember | 代金券不属于该用户 | enterPriceNotEnough | 该企业账户余额不足 | personEnterPriceNotEnough | 该企业个人账户余额不足 | couponSelfLimitError | 选择的代金券仅限本人乘车时使用 | floatFactorChange | 价格浮动系数发生变化 #### 6. 接机礼宾订单状态 | 状态值 | 描述 | ------ | --- | waitRecharge | 下单成功待充值。余额不够，需要充值 | waitConfirm | 待确认订单。订单已经创建，等待分配礼宾员 | waitService | 待服务。已经分配完礼宾员 | completed | 服务完成，用车订单状态变为serviceStarted时，接机礼宾状态自动变为completed | canceled | 已取消，可能会产生取消费 #### 7. 接机礼宾订单回调状态 | 回调值 | 描述 | ------ | --- | waitRecharge | 下单成功待充值。余额不够，需要用户主动拉取订单详情接口，以获取还差多少钱，如果欠费金额为0，则表明该单不欠费，可以进行后续流程 | waitConfirm | 待确认订单 | waitService | 待服务。已经分配完礼宾员，需要用户主动拉取订单详情接口，以获取礼宾员信息 | completed | 服务完成 | canceled | 已取消。可能产生取消费，需要用户主动拉取订单详情接口，以获得目前订单正确价格。 #### 8. 纸质发票状态 | 回调值 | 描述 | ------ | --- | waitInvoice | 待开票 | waitPost | 待邮寄 | posted | 已邮寄 | pickupBySelf | 已自取 | canceled | 已取消 #### 9. 电子发票状态 | 回调值 | 描述 | ------ | --- | waitInvoice | 待开票 | invoiced | 已开票 | invoiceFail | 开票失败 | reded | 已红冲 #### 10. 发票回调状态 | 回调值 | 描述 | ------ | --- | invoiced | 已开票 | posted | 已邮寄（纸质发票才有此状态） | reded | 已红冲（电子发票才有此状态） | fail | 开票失败 ## 上线前checklist 如发现如下问题请联系神州。下文中订车人指获取token的手机号 1.不希望司机或客服联系订车人？ 2.不希望乘客或订车人收到神州发送的用车信息短信？ 3.是否需要初始化可开票额度？否则线上无法开票。 4.评估各个接口QPS。目前神州同一个access_Token访问同一接口默认最大5秒50次，是否满足？

加载中...