数据流向：
DK业务管理服务->钱包云服务。
环境URL：
https://oauth-login.cloud.huawei.com/oauth2/v3/token
请求方式：
POST
请求头：
展开
参数

是否必选

参数类型

描述

Content-Type

是

String

固定值：application/x-www-form-urlencoded

参数	是否必选	参数类型	描述
Content-Type	是	String	固定值：application/x-www-form-urlencoded

请求体：

grant_type=client_credentials&client_id=<客户端ID>&client_secret=<客户端密钥>

参数说明：

展开

参数名称	是否必选	描述
grant_type	是	填写为“client_credentials”，表示为客户端模式。
client_id	是	在接入前准备中得到的OAuth 2.0客户端ID，对于AppGallery Connect类应用，该值为应用的Client ID。
client_secret	是	在接入前准备中给客户端ID分配的密钥，对于AppGallery Connect类应用，该值为应用的Client SECRET。

返回值：

{
    "access_token": "<返回的Access Token>",
    "expires_in": 3600,
    "token_type": "Bearer"
}

错误码：
见错误与异常机制。
示例代码
NetWorkService#getToken(String clientId, String clientSecret)

预置模板

卡片模板的创建是接入流程的第一步，这一步您将会通过http/https请求的方式向华为钱包云服务提供卡券样式的关键信息，如卡面主标题、副标题、logo、背景图片等；用于华为钱包钥匙页面的展示。

您可以创建多个模板，它们有着相同的机构名和服务号，而模板ID不同；当您申请车钥匙时，每一张卡必须和唯一的模板ID关联；即一个模板可供多张钥匙使用，而一张钥匙只能使用一个模板ID。

点击放大

数据流向：
DK业务管理服务->钱包云服务
环境URL：
https://wallet-passentrust-drcn.cloud.huawei.com.cn/hmspass/v2/key_stdcar/model
请求方式：
HTTPS POST

请求头：

展开

参数	是否必选	参数类型	描述
Authorization	是	String	将获取到的“access_token”的值拼接在字符串“Bearer”之后，以空格符相隔，组成“Authorization”参数的值。参考获取AccessToken
Content-Type	是	String	固定值：“application/json;charset=utf-8”。
Accept	是	String	固定值：“application/json;charset=utf-8”。

请求体：

{
  "passVersion": "10.0",
  "passTypeIdentifier": "Replace with the Service ID you applied on AGC",
  "passStyleIdentifier": "DigitalCarKeyTestModel",
  "organizationName": "Replace with your organization name",
  "fields": {
    "appendFields": [
      {
        "label": "NFCCardFlag",
        "value": "true",
        "key": "isCreateWhiteCard"
      }
    ],
    "commonFields": [
      {
        "label": "卡面主标题",
        "value": "我的车",
        "key": "merchantName"
      },
      {
        "label": "卡面副标题",
        "value": "XXX车钥匙",
        "key": "name"
      },
      {
        "label": "",
        "value": "https://xxx/xxx.png",
        "key": "logo"
      },
      {
        "label": "",
        "value": "https://xxx/xxx.webp",
        "key": "backgroundImage"
      },
      {
        "label": "",
        "value": "https://xxx/xxx.png",
        "key": "picUrl"
      }
    ]
  }
}

请求参数由HwWalletObject对象构成，在预置模板阶段只需要携带上面这些参数即可(全部参数说明可见HwWalletObject)，下面是对这些参数的说明：

展开

参数	是否必选	参数类型	参数值	描述
passTypeIdentifier	是	String	hwpass.stdcarkey.xxx.xxx（xxx可为公司/产品名称，总长度不超过32个英文小写字符，请严格按照此规则定义)	请使用在AGC平台上注册的服务号，需要开发者到华为AGC网站申请。
passStyleIdentifier	是	String	自定义，注：示例代码中的默认值仅作说明，请勿使用	模板ID，即modelId。在同一个appId下唯一。长度不超过64个字符，只能是字母、数字和（.）、（-）、（_）。
organizationName	是	String	自定义，注：示例代码中的默认值仅作说明，请勿使用	商户名称，最长64个字节，无具体格式要求，中英文均可。
passVersion	是	String	版本号，固定10.0	钱包对象版本，开发者可以依据此确定钱包对象的版本信息
fields	是	Fields	自定义	卡券展示信息。

appendFields参数说明：

展开

key	value	label	是否必须	描述
isCreateWhiteCard	true	NFCCardFlag	是	用于表明是否是NFC卡的flag

commonFields参数说明：

展开

key	value	label	是否必须	描述	规格
logo	https://开头的图片链接，具体地址车厂自定义	/	是	卡面logo	128*128px，大小<=20kb，直角图片，无需切圆角
backgroundImage	https://开头的图片链接，具体地址车厂自定义	/	是	卡面背景	1312*820px，直角图片，无需切圆角
picUrl	https://开头的图片链接，具体地址车厂自定义	/	是	带logo的卡面背景	1312*820px，直角图片，无需切圆角
merchantName	车厂定义	卡面主标题	是	卡面主标题	小于256字节
name	车厂定义	卡面副标题	是	卡面副标题	小于256字节

返回值：
模板预置成功，即http响应为200时，钱包云服务会将DK业务管理服务请求的数据原样返回，即和上面个的请求体中的数据一致；其他错误情况，可见错误码描述。
错误码：
见错误码。
示例代码：
StdCarKeyModelTest#createStdCarKeyModel()

个人领取

DK业务管理服务向钱包云服务器申请开通ICCE数字车钥匙，其中包括，申请添加车钥匙前检查当前手机是否支持开通ICCE数字车钥匙、生成车钥匙卡片以及拉起华为钱包app车钥匙开通页面。

点击放大

添加前的检查

在申请添加钥匙之前，您需要先检查当前设备是否支持开通ICCE车钥匙。

数据流向：
DK业务管理服务->钱包云服务。
环境URL：
https://wallet-gateway-drcn.cloud.huawei.com.cn/hmspass/v1/{terminal}/{romVersion}/{clientVersion}
请求方式：
GET

请求头：

展开

参数	是否必选	参数类型	描述
Authorization	是	String	将获取到的“access_token”的值拼接在字符串“Bearer”之后，以空格符相隔，组成“Authorization”参数的值。参考获取AccessToken
Content-Type	是	String	固定值：“application/json;charset=utf-8”。
Accept	是	String	固定值：“application/json;charset=utf-8”。

请求参数：

展开

参数	是否必选	参数类型	描述
terminal	是	String	终端机型，如NOH-AN00
romVersion	是	String	终端rom版本号，如NOH-AN00 11.0.0.135(C00E171R6P3log)
clientVersion	是	String	华为钱包版本，如900153000

这些参数，端侧可通过如下方式获取（钱包版本>=9015300）

端侧调用：

ContentResolver resolver = getContentResolver();
// passTypeIdentifier为您在AGC平台注册的服务号
Uri uri = Uri.parse("content://com.huawei.wallet.thirdprovider/getDeviceVersion/" + passTypeIdentifier);
String version = resolver.getType(uri);

