Overview
Process API can help you import data into a specific DCP through the form of interface docking. By adding the corresponding request parameters to the request according to the interface instructions, the system will return the processing results after the call. The request and response are encoded using the UTF-8 character set.
API | Description |
---|---|
v2/tokens | Get Token |
v2/process/create | Create DCP Data |
v2/process/update | Update DCP data |
v2/process/detail | Query the latest DCP data |
v2/process/getList | Query DCP data list |
v2/attachment/upload | Upload attachment |
v2/attachment/info | Query attachment information |
v2/attachment/{fileHash} | Download attachment |
v2/vid/generate | Generate tag VID in batches |
v2/vid/occupy | Register tag VID in batches |
v2/provenance/hash/query | Query the latest on-chain information |
v2/provenance/hash/queryHistory | Query historical on-chain information |
Request URL
-
AWS / Projects hosted outside of China: https://developer.vetoolchain.com/api/
-
Ali / Projects hosted inside China: https://developer.vetoolchain.cn/api/
Request Header
Header | Description | Example |
---|---|---|
content-type | indicates the media type of the resource | If there is no special statement, please use application/json;charset=utf-8 |
x-api-token | contains the JWT token to authenticate a user | eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9... |
Result Code
Please refer to here
Terms
Idempotent
ToolChain™'s idempotent processing of write requests requires the requester to provide the same set of request parameters according to the interface description. The same set of request parameters will only be executed once in ToolChain™, and repeated requests will be regarded as query operations.
Order status
Name | Type | Description |
---|---|---|
orderStatus | string | INIT,PROCESSING,SUCCESS,FAILURE |
For the idempotent processing of write requests, developers need to use the same set of request parameters to repeat the request until the order status becomes final status. Among them, SUCCESS and FAILURE are the final statuses, and INIT and PROCESSING are the initial statuses. For requests whose final status is FAILURE, developers need to design their own compensation mechanism to ensure the integrity of interface calls.
-
Get Token
POST v2/tokens
Get token, for the method of obtaining appid and appkey, please refer to here
Java Example:
signString :appid=15cf8af3ebeca443d377bd5c2658cae9
&appkey=15cf8af3ebeca443d377bd5c2658cae98a1030dd513184568e89fbbd776bc2cb
&nonce =3806143519628774
×tamp=1552185608
signature : sha256( signString )
public static String sha256( String text )
{
try {
MessageDigest message = MessageDigest.getInstance( "SHA-256" );
byte[] hash = message.digest( text.getBytes( "UTF-8" ) );
return(Hex.encodeHexString( hash ) );
} catch ( Exception e ) {
e.printStackTrace();
}
return(null);
}
public static String signature( TokenRequest request )
{
StringBuffer sign = new StringBuffer();
sign.append( String.format( "appid=%s&", request.getAppid() ) );
sign.append( String.format( "appkey=%s&", appkey ) );
sign.append( String.format( "nonce=%s&", request.getNonce() ) );
sign.append( String.format( "timestamp=%s", request.getTimestamp() ) );
return(sha256( sign.toString().toLowerCase() ) );
}
public static void testGetToken()
{
TokenRequest request = new TokenRequest();
request.setAppid( appid );
request.setNonce( RandomUtils.nextHexString( 8 ) );
request.setTimestamp( String.valueOf( (System.currentTimeMillis() / 1000) ) );
request.setSignature( signature( request ) );
System.out.println( JSONObject.toJSONString( request ) );
}
Request Parameters
Name | Type | Required | Description |
---|---|---|---|
appid | string | Y | appid |
nonce | string | Y | random number (length is 16) |
signature | string | Y | sha256 signature |
timestamp | string | Y | current timestamp, within 5 minutes (UTC time) |
source | string | N | application request source. For the same request source, the valid request is the latest request |
Request Example
{
"appid": "15cf8af3ebeca443d377bd5c2658cae9",
"nonce": "3806143519628774",
"signature": "1c442f56664317d81c32e41010660f54ba1e71223fa6d766ebbe45de3906998b",
"timestamp": "1552185608"
}
Response Example
{
"code": "common.success",
"data": {
"timeToLive": 86400,
"expireTime": 1593257539,
"expire": 86400,
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJsb2dpbklkIjoiNGNhY2IyNzk3NDVjIiwiYXBwSWQiOiJhODJiN2I5MGNmMDE0ZDFhMDk5YzEzOTdmMzA5NzZiYyIsInNvdXJjZSI6ImFhYSIsImV4cCI6MTU5MzI1NzUzOSwiaWF0IjoxNTkzMTcxMTM5fQ.YhXSdmicmbjajIiZqyIPpUPWn1lFrsO6G8-JWK_yXmY"
}
}
Response Parameters
Name | Type | Description |
---|---|---|
token | string | returned token |
expire | integer | token effective time (24 hours), unit: second |
timeTolive | integer | token remaining effective time, unit: second |
expireTime | integer | expiry timestamp |
After getting the token, you can start sending HTTP GET/POST requests to call the blockchain service. Each time it is called, please make sure that the value of the x-api-token of the HTTP request is valid.
-
Create DCP data
POST v2/process/create
Create DCP data. Interface has idempotent properties and is composed of 3 fields, dcpInstanceUUID, projectUUID, requestNo, and any one of the fields with different values will be treated as a new request. When calling this interface, you need to ensure that the operator has the create permission. For how to assign permissions, please refer to here. For permission comparison instructions, please refer to here. When uploading hash data(DCP type = DCP hash), please make sure the hash value(field: base.datalist.data) is hex string(sha256) , the length of which is 32 bytes.
Request Parameters
Name | Type | Required | Description |
---|---|---|---|
dcpInstanceUUID | string | Y | DCP UUID, please refer to here |
+ defaultLangDCPValue | DcpValueInfo | Y | DCP data in default language |
└ bizLanguage | string | N | default language, use the default language of process if not set. For language types, please refer to here |
└ dataValue | object(json) | Y | DCP detailed data, please refer to here |
+ otherLangDCPValue | array(DcpValueInfo) | N | DCP data collection in other languages |
└ bizLanguage | string | Y | language, please refer to here |
└ dataValue | object(json) | Y | DCP detailed data, please refer to here |
projectUUID | string | Y | project ID, please refer to here |
toolchainOperatorUUID | string | Y | operator ID, please refer to here |
requestNo | string | Y | request number, length is no more than 50, only letters and numbers are allowed |
smartcontractId | string | N | smart contrat address |
submitStatus | string | Y | submit status(DRAFT,SUBMIT), DRAFT can be updated to SUBMIT |
Request Example
{
"requestNo": "123456789022223",
"submitStatus": "SUBMIT",
"defaultLangDCPValue":
{
"bizLanguage": "zh-CN",
"dataValue":
{
"base":
{
"skucode": "SKU Operation B",
"productname": "English 22223",
"mainimage":
{
"filetype": "jpg",
"filelocation": "/resource/7a9c83bf70ee49e67dff864fc2762a18ea659c85b2038679787f3f52795a19b7",
"filename": "abc.jpg",
"filesize": "12990",
"filehash": "7a9c83bf70ee49e67dff864fc2762a18ea659c85b2038679787f3f52795a19b7"
},
"description": "VEBOOK",
"productparames": [
{
"key": "Number",
"value": "2019 No.1"
}],
"files": [
{
"filetype": "pdf",
"filelocation": "/resource/4244162a1f4eeb27d98805d8ad3722a6eb093fb4613d9ab7f4bac2b50ad07115",
"filename": "111.pdf",
"filesize": "102558",
"filehash": "4244162a1f4eeb27d98805d8ad3722a6eb093fb4613d9ab7f4bac2b50ad07115"
}],
"timestamp": 0
},
"custom":
{}
}
},
"smartcontractId": "",
"dcpInstanceUUID": "10516100-e593-4bf5-806f-048401200000",
"projectUUID": "15664C28-F375-61C2-1146-934D59400001",
"toolchainOperatorUUID": "0xde7f8974f9fe41b5b4f48350594d345fcda9a74a0c00e4b52cd4720b08f5bf44"
}
Response Example
{
"code": "common.success",
"data":
{
"dataUUID": "10516100-a73d-4e5b-99c3-22f702200000",
"dataVID": "0x9e39633d001592838332e6c0ddfa343b13ff69a8770e36b76a9c3800340a646a",
"orderStatus": "SUCCESS",
"requestNo": "1593397064284"
}
}
Response Parameters
Name | Type | Description |
---|---|---|
dataUUID | string | data UUID, which can be used as input parameter when call update DCP data and query the latest DCP data |
dataVID | string | data VID of on-chain information, return null if this DCP is not sent to blockchain. It can be used as input parameter when query the latest DCP data |
requestNo | string | request number |
orderStatus | string |
request status(INIT,PROCESSING,SUCCESS,FAILURE), for more details, please refer to here |
-
Update DCP data
POST v2/process/update
Update DCP data. The interface has idempotent attributes, and consists of 3 fields, dcpInstanceUUID, projectUUID, requestNo and any one of these fields with different values will be treated as a new request. When calling this interface, you need to ensure that the operator has the update permission. For how to assign permissions, please refer to here. For permission comparison instructions, please refer to here. When uploading hash data(DCP type = DCP hash), please make sure the hash value(field: base.datalist.data) is hex string(sha256) , the length of which is 32 bytes.
Request Parameters
Name | Type | Required | Description |
---|---|---|---|
dataUUID | string | Y | data UUID, which is from the response of create DCP data api. |
dcpInstanceUUID | string | Y | DCP UUID, please refer to here |
+ defaultLangDCPValue | DcpValueInfo | Y | DCP data in default language |
└ bizLanguage | string | N | default language, use the default language of process if not set. For language types, please refer to here |
└ dataValue | object(json) | Y | DCP detailed data, please refer to here |
+ otherLangDCPValue | array(DcpValueInfo) | N | DCP data collection in other languages |
└ bizLanguage | string | Y | language, please refer to here |
└ dataValue | object(json) | Y | DCP detailed data, please refer to here |
projectUUID | string | Y | project ID, please refer to here |
toolchainOperatorUUID | string | Y | operator ID, please refer to here |
requestNo | string | Y | request number, length is no more than 50, only letters and numbers are allowed |
smartcontractId | string | N | smart contract address |
submitStatus | string | Y | submit status(DRAFT,SUBMIT), DRAFT can be updated to SUBMIT |
Request Example
{
"dataUUID": "11000200-c7e3-43ac-bc11-70f302200015",
"dcpInstanceUUID": "11000200-7b66-42bf-a5d4-2fae01200015",
"defaultLangDCPValue":
{
"dataValue":
{
"custom":
{},
"base":
{
"datalist": [
{
"data": "3f357fb5638cc7169d2e48e8dff83f618bcd7b6c46ffb5e008134f6cc15be8fc",
"vidlist":
{
"type": 0,
"vidlist": ["0X912139A4001592476415F237CBDC72D08BED2039F47991DEED48C3E4176E8748", "0X912139A4001592476415AFF22CCEADA5B952FCEDE5E5B8E808A86D6FD0502072", "0X912139A40015924764157C5B5CCF46DA4E795A36849D6F3F71A364BDEAFF901A"]
}
}],
"name": "dcp hash name1592476426064"
}
}
},
"projectUUID": "15600000-0000-3B95-A485-00205DF934B3",
"requestNo": "1592476523177",
"submitStatus": "SUBMIT",
"toolchainOperatorUUID": "0x733a4d5427d06e8a9d6d25679df8c9a12df9ed5f459abff1f5d9b22ea5691ff6"
}
Response Example
{
"code": "common.success",
"data":
{
"dataUUID": "11000200-c7e3-43ac-bc11-70f302200015",
"orderStatus": "SUCCESS",
"requestNo": "1592476523177"
}
}
Response Parameters
Name | Type | Description |
---|---|---|
dataUUID | string | data UUID, which can be used as input parameter when call update DCP data and query the latest DCP data |
dataVID | string | data VID of on-chain information, return null if this DCP is not sent to blockchain. It can be used as input parameter when call query the latest DCP data |
requestNo | string | request number |
orderStatus | string | request status(INIT,PROCESSING,SUCCESS,FAILURE), for more details, please refer to here |
-
Query the latest DCP data
POST v2/process/detail
Query the results after creating or updating DCP data. For permission comparison instructions, please refer to here
Request Parameters
Name | Type | Required | Description |
---|---|---|---|
dataUUID | string | N | data UUID, which is from the response of create DCP data . At least one of dataUUID and dataVID needs to be passed in |
dataVID | string | N | data VID, which is from the response of create DCP data . At least one of dataUUID and dataVID needs to be passed in |
dcpInstanceUUID | string | Y | DCP UUID, please refer to here |
projectUUID | string | Y | project ID, please refer to here |
toolchainOperatorUUID | string | Y | operator ID, please refer to here |
bizLanguage | string | N | language type, return the DCP information of the default language if not set |
Request Example
{
"dataUUID": "11000200-882f-4a91-9865-e4c802200015",
"dcpInstanceUUID": "11000200-7b66-42bf-a5d4-2fae01200015",
"projectUUID": "15600000-0000-3B95-A485-00205DF934B3",
"toolchainOperatorUUID": "0x733a4d5427d06e8a9d6d25679df8c9a12df9ed5f459abff1f5d9b22ea5691ff6"
}
Response Example
{
"code": "common.success",
"data":
{
"dcpBasicInfo":
{
"blockChainStatus": "NO",
"createTime": 1592534751000,
"creator": "hm_operator",
"languageList": ["en"],
"modifier": "hm_operator",
"toolchainOperatorUUID": "0x733a4d5427d06e8a9d6d25679df8c9a12df9ed5f459abff1f5d9b22ea5691ff6",
"updateTime": 1592534791000,
"verificationStatus": "PROCESSING"
},
"dcpBlockchainInfo":
{
"dataHash": "2ecc08d1c6b2f243a9074818c857ab1f2e43485de86cb608c4877ce9eafdc090",
"dataUUID": "11000200-882f-4a91-9865-e4c802200015"
},
"dcpDataInfo":
{
"bizLanguage": "en",
"dataUUID": "11000200-882f-4a91-9865-e4c802200015",
"dcpDataInfo":
{
"custom":
{},
"base":
{
"datalist": [
{
"data": "d4ddcbbe0479b24a8e90ead9ba2e4a5d6722b95d90937da5e9698e81b69d4e6e",
"vidlist":
{
"type": 0,
"vidlist": ["0X912139A4001592534739A1791A06626E9B80E4ABCFEC97E2D8336669EEAF7B1F", "0X912139A4001592534739BDBAD8DC22F9866776A29463E1577EA1DBA30DEC0B70", "0X912139A4001592534739C36E6FADAABC3B877E106631086116EBB894F5471CF0"]
}
}],
"name": "dcp hash name1592534749410",
"timestamp": 1592534790876
}
},
"dcpInstanceUUID": "11000200-7b66-42bf-a5d4-2fae01200015",
"name": "dcp hash name1592534749410",
"submitStatus": "SUBMIT",
"version": "V11.0"
},
"dcpVerificatonInfo":
{}
}
}
Response Parameters
Name | Type | Description |
---|---|---|
+ dcpBasicInfo | DCPBasicInfoBrief | DCP basic information |
└ blockChainStatus | string | on-chain status(PROCESSING,SUCCESS,NO),‘NO’ means no blockchain information |
└ createTime | integer | create time |
└ creator | string | operators who create DCP data |
└ languageList | array(string) | types of submitted languages |
└ modifier | string | operators who create or update DCP data |
└ toolchainOperatorUUID | string | operator id who create or update DCP data |
└ updateTime | integer | update time |
└ verificationStatus | string | verification status(PROCESSING,SUCCESS,NO),’NO’ means no verification information |
+ dcpBlockchainInfo | DCPBlockChainInfoBrief | DCP on-chain information |
└ clauseIndex | integer | clause index of this blockchain transaction |
└ dataHash | string | hash value of this blockchain transaction |
└ dataUUID | string | data UUID |
└ dataVID | string | data VID |
└ txId | string | blockchain transaction ID |
+ dcpDataInfo | DCPDataInfoBrief | DCP data information |
└ bizLanguage | string | language |
└ dataUUID | string | data UUID |
└ dcpDataInfo | object(json) | DCP data information |
└ dcpInstanceUUID | string | DCP UUID |
└ name | string | DCP record name when creating or updating DCP data(ex: sku name) |
└ submitStatus | string | submit status of DCP data |
└ version | string | DCP version when creating or updating DCP data |
+ dcpVerificatonInfo | DCPVerificationInfoBrief | DCP verification information |
└ auditor | string | auditor when creating or updating DCP data |
└ clauseIndex | string | clause index of the blockchain transaction of the verification |
└ verificationDataHash | string | data hash of verification when creating or updating DCP data |
└ verificationDataUUID | string | data UUID of verification when creating or updating DCP data |
└ verificationDataVid | string | data VID of verification when creating or updating DCP data |
└ verificationResult | string | verification result when creating or updating DCP data |
└ verificationTime | integer | verification time when creating or updating DCP data |
└ verificationTxId | string | blockchain transaction ID of verification when creating or updating DCP data |
-
Query DCP data list
POST v2/process/getList
Query the DCP list and return the results in reverse order of creation time. This interface is implemented by the logic of page turning query. For example, if you need to query the latest 120 pieces of data on the chain, you can use page=1, size=100 and page=2, size=100 to request the interface respectively, and get the first 20 pieces of data in the second request. Similarly, you can also use page=1, size=60 and page=2, size=60 to request the interface to obtain data twice. If you want to further check the details, please use the query latest DCP data interface to query, currently only supports querying the latest updated record. For permission comparison instructions, please refer to here
Request Parameters
Name | Type | Required | Description |
---|---|---|---|
dcpInstanceUUID | string | Y | DCP UUID, please refer to here |
dcpName | string | N | DCP record name when creating or updating DCP data(ex: sku name) |
startTime | long | N | filter the start time of DCP data based on the UTC time (accurate to milliseconds) of the update time |
endTime | long | N | filter the end time of DCP data based on the UTC time (accurate to milliseconds) of the update time |
page | integer | Y | page number, ex: page 3 |
size | integer | Y | row number displayed per page, up to 100 |
submitStatus | string | N | submit status(DRAFT,SUBMIT) |
projectUUID | string | Y | project ID, please refer to here |
toolchainOperatorUUID | string | Y | operator ID, please refer to here |
Request Example
{
"dcpInstanceUUID": "11000200-7b66-42bf-a5d4-2fae01200015",
"page": 1,
"projectUUID": "15600000-0000-3B95-A485-00205DF934B3",
"size": 10,
"toolchainOperatorUUID": "0x733a4d5427d06e8a9d6d25679df8c9a12df9ed5f459abff1f5d9b22ea5691ff6"
}
Response Example
{
"code": "common.success",
"data":
{
"exist": true,
"list": [
{
"blockChainStatus": "NO",
"createTime": 1592534846000,
"creator": "hm_operator",
"dataUUID": "11000200-96f3-4fc9-b0e6-3b3a02200015",
"dcpInstanceUUID": "11000200-7b66-42bf-a5d4-2fae01200015",
"dcpName": "dcp hash name1592534749410",
"dcpType": "DCPHASH",
"modifier": "hm_operator",
"requestNo": "a41ea950-01e3-4e2f-acb2-6128e46d3079",
"submitStatus": "SUBMIT",
"updateTime": 1592534881000,
"verificationStatus": "PROCESSING",
"version": "V11.0"
},
{
"blockChainStatus": "NO",
"createTime": 1592534751000,
"creator": "hm_operator",
"dataUUID": "11000200-882f-4a91-9865-e4c802200015",
"dcpInstanceUUID": "11000200-7b66-42bf-a5d4-2fae01200015",
"dcpName": "dcp hash name1592534749410",
"dcpType": "DCPHASH",
"modifier": "hm_operator",
"requestNo": "11533e83-131f-4f0b-8702-851e2b7a5174",
"submitStatus": "SUBMIT",
"updateTime": 1592534791000,
"verificationStatus": "PROCESSING",
"version": "V11.0"
},
{
"blockChainStatus": "NO",
"createTime": 1592534426000,
"creator": "hm_operator",
"dataUUID": "11000200-bcb4-46c5-b5fc-eedf02200015",
"dcpInstanceUUID": "11000200-7b66-42bf-a5d4-2fae01200015",
"dcpName": "dcp hash name1592534276633",
"dcpType": "DCPHASH",
"modifier": "hm_operator",
"requestNo": "0806e053-865f-463e-b546-8f0dcc085605",
"submitStatus": "SUBMIT",
"updateTime": 1592534462000,
"verificationStatus": "PROCESSING",
"version": "V11.0"
},
{
"blockChainStatus": "NO",
"createTime": 1592534279000,
"creator": "hm_operator",
"dataUUID": "11000200-9b22-487f-b090-52ba02200015",
"dcpInstanceUUID": "11000200-7b66-42bf-a5d4-2fae01200015",
"dcpName": "dcp hash name1592534276633",
"dcpType": "DCPHASH",
"modifier": "hm_operator",
"requestNo": "bc545873-3ae7-45a3-bee5-abdd1f03db83",
"submitStatus": "SUBMIT",
"updateTime": 1592534312000,
"verificationStatus": "PROCESSING",
"version": "V11.0"
},
{
"blockChainStatus": "NO",
"createTime": 1592476524000,
"creator": "hm_operator",
"dataUUID": "11000200-2143-4ef1-9ae1-ee4102200015",
"dcpInstanceUUID": "11000200-7b66-42bf-a5d4-2fae01200015",
"dcpName": "dcp hash name1592476426064",
"dcpType": "DCPHASH",
"modifier": "hm_operator",
"requestNo": "15881c21-6a48-4201-afa5-cba4d39bacbb",
"submitStatus": "SUBMIT",
"updateTime": 1592476562000,
"verificationStatus": "PROCESSING",
"version": "V11.0"
},
{
"blockChainStatus": "NO",
"createTime": 1592476428000,
"creator": "hm_operator",
"dataUUID": "11000200-c7e3-43ac-bc11-70f302200015",
"dcpInstanceUUID": "11000200-7b66-42bf-a5d4-2fae01200015",
"dcpName": "dcp hash name1592476426064",
"dcpType": "DCPHASH",
"modifier": "hm_operator",
"requestNo": "468e7074-e8e3-4cde-9da2-a6e0c83f5c8e",
"submitStatus": "SUBMIT",
"updateTime": 1592476442000,
"verificationStatus": "PROCESSING",
"version": "V11.0"
},
{
"blockChainStatus": "NO",
"createTime": 1592364953000,
"creator": "hm_operator",
"dataUUID": "11000200-0274-4029-acfb-104502200015",
"dcpInstanceUUID": "11000200-7b66-42bf-a5d4-2fae01200015",
"dcpName": "哈希上链测试",
"dcpType": "DCPHASH",
"modifier": "hm_operator",
"requestNo": "fa385820-942b-4aa6-9367-0e8c71e7e707",
"submitStatus": "SUBMIT",
"updateTime": 1592364991000,
"verificationStatus": "PROCESSING",
"version": "V11.0"
},
{
"blockChainStatus": "NO",
"createTime": 1592314825000,
"creator": "hm_operator",
"dataUUID": "11000200-6350-4788-a011-3a3b02200015",
"dcpInstanceUUID": "11000200-7b66-42bf-a5d4-2fae01200015",
"dcpName": "dcp hash name1592314695855",
"dcpType": "DCPHASH",
"modifier": "hm_operator",
"requestNo": "56afe14d-3c3c-45a8-9aa8-a5c813a5bc3d",
"submitStatus": "SUBMIT",
"updateTime": 1592314861000,
"verificationStatus": "PROCESSING",
"version": "V11.0"
},
{
"blockChainStatus": "NO",
"createTime": 1592314697000,
"creator": "hm_operator",
"dataUUID": "11000200-12b4-417c-a903-20dc02200015",
"dcpInstanceUUID": "11000200-7b66-42bf-a5d4-2fae01200015",
"dcpName": "dcp hash name1592314695855",
"dcpType": "DCPHASH",
"modifier": "hm_operator",
"requestNo": "e612d10b-34d6-4e3e-9864-656d4b7901fc",
"submitStatus": "SUBMIT",
"updateTime": 1592314741000,
"verificationStatus": "PROCESSING",
"version": "V11.0"
},
{
"blockChainStatus": "NO",
"createTime": 1592310086000,
"creator": "hm_operator",
"dataUUID": "11000200-4138-45c7-9ff4-674b02200015",
"dcpInstanceUUID": "11000200-7b66-42bf-a5d4-2fae01200015",
"dcpName": "dcp hash name1592309967122",
"dcpType": "DCPHASH",
"modifier": "hm_operator",
"requestNo": "a04330cd-2851-40e2-b15f-fa7be2306254",
"submitStatus": "SUBMIT",
"updateTime": 1592310121000,
"verificationStatus": "PROCESSING",
"version": "V11.0"
}],
"page": 1,
"rows": 29,
"size": 10
}
}
Response Parameters
Name | Type | Description |
---|---|---|
exist | boolean | if data exist |
+ list | array(DataPointListInfoBrief) | collection of DCP data information |
└ blockChainStatus | string | on-chain status(PROCESSING,SUCCESS,NO),‘NO’ means no blockchain information |
└ createTime | integer | create time |
└ creator | string | operators who create DCP data |
└ dataUUID | string | data UUID when creating or updating DCP data |
└ dcpInstanceUUID | string | DCP UUID when creating or updating DCP data |
└ updateTime | integer | update time |
└ dcpName | string | DCP record name when creating or updating DCP data(ex: sku name) |
└ dcpType | string | DCP type when creating or updating DCP data |
└ modifier | integer | operators who modify DCP data |
└ requestNo | string | request number when creating or updating DCP data |
└ submitStatus | string | submit status when creating or updating DCP data |
└ verificationStatus | string | verification status(PROCESSING,SUCCESS,NO),’NO’ means no verification information |
└ version | string | DCP version when creating or updating DCP data |
-
Upload attachment
POST v2/attachment/upload
upload static resources. please record the return fields filetype, filelocation, filename, filesize, filehash, which are needed when assembling DCP data. When sending a request, please use multipart/form-data for Body's content-type. Please ensure that the size of the resource is within the range allowed by the DCP data format, such as <=3000bytes.
Postman settings are as follows:
Supported media types are as follows:
Media type | File format | Size |
---|---|---|
data | ["json"] | 1MB |
image | ["jpeg","jpg","png","jpe","ico","gif"] | 10MB |
vedio | ["mp4","3gp","avi","m3u8","mp3","rmvb"] | 30MB |
file | ["xls","csv","doc","xlsx","txt","docx","md","wps","ppt","pptx","pdf"] | 30MB |
zip | ["zip"] | 30MB |
Request Parameters
Name | Type | Required | Description |
---|---|---|---|
file | File | Y | the local path of static resources, temporarily does not support http(s) links |
Curl Request Example
curl --location --request POST 'https://developer.vetoolchain.com/api/v2/attachment/upload' \
--header 'Content-Type: application/json;charset=utf-8' \
--header 'x-api-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJsb2dpbklkIjoiNWIwMWE5MmIzOGI3IiwiYXBwSWQiOiJhODJiN2I5MGNmMDE0ZDFhMDk5YzEzOTdmMzA5NzZiYyIsInNvdXJjZSI6ImFhYSIsImV4cCI6MTU5MzM0MDM5NCwiaWF0IjoxNTkzMjUzOTk0fQ.OcVyoPx9a4VAbLHAY4MYdDlRJpHnzChToMnXNZeIr-s' \
--form 'file=@/Users/junzhang/Desktop/WechatIMG95.jpeg'
Response Example
{
"code": "common.success",
"data":
{
"filehash": "56c9cbdb4fa51f2b247e0b4d6fbe4a6d1c6c7cecca2925b5b69d4e073e366ac4",
"filelocation": "/resource/56c9cbdb4fa51f2b247e0b4d6fbe4a6d1c6c7cecca2925b5b69d4e073e366ac4",
"filename": "jsonlist_cn.png",
"filesize": 36632,
"filetype": "png"
}
}
Response Parameters
Name | Type | Description |
---|---|---|
filehash | string | hash value of resource |
filelocation | string | file location of resource |
filename | string | name of resource |
filesize | integer | size of resource |
filetype | string | media type of resource |
-
Query the uploaded resource information
GET v2/attachment/info?fileHash={fileHash}
Query the uploaded resource information。
Request Parameters
Name | Type | Required | Description |
---|---|---|---|
fileHash | string | Y | file hash returned by the interface after a successful upload |
Curl Request Example
curl --location --request GET 'https://developer.vetoolchain.com/api/v2/attachment/info?fileHash=e39549740cf40bc9c2ec82866efda33a7eeaba1e97e3dd3422289989b58bb28c' \
--header 'language: zh_hans' \
--header 'Content-Type: application/json;charset=utf-8' \
--header 'x-api-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJsb2dpbklkIjoiNWIwMWE5MmIzOGI3IiwiYXBwSWQiOiJhODJiN2I5MGNmMDE0ZDFhMDk5YzEzOTdmMzA5NzZiYyIsInNvdXJjZSI6ImFhYSIsImV4cCI6MTU5MzM0MDM5NCwiaWF0IjoxNTkzMjUzOTk0fQ.OcVyoPx9a4VAbLHAY4MYdDlRJpHnzChToMnXNZeIr-s'
Response Example
{
"code": "common.success",
"data":
{
"filehash": "56c9cbdb4fa51f2b247e0b4d6fbe4a6d1c6c7cecca2925b5b69d4e073e366ac4",
"filelocation": "/resource/56c9cbdb4fa51f2b247e0b4d6fbe4a6d1c6c7cecca2925b5b69d4e073e366ac4",
"filename": "jsonlist_cn.png",
"filesize": 36632,
"filetype": "png"
}
}
Response Parameters
Name | Type | Description |
---|---|---|
filehash | string | hash value of resource |
filelocation | string | file location of resource |
filename | string | name of resource |
filesize | integer | size of resource |
filetype | string | media type of resource |
-
Download attachment
GET v2/attachment/{fileHash}
Download resources
Request Parameters
Name | Type | Required | Description |
---|---|---|---|
fileHash | string | Y | file hash returned by the interface after a successful upload |
Curl Request Example
curl --location --request GET 'https://developer.vetoolchain.com/api/v2/attachment/e39549740cf40bc9c2ec82866efda33a7eeaba1e97e3dd3422289989b58bb28c' \
--header 'language: zh_hans' \
--header 'Content-Type: application/json;charset=utf-8' \
--header 'x-api-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJsb2dpbklkIjoiNzliM2VjZTVkY2VkIiwiYXBwSWQiOiJhODJiN2I5MGNmMDE0ZDFhMDk5YzEzOTdmMzA5NzZiYyIsInNvdXJjZSI6ImFhYSIsImV4cCI6MTU5MzQyNjg1MiwiaWF0IjoxNTkzMzQwNDUyfQ.WJ0oQEoWV7kSagzSUbarzlrbKHwAJRaOh7GUaG8-1v0'
Response Example
Response Parameters
-
Generate tag VID in batches
POST v2/vid/generate
Generate VID in batches, up to 2000 per request. The unique identifier of the request: requestNo, which is a random number generated by the requester, and the same identifier is treated as the same request.
Request Parameters
Name | Type | Required | Description |
---|---|---|---|
quantity | integer | Y | requested quantity, up to 2000 |
requestNo | string | Y | request number, length is no more than 50, only letters and numbers are allowed |
Request Example
{
"quantity": 10,
"requestNo": "20200607001"
}
Response Example
{
"code": "common.success",
"data": {
"quantity": 10,
"requestNo": "20200607001",
"url": "https://v3-dev.vechaindev.com/v1/artifacts/",
"vidList": [
"0XEA1451450015915098673EB9A02518F5AFFC42592F92ED3399B7A661DF1313DF",
"0XEA145145001591509867E59844F42B770406BD7C9BA1028D4C4BE39540B75A57",
"0XEA145145001591509867E4833C21A5E5ED518EBB5688A1B74C3C7D9AE1CA7F90",
"0XEA145145001591509867E52C417EA421C0E07D447B897BC571552470F62A1072",
"0XEA1451450015915098676C150F3533D2EC5948854AEDA21E7F2AA98D4EEDF51C",
"0XEA145145001591509867AC096082AEC0092DE7CC739C0227180CE96623C5E113",
"0XEA14514500159150986744A63EA4315493AFF6AF828A6BACBE854B8E6A85466F",
"0XEA14514500159150986702C02E1BDFF6F0B533C54B6F43D850F0F663CDD42133",
"0XEA145145001591509867551158F2DCD1DFB6292D4185D98373E8ACA430E2547B",
"0XEA14514500159150986738D8EB8957AD307F085977EB0A00A9586347BD710045"
],
"status": "SUCCESS"
}
}
Response Parameters
Name | Type | Description |
---|---|---|
quantity | string | requested quantity |
requestNo | string | request number |
url | string | VID access url |
vidList | array(string) | list of successfully requested VIDs |
status | string | request status(PROCESSING,SUCCESS) |
-
Register tag VID in batches
POST v2/vid/occupy
Register VID in batches, up to 100 per request. The unique identifier of the request: requestNo, which is a random number generated by the requester, and the same identifier is treated as the same request. This interface is usually used for customers to have their own specific code segment generation rules, ex: "0x202006FC01B101M666...", 202006 represents the production month, FC01 represents the code of the production plant, B101 represents the batch number, M666 represents the product model, etc.
Request Parameters
Name | Type | Required | Description |
---|---|---|---|
vidList | array(string) | Y | requested VID list, up to 100 |
requestNo | string | Y | request number, length is no more than 50, only letters and numbers are allowed |
Request Example
{
"requestNo": "20200607002",
"vidList": ["0XEA145145001591512024A585B1CAB44A74FE53692F4D69513A58BCA1CF5DCB22",
"0XEA145145001591512024A585B1CAB44A74FE53692F4D69513A58BCA1CF5DCB23"
]
}
Response Example
{
"code": "common.success",
"data": {
"failureList": [
"0XEA145145001591512024A585B1CAB44A74FE53692F4D69513A58BCA1CF5DCB22"
],
"successList": [
"0XEA145145001591512024A585B1CAB44A74FE53692F4D69513A58BCA1CF5DCB23"
],
"requestNo": "20200607002",
"url": "https://v3-dev.vechaindev.com/v1/artifacts/",
"status": "SUCCESS"
}
}
Response Parameters
Name | Type | Description |
---|---|---|
failureList | array(string) | failure list |
successList | array(string) | success list |
url | string | VID access url |
status | string | request status(PROCESSING,SUCCESS) |
requestNo | string | request number |
-
Query the latest on-chain information
POST v2/provenance/hash/query
For DCPs with on-chain records, you can query the latest on-chain record by VID.
Request Parameters
Name | Type | Required | Description |
---|---|---|---|
vid | string | Y | VID, starting at '0x', 32 bytes |
smartcontractId | string | N | smart contract address |
Request Example
{
"vid": "0xea1451450015915120247ed1dd9f1dc44f8ab2d6a15618adc85c112391c2c886"
}
Response Example
{
"code": "common.success",
"data":
{
"clauseIndex": 1,
"submitTime": 1591517456,
"dataHash": "03042cf8100db386818cee4ff0f2972431a62ed78edbd09ac08accfabbefd819",
"txId": "0x215804059e2ddc58261bbcbd31cbb09920773dca464d73efa998fdc24933a3b1"
}
}
Response Parameters
Name | Type | Description |
---|---|---|
txId | string | blockchain transaction ID |
dataHash | string | hash value , hex string |
submitTime | integer | time of on-chain |
clauseIndex | integer | clause index of this blockchain transaction ID |
-
Query historical on-chain information
POST v2/provenance/hash/queryHistory
For DCPs with on-chain records, you can query the historical on-chain record by VID. This interface is implemented by the logic of page turning query. For example, if you need to query the latest 120 pieces of data from the blockchain, you can use page=1, size=100, sort=desc and page=2, size=100, sort=desc to request the interface respectively, and get the first 20 pieces of data in the second request.. Similarly, you can also use page=1, size=60, sort=desc, and page=2, size=60, sort=desc to request the interface to obtain data twice.
Request Parameters
Name | Type | Required | Description |
---|---|---|---|
vid | string | Y | VID, starting at '0x', 32 bytes |
page | integer | Y | page number, ex: page 3 |
size | integer | Y | row number displayed per page, up to 100 |
sort | string | Y | blockchain on-chain time sorting (desc, asc) |
smartcontractId | string | N | smart contract address |
Request Example
{
"page": 1,
"size": 10,
"sort": "asc",
"vid": "0xea1451450015915120247ed1dd9f1dc44f8ab2d6a15618adc85c112391c2c886"
}
Response Example
{
"code": "common.success",
"data": {
"vid": "ea1451450015915120247ed1dd9f1dc44f8ab2d6a15618adc85c112391c2c886",
"smartcontractId": "3f6e5cda7baa4004b911446cfca76191",
"page": 1,
"history": [
{
"clauseIndex": 0,
"submitTime": 1591517456,
"dataHash": "03042cf8100db386818cee4ff0f2972431a62ed78edbd09ac08accfabbefd818",
"txId": "0x215804059e2ddc58261bbcbd31cbb09920773dca464d73efa998fdc24933a3b1"
},
{
"clauseIndex": 1,
"submitTime": 1591517456,
"dataHash": "03042cf8100db386818cee4ff0f2972431a62ed78edbd09ac08accfabbefd819",
"txId": "0x215804059e2ddc58261bbcbd31cbb09920773dca464d73efa998fdc24933a3b1"
}
],
"rows": 2
}
}
Response Parameters
Name | Type | Description |
---|---|---|
+ history | array(HashHistoryModel) | collection of on-chain history |
└ txId | string | blockchain transaction ID |
└ dataHash | string | hash value, hex string |
└ submitTime | integer | time of on-chain |
└ clauseIndex | integer | clause index of this blockchain transaction ID |
page | integer | page number |
rows | integer | total rows |
smartcontractId | string | smart contract address |
vid | string | VID |
Appendix
Q: How to get the appid and appkey of the project
A: Log in to the system with an administrator account, click Developer Center -> Server Application, and copy APPID and APPIKEY. Each account can support up to 10 pairs of appid and appkey
Q: How to get the operator ID
A: Log in to the system with an administrator account, click Console->Staff List in turn, find the corresponding user, click Details, and the account ID is the operator ID.
Q: How to get the DCP UUID
A: Log in to the system with an administrator account, clickWorkspace->Project List, find the project that needs to upload data, and then clickConfigure->View->Data collection points, find the DCP that needs to upload data, DCP UUID is UUID.
Q: How to get the project ID
A: Log in to the system with an administrator account, click Workspace ->Project List in turn, find the project that needs to be uploaded, and click Configure to get the ID.
Q: How to get DCP data template
A: Log in to the system with an administrator account, click Workspace->Project List, find the project that needs to upload DCP data, and click Configure->Download
Unzip the file to get all DCP data templates, the file name consists of DCP name and DCP UUID.
Different DCP data has different json data format, and customers need to find the corresponding json data format template and pass in the correct data as required.
Attribute | Description |
---|---|
required | if requried(true, false) |
min | the minimum value range, for the list, represents the number, for the textbox represents the character length, for the media resource such as pictures, videos, etc. represents the size (byte), for the integer represents value, need to be considered together with the max attribute |
max | the maximum value range, for the list, represents the number, for the textbox represents the character length, for the media resource such as pictures, videos, etc. represents the size (byte), for the integer represents value, need to be considered together with the min attribute |
must be | Mandatory assignment |
default value | default value |
label | the field name on the front-end page |
Each object in the json data format corresponds to a DCU control. The data types of different DCUs are as follows.
DCU control | Value type |
---|---|
Dropdown | string |
Boolean | boolean |
Date | integer(UTC time, accurate to day) |
Date time | integer(UTC time ,accurate to second) |
Float | float |
Integer | integer |
Long text | string |
Short text | string |
List Items | determined by the type of child control |
Container | determined by the type of child control |
GPS |
Combination type, including: "country": "//required=false && min=0.0 && max=255.0 && type=String", |
Audio |
Use the upload resource interface and fill it with the returned result Combination type, including: "filelocation": "//required=true && min=0.0 && max=255.0 && type=String && defaultValue=", |
File |
Use the upload resource interface and fill it with the returned result Combination type, including: "filelocation": "//required=true && min=0.0 && max=255.0 && type=String && defaultValue=", |
Image |
Use the upload resource interface and fill it with the returned result Combination type, including: "filelocation": "//required=true && min=0.0 && max=255.0 && type=String && defaultValue=", |
Video |
Use the upload resource interface and fill it with the returned result Combination type, including: "filelocation": "//required=true && min=0.0 && max=255.0 && type=String && defaultValue=", |
VID list |
Combination type, including: "num": "//required=false && min=1.0 && max=10000.0 && type=int", |
Combination type, including: "emailname": "//required=false && min=0.0 && max=100.0 && type=String && defaultValue= && label=Email Name", |
|
Website |
Combination type, including: "webpagelink": "//required=false && min=0.0 && max=255.0 && type=String && defaultValue= && label=Web Page Link", |
DCP reference |
Combination type, including: "datavid": "//required=false && min=66.0 && max=66.0 && type=String", |
Language Type
Language | Interface language |
---|---|
English | en |
中文简体 | zh-CN |
中文繁体 | zh-HK |
Deutsch | de |
日本語 | ja |
한국어 | ko |
Bahasa Melayu | ms |
italiano | it-CH |
français | fr-CH |
Türkçe | tr |
Русский | ru |
ไทย | th |
العربية | ar |
עברית | he |
Bahasa Indonesia | id |
Português | pt-br |
Tiếng Việt | vi |
Español | es |
Suomi kieli | fi |
Permission introduction
Permission | Description |
---|---|
View | View all project information |
Update | View all project information and update all user data |
Operate | View project's own information, create and update own information |
Audit | View all project information and verify data submitted by other users |
Admin | All of above |
Comments
0 comments
Please sign in to leave a comment.