Interface

Attestations - /attestations

When member created the template on Baoquan.com, he/she/it can send data, which is required by consummating the template, through this interface.

payload

Parameter name	Description	Mandatory/Optional
unique_id	String, the unique id of attestation, length < 255	Mandatory
template_id	String, the ID of template	Mandatory
identities	Object, item for identities	Mandatory
factoids	Array, factoids set	Optional
completed	Boolean value, whether factoids set is uploaded successfully	Optional, default is true
attachments	Array, information object of attachments, optional	Optional

unique_id is the unique code of attestation, which prevent from repeat upload same attestation cause by network timeout or other exceptions. If an attestation uploads several times, we just save once, and return the same attestion id.

Factoid is an Object, which contains two fields: “type”, “data”, for example:

{
        "unique_id": "9de7be94-a697-4398-945a-678d3f916b9f",
        "type": "hash",
        "data": {
                "userName": "David Smith",
                "idCard": "42012319800127691X"
        }
}

The “unique_id” of factoid is similar to the “unique_id” of attestation. If the same factoid contents upload several times at the one attestation, we just handle once.

The “type” is the user defined name of factoids, “data” is the field value of factoids, as following：

The template contains two factoids: “common” and ”hash”. attestation_no, attestation_at, product_name, organization_name in the “common” are provided by Baoquan.com when you are consummating the template. “hash” is defined by members selves, therefore, ,members need to upload that through API.

Template could contain multiple customisable factoids, for example, factoA and factoB. Members could choose to upload twice separately: upload factoA first and set “completed” to false, and then upload factoB again, set “completed” to true.

Note

Once “completed” has been set to true, no more factoids uploading will be accepted.

Assume payload is as below:

{
        "unique_id": "acafa00d-5579-4fe5-93c1-de89ec82006e",
        "template_id": "2hSWTZ4oqVEJKAmK2RiyT4",
        "identities": {
                "MO": "15857112383",
                "ID": "42012319800127691X"
        },
        "factoids": [
                {
                        "unique_id": "9de7be94-a697-4398-945a-678d3f916b9f",
                        "type": "hash",
                        "data": {
                                "userName": "Richard Hammond",
                                "idCard": "330124199501017791",
                                "buyAmount": 0.3,
                                "incomeStartTime": "2015-12-02",
                                "incomeEndTime": "2016-01-01",
                                "createTime": "2015-12-01 14:33:44",
                                "payTime": "2015-12-01 14:33:59",
                                "payAmount": 600
                        }
                }
        ],
        "completed": true
}

After Attestations, you can check the consummated content on Baoquan.com by reference number. As shown below:

Attachments

When you uploading the factoids data, you can upload attachments related to the factoids simultaneously. In payload, the “attachments” store the check code of attachments.

Upload a single attachment as “form” data:

<form method='post' enctype='multipart/form-data'>
  ...
  <input type=file name="attachments[0][]">
</form>

payload = {
        "unique_id": "...",
        "template_id": "...",
        "identities": {...},
        "factoids": [
                {
                        "unique_id": "...",
                        "type": "...",
                        "data": {...}
                }
        ],
        "completed": true,
        "attachments": {
                "0": ["checkSum"]
        }
}

Upload multiple attachments as “form” data:

<form method='post' enctype='multipart/form-data'>
  ...
  <input type=file name="attachments[0][]">
  <input type=file name="attachments[0][]">
  <input type=file name="attachments[1][]">
</form>

payload = {
        "unique_id": "...",
        "template_id": "...",
        "identities": {...},
        "factoids": [
                {
                        "unique_id": "...",
                        "type": "...",
                        "data": {...}
                },
                {
                        "unique_id": "...",
                        "type": "...",
                        "data": {...}
                }
        ],
        "completed": true,
        "attachments": {
                "0": [
                        "checkSum1",
                        {
                                "checksum": "checkSum2",
                                "sign": {
                                        "F98F99A554E944B6996882E8A68C60B2": ["Party A (signature)", "Party A juristische Person (signature)"],
                                        "0A68783469E04CAC95ADEAE995A92E65": ["Party B (signature)"]
                                }
                        }
                ],
                "1": ["checkSum3"]
        }
}

The “key” of “attachments” is referring as the superscript of the factoids array， for example, “0” correspond with factoids[0]. The “value” of “attachments” is an array, each element correspond with attachment information.

There are two kinds of attachment informations: checksum and sign information, and you must offer checksum. While attachment information contain checksum, you can use String object; While attachment information contain sign information, you need to use object instead.

Note

only pdf attachment can make sign.

The “checksum” is generated from file by SHA256, take Java as an example:

String file = "/path/to/file";
InputStream in = new FileInputStream(new File(file));

// Use SHA256 to hash the file
bytes[] digestBytes = DigestUtils.getDigest("SHA256").digest(StreamUtils.copyToByteArray(in));