返回值：

NOH-AN00/NOH-AN00 11.0.0.135(C00E171R6P3log)/900153000

直接将该返回值拼接在https://wallet-gateway-drcn.cloud.huawei.com.cn/hmspass/v1/后面发起请求即可。

返回值：

{
	"issuerAndFlag": "BackupRecovery#0|license_idcard#0|eid_passwordfree#2|t_huawei_mjk_blank#0|hwpass.byga.pahjv1#2|card_manage_control#0|hwpass.stdcarkey.bluecarkey.xpki#0|licens_driver#0|hwpass.stdcarkey.bluecarkey.xcar#0|key_device#0|RideCodeSwitch#0|intellgentCardSwitch#0|key_organization#0|card_allpowerful#0|hwpass.campuscard.pkuecard#0|community_wish#2|key_car#0|idcard_a4photo#0|t_huawei_mjk_m1#0|licens_driving#0|access_user_interactive#0|swipe_card_express_notice#0|license_passport#0|key_household#0|key_stdcar#0|hwpass.card.enfc.lingyun#2|key_ccccar#0|logoutDeleteCardSwitch#0|MembershipCard_NFC#2|hwpass.stdcarkey.bluecarkey.mgqa#0|license_other#0|wallet_clone_control_flag#2|key_stdBleCar#0|key_car_entrance#0|1040034#0|Campus_Synjones#0|intelligentFenceSwitch#0|ihg_hotel_control#0|hwpass.stdcarkey.bluecarkey.iccedemo#0",
	"queryAddress": "https://nfcws.wallet.hicloud.com/h5/queryruleissuer"
}

参数说明：

展开

参数	参数类型	描述
issuerAndFlag	String	钱包在相应机型中支持的功能列表。每个功能采用“issuer#flag”模式展示，每个功能之间使用“\|”符号分割。 issuer为您在AGC上配置的服务号； flag取值的具体含义如下： 0：表示支持该功能； 1：表示由于rom版本过低，不支持该功能； 2：表示由于client版本过低，不支持该功能； 3：表示由于rom版本和client版本都过低，不支持该功能。
queryAddress	String	用于展示功能列表的页面，该页面暂未开放。

参数

参数类型

描述

issuerAndFlag

String

钱包在相应机型中支持的功能列表。每个功能采用“issuer#flag”模式展示，每个功能之间使用“|”符号分割。

issuer为您在AGC上配置的服务号；

flag取值的具体含义如下：

0：表示支持该功能；

1：表示由于rom版本过低，不支持该功能；

2：表示由于client版本过低，不支持该功能；

3：表示由于rom版本和client版本都过低，不支持该功能。

queryAddress

String

用于展示功能列表的页面，该页面暂未开放。

错误码：
见错误码。
示例代码：
StdCarKeyQuerySupportFeatureTest#querySupportedFeatured()

申请ICCE钥匙

车主APP向DK业务管理服务申请开通ICCE车钥匙，DK业务管理服务将车钥匙卡片信息添加至钱包云服务中；其中：车主APP->DK业务管理服务之间的交互由车厂自行实现，本章主要侧重于DK业务管理服务->钱包云服务申请ICCE车钥匙的过程，主要包括：申请钥匙卡片和生成JWE数据。

1.申请钥匙卡片

DK业务管理服务向华为钱包云服务请求创建车钥匙卡片。

数据流向：
DK业务管理服务->钱包云服务。
环境URL：
https://wallet-passentrust-drcn.cloud.huawei.com.cn/hmspass/v2/key_stdcar/instance
请求方式：
POST

请求头：

展开

参数	是否必选	参数类型	描述
Authorization	是	String	将获取到的“access_token”的值拼接在字符串“Bearer”之后，以空格符相隔，组成“Authorization”参数的值。参考获取AccessToken
Content-Type	是	String	固定值：“application/json;charset=utf-8”。
Accept	是	String	固定值：“application/json;charset=utf-8”。

请求体：

{
  "organizationName": "Replace with your organization name",
  "passTypeIdentifier": "Replace with the Service ID you applied on AGC",
  "passStyleIdentifier": "DigitalCarKeyTestModel",
  "organizationPassId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "serialNumber": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "fields": {
    "timeList": [
      {
        "value": "timeListValue",
        "key": "linkDevicePassExpireTime"
      }
    ],
    "status": {
      "state": "active",
      "effectTime": "2020-04-06T00:00:00.111Z",
      "expireTime": "2030-04-06T00:00:00.111Z"
    },
    "commonFields": [
      {
        "value": "xxx.CarActivity",
        "key": "bleTargetActivity"
      },
      {
        "value": "hwpass.carkey.ble",
        "key": "bleFeature"
      },
      {
        "value": "01:23:45:67:89:AB",
        "key": "bleMacAddress"
      },
      {
        "label": "readerId",
        "value": "CAD34B258391C097",
        "key": "readerMatchValue"
      },
      {
        "label": "主卡服务号",
        "value": "hwpass.stdcarkey.std",
        "key": "ownerPassTypeIdentifier"
      },
      {
        "value": "0000xxxx-0000-1000-8000-00805f9b34fb",
        "key": "bleServiceUuid"
      },
      {
        "value": "xxx",
        "key": "bleTargetPackage"
      },
      {
        "value": "xxx",
        "key": "bleTargetService"
      }
    ]
  },
  "linkDevicePass": {
    "webServiceURL": "https://xxx",
    "nfcType": "1",
    "serialNumber": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "passVersion": "10.0",
    "spPublickey": "xxx",
    "token": "xxx"
  }
}

请求参数由HwWalletObject对象构成，在申请ICCE钥匙阶段只需要携带上面这些参数即可，下面是对这些参数的说明：

展开

参数	是否必选	参数类型	参数值	描述
passTypeIdentifier	是	String	hwpass.stdcarkey.xxx.xxx（xxx可为公司/产品名称，总长度不超过32个英文小写字符，请严格按照此规则定义)	请使用在AGC平台上注册的服务号，需要开发者到华为AGC网站申请。
passStyleIdentifier	是	String	自定义，注：示例代码中的默认值仅作说明，请勿直接使用	请使用“预置模板中创建的”模板ID，即modelId。在同一个appId下唯一。长度不超过64个字符，只能是字母、数字和（.）、（-）、（_）。
organizationName	是	String	自定义，注：示例代码中的默认值仅作说明，请勿直接使用	请使用“预置模板中创建的商户名称，最长64个字节。
organizationPassId	是	String(64)	自定义，注：示例代码中的默认值仅作说明，请勿直接使用	车钥匙卡片在开发者服务器中的卡号。在同一个appId下唯一。长度16个字节，为保证唯一性，请勿手动输入，建议使用代码随机生成，只能是字母、数字（全大写）。当前和和serialNumber保持一致
serialNumber	是	String(64)	自定义，注：示例代码中的默认值仅作说明，请勿直接使用	车钥匙卡片在华为钱包服务器中的卡号，即instanceId。在同一个appId下唯一。长度16个字节，为保证唯一性，请勿手动输入，建议使用代码随机生成，只能是字母、数字（全大写）。当前和organizationPassId保持一致。
fields	是	Fields	自定义	卡券展示信息。
linkDevicePass	是	LinkDevicePass	自定义	此参数用于保存车钥匙管理台服务器地址、公钥信息以及是否使能卡券的NFC能力。

