4.3.1 凭证API应用基础概述

4.3.1.1 接入前准备

• 接入节点
• 中间件（底层链通讯的封装，链上数据同步，链上数据推送）
• mongodb（中间件数据存储）
• RocketMQ（中间件数据推送）
• 加密机（可选，密钥管理，签名工具）
• API服务（合约业务接口封装）
• MySQL（API服务数据存储）

4.3.1.2 相关名词表

4.3.2 凭证API应用调用说明

4.3.2.1 接口调用说明

请求：

GET http://API_HOST:port/path HTTP/1.1

POST http://API_HOST:port/path HTTP/1.1
Content-Type: application/json; charset=utf-8

响应：

响应的格式为：

{
    "code": Integer(),
    "message": "描述",
    "detail": Object()
}

其中code为错误码，message为错误描述，detail为请求成功时的返回值。

4.3.2.2 注意事项

上链接口的bizId在交易重试时需要重新计算,blockLimit由api服务计算超时块号可在配置文件中配置。

1. bizId区块链要求在一定的块区间内不能重复，如果重复则直接上链失败。
2. blockLimit超时块号会在请求API服务时返回。

使用我们提供的安全插件生成公钥信息的接口， http://[HSM_HOST:port]/[server]/crypt/generateKeyFromHsm.json?userId=TEST12345678&type=SM2。

参数userId要业务方保证不可重复，因为重复的userId接口会返回相同的公钥地址。从业务上讲，公钥地址应该是不能重复的。

4.3.2.3 解析MQ事件

消息监听请参照MQ产品官方文档。

下面以阿里RocketMQ接入举例。

MQ消息主要有两种类型。

• EVENT_BLOCKNUMBER 块号更新事件

  块号更新事件是指中间件同步了一个新块下来，然后发送了一条MQ消息给业务系统。

  消息内容为：

  {
      "blockNumber":9571,
      "blockHash":"095d8fe634c54b11752d2847cd5cd4e33abd1f4d24714ca5f693bece36e1d1b2",
      "preBlockHash":"23a5e309dd87b49ccf03874cdebf59c4f6bad2697dbf38628205a619b9cf4c3b",
      "blockTime":1595503411925,
      "regionId":"0000000000000000000000000000000000000000"
  }
  

  | 字段名 | 字段类型 | 字段说明 | | ------------ | ---------- | -------------- | | blockNumber | biginteger | 块号 | | blockHash | string | 当前块的块hash | | preBlockHash | string | 前一块的块hash | | blockTime | long | 上链时间戳 | | regionId | string | 专区编号 |

• EVENT_TX_RECORDED 交易事件

  消息内容如下

  {
      "txHash":"3fbc0b8dbfe74ec8b7a1178895d98ffff73afa2fc179346def776b761c2c80d0",
      "success":true,
      "bizId":"1598001532",
      "code":0,
      "blockNumber":7487508,
      "timestamp":null,
      "signer":"7823540e2f6fe796e95c761b1328dec0387c8adf",
      "regionId":"000000000052d197000000005edf67c300000000",
      "regionPageHash":"144370c6e0456744d221109a821e96bb32f7c2586254913739eea19aa3cad9c7",
      "contractList":[
          "aae0f4dabab653910570454854a84f36e5f6ab31",
          "bae0f4dabab653910570454854a84f36e5f6ab31",
          "cae0f4dabab653910570454854a84f36e5f6ab31"
      ]
  }
  

  | 字段名 | 字段类型 | 字段说明 | | -------------- | ---------- | --------------- | | txHash | string | 交易hash | | success | bool | 交易是否成功 | | bizId | string | 业务流水号 | | code | int | 0为合约调用成功 | | blockNumber | biginteger | 块号 | | timestamp | object | 预留字段 | | signer | string | 交易发起方 | | regionId | string | 专区编号 | | regionPageHash | string | 专区页Hash | | contractList | string[] | 合约地址列表 |

