活动/景点门票接口

预置模板

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

开发者可创建多个共享相同机构名和服务号但模板ID不同的模板。在申请门票时，每张卡必须绑定唯一的模板ID，即一个模板可被多张门票复用，而一张门票仅能关联一个模板ID。

接口原型

• 承载协议：HTTPS POST

• 接口方向：开发者业务管理服务->钱包云服务

• 接口URL：https://wallet-passentrust-drcn.cloud.huawei.com.cn/hmspass/v2/{cardType}/model

• 数据格式：

  请求消息：Content-Type: application/json;charset=UTF-8

  响应消息：Content-Type: application/json;charset=UTF-8

请求参数

Request Header

Request Body

请求示例

POST /hmspass/v2/key_ticket/model HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer bKyECwrVGw********************e
Accept: application/json;charset=UTF-8
{
  "passVersion": "10.0",
  "passTypeIdentifier": "hwpass.xxx.xxx.xxx",
  "passStyleIdentifier": "keyTicketModelTest",
  "organizationName": "xxx",
  "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"
      }
    ]
  }
}

响应参数

模板预置成功，即http响应为200时，钱包云服务会将开发者业务管理服务请求的数据原样返回，即和请求体中的数据一致；其他错误情况，可见REST API错误码。

调用示例

public HwWalletObject invokeHwCreateKeyTicketClass(){
    HwWalletObject request=new HwWalletObject();
    request.setPassVersion("1.0");
    request.setPassTypeIdentifier("hwpass.keyticket.test");
    request.setPassStyleIdentifier("keyTicketModelTest");
    request.setOrganizationName("XXXX");
    Fields fields=new Fields();
    fields.setCountryCode("CN");
    List<ValueObject> commonFields=new ArrayList<>();
    ValueObject logo=new ValueObject();
    logo.setKey("logo");
    logo.setValue("https://www.huawei.com/XXX.png");
    commonFields.add(logo);
    fields.setCommonFields(commonFields);
    request.setFields(fields);
    HttpHeaders header=constructHttpHeaders();
    String baseUrl="https://wallet-passentrust-drcn.cloud.huawei.com.cn/hmspass";
    String walletServerUrl=baseUrl+"/v2/key_ticket/model";
    HttpEntity<JSONObject> entity=new HttpEntity<>(JSONObject.parseObject(JSONObject.toJSONString(request)),header);
    ResponseEntity<JSONObject> exchange = REST_TEMPLATE.exchange(walletServerUrl,HttpMethod.POST,entity,JSONObject.class);
    return JSONObject.parseObject(exchange.getBody().toJSONString(),HwWalletObject.class);
}

申请门票

开发者向开发者服务器申请开通门票，开发者服务器将门票卡片信息添加至钱包云服务中。其中：开发者App->开发者服务之间的交互由开发者自行实现，本章主要侧重于开发者服务器->钱包云服务申请门票的过程，主要包括：申请卡片和生成JWE数据。

接口原型

• 承载协议：HTTPS POST

• 接口方向：开发者业务管理服务->钱包云服务

• 接口URL：https://wallet-passentrust-drcn.cloud.huawei.com.cn/hmspass/v2/{cardType}/instance

• 数据格式：

  请求消息：Content-Type: application/json;charset=UTF-8

  响应消息：Content-Type: application/json;charset=UTF-8

请求参数

Request Header

Request Body

请求示例

