授权通信数据服务API

1. 简介

所谓“授权通信”,即只有经过用户授权才可以通信,未经授权的电话或者短信都将被视作不良信息。星火链网授权通信服务以区块链技术为核心,通过不可逆加密技术存储使用授权及通信凭证,实现企业到网络到终端到用户的端到端语音、短信管控。

通过授权通信数据服务API,可将授权凭证信息上链存储,由于上链交易不是实时进行,可通过接口查询上链状态。同时,主链为每个授权凭证生成凭证BID,后续可通过星火链网统一解析入口,解析该BID详情。

2.接入说明

1、本文档用于指导后端开发者对授权通信数据服务的开发。

2、申请应用api_keyapi_secret(联系李瑾(lijin1@caict.ac.cn)获取)。

(注意:api_keyapi_secret相当于用户名和密码,请不要随意泄露)

3、本文档的接口采用 HTTPS 加密方式请求。

访问域名:https://sqtxapi.bitfactory.cn

3.API调用说明

用户通过获取accessToken接口获取开发者账户token,token有效期两小时, 业务接口所有api接口都需要将开发者账户token放入请求头部, api具体参数详见接口文档。

4.API接口

4.1 基础接口

4.1.1 获取accessToken

http请求方式:POST
https://{url}/traf/get/accessToken
{
  "apiKey": "",
  "apiSecret":""
}

请求参数说明:

字段名

类型

是否必填

描述

apiKey

String

开发者账户标识

apiSecret

String

开发者账户密钥

成功的返回JSON数据:

{
    "data": {
       "accessToken":""
    }, 
    "errorCode": 0, 
    "message": "成功"
}

响应参数说明:

字段名

类型

描述

accessToken

String

开发者账户token

4.2 业务接口

4.2.1 数据链上存储

http请求方式:POST
https://{url}/traf/data/store
{
    "requestNo": "",
    "scene": 1000,
    "data": "{\"mobile\": \"136****1024\",\"appId\": \"did:bid:ef14uPsX7XYLzsU4t2rnRrsK2zfUbFEj\",\"companyBid\": \"did:bid:ef14uPsX7XYLzsU4t2rnRrsK2zfUbFEj\",\"authProtocoHash\": \"da638834453294c3cc51cec148b62838c336bd9f5d11689b183580491bb89286d\",\"authTime\": \"2021-09-26\",\"authDuration\": \"2021-09-26\"}"
}

请求参数说明:

字段名

类型

是否必填

描述

requestNo

String

请求序号(在开发者APIKey中唯一),推荐使用UUID

scene

int

场景(1000:授权通信数据存储场景)

data

String

上传数据(JSON格式字符串)

data.mobile

String

加密手机号

data.appId

String

应用bid

data.companyBid

String

企业bid

data.authProtocoHash

String

授权协议Hash

data.authTime

String

授权时间

data.authDuration

String

授权过期时间

成功的返回JSON数据:

{
    "data": {
        "dataBid":"",
        "requestNo":""
    }, 
    "errorCode": 0, 
    "message": "成功"
}

响应参数说明:

字段名

类型

描述

dataBid

String

数据链上存储索引BID

requestNo

String

请求序号(由开发者定义并调用本接口时传入)

4.2.2 获取数据链上存储状态

http请求方式:POST
https://{url}/traf/data/query/status
{
  "dataBid": "",
  "requestNo":""
}

请求参数说明:

字段名

类型

是否必填

描述

dataBid

String

数据链上存储索引BID

requestNo

String

请求序号(数据存储接口由开发者定义并传入)

注意dataBidrequestNo二者不能同时为空。

成功的返回JSON数据:

{
    "data": {
       "status":"",
       "txHash": ""
    }, 
    "errorCode": 0, 
    "message": "成功"
}

响应参数说明:

字段名

类型

描述

status

String

存储状态(0:待处理,1:处理中,2:处理成功,3:处理失败)

txHash

String

数据上链交易hash

4.2.3 获取存储数据详情

http请求方式:POST
https://{url}/traf/data/query/detail
{
  "dataBid": "",
  "requestNo":""
}

请求参数说明:

字段名

类型

是否必填

描述

dataBid

String

数据链上存储索引BID

requestNo

String

请求序号(数据存储接口由开发者定义并传入)

注意dataBidrequestNo二者不能同时为空。

成功的返回JSON数据:

{
    "data": {
        "txHash": "",
        "dataBid": "",
        "bidDocument": "\"@context\": [\"https://w3.org/ns/did/v1\"],
    \"authentication\": [\"did:bid:efx1dx9wdRzwy5J68dxhcXN2oaAToPXY#key-1\"],
    \"created\": \"2021-09-26T09:00:21Z\",
    \"extension\": {
      \"attributes\": [{
        \"encrypt\": 0,
        \"format\": \"text\",
        \"value\": \"133****9999\",
        \"key\": \"mobile\",
        \"desc\": \"加密手机号\"
      },{
        \"encrypt\": 0,
        \"format\": \"text\",
        \"value\": \"did:bid:ac01:ef14uPsX7XYLzsU4t2rnRrsK2zfUbFEj\",
        \"key\": \"appId\",
        \"desc\": \"应用id\"
      },{
        \"encrypt\": 0,
        \"format\": \"text\",
        \"value\": \"did:bid:ac01:ef14uPsX7XYLzsU4t2rnRrsK2zfUbFEj\",
        \"key\": \"companyBid\",
        \"desc\": \"企业Bid\"
      },{
        \"encrypt\": 0,
        \"format\": \"text\",
        \"value\": \"da638834453294c3cc51cec148b62838c336bd9f5d11689b183580491bb89286d\",
        \"key\": \"authProtocoHash\",
        \"desc\": \"授权协议hash\"
      },{
        \"encrypt\": 0,
        \"format\": \"text\",
        \"value\": \"2021-09-26\",
        \"key\": \"authTime\",
        \"desc\": \"授权时间\"
      },{
        \"encrypt\": 0,
        \"format\": \"text\",
        \"value\": \"2021-09-26\",
        \"key\": \"authDuration\",
        \"desc\": \"授权过期时间\"
      }],
      \"recovery\": [\"did:bid:efx1dx9wdRzwy5J68dxhcXN2oaAToPXY#key-1\"],
      \"ttl\": 86400,
      \"type\": 102
    },
    \"id\": \"did:bid:efx1dx9wdRzwy5J68dxhcXN2oaAToPXY\",
    \"publicKey\": [{
      \"controller\": \"did:bid:efx1dx9wdRzwy5J68dxhcXN2oaAToPXY\",
      \"id\": \"did:bid:efx1dx9wdRzwy5J68dxhcXN2oaAToPXY#key-1\",
      \"publicKeyHex\": \"b0656629cac2866320b05cc614c2a92c9090d891b7f6d86a9545c715a99254925875cd\",
      \"type\": \"Ed25519\"
    }],
    \"updated\": \"2021-09-26T09:00:21Z\",
    \"version\": \"1.0.0\""
    },
    "errorCode": 0,
    "message": "成功"
}

响应参数说明:

字段名

类型

描述

txHash

JSON

数据上链交易hash

dataBid

String

数据链上存储索引BID

bidDocument

String

数据链上存储docuemnt文档