这个事件类型可以使用以下方式获取。

阿里RocketMQ

com.aliyun.openservices.ons.api.Message#getUserProperties("eventType")

4.3.3 接口列表

4.3.3.1 通用查询接口

4.3.3.1.1获取当前最新块号

请求路径：/search/blockNumber

请求方式：GET

请求参数

无

返回参数

4.3.3.1.2根据bizId查询txHash

场景：上链请求接口调用失败时，需要调用此接口根据bizId查询txHash

请求路径：/search/txHash

请求方式：GET

Content-Type：application/json; charset=utf-8

请求参数

返回参数

4.3.3.1.3根据txHash和regionId查询交易回执

场景：收到交易事件EVENT_TX_RECORDED后，根据txHash和regionId查询交易详情。

请求路径：/common/getTransactionByHash

请求方式：POST

Content-Type：application/json; charset=utf-8

请求参数

返回参数

接口返回举例：

注：以下内容仅为格式定义，不代表真实数据，往下面翻有交易举例

{
    "code": "SUCCESS",
    "detail": {
        "transactionHash": "0xc18459fff78e33e2bdfbec581b1e55247bb05ff7c565f78983a155d65faf0dbb",
        "blockNumber": 15429451,
        "regionId": "0x0000000000eab696000000005fd0bc0b00000000",
        "hash": "0x9f6f42999cdeb89d88ddcfb0c737d7b7fc82fb7da86a8d0507d06758e4592a03",
        "contractAddress": null,
        "errorMessage": null,
        "resultCode": 0,
        "resultMsg": "运行成功",
        "logs": [
            {
                "address": "0xb239b199972e08367dcd2c1c383f07d701b22e74",
                "data": {
                    "amount": 100000,
                    "tokenSymbol": "464b464b00000000000000000000000000000000000000000000000000000000",
                    "data": "323233",
                    "partitionId": "464b464b30303030310000000000000000000000000000000000000000000000",
                    "holder": "97fdea898d471a368df2ec6a4de4f0305371a871",
                    "extraParams": "31",
                    "issuer": "97fdea898d471a368df2ec6a4de4f0305371a871"
                },
                "topics": [
                    "IssueToken"
                ]
            }
        ]
    }
}j

4.3.3.2合约上链接口

4.3.3.2.1创建普通用户身份

场景：创建一个普通用户身份

请求路径：/tx/buildAndSend

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.2.2更改主公钥地址

场景：更改身份的主公钥地址

请求路径：/tx/buildAndSend

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.2.3增加备选公钥地址

场景：为指定的身份增加一组备选公钥地址

请求路径：/tx/buildAndSend

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.2.4移除备选公钥地址

场景：移除指定身份的一组备选公钥地址

请求路径：/tx/buildAndSend

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.2.5创建角色

场景：创建一个角色

请求路径：/tx/buildAndSend

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.2.6更新角色权限

场景：更新指定的角色的权限集合

请求路径：/tx/buildAndSend

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.2.7更新角色描述

场景：更新指定的角色描述信息

请求路径：/tx/buildAndSend

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.2.8创建账户

场景：创建一个账户及其对应的身份

请求路径：/tx/buildAndSend

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.2.9登记账户

场景：将指定的身份登记为指定凭证的账户

请求路径：/tx/buildAndSend

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.2.10增加账户角色

场景：为指定的账户增加一组角色

请求路径：/tx/buildAndSend

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.2.11移除账户角色

场景：移除指定账户的一组角色

请求路径：/tx/buildAndSend

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.2.12更新账户附加信息

场景：更新指定账户的附加信息

请求路径：/tx/buildAndSend

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.2.13发行凭证

场景：发行（默认分片的）凭证

请求路径：/tx/buildAndSend

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.2.14发行指定分片的凭证

场景：发行指定分片的凭证

请求路径：/tx/buildAndSend

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.2.15发行指定分片的凭证并更新分片信息

场景：发行指定分片的凭证，同时更新分片信息

