Skip to main content

Process API List

VeChain
  • Updated
Follow

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

  • 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 instance 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 UUID, 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)

  • 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 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 instance 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 UUID, 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)

  • 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 instance UUID, please refer to here
projectUUID string Y project UUID, 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 instance 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 instance 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 instance UUID, please refer to here
dcpName string N DCP record name when creating or updating DCP data（ex: sku name)
startTime integer N filter the start time of DCP data based on update time
endTime integer N filter the end time of DCP data based on 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 UUID, 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 instance id 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 instance 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. The maximum size allowed by the current system is 30mb.
Postman settings are as follows:
POSTMAN_FILE.png

Supported media types are as follows:

Media type File format
data ["json"]
image ["jpeg","jpg","png","jpe","ico","gif"]
vedio ["mp4","3gp","avi","m3u8","mp3","rmvb"]
file ["xls","csv","doc","xlsx","txt","docx","md","wps","ppt","pptx","pdf"]
zip ["zip"]

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

appidappkey_en.png

 

Q: How to get the operator ID

A: Log in to the system with an administrator account, click Project Management->User Management in turn, find the corresponding user, click Details, and the account ID is the operator ID.

OPUUID_EN.png

 

Q: How to get the DCP UUID

A: Log in to the system with an administrator account, click Project Management->Project List, find the project that needs to upload data, and then click Details->View->Data collection points, find the DCP that needs to upload data, DCP InstanceUUID is UUID.

DCPUUID_EN.png

 

Q: How to get the project UUID

A: Log in to the system with an administrator account, click Project Management -> Project List in turn, find the project that needs to be uploaded, and click Details to get the UUID.

PROJECTUUID_EN.png

 

Q: How to get DCP data template

A: Log in to the system with an administrator account, click Project Management->Project List, find the project that needs to upload DCP data, and click Details->Download

downloadprocess_en.png

Unzip the package to get all DCP data templates

jsonlist_en.png

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), 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), 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(Accurate to second）
Date time integer(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

 

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

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

Related articles

Comments

0 comments

Please sign in to leave a comment.