POST /hmspass/v2/key_ticket/instance HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer bKyECwrVGw********************e
Accept: application/json;charset=UTF-8
{
  "organizationPassId": "The122",
  "passTypeIdentifier": "hwpass.xxx.xxx",
  "passStyleIdentifier": "TicketModel001",
  "serialNumber": "The122",
  "organizationName": "XX景区",
  "fields": {
    "status": {
      "state": "active",
      "effectTime": "2019-11-11T00:00:00.000Z",
      "expireTime": "2060-12-31T23:59:59.999Z"
    },
    "barCode": {
      "text": "xxx",
      "type": "qrCode",
      "value": "xxx",
      "encoding": "UTF-8"
    },
    "commonFields": [
      {
        "key": "merchantName",
        "value": "XX景区",
        "label": "merchantName"
      },
      {
        "key": "name",
        "value": "XX门票",
        "label": "name"
      },
      {
        "key": "logo",
        "value": "https://xxx/xxx.png",
        "label": "logo"
      },
      {
        "key": "backgroundImage",
        "value": "https://xxx/xxx.webp",
        "label": "backgroundImage"
      },
      {
        "key": "picUrl",
        "value": "https://xxx/xxx.png",
        "label": "picUrl"
      },
      {
        "key": "showQrCodeLink",
        "value": "{\"harmonyNext\":{\"type\":3,\"jumpInfo\":{\"bundleName\":\"com.xxx.xxx\",\"abilityName\":\"MainAbility\",\"action\":\"home\",\"moduleName\":\"entry\",\"parameters\":{\"scene\":\"scene\"}}}}"
      },
      {
        "key": "backgroundColor",
        "value": "#1A73E8",
        "label": "backgroundColor"
      },
      {
        "key": "maskColor",
        "value": "#000000",
        "label": "maskColor"
      },
      {
        "key": "textColor",
        "value": "#FFFFFF",
        "label": "textColor"
      }
    ],
    "appendFields": [
      {
        "key": "isCreateWhiteCard",
        "value": "false",
        "label": "NFCCardFlag"
      },
      {
        "key": "seat",
        "value": "A12",
        "label": "座位"
      },
      {
        "key": "gate",
        "value": "东门",
        "label": "入口"
      }
    ],
    "flexFields": {
      "primaryFields": [
        {
          "key": "ticketNumber",
          "value": "xxx",
          "label": "票号"
        }
      ],
      "secondaryFields": [
        {
          "key": "venueOfPerformance",
          "value": "XX",
          "label": "演出场所"
        }
      ],
      "supplementaryFields": [
        {
          "key": "ticketStatus",
          "value": "有效",
          "label": "门票状态"
        }
      ]
    },
    "localized": [
      {
        "key": "ticketNumberLabel",
        "value": "票号",
        "language": "zh-CN"
      },
      {
        "key": "ticketNumberLabel",
        "value": "Ticket No.",
        "language": "en-US"
      }
    ]
  }
}

响应参数

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

调用示例

完整的调用示例，请参见钱包服务-服务端卡片开通示例代码。

public HwWalletObject invokeHwCreateKeyTicketObject() {
    HwWalletObject request = new HwWalletObject();
    request.setPassTypeIdentifier("hwpass.keyticket.test");
    request.setPassStyleIdentifier("keyTicketModelTest");
    request.setOrganizationPassId("20001");
    request.setSerialNumber("20001");
    Fields fields = new Fields();
    fields.setCountryCode("CN");
    List<ValueObject> commonFields = new ArrayList<>();
    ValueObject seatNumber = new ValueObject();
    seatNumber.setKey("seatNumber");
    seatNumber.setValue("12A");
    commonFields.add(seatNumber);
    fields.setCommonFields(commonFields);
    request.setFields(fields);
    HttpHeaders header = constructHttpHeaders();
    String baseUrl = "https://wallet-passentrust-drcn.cloud.huawei.com.cn/hmspass";
    String walletServerUrl = baseUrl + "/v2/key_ticket/instance";
    HttpEntity<JSONObject> entity = new HttpEntity<>(JSONObject.parseObject(JSONObject.toJSONString(request)), header);
    ResponseEntity<JSONObject> exchange =
        REST_TEMPLATE.exchange(walletServerUrl, HttpMethod.POST, entity, JSONObject.class);
    return JSONObject.parseObject(exchange.getBody().toJSONString(), HwWalletObject.class);
}

生成JWE数据

华为钱包门票卡片的开通是基于JWE（JSON Web Encryption）方式。因此开发者业务管理服务向钱包云服务申请创建门票成功后，基于创建成功的门票serialNumber生成JWE数据，并将其返回给开发者客户端。JWE数据包含JWE Encrypted Key，iv，Ciphertext，signature，可参见如下步骤获取：

1. 生成一个随机的CEK（Content Encryption Key）。