Fields参数说明：

展开

参数	是否必选	参数类型	描述
commonFields	是	List<ValueObject>	通用展示字段列表，即一种卡券中通常需要使用到的属性。各类卡券的具体字段详见各卡券的UI设计。
timeList	是	List<ValueObject>	时间列表。
status	是	Status	开发者自定义状态信息，包括状态和有效时间，会根据此状态值展示卡券是否失效。

ValueObject数据结构说明：

展开

参数	是否必选	参数类型	描述
key	是	String	字段标识，在整个卡券对象中保持唯一。
value	是	String	字段值。
label	否	String	字段标签值。必填还是非必填由各卡券中的具体字段决定。

Status数据结构说明：

展开

参数	是否必选	参数类型	描述
state	是	String	状态值，取值如下:active：生效inactive：未激活completed：已使用expired：已过期
effectTime	是	String	UTC格式，生效时间
expireTime	是	String	UTC格式，失效时间，如果超过此事件，卡券自动按照expired状态处理

commonFields参数说明：

展开

key	value	label	是否必须	描述
bleServiceUuid	由车厂定义	/	是	车厂蓝牙设备的SERVIE_UDID，用于手机发现车端蓝牙模块开启的车钥匙服务；请使用蓝牙标准规范：如0000xxxx-0000-1000-8000-00805f9b34fb；如需自行定义，请联系ICCE确认
ownerPassTypeIdentifier	固定值	"主卡服务号"	是	hwpass.stdcarkey.std：归属ICCE车钥匙类别
readerMatchValue	由车厂定义	"readerId"	是	车钥匙标识，建议字节：不超过20字节（第一字节：车厂标识，第二字节：品牌/系列标识，后续字节保证在车厂内唯一）, 只能包含0-9，A-F
bleTargetPackage	由车厂定义	/	是	车厂app的包名，用于钱包在特定场景下拉起车厂app，见#ZH-CN_TOPIC_0000001225460853/section188661465132。注：请提供应用安装后的全包名，即应用的applicationId, 如com.huawei.wallet
bleTargetActivity	由车厂定义	/	是	车厂app的activity，供钱包在特定场景下拉起车厂app；注：全路径名称，不带文件后缀，如com.huawei.xxx.xxx.ShowCarDetailActivity
bleTargetService	由车厂定义	/	是	车厂app的service，供钱包在特定场景下拉起车厂app，见#ZH-CN_TOPIC_0000001225460853/section188661465132；注：全路径名称，不带文件后缀名，如com.huawei.xxx.xxx.BleICCEService
bleMacAddress	由车厂定义	/	是	车端蓝牙设备的mac地址，用于华为手机扫描车端蓝牙模块、向车端蓝牙发起Gatt连接等。请注意格式合法性，如：01:23:45:67:89:0A；注：字符必须全大写
bleFeature	固定值	/	是	hwpass.carkey.ble：标识支持蓝牙车钥匙
deviceType	设备类型	/	是	当前钥匙开通的设备类型，如手机：Phone，穿戴：Wear
keyHolderType	钥匙持有者性质	/	是	当前钥匙持有者的性质，如车主：Owner，分享：Share
vehicleId	由车厂定义	/	是	车辆vin码，不超过20个字节
personalizedData	由车厂定义	/	否	车厂个性化数据，可用于储存车辆标定数据等
logo	https://开头的图片链接，具体地址车厂自定义	/	否	卡面logo；128*128px，大小<=20kb，直角图片，无需切圆角如果此处携带该参数，则会覆盖对应模板中的相应字段数据。
backgroundImage	https://开头的图片链接，具体地址车厂自定义	/	否	卡面背景；1312*820px，直角图片，无需切圆角如果此处携带该参数，则会覆盖对应模板中的相应字段数据。
picUrl	https://开头的图片链接，具体地址车厂自定义	/	否	带logo的卡面背景；1312*820px，直角图片，无需切圆角如果此处携带该参数，则会覆盖对应模板中的相应字段数据。
merchantName	车厂定义	卡面主标题	否	卡面主标题；小于256字节如果此处携带该参数，则会覆盖对应模板中的相应字段数据。
name	车厂定义	卡面副标题	否	卡面副标题；小于256字节如果此处携带该参数，则会覆盖对应模板中的相应字段数据。

timeList参数说明：

展开

key	value	是否必须
linkDevicePassExpireTime	自定义	是

LinkDevicePass参数说明：

展开

参数	是否必选	参数类型	描述
webServiceURL	是	String	DK业务管理服务地址，用于“开通激活“过程中向DK业务管理服务发起设备认证、获取个人化token以及获取个人化数据
token	是	String	DK业务管理服务自行生成，没有格式要求，用于"开通激活"过程中钱包向DK业务管理服务进行“设备认证”和“获取个人化数据Token”请求头中携带的Authorization信息
serialNumber	是	String	请和上述提及的serialNumber保持一致
passVersion	否	String	DevicePass卡券包版本，固定10.0
spPublickey	是	String	开发者在AGC网站提供的公钥。用于对DK业务管理服务返回的“Applet个人化数据”进行验签。NFC卡片信息不会上传到钱包云服务器，所以终端设备需要这个参数来进行验签。
nfcType	是	String	固定值"1"，表示开启NFC能力。如果这个值不是"1"，当前个人化实例的NFC能力会被关闭。

返回值：

返回结果中会携带预置模板中的信息一并返回。

