Skip to content

OpenAPI使用说明

OpenAPI提供了多种方式，让接入方能够获取在百姓车联托管的数据。

  • 实时接口: 接入方通过HTTP(s)接口，实时查询用户、行程列表、行程详情等数据。

  • 离线数据导出: 接入方通过HTTP(s)接口，发起一个批量数据导出的任务。包括用户列表，所有行程列表，危险行为等。

  • 异步消息通知: 当用户在 UBI SDK 上产生某些行为数据(比如完成某条行程)，百姓车联可以主动将消息推送给接入方。

准备工作

首先，请确保你已经在百姓车联创建了个应用（如果还没有，去创建一个应用）。不同应用之间的数据是完全隔离的，使用某个应用的认证密钥，调用OpenAPI只能获取该应用内的数据。

调用认证

调用 UBI OpenAPI 的所有接口均需要在 HTTP header 中携带认证信息。UBI OpenAPI 支持的认证方式有 APPCODE 认证和摘要认证两种方式，接入方可以选择两种方式的任意一种。

APPCODE 认证

使用 APPCODE 认证方式只需在调用接口的 HTTP 请求中加入 Authorization header 即可，Authorization header 的具体形式为：

  • Header 名称为 Authorization；
  • 值的格式为 APPCODE ＋ 半角空格 ＋ AppCode值。

格式：

1
Authorization:APPCODE AppCode值

示例：

1
Authorization:APPCODE 3F2504E04F8911D39A0C0305E82C3301

AppCode的获取，参考应用的关联密钥。

摘要认证

调用方也可以采用消息认证码的方式进行接口调用认证。该认证方式需要调用方在请求的 HTTP header 中携带 AppID 和消息签名完成接口调用的认证，其中消息签名可使用请求本体与 AppSecret 计算得到。

摘要认证的具体过程和详细的签名计算方式可以参考文档 使用摘要签名认证方式调用API。百姓车联也提供了接入 UBI Passport OpenAPI 的 Java 示例项目 供接入方参考。

一般约定

UBI OpenAPI 的 endpoint：

  • HTTPS: https://driver-behavior-api.haochezhu.club
  • HTTP: http://driver-behavior-api.haochezhu.club

UBI OpenAPI 接口返回的数据均为 application/json 格式。对于 POST 接口，UBI OpenAPI 接受 Content-Type 为 application/json 的请求，请求体应为一个包含调用接口所需字段的 JSON object。

参数格式说明

日期类型参数：接口参数或响应字段中的 startTime, endTime 等表征时间的参数采用形如 YYYY-mm-dd 或 YYYY-mm-dd HH:MM:SS 的字符串表示。例如 2021-12-30 或 2021-12-30 08:00:00。

列表滚动：返回列表的接口一般支持滚动机制。这些接口接受 nextCursor 和 limit 参数，在响应中返回 nextCursor 用于获取下一页数据。获取首页数据时无需指定 nextCursor 和 limit，获取下一页数据时需要将上一次响应中的 nextCursor 携带到下一次请求的参数中。

响应格式说明

API 响应成功时的 HTTP 状态码为 2XX，HTTP 响应体格式请参考各个接口的说明；当接口响应失败时统一返回形如 ErrorResult 的响应体。

ErrorResult

名称 类型 说明
code * integer 错误代码
msg * long 错误描述
extra * object 错误附加信息