说明
以下api说明中{xxx}表示变量/参数
所有请求和返回均为json
请求格式
{
"jsonrpc": "2.0",
"method": "{method}",
"params": {
"type": 1,
"chaincodeID":{
"name":"{chaincodeId}"
},
"ctorMsg": {
"function":"{function}",
"args":["{参数1}","{参数2}","{参数3}"...]
}
},
"id":{id}
}
{method} query/invoke
{chaincodeId} 测试前提供
{function} 实际操作，见具体API
{args} 调用参数，见具体API
返回格式
{
"jsonrpc": "2.0",
"result": {
"status": "{status}",
"message": "{body}"
},
"id":{id}
}
- 所有invoke方法调用都是异步提交方式，返回结果只有事务TXID。
status ok不代表执行成功，执行结果无法直接查看，只能通过查看world state状态查看调用结果
{
"jsonrpc": "2.0",
"result": {
"status": "OK",
"message": "{TXID}"
},
"id":{id}
}
{id}:数字,序号,暂无意义,下同
-
目前fabric无法查询到返回结果，demo阶段将执行结果放入world state供查询。
request
{
"jsonrpc": "2.0",
"method": "query",
"params": {
"type": 1,
"chaincodeID":{
"name":"{chaincodeId}"
},
"ctorMsg": {
"function":"result",
"args":["{TXID}"]
}
},
"id":{id}
}
response
{
"jsonrpc": "2.0",
"result": {
"status": "OK",
"message": "{\"message\":\"OK\",\"result\":{json}/"{string}",\"status\":\"20000000\",\"success\":true}"
},
"id":{id}
}
{status}="20000000"或者{success}=true为成功
result为结果json
api
1.交易所
字段
- marketId 交易所id,demo阶段只需要创建一个票交所，所有交易都在一个票交所交易
- address 地址
- name 名称
- priKey 私钥。签名使用，demo不做数字签名，只简单比较私钥。值为pri-{marketId}
- pubKey 公钥。值为pub-{marketId}
1.1创建交易所
request
{
"jsonrpc": "2.0",
"method": "invoke",
"params": {
"type": 1,
"chaincodeID":{
"name":"{chaincodeId}"
},
"ctorMsg": {
"function":"market.create",
"args":["{\"marketId\":\"{marketId}\",\"address\":\"{地址}\",\"name\":\"{name}\"}"]
}
},
"id":{id}
}
response
{
"jsonrpc": "2.0",
"result": {
"status": "OK",
"message": "{TXID}"
},
"id":{id}
}
该返回并不代表创建成功，见说明
1.2查询交易所
request
{
"jsonrpc": "2.0",
"method": "query",
"params": {
"type": 1,
"chaincodeID":{
"name":"{chaincodeId}"
},
"ctorMsg": {
"function":"market",
"args":["{marketId}"]
}
},
"id":{id}
}
response
{
"jsonrpc": "2.0",
"result": {
"status": "OK",
"message": "{\"message\":\"OK\",\"result\":\"{\"address\":\"{address}\",\"marketId\":\"{market}\",\"name\":\"{name}\",\"priKey\":\"{priKey}\",\"pubKey\":\"{pubKey}\"}\",\"status\":\"20000000\",\"success\":true}"
},
"id": 0
}
- demo ok
{
"jsonrpc": "2.0",
"result": {
"status": "OK",
"message": "{\"message\":\"OK\",\"result\":\"{\"address\":\"beijing\",\"marketId\":\"qianbao\",\"name\":\"qianbao\",\"priKey\":\"pri-qianbao\",\"pubKey\":\"pub-qianbao\"}\",\"status\":\"20000000\",\"success\":true}"
},
"id": 0
}
- demo-not found
{
"jsonrpc": "2.0",
"result": {
"status": "OK",
"message": "{\"message\":\"market not found!\",\"status\":\"40400000\",\"success\":false}"
},
"id": 0
}
2.用户
- userId 为公司或组织业务ID
- marketId 所属票交所
- type 1:spv,可以做资产打包合约;2:普通票据持有者
- market-priKey 必须为票交所对应priKey,用户创建只能通过票交所上链，通过该字段检查来模拟票交所签名
- address 地址
- businessLicense 营业执照
- organizationCodeCertificate 税务登记证
- taxRegistrationCertificate 组织机构代码证
- priKey 用户私钥。demo不做数字签名，只简单比较私钥。值为pri-{userId}
- pubKey 用户公钥。值为pub-{userId}
2.1用户上链
request
{
"jsonrpc": "2.0",
"method": "invoke",
"params": {
"type": 1,
"chaincodeID":{
"name":"{chaincodeId}"
},
"ctorMsg": {
"function":"user.create",
"args":["{\"name\":\"{name}\",\"address\":\"{address}\",\"marketId\":\"{marketId}\",\"type\":{type},\"userId\":\"{userId}\",\"businessLicense\":\"{businessLicense}\",\"organizationCodeCertificate\":\"{organizationCodeCertificate}\",\"taxRegistrationCertificate\":\"{organizationCodeCertificate}\"}","{market-priKey"]
}
},
"id":{id}
}
response
{
"jsonrpc": "2.0",
"result": {
"status": "OK",
"message": "{TXID}"
},
"id":{id}
}
该返回并不代表创建成功，见说明
2.2查询用户
request
{
"jsonrpc": "2.0",
"method": "query",
"params": {
"type": 1,
"chaincodeID":{
"name":"{chaincodeId}"
},
"ctorMsg": {
"function":"user",
"args":["userId"]
}
},
"id":{id}
}
response demo
- ok
{
"jsonrpc": "2.0",
"result": {
"status": "OK",
"message": "{\"message\":\"OK\",\"result\":\"{\"address\":\"beijing\",\"businessLicense\":\"xxxxx\",\"marketId\":\"qianbao\",\"name\":\"zhangzheng\",\"organizationCodeCertificate\":\"xxxxxx\",\"priKey\":\"pri-zz\",\"pubKey\":\"pub-zz\",\"taxRegistrationCertificate\":\"xxxxxx\",\"type\":1,\"userId\":\"zz\"}\",\"status\":\"20000000\",\"success\":true}"
},
"id": 0
}
- not found
{
"jsonrpc": "2.0",
"result": {
"status": "OK",
"message": "{\"message\":\"user not found!\",\"status\":\"40400000\",\"success\":false}"
},
"id": 0
}
3.票据
- userId 用户id
- marketId 所属票交所
- billId 票据id
- type 1:纸银;2:纸商
- status 10.持有，20.交易中，30.资产，40.已承兑。允许状态转换:持有->交易中;交易中->资产;持有->已承兑;交易中->持有;资产->已承兑
- amount 面值
- startDate yyyyMMdd
- endDate yyyyMMdd
- bank 银行
- bankAddress 银行地址
- billPackage 资产包。资产打包后改字段有值
- transactions 历史交易id。字符串数组
3.1 票据上链
request
{
"jsonrpc": "2.0",
"method": "invoke",
"params": {
"type": 1,
"chaincodeID":{
"name":"{chaincodeId}"
},
"ctorMsg": {
"function":"bill.create",
"args":["{\"billId\":\"{billId}\",\"type\":{type},\"marketId\":\"{marketId}\",\"userId\":\"{userId}\",\"amount\":{amout},\"startDate\":\"{startDate}\",\"endDate\":\"{endDate}\",\"bank\":\"{bank}\",\"bankAddress\":\"{bankAddress}\"}","market-priKey","user-priKey"]
}
},
"id":{id}
}
response
{
"jsonrpc": "2.0",
"result": {
"status": "OK",
"message": "{TXID}"
},
"id":{id}
}
该返回并不代表创建成功，见说明
3.2 票据查询
request
{
"jsonrpc": "2.0",
"method": "query",
"params": {
"type": 1,
"chaincodeID":{
"name":"{chaincodeId}"
},
"ctorMsg": {
"function":"bill",
"args":["{billId}"]
}
},
"id":{id}
}
response demo
- ok
{
"jsonrpc": "2.0",
"result": {
"status": "OK",
"message": "{\"message\":\"OK\",\"result\":\"{\"amount\":1000000,\"billId\":\"bill002\",\"endDate\":\"20180107\",\"startDate\":\"20180107\",\"bank\":\"ccbc\",\"bankAddress\":\"beijing\",\"marketId\":\"qianbao\",\"startDate\":\"20170107\",\"status\":10,\"transactions\":[\"5fe73654-dd53-433b-993f-62435ed3eeb4\",\"39a06dc2-f6a3-45d1-80c8-e42e5105afad\"],\"type\":1,\"userId\":\"gaoxiang\"}\",\"status\":\"20000000\",\"success\":true}"
},
"id": 0
}
- not found
{
"jsonrpc": "2.0",
"result": {
"status": "OK",
"message": "{\"message\":\"bill not found!\",\"status\":\"40400000\",\"success\":false}"
},
"id": 0
}
4.交易
- transactionId 交易ID,使用交易创建返回的区块链TXID作为交易ID。
- billId 票据Id
- buyer 买方Id
- buyerMarket 买方票交所Id
- seller 卖方Id
- sellerMarket 卖方票交所Id
- buyerStatus 买方状态，只能买方修改。0,交易中;1,完成;2,取消
- sellerStatus 卖方状态，只能卖方修改。0,交易中;1,完成;2,取消
- status 交易状态。0,交易中;1,完成（交易双方状态都是完成）;2,取消（交易双方状态都是取消）
- createTime 交易创建时间
4.1交易创建
request
{
"jsonrpc": "2.0",
"method": "invoke",
"params": {
"type": 1,
"chaincodeID":{
"name":"{chaincodeId}"
},
"ctorMsg": {
"function":"transaction.create",
"args":["{\"billId\":\"{billId}\",\"sellerMarket\":\"{sellerMarket}\",\"seller\":\"{seller}\",\"buyerMarket\":\"{buyerMarket}\",\"buyer\":\"{buyer}\",\"price\":{price},\"createTime\":{createTime}}","{sellerMarket-priKey}","{seller-priKey}"]
}
},
"id":{id}
}
response
{
"jsonrpc": "2.0",
"result": {
"status": "OK",
"message": "{TXID}"
},
"id":{id}
}
返回消息中的TXID直接作为票据交易的transactionId,该返回并不代表交易创建成功，见说明。
交易创建成功，票据状态变更为交易中（20）。
4.2买方确认
request
{
"jsonrpc": "2.0",
"method": "invoke",
"params": {
"type": 1,
"chaincodeID":{
"name":"{chaincodeId}"
},
"ctorMsg": {
"function":"transaction.buyer.confirm",
"args":["transactionId","{buyerMarket-priKey}","{buyer-priKey}"]
}
},
"id":{id}
}
response
{
"jsonrpc": "2.0",
"result": {
"status": "OK",
"message": "{TXID}"
},
"id":{id}
}
该返回并不代表交易确认成功，见说明。
买方确认成功时，买方状态变更为完成（1）。若卖方状态为完成（1）。则交易状态变更为完成（1），同时修改票据所有人，及票据状态（10）。
4.3卖方确认
request
{
"jsonrpc": "2.0",
"method": "invoke",
"params": {
"type": 1,
"chaincodeID":{
"name":"{chaincodeId}"
},
"ctorMsg": {
"function":"transaction.seller.confirm",
"args":["transactionId","{sellerMarket-priKey}","{seller-priKey}"]
}
},
"id":{id}
}
response
{
"jsonrpc": "2.0",
"result": {
"status": "OK",
"message": "{TXID}"
},
"id":{id}
}
该返回并不代表交易确认成功，见说明。
卖方确认成功时，卖方状态变更为完成（1）。若买方状态为完成（1）。则交易状态变更为完成（1），同时修改票据所有人，及票据状态（10）。
4.4买方取消
request
{
"jsonrpc": "2.0",
"method": "invoke",
"params": {
"type": 1,
"chaincodeID":{
"name":"{chaincodeId}"
},
"ctorMsg": {
"function":"transaction.buyer.cancle",
"args":["transactionId","{buyerMarket-priKey}","{buyer-priKey}"]
}
},
"id":{id}
}
response
{
"jsonrpc": "2.0",
"result": {
"status": "OK",
"message": "{TXID}"
},
"id":{id}
}
该返回并不代表交易取消成功，见说明。
买方取消成功时，买方状态变更为取消（2）。若卖方状态为取消（2）。则交易状态变更为取消（2），同时修改票据状态（10）。
4.5卖方取消
request
{
"jsonrpc": "2.0",
"method": "invoke",
"params": {
"type": 1,
"chaincodeID":{
"name":"{chaincodeId}"
},
"ctorMsg": {
"function":"transaction.seller.cancle",
"args":["transactionId","{sellerMarket-priKey}","{seller-priKey}"]
}
},
"id":{id}
}
response
{
"jsonrpc": "2.0",
"result": {
"status": "OK",
"message": "{TXID}"
},
"id":{id}
}
该返回并不代表交易取消成功，见说明。
卖方取消成功时，卖方状态变更为取消（2）。若买状态为取消（2）。则交易状态变更为取消（2），同时修改票据状态（10）。
4.5交易查询
request
{
"jsonrpc": "2.0",
"method": "query",
"params": {
"type": 1,
"chaincodeID":{
"name":"{chaincodeId}"
},
"ctorMsg": {
"function":"transaction",
"args":["{transactionId}"]
}
},
"id":{id}
}
5.资产
- packageId 资产ID,使用资产上链返回的区块链TXID作为资产ID。
- marketId 票交所
- userId 资产所有人，只有SPV才能打包资产
- name 资产名称
- endDate 资产到期日yyyyMMdd
- status 资产状态。10,资产;20,兑付中;30,已兑付
- startDate yyyyMMdd
- price 资产价格,double
- billIds 票据id。字符串数组
5.1资产打包上链
request
{
"jsonrpc": "2.0",
"method": "invoke",
"params": {
"type": 1,
"chaincodeID":{
"name":"{chaincodeId}"
},
"ctorMsg": {
"function":"package.create",
"args":["{\"userId\":\"{userId}\",\"marketId\":\"{marketId}\",\"name\":\"{name}\",\"endDate\":\"{endDate}\",\"price\":{price},\"billIds\":[\"{billId}",\"{billId}\"]}","{market-priKey}","{user-priKey}"]
}
},
"id":{id}
}
response
{
"jsonrpc": "2.0",
"result": {
"status": "OK",
"message": "{TXID}"
},
"id":{id}
}
返回消息中的TXID直接作为资产的packageId,该返回并不代表资产创建成功，见说明。
资产打包会检查票据持有人及priKey。
资产创建成功，票据状态变更为资产（30）。
5.2资产状态更新
request
{
"jsonrpc": "2.0",
"method": "invoke",
"params": {
"type": 1,
"chaincodeID":{
"name":"{chaincodeId}"
},
"ctorMsg": {
"function":"package.create",
"args":["{package}","{market-priKey}","{user-priKey}","{status}"]
}
},
"id":{id}
}
{status}只能为"20"或者"30"
response
{
"jsonrpc": "2.0",
"result": {
"status": "OK",
"message": "{TXID}"
},
"id":{id}
}
该返回并不代表资产状态更新成功，见说明。
资产状态更新为已兑付（30）时，票据状态变更为已兑付（40）。
5.3资产查询
request
{
"jsonrpc": "2.0",
"method": "query",
"params": {
"type": 1,
"chaincodeID":{
"name":"{chaincodeId}"
},
"ctorMsg": {
"function":"package",
"args":["{package}"]
}
},
"id":{id}
}