{
  "passVersion": "10.0",
  "organizationName": "Replace with your organization name",
  "passTypeIdentifier": "Replace with the Service ID you applied on AGC",
  "passStyleIdentifier": "DigitalCarKeyTestModel",
  "organizationPassId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "serialNumber": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "fields": {
    "timeList": [
      {
        "value": "timeListValue",
        "key": "linkDevicePassExpireTime"
      }
    ],
	"appendFields": [
	  {
		"label": "NFCCardFlag",
		"value": "true",
		"key": "isCreateWhiteCard"
	  }
	],
    "status": {
      "state": "active",
      "effectTime": "2020-04-06T00:00:00.111Z",
      "expireTime": "2030-04-06T00:00:00.111Z"
    },
    "commonFields": [
	  {
        "label": "卡面主标题",
        "value": "我的车",
        "key": "merchantName"
      },
      {
        "label": "卡面副标题",
        "value": "XXX车钥匙",
        "key": "name"
      },
      {
        "value": "https://xxx/xxx.png",
        "key": "logo"
      },
      {
        "value": "https://xxx/xxx.webp",
        "key": "backgroundImage"
      },
      {
        "value": "https://xxx/xxx.png",
        "key": "picUrl"
      },
      {
        "value": "xxx.CarActivity",
        "key": "bleTargetActivity"
      },
      {
        "value": "hwpass.carkey.ble",
        "key": "bleFeature"
      },
      {
        "value": "01:23:45:67:89:AB",
        "key": "bleMacAddress"
      },
      {
        "label": "readerId",
        "value": "CAD34B258391C097",
        "key": "readerMatchValue"
      },
      {
        "label": "主卡服务号",
        "value": "hwpass.stdcarkey.std",
        "key": "ownerPassTypeIdentifier"
      },
      {
        "value": "0000xxxx-0000-1000-8000-00805f9b34fb",
        "key": "bleServiceUuid"
      },
      {
        "value": "xxx",
        "key": "bleTargetPackage"
      },
      {
        "value": "xxx",
        "key": "bleTargetService"
      }
    ]
  },
  "linkDevicePass": {
    "webServiceURL": "https://xxx",
    "nfcType": "1",
    "serialNumber": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "passVersion": "10.0",
    "spPublickey": "xxx",
    "token": "xxx"
  }
}

错误码：
见错误码。
示例代码：
StdCarKeyInstanceTest#addStdCarKeyInstance()

2.生成JWE数据

华为钱包车钥匙卡片的开通是基于JWE方式。因此DK业务管理服务向钱包云服务申请创建车钥匙成功后，基于创建成功的车钥匙serialNumber生成JWE数据，并将其返回给车厂app，如下所示：

JWE串包含JWE Encrypted Key，iv，Ciphertext，signature；可参见如下步骤：

生成一个随机的Content Encryption Key（CEK）。
使用RSAES-OAEP 加密算法，用钱包服务器给的公钥加密CEK，生成JWE Encrypted Key。 ·
生成JWE初始化向量。 ·
使用AES GCM加密算法对明文部分进行加密生成密文Ciphertext,算法会随之生成一128位的认证标记 Authentication Tag。对以上部分分别进行base64编码。
Signature 是使用 AGC上创建卡片服务生成的私钥对以上部分进行的签名。

示例代码：
JweTest#generateThinJWEToBindUser()

添加ICCE车钥匙

车主APP获取到DK业务管理服务生成的JWE数据，通过Schema方式将JWE数据透传给华为钱包APP。

Schema：
wallet://com.huawei.wallet/walletkit/consumer/pass/save?content={jwe_content}

说明
此处的{}表示引用，请求时无需携带{}。

建议：调用此接口前，先检查华为钱包的应用签名和包名
数据流向：
车主APP->华为钱包

示例代码：

String url = "wallet://com.huawei.wallet/walletkit/consumer/pass/save?content=jwe_content";
Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(url));
intent.setFlags(FLAG_ACTIVITY_BROUGHT_TO_FRONT|FLAG_ACTIVITY_NEW_TASK);
intent.setPackage("com.huawei.wallet"); // 此处需要指定华为钱包应用包名；若不指定，理论上存在请求被劫持的风险
startActivity(intent);

开通激活

拉起华为钱包车钥匙开通页面后，用户点击“立即开通”后，华为钱包会向DK业务管理服务进行钥匙的开通和激活，其中需要和DK业务管理服务进行交互的包括：设备的认证（和车钥匙管理台交换证书信息）、获取请求个人化数据时的token（用于向车钥匙管理台请求Applet个人化数据）、以及最后的请求Applet个人化数据。

设备认证

预个人化执行完成后，华为钱包APP经由钱包云服务中转后请求认证设备，将applet身份公钥以及身份公钥的钱包服务器签名携带在请求体中，向DK业务管理服务请求DK业务管理服务认证授权证书。

数据流向：
钱包云服务->DK业务管理服务
环境URL：
https://{webServiceURL}/v1/passes/registrations

说明
webServiceURL为DK业务管理服务域名。
请求方式：
POST

请求头：

展开

参数名称	是否必选	参数类型	描述
Content-Type	是	String	固定值："application/json;charset=utf-8"。
Authorization	是	String	请求头中携带的token，用于校验该请求是否合法。

请求体：

{
    "requestBody": {
	"passTypeIdentifier": "Replace with the Service ID you applied on AGC",
	"passVersion": "10.0",
	"serialNumber": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
	"transId": "16198381994485116358",
	"userDeviceId": "xxx"
    },
    "certificate": {
	"publicKey": "xxx",
	"signature": "xxx"
    },
    "signature": "xxx"
}

展开

父节点参数	子节点参数	类型	是否可选	描述
requestBody	passTypeIdentifier	String	必选	请使用在AGC平台上注册的服务号，需要开发者到华为AGC网站申请。
	serialNumber	String	必选	车钥匙卡片在华为钱包云服务器中的卡号，回调时以便发卡方根据此值识别具体的卡券记录。
	passVersion	String	可选	版本号，固定10.0。
	userDeviceId	String	必选	用户在当前设备上的唯一标识。
	transId	String	必选	随机数。
signature	-	String	必选	Applet的身份私钥对requestBody的Hash值的签名。
certificate	signature	String	必选	钱包云服务使用钱包服务器私钥对publicKey的签名值。DK业务管理服务收到该请求后，需要使用钱包云服务公钥对其进行验签。
	publicKey	String	必选	Applet的身份公钥。
	type	String	可选	类型，默认为私钥签名方式。

返回值：

{
    "httpStatus": "0",
    "response": {
        "certificate": {
            "signature": "xxx",
            "publicKey": "xxx"
        }
    }
}

展开

父节点参数	子节点参数	类型	是否可选	描述
Httpstatus	-	String	必选	接口网络状态码。
response	certificate	Certificate	可选	DK业务管理服务使用在AGC平台上注册的公钥相对应的私钥对publicKey进行签名后返回。

示例代码：
PassesController#register(HttpServletRequest res, @RequestBody RegistrationsRequest request)

获取个人化数据Token

华为钱包APP经由钱包云服务中转后向DK业务管理服务平台获取token(个人化数据请求报文里参与计算hash)。

数据流向：
钱包云服务->DK业务管理服务。
环境URL：
https://{webServiceURL}/v1/passes/requestPersonalizeToken
请求方式：
POST

请求头：

展开

参数名称	是否必选	参数类型	描述
Content-Type	是	String	固定值："application/json;charset=utf-8"。
Authorization	是	String	请求头中携带的token，用于校验该请求是否合法。

请求体：

{
    "requestBody": {
        "passTypeIdentifier": "Replace with the Service ID you applied on AGC",
        "passVersion": "10.0",
        "serialNumber": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "transId": "16198386115793732834",
        "userDeviceId": "xxx"
    },
    "certificate": {
        "publicKey": "xxx",
        "signature": "xxx"
    },
    "signature": "xxx"
}

展开

