CCC数字钥匙3.0标准解读(22)

---

17 服务器对服务器通信和API

17.1 介绍

本节介绍设备制造商服务器和车辆制造商服务器之间通信的API规范。
请求和响应主体的格式应为JSON格式。用于所有接口的通信协议应为HTTPS协议。所有字符串应为UTF-8编码（Unicode规范化形式C（NFC））。

17.2 API设计

 除非另有规定，否则所有API都应实现为HTTPS POST请求。
 请求和响应有效数据应由简单的基于JSON的数据结构组成，以便将来扩展。使用的主要数据类型有数组、字典、布尔值和字符串。
 错误代码分为三个级别：
 传输级别错误代码
 HTTP错误代码，如第17.9节所述
 标准化应用层错误代码
 公共响应标头中的状态代码字段；第17.9节中定义的值
 详细错误代码
 通用响应标头中的可选子状态代码字段，如第17.10节所述

17.3 安全

客户端应用程序应运行在用户设备上。设备制造商服务器和车辆制造商服务器应部署在安全的数据中心。
服务器API只能通过https支持。在适用的情况下，应使用额外的加密协议保护敏感数据元素。
服务器API只能通过具有相互身份验证的https支持，即双向TLS。

17.4 URL规划

所有服务器的服务URI应符合以下方案：
scheme://host:port/{service}/{version}/apiName
这里：
 scheme = https
 host:port =提供端点访问的主机名和端口号
 service =支持API的目标应用程序
 version =方案的版本号。当前的主要版本是v1
 apiName =被调用的API的名称
API版本应包含在所有接口的URI中。第一个支持的版本是v1。对于API的主要变更或现有API上的向后不兼容迭代，版本应增加1。

17.5 心跳检查

心跳检查是确定设备OEM和车辆OEM服务器的服务器可用性的一种方法。

17.6 用户界面

17.6.1 描述

用户界面由设备制造商创建和控制。每个设备制造商都可以根据其平台定制用户界面。
投入使用之前，车辆制造商应用离线过程为特定车辆/型号向设备制造商提供所有必要的视觉元素。视觉元素的细节不在规范范围内，应由车辆制造商和设备制造商协商。可以由车辆制造商选择的标识符被分配给UI元素。此标识符称为uiIdentifier。
为了确保车辆制造商之间的唯一性，可以使用前缀。uiIdentifier应该是通用的，并且系统不能使用uiIdentifier来识别车主或好友。
特定车辆的uiIdentifier示例：“VehicleOEMNameModelYearColor”。UI元素存储在设备制造商服务器上，以确保运行时的最佳可用性。
在不同类型的服务（车主配对、钥匙共享）期间，uiIdentifier由车辆制造商服务器提供给设备制造商服务器。设备制造商然后可以选择预定义的UI元素。设备制造商负责显示适用于设备特定参数的UI元素。

17.7 服务器APIs

17.7.1 API -跟踪钥匙

这是车辆制造商服务器提供的通用API，用于跟踪数字钥匙。这个API应该具有等幂行为。如果对已注册的一个keyID调用trackKey，则API调用应成功，并返回正常响应。本API分别用于第6.3.4.4节和第11.8.5节所述的车主配对和钥匙共享。
理解说明：什么幂等？即任意多次执行所产生的影响均与一次执行的影响相同。

17.7.1.1 端点

HTTPS POST /{service}/{version}/trackKey

17.7.1.2 trackKey ()