// Transform bytes into hexadecimal
String checkSum = Hex.encodeHexString(digestBytes);

Sign is an object, the “key” is caId (when member apply Certification, it will return caId), the “value” is the sign keyword array. For example, Richard and Edward would like to sign at “xxx.pdf” paper, Richard call ca interface to get the caId is “F98F99A554E944B6996882E8A68C60B2”, Edward call ca interface to get the caId is “0A68783469E04CAC95ADEAE995A92E65”, then Richard need to sign at “Party A (signature)” and “Party A juristische Person (signature)”, and Edward need to sign at “Party B (signature)”, so the sign object is like following:

"sign": {
        "F98F99A554E944B6996882E8A68C60B2": ["Party A (signature)", "Party A juristische Person (signature)"],
        "0A68783469E04CAC95ADEAE995A92E65": ["Party B (signature)"]
}

Note

One user can sign at different sign channel, but keyword should be keep the same, and can’t repeat with the body part.

Returned data

When Attestation interface is requested successfully, the reference number will be returned.

Field name	Description
no	String, reference number of the attestation

For example:

{
        "request_id": "2XiTgZ2oVrBgGqKQ1ruCKh",
        "data": {
                "no": "rBgGqKQ1ruCKhXiTgZ2oVr",
        }
}

Add factoids - /factoids

Members could use Factoids interface to upload more factoids set.

payload

Parameter name	Description	Mandatory/Optional
ano	String, the ID of attestation	Mandatory
factoids	Array, factoids set	Mandatory
completed	Boolean value, whether factoids set is uploaded successfully	Optional, default is true
attachments	Array, checksum code of attachments, optional	Optional

For example:

{
        "ano": "2hSWTZ4oqVEJKAmK2RiyT4",
        "factoids": [
                {
                        "unique_id": "9de7be94-a697-4398-945a-678d3f916b9f",
                        "type": "hash",
                        "data": {
                                "userName": "Edward Snow",
                                "idCard": "330124199501017791",
                                "buyAmount": 0.3,
                                "incomeStartTime": "2015-12-02",
                                "incomeEndTime": "2016-01-01",
                                "createTime": "2015-12-01 14:33:44",
                                "payTime": "2015-12-01 14:33:59",
                                "payAmount": 600
                        }
                }
        ],
        "completed": false
}

Returned data

Field name	Description
success	Boolean, whether successful or not

For example:

{
        "request_id": "2XiTgZ2oVrBgGqKQ1ruCKh",
        "data": {
                "success": true,
        }
}

Get attestation data - /attestation

Member can get get the upload attestation data through this API, such as identities, factoids, etc.

payload

Parameter name	Description	Mandatory/Optional
ano	String, reference number of the attestation	Mandatory
fields	Array, returned fields	Optional, default is true

Get attestation data such as identities, factoids, attachments should take a long time to access database and decode data, so you can choose which fields you want to return.

Returned data

Parameter name	Description
no	Reference number of the attestation
template_id	The ID of template
identities	Identities
factoids	List of factoids
completed	Return true if factoids is uploaded, or return fasle.
attachments	List of attachments
blockchain_hash	The hash of blockchain, return null if it doesn’t link to blockchain yet

attachments is an array, which The “key” of “attachments” is referring as the superscript of the factoids array, and the “value” is an attachment array.

（1）When fields set null, we will get all data, the result is as below:

{
        "request_id": "2XiTgZ2oVrBgGqKQ1ruCKh",
        "data": {
                "no": "DB0C8DB14E3C44C7B9FBBE30EB179241",
                "unique_id": "acafa00d-5579-4fe5-93c1-de89ec82006e",
                "template_id" : "5Yhus2mVSMnQRXobRJCYgt",
                "identities": {
                        "ID": "42012319800127691X",
                        "MO": "15857112383"
                },
                "factoids": [
                        {
                                "unique_id": "28fcdf56-bff3-4ed9-9f87-c8d35ad49e0c",
                                "type": "product",
                                "data": {
                                        "name:: "zjmax",
                                        "description": "p2g financing platform""
                                }
                        },
                        {
                                "unique_id": "e68eb8bc-3d7a-4e22-be47-d7999fb40c9a",
                                "type": "user",
                                "data": {
                                        "name": "David Smith",
                                        "phone_number": "13234568732",
                                        "registered_at": "1466674609",
                                        "username": "tom"
                                }
                        }
                ],
                "completed": true,
                "attachments": {
                        "1": [
                                "2EHJQPs5j4SZpEKQXQ7r6C",
                                "2F81ZJXosNjzrPJsXKywAu"
                        ]
                },
                "blockchain_hash": "s5j4SZpEKQXQ7r6C2F81ZJXosNjzrPJsXKywAu"
        }
}