父节点参数	子节点参数	类型	是否可选	描述
requestbody	passTypeIdentifier	String	必选	请使用在AGC平台上注册的服务号，需要开发者到华为AGC网站申请。
	serialNumber	String	必选	车钥匙卡片在华为钱包云服务器中的卡号，回调时以便发卡方根据此值识别具体的卡券记录。
	passVersion	String	可选	版本号，固定10.0。
	userDeviceId	String	必选	用户在当前设备上的唯一标识。
	transId	String	必选	随机数。
signature	-	String	必选	Applet的身份私钥对requestbody的Hash值的签名。
certificate	-	Certificate	必选	Applet证书，车钥匙管理台在registrations接口返回的certificate。

Certificate格式如下：

展开

父节点参数	子节点参数	类型	是否可选	描述
certificate	signature	String	必选	DK业务管理服务使用在AGC平台上注册的公钥相对应的私钥对Applet的身份公钥签名信息。
publicKey	String	可选	Applet的身份公钥。
type	String	可选	类型，默认为私钥签名方式。

父节点参数

子节点参数

类型

是否可选

描述

certificate

signature

String

必选

DK业务管理服务使用在AGC平台上注册的公钥相对应的私钥对Applet的身份公钥签名信息。

publicKey

String

可选

Applet的身份公钥。

type

String

可选

类型，默认为私钥签名方式。

返回值：
```
{
    "httpStatus": "0",
    "response": {
        "token": "sp.token.1619838979341"
    }
}
```
展开
父节点参数

子节点参数

类型

是否可选

描述

Httpstatus

-

int

必选

接口网络状态码。

response

token

String

必选

个人化token。
示例代码：
PassesController#requestToken(@RequestBody RequestTokenRequest request)

父节点参数	子节点参数	类型	是否可选	描述
Httpstatus	-	int	必选	接口网络状态码。
response	token	String	必选	个人化token。

获取个人化数据

华为钱包APP经由钱包云服务中转后向DK业务管理服务获取个人化数据。

数据流向：
钱包云服务->DK业务管理服务。
环境URL：
{webServiceURL}/v1/passes/requestPersonalize
请求方式：
POST

请求头：

展开

参数名称	是否必选	参数类型	描述
Content-Type	是	String	固定值："application/json;charset=utf-8"。
Authorization	是	String	请求头中携带的token，用于校验该请求是否合法。

请求体：

{
    "requestBody": {
        "cardSEId": "xxxxxxxxxxxxxxxx",
        "personalizeCert": "xxx",
        "personalizeCertType": "",
        "personalizePublicKey": "xxx",
        "transPublicKey": "xxx",
        "passTypeIdentifier": "Replace with the Service ID you applied on AGC",
        "passVersion": "10.0",
        "serialNumber": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "transId": "858947076d58a5e66ee22b9ed1c43c4d",
        "userDeviceId": "xxx"
    },
    "certificate": {
        "publicKey": "xxx",
        "signature": "xxx"
    },
    "signature": "xxx"
}

展开

父节点参数	子节点参数	类型	是否可选	描述
requestbody	cardSEId	String	必选	Applet唯一标识，可以用于车端秘钥分散
	passTypeIdentifier	String	必选	请使用在AGC平台上注册的服务号，需要开发者到华为AGC网站申请。
	serialNumber	String	必选	车钥匙卡片在华为钱包云服务器中的卡号，回调时以便发卡方根据此值识别具体的卡券记录。
	passVersion	String	可选	版本号，固定10.0。
	userDeviceId	String	必选	用户在当前设备上的唯一标识。
	personalizePublicKey	String	必选	Applet的个人化公钥，用于加密个人化字段值。
	personalizeCert	String	必选	Applet身份私钥对个人化公钥personalizePublicKey的签名。
	personalizeCertType	String	必选	固定值，默认为私钥签名。
	transPublicKey	String	必选	用于加密返回的对称秘钥，用于对返回的数据做数字信封。
	transId	String	必选	事务流水，用于拼接返回的对称秘钥后进行加密。
signature	-	String	必选	Applet的身份私钥对requestBody的Hash值的签名。申请到的个人化token作为其中requestbody一个key参与Hash值计算。
certificate	-	Certificate	必选	Applet证书，DK业务管理服务签发。

Certificate定义：

展开

父节点参数	子节点参数	类型	是否可选	描述
certificate	signature	String	必选	DK业务管理服务对publicKey的签名值。
publicKey	String	可选	Applet的身份公钥。
type	String	可选	类型，默认为私钥签名方式。

父节点参数

子节点参数

类型

是否可选

描述

certificate

signature

String

必选

DK业务管理服务对publicKey的签名值。

publicKey

String

可选

Applet的身份公钥。

type

String

可选

类型，默认为私钥签名方式。

返回值：

{
    "httpStatus": "0",
    "response": {
        "encryptDevicePass": "xxx",
        "encryptAppletPersonalizeFields": "xxx",
        "encryptSessionKey": "xxx"
    },
    "signature": "xxx"
}

展开

父节点参数	子节点参数	类型	是否可选	描述
Httpstatus	-	String	必选	接口网络状态码。
response	encryptSessionKey	String	必选	DK业务管理服务使用请求中的transPublicKey加密生成的sessionKey。采用Base64编码
	encryptDevicePass	String	可选	空字符串""
	encryptAppletPersonalizeFields	String	必选	用于蓝牙/NFC刷卡时的认证以及数据加解密操作。DK业务管理服务通过生成的sessionKey加密Applet的个人化参数密文。采用Base64编码
signature	-	String	必选	使用DK业务管理服务的私钥对response的Hash值进行签名。说明私钥请和“生成钥匙卡片”过程中下发的linkDevicePass节点中的spPublicKey保持一对

encryptSessionKey加密前的字段说明：

展开

类型	是否可选	描述
String	必选	三方生成 AES128 的 aesKey 和 aesIv，用于加密生成 encryptAppletPersonalizeFields 和 encryptDevicePass。使用请求中transPublicKey字段加密transId+aesKey+aesIv，对结果进行base64编码即得到encryptSessionKey。加密算法: RSA/ECB/OAEPWithSHA-256AndMGF1Padding。

encryptAppletPersonalizeFields各个字段说明如下：

展开