请求路径：/tx/buildAndSend

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.2.16更新分片信息

场景：更新指定分片的附加信息

请求路径：/tx/buildAndSend

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.2.17转移凭证

场景：转移（默认分片的）凭证

请求路径：/tx/buildAndSend

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.2.18转移指定分片的凭证

场景：转移指定分片的凭证

请求路径：/tx/buildAndSend

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.2.19转移多个分片的凭证

场景：转移多个分片的凭证

请求路径：/tx/buildAndSend

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.2.20代理转移凭证

场景：适用于代理人转移持有者的凭证，以及管理者强制转移持有者的凭证

请求路径：/tx/buildAndSend

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.2.21代理转移指定分片的凭证

场景：适用于代理人转移持有者的凭证，以及管理者强制转移持有者的凭证

请求路径：/tx/buildAndSend

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.2.22冻结凭证

场景：冻结指定账户的指定分片的凭证，并产生一条冻结记录

请求路径：/tx/buildAndSend

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.2.23解冻凭证

场景：根据冻结记录，解冻指定账户的指定分片的凭证

请求路径：/tx/buildAndSend

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.2.24核销凭证

场景：核销（默认分片的）凭证

请求路径：/tx/buildAndSend

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.2.25核销指定分片的凭证

场景：核销指定分片的凭证

请求路径：/tx/buildAndSend

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.2.26代理核销凭证

场景：核销其他账户的（默认分片的）凭证

请求路径：/tx/buildAndSend

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.2.27代理核销指定分片的凭证

场景：核销其他账户的指定分片的凭证

请求路径：/tx/buildAndSend

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.2.28变更代理授权

场景：变更其他账户代理授权的范围。当授权范围变更为“无”时，分片列表会被清空

请求路径：/tx/buildAndSend

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.2.29授权代理指定分片

场景：授权其他账户代理指定分片的凭证

请求路径：/tx/buildAndSend

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.2.30取消授权代理指定分片

场景：取消授权其他账户代理指定分片的凭证

请求路径：/tx/buildAndSend

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.3合约查询接口

4.3.3.3.1获取分片信息

请求路径：/search/contract

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.3.2获取分片列表

请求路径：/search/contract

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.3.3获取余额信息

请求路径：/search/contract

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.3.4获取冻结数量

请求路径：/search/contract

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.3.5获取冻结记录

请求路径：/search/contract

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.3.6获取角色信息

请求路径：/search/contract

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.3.7获取账户信息

请求路径：/search/contract

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.3.8获取代理列表

请求路径：/search/contract

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.3.9获取代理信息

请求路径：/search/contract

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.3.10获取凭证项目标识列表

请求路径：/search/contract

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.3.3.11获取凭证项目合约

请求路径：/search/contract

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数

4.3.4合约查询接口注意事项

4.3.4.1获取凭证项目的AccountRegistry合约地址

请求路径：/search/contract

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数为AccountRegistry合约地址

{
    "code": "SUCCESS",
    "detail": {
        "0": "779a038a38c5c398ae528dfe6dd9b7049c003c70"
    }
}

4.3.4.2获取凭证项目的AgentRegistry合约地址

请求路径：/search/contract

请求方式：POST

Content-Type：application/json; charset=utf-8

返回参数为AgentRegistry合约地址

{
    "code": "SUCCESS",
    "detail": {
        "0": "02a600c1b1d7c632217d47fb7b37c51f3bb8dc97"
    }
}

4.3.5凭证默认角色

凭证合约在部署时会创建以下默认角色。

4.3.6签名错误

上链接口返回

{
    "code":"PARAM_INVALID_ERROR",
    "message":"The account does not have permission to send the transaction",
    "detail":null
}

此种情况一般是签名的公钥地址未在链上注册，例如未使用此公钥地址创建身份合约地址，或未将改公钥地址加入到某个身份合约地址中。也有可能是签名是的原文和发到链上的原文不一致导致的。