2. 使用RSA-OAEP加密算法，用钱包服务器给的公钥加密CEK，生成JWE Encrypted Key。

3. 生成JWE初始化向量。

4. 使用AES GCM加密算法对明文部分进行加密生成密文Ciphertext，算法会随之生成128位的认证标记Authentication Tag。对以上部分分别进行base64编码。

5. 使用开发者创建Wallet Kit服务生成的私钥对以上部分进行签名从而获取Signature。

完整的调用示例，请参见钱包服务-服务端卡片开通示例代码。

public static String generateJwe(String jwePrivateKey, String payload) {
    Map<String, String> jweHeader = getHeader();
    String jweHeaderEncode = getEncodeHeader(jweHeader);
    String sessionKey = generateSecureRandomFactor(16);
    String sessionKeyPublicKey = "MIIBojA****";
    String encryptedKeyEncode = getEncryptedKey(sessionKey, sessionKeyPublicKey);
    byte[] iv = AesUtil.getIvByte(12);
    String ivHexStr = new String(Hex.encodeHex(iv, false));
    String ivEncode = Base64.encodeBase64URLSafeString(ivHexStr.getBytes(StandardCharsets.UTF_8));
    String cipherTextEncode = getCipherText(payload, sessionKey, iv);
    String signature = getSignature(jwePrivateKey, sessionKey, payload, jweHeaderEncode, ivEncode);
    StringBuilder stringBuilder = new StringBuilder().append(jweHeaderEncode)
        .append(".")
        .append(encryptedKeyEncode)
        .append(".")
        .append(ivEncode)
        .append(".")
        .append(cipherTextEncode)
        .append(".")
        .append(signature);
    return stringBuilder.toString();
}

门票数据更新

更新门票卡片数据。

接口原型

• 承载协议：HTTPS

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

• 接口方向：开发者业务管理服务->钱包云服务

• 接口URL：https://wallet-passentrust-drcn.cloud.huawei.com.cn/hmspass/v2/{cardType}/instance/{instanceId}

• 数据格式：

  请求消息：Content-Type: application/json;charset=UTF-8

  响应消息：Content-Type: application/json;charset=UTF-8

请求参数

Request Header

Request Body

参见申请门票的请求体，如果是全量更新，与申请门票接口请求体相同。如果是局部更新，则只需传入需要变更的数据体。

请求示例

PATCH /hmspass/v2/key_ticket/instance/100005 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer bKyECwrVGw********************e
Accept: application/json;charset=UTF-8
{
  "fields": {
    "commonFields": [
      {
        "value": "xxxx",
        "key": "personalizedData"
      }
    ]
  }
}

响应参数

http响应为200时表示成功。其他错误情况，可见REST API错误码。

调用示例

public HwWalletObject invokeHwCreateKeyTicketObject() {
    HwWalletObject request = new HwWalletObject();
    request.setPassTypeIdentifier("hwpass.keyticket.test");
    request.setPassStyleIdentifier("keyTicketModelTest");
    request.setOrganizationPassId("20001");
    request.setSerialNumber("20001");
    Fields fields = new Fields();
    fields.setCountryCode("CN");
    List<ValueObject> commonFields = new ArrayList<>();
    ValueObject seatNumber = new ValueObject();
    seatNumber.setKey("seatNumber");
    seatNumber.setValue("12A");
    commonFields.add(seatNumber);
    fields.setCommonFields(commonFields);
    request.setFields(fields);
    HttpHeaders header = constructHttpHeaders();
    String baseUrl = "https://wallet-passentrust-drcn.cloud.huawei.com.cn/hmspass";
    // 100005仅为instanceId的示例值，实际使用时请替换为真实的instanceId。
    String walletServerUrl = baseUrl + "/v2/key_ticket/instance/100005";
    HttpEntity<JSONObject> entity = new HttpEntity<>(JSONObject.parseObject(JSONObject.toJSONString(request)), header);
    ResponseEntity<JSONObject> exchange =
        REST_TEMPLATE.exchange(walletServerUrl, HttpMethod.PATCH, entity, JSONObject.class);
    return JSONObject.parseObject(exchange.getBody().toJSONString(), HwWalletObject.class);
}