子节点参数	类型	是否可选	存储格式	描述
temp_key	String	必选	-	aesKey(AES128的key)，长度16字节，用于加密CardId，cardPrivateInfo信息。temp_key：aesKey明文之前拼接一个固定的十六进制字符前缀”34810233”后，使用Applet个人化公钥appletPublicKey对其进行加密。加密算法RSA/NONE/OAEPWithSHA1AndMGF1Padding。
temp_iv	String	必选	-	aesIv(AES128的iv)，长度16字节，用于applet解密写卡数据。temp_iv：aesIv使用Applet个人化公钥appletPublicKey加密。加密算法RSA/NONE/OAEPWithSHA1AndMGF1Padding。
card_id	String	必选	9F3B + Lc + CardId	CardId即发卡方发放的卡片唯一标志（和"生成钥匙卡片"中的serialNumber保持一致），长度16字节。使用TLV格式存储：T=9F3B，Lc=10，V=CardId；加密方式：使用aesKey，aesIv对整个TLV加密，并转换成十六进制字符串。CBC模式加密，加密算法：AES/CBC/NoPadding。
card_key	String	必选	-	发卡方发放的卡片密钥，16字节，一张卡支持1个秘钥，计算SessionKey时使用。使用”34010133”作为前缀拼接后加密；使用Applet个人化公钥appletPublicKey对拼接后的十六进制字符进行加密。加密算法RSA/NONE/OAEPWithSHA1AndMGF1Padding。
card_info	String	必选	9F05 + Lc + CardInfo1 + 9F31 + Lc + CardAuthParameter	发卡方发放的卡片私有信息，允许在AUTH认证之前读取（GetProcessData步骤），TLV格式存储（多个TLV数据拼接）。加密方式：TLV明文数据补800...00到16字节整数倍，使用aesKey，aesIv加密后的结果，并转换成十六进制字符串。CBC模式加密，加密算法：AES/CBC/NoPadding。
card_privateInfo	String	必选	-	发卡方发放的卡片私有信息，如卡片有效期、权限等信息，在AUTH认证之后读取（ReadBinary步骤），三方自行解析。加密方式：数据明文后补800...00到16字节整数倍，使用aesKey，aesIv加密后的结果，并转换成十六进制字符串。CBC模式加密，加密算法：AES/CBC/NoPadding。
card_key_iv	String	必选	Lc + CardKeyIV	交易流程协商的SessionKey使用（需要同步下发到车端），16字节，如您无需使用此值，请传入全0。

示例代码：
PassesController#getPersonalInfo(HttpServletRequest res, @RequestBody PersonalizeRequest request)

说明
示例代码中的样例数据请根据自身业务填入真实的值。

卡片更新

DK业务管理服务更新通知信息（同一实例下的个人化数据）到钱包云服务器，再由钱包云服务器推送给钱包APP。

点击放大

数据流向：
DK业务管理服务->钱包云服务->华为钱包 APP。

环境URL：

https://wallet-passentrust-drcn.cloud.huawei.com.cn/hmspass/v2/{cardType}/instance/{instanceId}

展开

参数	是否必选	参数类型	描述
cardType	是	String	开发者根据卡券类型自行选择，请参见当前支持的其他卡券类型。在车钥匙场景中，该值为key_stdcar
instanceId	是	String	个人化实例的唯一标识符。这个ID在同一个appId下唯一。这个ID只能包含字母、数字和（.）、（-）、（_）。在该场景中，该值对应为卡券的serialNumber

请求方式：
PUT：全量更新；PATCH：局部更新。

请求头：

展开

参数	是否必选	参数类型	描述
Authorization	是	String	将获取到的“access_token”的值拼接在字符串“Bearer”之后，以空格符相隔，组成“Authorization”参数的值。参考获取AccessToken
Content-Type	是	String	固定值："application/json;charset=utf-8"。
Accept	是	String	固定值："application/json;charset=utf-8"。

请求体：

{
  "organizationName": "Replace with your organization name",
  "passTypeIdentifier": "Replace with the Service ID you applied on AGC",
  "passStyleIdentifier": "DigitalCarKeyTestModel2",
  "organizationPassId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "serialNumber": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "fields": {
    "timeList": [
      {
        "value": "timeListValue",
        "key": "linkDevicePassExpireTime"
      }
    ],
    "status": {
      "state": "active",
      "effectTime": "2020-04-06T00:00:00.111Z",
      "expireTime": "2040-04-06T00:00:00.111Z"
    },
    "commonFields": [
      {
        "value": "xxx.CarKeyActivity",
        "key": "bleTargetActivity"
      },
      {
        "value": "hwpass.carkey.ble",
        "key": "bleFeature"
      },
      {
        "value": "01:23:45:67:89:AB",
        "key": "bleMacAddress"
      },
      {
        "label": "readerId",
        "value": "CAD34B258391C097",
        "key": "readerMatchValue"
      },
      {
        "label": "主卡服务号",
        "value": "hwpass.stdcarkey.std",
        "key": "ownerPassTypeIdentifier"
      },
      {
        "value": "0000xxxx-0000-1000-8000-00805f9b34fb",
        "key": "bleServiceUuid"
      },
      {
        "value": "xxx",
        "key": "bleTargetPackage"
      },
      {
        "value": "xxx",
        "key": "bleTargetService"
      }
    ]
  },
  "linkDevicePass": {
    "webServiceURL": "https://xxx",
    "nfcType": "1",
    "serialNumber": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "passVersion": "10.0",
    "spPublickey": "xxx",
    "token": "xxx"
  }
}

返回值：
错误码为200时，返回更新的卡券实例。

展开
参数

参数类型

描述

详见HwWalletObject参数描述

HwWalletObject

已更新的卡券实例
错误码：
见错误码
示例代码：
全量更新StdCarKeyInstanceTest#fullUpdateStdCarKeyInstance()

局部更新StdCarKeyInstanceTest#partialUpdateStdCarKeyInstance()

参数	参数类型	描述
详见HwWalletObject参数描述	HwWalletObject	已更新的卡券实例

卡片删除

华为钱包ICCE车钥匙提供了两个删除入口，第一个是用户从华为钱包的车钥匙详情页删除，另一个是DK业务管理服务通过云侧接口进行车钥匙的删除。

华为钱包删卡

当用户从华为钱包的车钥匙详情页点击删除卡片时，会触发卡片删除的流程

点击放大

数据流向：
钱包云服务->DK业务管理服务。
环境URL：
开发者在华为AGC网站上提供的NFC回调地址。
请求方式：
POST

请求头：

展开

参数	是否必选	参数类型	描述
Content-Type	是	String	固定值："application/json;charset=utf-8"。
Accept	是	String	固定值："application/json;charset=utf-8"。
HMSSignType	是	String	签名方式。值为固定值："SHA256WithRSA/PSS"。
HMSSign	是	String	签名值
Version	是	String	回调接口版本号。为固定值“V2”。

请求体：

{
    "eventId": "856979810852124160",
    "passTypeIdentifier": "hwpass.stdcarkey.bluecarkey.xxxx",
    "passNumber": "***32",
    "eventTime": "2022-03-28T01:45:53.695Z",
    "eventType": "RECEIVE_CARD",
    "pushToken": "***43",
    "sceneType": "",
    "noticeToken": "***64"
}

展开

