Process API List – VeChain ToolChain™ Help Center

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
&timestamp=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 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", "address": "//required=false && min=0.0 && max=300.0 && type=String", "province": "//required=false && min=0.0 && max=255.0 && type=String", "city": "//required=false && min=0.0 && max=255.0 && type=String", "street": "//required=false && min=0.0 && max=255.0 && type=String", "district": "//required=false && min=0.0 && max=255.0 && type=String", "lon": "//required=true && min=-180.0 && max=180.0 && type=float", "lat": "//required=true && min=-90.0 && max=90.0 && type=float"
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=", "filetype": "//required=true && min=0.0 && max=255.0 && type=String && defaultValue=", "filename": "//required=true && min=0.0 && max=255.0 && type=String && defaultValue=", "filesize": "//required=true && min=0.0 && max=1.0E8 && type=String && defaultValue=", "filehash": "//required=true && min=64.0 && max=64.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=", "filetype": "//required=true && min=0.0 && max=255.0 && type=String && defaultValue=", "filename": "//required=true && min=0.0 && max=255.0 && type=String && defaultValue=", "filesize": "//required=true && min=0.0 && max=1.0E8 && type=String && defaultValue=", "filehash": "//required=true && min=64.0 && max=64.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=", "filetype": "//required=true && min=0.0 && max=255.0 && type=String && defaultValue=", "filename": "//required=true && min=0.0 && max=255.0 && type=String && defaultValue=", "filesize": "//required=true && min=0.0 && max=1.0E8 && type=String && defaultValue=", "filehash": "//required=true && min=64.0 && max=64.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=", "filetype": "//required=true && min=0.0 && max=255.0 && type=String && defaultValue=", "filename": "//required=true && min=0.0 && max=255.0 && type=String && defaultValue=", "filesize": "//required=true && min=0.0 && max=1.0E8 && type=String && defaultValue=", "filehash": "//required=true && min=64.0 && max=64.0 && type=String && defaultValue="
VID list	Combination type, including: "num": "//required=false && min=1.0 && max=10000.0 && type=int", "type": "//required=true && min=0.0 && max=2.0 && type=int", There are currently 2 types , 0 means VID, 1 means Customer ID, please check here for the registration of Customer ID "vidlist": ["//required=true && min=66.0 && max=66.0 && type=String"]
Email	Combination type, including: "emailname": "//required=false && min=0.0 && max=100.0 && type=String && defaultValue= && label=Email Name", "emailaddress": "//required=false && min=0.0 && max=255.0 && type=String && defaultValue= && label=Email"
Website	Combination type, including: "webpagelink": "//required=false && min=0.0 && max=255.0 && type=String && defaultValue= && label=Web Page Link", "webpagename": "//required=false && min=0.0 && max=100.0 && type=String && defaultValue= && label=Web Page Name"
DCP reference	Combination type, including: "datavid": "//required=false && min=66.0 && max=66.0 && type=String", "datahash": "//required=false && min=64.0 && max=64.0 && type=String", "datauuid": "//required=true && min=36.0 && max=36.0 && type=String", "clauseindex": "//required=false && min=0.0 && max=null && type=int", "txid": "//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

Overview

Request URL

Request Header

Result Code

Terms

Idempotent

Order status

Get Token

Create DCP data

Update DCP data

Query the latest DCP data

Query DCP data list

Upload attachment

Query the uploaded resource information

Download attachment

Generate tag VID in batches

Register tag VID in batches

Query the latest on-chain information

Query historical on-chain information

Appendix

Each object in the json data format corresponds to a DCU control. The data types of different DCUs are as follows.

Language Type

Permission introduction

Related articles