（2）When fields set an empty array, it doesn’t return the values of identities, factoids and attachments, the result is as below:

{
        "request_id": "2XiTgZ2oVrBgGqKQ1ruCKh",
        "data": {
                "no": "DB0C8DB14E3C44C7B9FBBE30EB179241",
                "unique_id": "acafa00d-5579-4fe5-93c1-de89ec82006e",
                "template_id" : "5Yhus2mVSMnQRXobRJCYgt",
                "identities": null,
                "factoids": null,
                "completed": true,
                "attachments": null,
                "blockchain_hash": "s5j4SZpEKQXQ7r6C2F81ZJXosNjzrPJsXKywAu"
        }
}

So when you want to get the hash of blockchain immediately, it’s best way to set field as an empty array.

（3）When fields set an array, such as [“identities”], the result is as below:

{
        "request_id": "2XiTgZ2oVrBgGqKQ1ruCKh",
        "data": {
                "no": "DB0C8DB14E3C44C7B9FBBE30EB179241",
                "unique_id": "acafa00d-5579-4fe5-93c1-de89ec82006e",
                "template_id" : "5Yhus2mVSMnQRXobRJCYgt",
                "identities": {
                        "ID": "42012319800127691X",
                        "MO": "15857112383"
                },
                "factoids": null,
                "completed": true,
                "attachments": null,
                "blockchain_hash": "s5j4SZpEKQXQ7r6C2F81ZJXosNjzrPJsXKywAu"
        }
}

Download the attestation file - /attestation/download

When member upload data to Baoquan, we should take some certain process(rendered by template) to create a Baoquan file. a Baoquan file will be eventually hashed to the blockchain, so it can eventually make a notarised certificate at notary office or make a judicial report at judicial evaluation center.

payload

Parameter name	Description	Mandatory/Optional
ano	String, reference number of the attestation	Mandatory

Returned file

This interface will get the Baoquan file and filename. The file is body of the result of http message, and the filename is header of http message. Content=Disposition is the header name. The value of header is like below:

form-data; name=Content-Disposition; filename=5Yhus2mVSMnQRXobRJCYgt.zip

As Java for example:

// ommit using apache http client to create http request
// closeableHttpResponse is an instance of CloseableHttpResponse
HttpEntity httpEntity = closeableHttpResponse.getEntity();
Header header = closeableHttpResponse.getFirstHeader(MIME.CONTENT_DISPOSITION);
Pattern pattern = Pattern.compile(".*filename=\"(.*)\".*");
Matcher matcher = pattern.matcher(header.getValue());
String fileName = "";
if (matcher.matches()) {
        fileName = matcher.group(1);
}
FileOutputStream fileOutputStream = new FileOutputStream(fileName);
IOUtils.copy(httpEntity.getContent(), fileOutputStream)

Apply for Certification - /cas

If the attachment of attestation need to sign, you must apply for Certification.

payload

Parameter name	Description	Mandatory/Optional
type	String，user type：PERSONAL、ENTERPRISE	Mandatory
name	enterprise name	Mandatory when user type is ENTERPRISE
ic_code	enterprise Register Code or Unified Social Credit Code	Mandatory when user type is ENTERPRISE
org_code	enterprise oragnization code	Mandatory when user type is ENTERPRISE
tax_code	enterprise tax code	Mandatory when user type is ENTERPRISE
link_name	user name or enterprise contact user name	Mandatory
link_id_card	user ID card or enterprise contact user ID card	Mandatory
link_phone	user phone number or enterprise contact user phone number	Mandatory
link_email	user mail or enterprise contact user mail	Mandatory

Apply for personal certification:

{
        "type": "PERSONAL",
        "link_name": "Richard Hammond",
        "link_id_card": "330184198501184115",
        "link_phone": "13378784545",
        "link_email": "123@qq.com"
}

If enterprise has “three in one” situation, you should use Unified Social Credit Code:

{
        "type": "ENTERPRISE",
        "name": "xxx Co., Ltd.",
        "ic_code": "91332406MA27XMXJ27",
        "link_name": "Richard Hammond",
        "link_id_card": "330184198501184115",
        "link_phone": "13378784545",
        "link_email": "123@qq.com"
}

If not, then use business registration code, organization code, tax code to apply for certification:

{
        "type": "ENTERPRISE",
        "name": "xxx Co., Ltd.",
        "ic_code": "419001000033792",
        "org_code": "177470403",
        "tax_code": "419001177470403",
        "link_name": "Richard Hammond",
        "link_id_card": "330184198501184115",
        "link_phone": "13378784545",
        "link_email": "123@qq.com"
}

returned data

Description	Description
no	caId

For example:

{
        "request_id": "2XiTgZ2oVrBgGqKQ1ruCKh",
        "data": {
                "no": "F98F99A554E944B6996882E8A68C60B2",
        }
}