参数	是否必选	参数类型	描述
eventId	是	String(32)	事件ID。若钱包服务器多次重试发送回调通知，开发者服务器可以用此参数去重。
passTypeIdentifier	是	String(64)	卡券对应的服务号。
passNumber	是	String(32)	卡券号，即“serialNumber”。说明：中国大陆卡券包方式生成的卡券，此参数为“organizationPassId”。
eventTime	是	String(32)	事件发生时间（UTC时间）："yyyy-MM-dd'T'HH:mm:ss:SSS'Z'"
eventType	是	String(32)	事件类型： “RECEIVE_CARD”：用户在华为钱包App中领取卡券。 “DELETE_CARD”：用户在华为钱包App中删除卡券。
pushToken	否	String(64)	帐号及设备关联的唯一标识。
sceneType	否	String(32)	场景类型： “USER_OPERATION_DELETE_CARD”：用户在华为钱包APP里删卡，或用户在华为钱包App退出华为帐号触发删卡。 “RESTORE_FACTORY_SETTINGS”：用户恢复手机出厂设置触发删卡。 “REMOTE_DELETE_CARD”：华为服务器删卡，如用户挂失场景。 “THIRD_PARTY_DELETE_CARD ”：开发者删卡。
noticeToken	否	String(64)	NFC事件对应的标识，用于调用用户使用NFC能力后推送消息接口。此标识有效时间为3分钟。

返回值：
```
{
    "returnCode": "0",
    "returnDesc": "success"
}
```
展开
参数

参数类型

描述

returnCode

String

响应码，详见回调接口公共定义中的公共响应码。

returnDesc

String

错误描述

参数	参数类型	描述
returnCode	String	响应码，详见回调接口公共定义中的公共响应码。
returnDesc	String	错误描述

错误码：

展开

错误码	描述	说明
0	成功	-
1	参数错误	进一步的信息可以查看响应中的返回描述。
2	签名错误	-
3	内部错误，一般是无具体原因的错误，比如异常。	加解密失败、数据缺失、各种无具体原因的处理异常等。
6	外部依赖错误	服务器所依赖的其他系统出错，或者其返回不符合预期。

示例代码：

String priKey = "xxx";

Map<String, String> header = new HashMap<>(8);
header.put("Content-Type", "application/json;charset=UTF-8");
header.put("Accept", "application/json;charset=UTF-8");
header.put("HMSSignType", "SHA256WithRSA");
header.put("Version", "V2");
// 验签时请使用[hms-wallet-severdemo]-SignatureTest.java中的固定公钥
String hmsSign = RSAUtils.signByRSA(ToStringUtil.signString(requestBody), priKey);
header.put("HMSSign", hmsSign);

CallbackRequest deleteBody = null; // 此处会填写真实的待删除卡券数据
HttpEntity<CallbackRequest> httpEntity = new HttpEntity(deleteBody, header);
// callBackUrl为车厂在华为AGC平台上注册的回调地址
// BaseResponse为公共响应数据结构体
BaseResponse response =  restful.postForObject(callbackUrl, httpEntity, BaseResponse.class);

车钥匙管理台删卡

DK业务管理服务可通过华为钱包云服务接口，触发车钥匙的删除；该部分复用卡券局部更新接口。

数据流向：
DK业务管理服务->钱包云服务->华为钱包 APP。

环境URL：

https://wallet-passentrust-drcn.cloud.huawei.com.cn/hmspass/v2/{cardType}/instance/{instanceId}

展开

参数	是否必选	参数类型	描述
cardType	是	String	开发者根据卡券类型自行选择，请参见当前支持的其他卡券类型。在车钥匙场景中，该值为key_stdcar
instanceId	是	String	个人化实例的唯一标识符。这个ID在同一个appId下唯一。这个ID只能包含字母、数字和（.）、（-）、（_）。在该场景中，该值对应为卡券的serialNumber

请求方式：
PATCH。

请求头：

展开

参数	是否必选	参数类型	描述
Authorization	是	String	将获取到的“access_token”的值拼接在字符串“Bearer”之后，以空格符相隔，组成“Authorization”参数的值。参考“获取AccessToken”
Content-Type	是	String	固定值："application/json;charset=utf-8"。
Accept	是	String	固定值："application/json;charset=utf-8"。

请求体：

{
  "fields": {
    "status": {
      "state": "expired"
    }
  }
}

返回值：
错误码为200时，返回更新的卡券实例。

参数

参数类型

描述

详见HwWalletObject参数描述

HwWalletObject

已更新的卡券实例
错误码：
见错误码。
示例代码：
StdCarKeyInstanceTest#partialUpdateStdCarKeyInstance()

卡片冻结、解冻

DK业务管理服务可通过华为钱包云服务接口，触发车钥匙的冻结和解冻；该部分复用卡券局部更新接口。

数据流向：
DK业务管理服务->钱包云服务->华为钱包 APP。

环境URL：

https://wallet-passentrust-drcn.cloud.huawei.com.cn/hmspass/v2/{cardType}/instance/{instanceId}

展开

参数	是否必选	参数类型	描述
cardType	是	String	开发者根据卡券类型自行选择，请参见当前支持的其他卡券类型。在车钥匙场景中，该值为key_stdcar
instanceId	是	String	个人化实例的唯一标识符。这个ID在同一个appId下唯一。这个ID只能包含字母、数字和（.）、（-）、（_）。在该场景中，该值对应为卡券的serialNumber

请求方式：
PATCH

请求头：

展开

参数	是否必选	参数类型	描述
Authorization	是	String	将获取到的“access_token”的值拼接在字符串“Bearer”之后，以空格符相隔，组成“Authorization”参数的值。参考获取AccessToken
Content-Type	是	String	固定值："application/json;charset=utf-8"。
Accept	是	String	固定值："application/json;charset=utf-8"。

请求体：

1）冻结

{
  "fields": {
    "status": {
      "state": "freeze"
    }
  }
}

2）解冻

{
  "fields": {
    "status": {
      "state": "active",
      "effectTime": "2020-04-06T00:00:00Z",
      "expireTime": "2040-04-06T00:00:00Z"
    }
  }
}

展开

参数	参数类型	描述
state	String	freeze：冻结、active：解冻

返回值：
错误码为200时，返回更新的卡券实例。

参数

参数类型

描述

详见HwWalletObject参数描述

HwWalletObject

已更新的卡券实例
错误码：
见错误码
示例代码：
StdCarKeyInstanceTest#partialUpdateStdCarKeyInstance()

车厂自由业务云云对接接口

点击放大

数据流向：
钱包云服务->DK业务管理服务。
环境URL：
开发者在华为钱包管理台网站上提供的回调地址
请求方式：
POST

请求头：

展开

参数	是否必选	参数类型	描述
Content-Type	是	String	固定值：“application/json”。
Charset	是	String	固定值：“UTF-8”。
Accept-Encoding	是	String	固定值：identity

请求体：

{
    "requestBody": {
	"passTypeIdentifier": "Replace with the Service ID you applied on AGC",
	"serialNumber": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
	"payload": "10101"
    },
    "signature": "xxx"
}

展开

父节点参数	子节点参数	类型	是否可选	描述
requestBody	passTypeIdentifier	String	否	AGC平台上申请的服务号。
	serialNumber	String	否	Pass对象在发卡方的唯一键值，回调时以便发卡方根据此值识别具体的卡券记录。
	payload	String	否	车端请求报文中的整个body部分，如03040102xxxx。
