API接入

1. 服务注册

在调用存证服务前，需要调用该接口完成服务注册，仅需要注册一次。

请求

接口地址：https://api1.btsi.org.cn/tec/evi/register

请求方式：POST

HTTP请求报文示例：

其中参数含义如下：

参数	类型	说明	示例
btsiAppId	String	信链盟appId	bt1675747713277333505si
btsiAppKey	String	信链盟appKey	e242fc132e74937cd5b5e34d7fe3bd9bd
notificationUrl	String	异步上链通知地址，可以缺省	http://localhost:8082/api/notification

1.
其中btsiAppId和btsiAppKey在“快速接入-接入流程-step2：申请API”环节申请，如下图：
2.
notificationUrl，为异步上链成功后的通知地址，存证服务在异步处理完上链请求后，会将处理结果POST到该地址（POST失败会连续尝试3次）。该字段可以缺省，如果缺省，异步上链后将不会通知，业务代码可通过查询存证自行查询上链是否成功。
3.
通知POST内容为JSON字符串，具体格式和提交存证接口返回的内容一致。
4.
该接口可以多次调用，用于修改或设置btsiAppkey和notificationUrl。

应答

{
    "code": 0,
    "msg": "success"
}

2. 提交存证

请求

接口地址：https://api1.btsi.org.cn/tec/evi/evidences

请求方式：POST

HTTP请求报文示例：

其中参数含义如下：

参数	类型	说明	示例
btsiAppId	String	信链盟appId	bt1675747713277333505si
text	String	需要存证信息的hash值，建议采用sm3生成	36594c6ab448e001a1032cf857e9516c36594c6ab448e001a1032cf857e9516c
groupId	String	信链盟子链Id	grouptec
contractAddress	String	存证合约地址	0x0e71cf2eea38a7f446a12e3b1b8298ddc7941f05
nonce	String	随机数,要求8位长度; 注意：是query参数	12345678
sign	String	接口参数签名(长度为64位); 注意：是query参数	a7da948b13cca9ee6aed1fe64650e383450b0b123e9182d949227ae173f65df8

关于nonce的特别说明
1.存证服务允许对相同内容做多次存证。
2.存证内容相同时，多次调用服务，如果nonce保持不变，服务认为是单次存证的多次请求；如果存证成功，再次请求会返回存证已经存在的错误和对应的存证编码以供查询，只会产生一次计费。
3.存证内容相同时，多次调用服务，如果nonce发生变化，服务认为是对相同内容的多次存证，服务将返回不同的存证编码，并且会产生多次计费。

其中“接口参数签名”的生成算法如下：

支持TEC合约各链的群组名及其合约地址详见：快速接入 → 服务调用 栏目内容。

应答

{
    "code": 0,
    "msg": "success",
    "data": {
        "evidenceCode": "2739c677dd06c11d25dbf2209de43e01", //存证编号
        "text": "evidence hash", //存证hash
        
        //区块hash
        "blockHash": "0xfceaa494cb383f4c58467a4720578a1a80df15fd116266b4973990f76b65debc",
        //区块高度
        "blockHeight": 10078,
        //前一区块hash 
        "preBlockHash":"0x5e9ec9b3cf38b44cc4bee336f755745b1454ee15af5656039c919d6d9a9ec533"

        
        //交易hash
        "txHash": "0x4659461ff8b3f665660f65205749cb3498bff9629dceb7f1b35afe0040414463"，
    }
}

异常应答

接口超时

推荐处理方案：保持所有参数不变（包括nonce）重试；重试时，服务会先查询存证是否存在，如果“存证已存在”，将返回存证编码。

存证已经已存在

存证已经存在，本次存证请求失败，不会另外收取费用。

示例:

{
    "code": 202,
    "msg": "存证已存在",
    "data": {
      "evidenceCode": "0x29d2f0ccb949dfa51ed76bed1e4fe5382535f54b7e2b0ee951bc4af05b4a5341"
    }
  }

参数错误

请求参数错误，请求检查参数是否齐全，字段名是否正确

{
    "code": 400,
    "msg": "参数错误"
}

签名错误

{
    "code": 201,
    "msg": "签名错误"
}

3. 查询存证

请求

接口地址：https://api1.btsi.org.cn/tec/evi/evidences/:evidenceCode

请求方式：GET

HTTP请求报文示例：

其中参数含义如下：

参数	类型	说明	示例
evidenceCode	String	存证编号	bt1675747713277333505si
groupId	String	信链盟子链Id	grouptec
contractAddress	String	存证合约地址	0x0e71cf2eea38a7f446a12e3b1b8298ddc7941f05

应答

{
    "code": 0,
    "msg": "success",
    "data": {
        "evidenceCode": "2739c677dd06c11d25dbf2209de43e01", //存证编号
        "text": "evidence hash" //存证hash
    }
}

4. 异步存证

请求

接口地址：https://api1.btsi.org.cn/tec/evi/async-evidences

请求方式：POST

HTTP请求报文示例：

其中参数含义和提交存证接口的请求参数一致。

应答

{
    "code": 0,
    "msg": "success",
    "data": {
        "evidenceCode": "2739c677dd06c11d25dbf2209de43e01" //存证编号
    }
}

说明：异步存证接口不会等待存证数据提交到蜀信链，而是建立一个上链任务后立即返回一个存证编号。存证服务任务进程会执行上链任务，如果用户在注册服务时提交了notificationUrl参数，任务进程会尝试通过该地址发送POST请求，通知上链任务的执行结果。用户可以使用 存证编号 通过查询存证接口获取存证结果。

如果服务器上的上链任务过多，服务器将拒绝上链的异步请求：{"code": 510,"msg": "当前请求上链的请求过多，请稍后重试"}

关于异步通知
a. Method：POST
b. Body，与同步存证接口返回的内容一致，如下示例：

    {
        "code": 0,
        "msg": "success",
        "data": {
            "evidenceCode": "2739c677dd06c11d25dbf2209de43e01", //存证编号
            "text": "evidence hash", //存证hash
            
            //区块hash
            "blockHash": "0xfceaa494cb383f4c58467a4720578a1a80df15fd116266b4973990f76b65debc",
            //区块高度
            "blockHeight": 10078,
            //前一区块hash 
            "preBlockHash":"0x5e9ec9b3cf38b44cc4bee336f755745b1454ee15af5656039c919d6d9a9ec533"

            
            //交易hash
            "txHash": "0x4659461ff8b3f665660f65205749cb3498bff9629dceb7f1b35afe0040414463"，
        }
    }

1. 服务注册#

2. 提交存证#

3. 查询存证#

4. 异步存证#

1. 服务注册

2. 提交存证

3. 查询存证

4. 异步存证