signature	-	String	否	钱包服务器使用signByRSAWithPSS方式对请求体的签名。

返回值：
```
{
    "httpStatus": "0",
    "response": {
	"payload": "xxx"
    }
}
```
展开
父节点参数

子节点参数

类型

是否可选

描述

Httpstatus

-

String

否

接口网络状态码。

response

payload

String

否

SP验证请求后，返回的数据。

父节点参数	子节点参数	类型	是否可选	描述
Httpstatus	-	String	否	接口网络状态码。
response	payload	String	否	SP验证请求后，返回的数据。

开卡结果通知

云侧接口

华为钱包云会将车钥匙的开通结果，通过车厂在AGC平台配置的NFC回调地址通知到DK业务管理服务，DK业务管理服务收到该回调后进行后续的处理。

数据流向：
钱包云服务->DK业务管理服务。

环境URL：
开发者在华为AGC网站上提供的回调地址，见配置NFC参数。
请求方式：
POST

请求头：

展开

参数	是否必选	参数类型	描述
Content-Type	是	String	固定值："application/json;charset=utf-8"。
Accept	是	String	固定值："application/json;charset=utf-8"。
HMSSignType	是	String	签名方式。值为固定值："SHA256WithRSA/PSS"。
HMSSign	是	String	钱包云服务使用私钥对请求体进行签名后的值；DK业务管理服务使用钱包云服务的公钥验签
Version	是	String	回调接口版本号。为固定值“V2”。

请求体：

{
    "eventId": "856979810852124160",
    "passTypeIdentifier": "hwpass.stdcarkey.bluecarkey.xxxx",
    "passNumber": "***32",
    "eventTime": "2022-03-28T01:45:53.695Z",
    "eventType": "RECEIVE_CARD",
    "pushToken": "***43",
    "sceneType": "",
    "noticeToken": "***64"
}

展开

参数	是否必选	参数类型	描述
eventId	是	String(32)	事件ID。若钱包服务器多次重试发送回调通知，开发者服务器可以用此参数去重。
passTypeIdentifier	是	String(64)	卡券对应的服务号。
passNumber	是	String(32)	卡券号，即“serialNumber”。说明：中国大陆卡券包方式生成的卡券，此参数为“organizationPassId”。
eventTime	是	String(32)	事件发生时间（UTC时间）："yyyy-MM-dd'T'HH:mm:ss:SSS'Z'"
eventType	是	String(32)	事件类型： “RECEIVE_CARD”：用户在华为钱包App中领取卡券。 “DELETE_CARD”：用户在华为钱包App中删除卡券。 “USER_CANCEL_BIND_CARD”：用户取消绑定卡片（钱包开卡预览页点击“取消”）
pushToken	否	String(64)	帐号及设备关联的唯一标识。
sceneType	否	String(32)	场景类型： “USER_OPERATION_DELETE_CARD”：用户在华为钱包App里删卡，或用户在华为钱包App退出华为帐号触发删卡。 “RESTORE_FACTORY_SETTINGS”：用户恢复手机出厂设置触发删卡。 “REMOTE_DELETE_CARD”：华为服务器删卡，如用户挂失场景；用户本机删除。 “THIRD_PARTY_DELETE_CARD ”：开发者删卡。
noticeToken	否	String(64)	NFC事件对应的标识，用于调用用户使用NFC能力后推送消息接口。此标识有效时间为3分钟。

返回值：
```
{
    "returnCode": "0",
    "returnDesc": "success"
}
```
展开
参数

参数类型

描述

returnCode

String

响应码，详见回调接口公共定义中的公共响应码。

returnDesc

String

错误描述

参数	参数类型	描述
returnCode	String	响应码，详见回调接口公共定义中的公共响应码。
returnDesc	String	错误描述

错误码：

展开

错误码	描述	说明
0	成功	-
1	参数错误	进一步的信息可以查看响应中的返回描述。
2	签名错误	-
3	内部错误，一般是无具体原因的错误，比如异常。	加解密失败、数据缺失、各种无具体原因的处理异常等。
4	外部依赖错误	服务器所依赖的其他系统出错，或者其返回不符合预期。

示例代码：

String priKey = "xxx";

Map<String, String> header = new HashMap<>(8);
header.put("Content-Type", "application/json;charset=UTF-8");
header.put("Accept", "application/json;charset=UTF-8");
header.put("HMSSignType", "SHA256WithRSA");
header.put("Version", "V2");
String hmsSign = RSAUtils.signByRSA(ToStringUtil.signString(requestBody), priKey);
header.put("HMSSign", hmsSign);

CallbackRequest body = null; // 此处会填写真实的待通知的请求数据
HttpEntity<CallbackRequest> httpEntity = new HttpEntity(body, header);
// callBackUrl为车厂在华为AGC平台上注册的NFC回调地址
// BaseResponse为公共响应数据结构体
BaseResponse response =  restful.postForObject(callbackUrl, httpEntity, BaseResponse.class);

端侧接口

端侧卡片状态发生变更后，支持发送端侧广播，车厂App可以通过监听广播获取状态；华为钱包APP发送全局的普通广播，车厂APP动态注册广播，指定接收广播的车厂APP。

数据流向：
华为钱包APP->车主APP

参数：

展开

key

类型

参数值

eventType

String(32)

“RECEIVE_CARD”：领取车钥匙卡片；

“DELETE_CARD”：用户在华为钱包App中删除卡券。

“USER_CANCEL_BIND_CARD”：用户取消绑定卡片（钱包开卡预览页点击“取消”）

eventResult

int

领卡的结果值：0-领卡成功，1-内部参数错误，10-其他错误，0xffffffff-初始化安全芯片失败

passNumber

String(32)

卡号

示例代码：

创建华为钱包ICCE车钥匙事件广播监听类

public class NotifyICCECarKeyEventTypeReceiver extends BroadcastReceiver {
    @Override
    public void onReceive(Context context, Intent intent) {
        if (intent == null) {
            return;
        }
        String passNumber = intent.getStringExtra(BleProcedureConstants.KEY_PASS_NUMBER);
        String eventType = intent.getStringExtra(BleProcedureConstants.KEY_EVENT_TYPE);
        int eventResult = intent.getIntExtra(BleProcedureConstants.KEY_EVENT_RESULT, -1);

        // do your task
    }
}

动态注册广播接收

NotifyICCECarKeyEventTypeReceiver receiver = new NotifyICCECarKeyEventTypeReceiver();
IntentFilter filter = new IntentFilter();
filter.addAction(BleProcedureConstants.BLE_CAR_KEY_EVENT_NOTIFY);
registerReceiver(receiver, filter);

意见反馈

以上内容对您是否有帮助？

意见反馈

如果您有其他疑问，您也可以通过开发者社区问答频道来和我们联系探讨。

社区提问智能客服提问