Fetching the information about files

  1. Start the Python shell and configure its session.

    The following variables should be available now:

    >>> base_url  # the base URL of the API
    'https://eu2-cloud.acronis.com/api/notary/v2'
    >>> auth  # the 'Authorization' header value with the access token
    {'Authorization': 'Bearer 8770b34b74f9e4d9424eff50c38182bb4ae7f5596582ae61900b1b6a23e3ec58'}
    
  2. Fetch the information about all your files uploaded to the notary storage by sending a GET request to the /stored-files endpoint:

    >>> response = requests.get(f'{base_url}/stored-files', headers=auth)
    

    The list of files to fetch can be configured by using the URL parameters. By default, the first twenty files are fetched from the storage. Refer to the API reference for more details.

  3. Check the status code of the response:

    >>> response.status_code
    200
    

    Status code 200 means that the notary service has fetched the information about the required files.

    A different status code means that an error has occurred. For the details, refer to “Status and error codes”.

    Also, the response body contains the files key containing an array of file details objects formatted as a JSON text. When converted to an object, it will look as follows:

    >>> pprint.pprint(response.json())
    {'files': [{'certificate': {'contract': '0xd10e3Be2bc8f959Bc8C41CF65F60dE721cF89ADF',
                                'id': '59dc41af270b017ac9b4d94643f7f20264e0078fadec6d529fa8d9f7d304c5b7',
                                'merkle_proof': '[{"right":"b92a52842f30275afb855990b11679b170fabeeebd8979c990554be51922c987"}]',
                                'merkle_root': 'db5bdbf35608852e3e10b91fb044ad4d703926245241d532b25a64f412e14135',
                                'object': {'eTag': '67458ab9ba0bb494062f6f0b40ada5098200cb4dcc83efa22ba28aca6b6eff2c',
                                           'key': 'contract_notarized.pdf',
                                           'sequencer': '9e756148cf1315f782',
                                           'size': 6518},
                                'blockchain': 'eth',
                                'sender': '0x201354729f8d0f8b64e9a0c353c672c6a66b3857',
                                'timestamp': 1573572432,
                                'txid': '0x6494a098f6487ebbcfa85b7cbe64c1f9f077f03866477b67be64320ea109fa73'},
                'certificate_id': '59dc41af270b017ac9b4d94643f7f20264e0078fadec6d529fa8d9f7d304c5b7',
                'created_at': '2019-11-11T13:07:05.638572Z',
                'etag': '67458ab9ba0bb494062f6f0b40ada5098200cb4dcc83efa22ba28aca6b6eff2c',
                'etag_type': 'sha256',
                'id': 'cc3ecc8d-de0e-4809-8bc2-3a6368110824',
                'name': 'favicon.ico',
                'size': 6518,
                'updated_at': '2019-11-11T13:07:07.003639Z'
                'esign': {'embedded': False}},
               {'created_at': '2019-11-11T13:08:35.774437Z',
                'document': {'certificate_id': 'fa36a19f8434020e96ca1248ad8fd0738d821f1fedcd2f7954d0ab22b8a58568',
                             'id': '8eb2c5179b84a1b97a4f69eb0e97b4e910a1eace1b781926f83ee964f12e6922',
                             'signed_at': '2019-11-11T13:54:47.066903Z',
                             'signature_certificate_link': '/doc/8eb2c5179b84a1b97a4f69eb0e97b4e910a1eace1b781926f83ee964f12e6922/download',
                             'notarization_certificate_link': '/certificate/fa36a19f8434020e96ca1248ad8fd0738d821f1fedcd2f7954d0ab22b8a58568',
                             'signees': [{'email': 'johncustomer@mysite.com',
                                          'fullname': 'John Doe',
                                          'id': '867139bf-30ca-4c83-8683-a30c5db57046',
                                          'owner': True,
                                          'signed_at': '2019-11-11T13:54:38.619811Z'},
                                         {'email': 'foobar@newcompany.com',
                                          'fullname': 'Foo Bar',
                                          'id': '32ff6407-605c-4203-a611-34deb036cda4',
                                          'owner': False,
                                          'signed_at': '2019-11-11T13:54:47.066903Z'}]},
                'document_id': '8eb2c5179b84a1b97a4f69eb0e97b4e910a1eace1b781926f83ee964f12e6922',
                'etag': '67458ab9ba0bb494062f6f0b40ada5098200cb4dcc83efa22ba28aca6b6eff2c',
                'etag_type': 'sha256',
                'id': '5d7240a4-8c16-47e0-9d5e-39616ba32c9c',
                'name': 'contract_signed.pdf',
                'size': 6518,
                'updated_at': '2019-11-11T13:08:42.651235Z',
                'esign': {'embedded': False}}]}
    

All file objects contain the following information:

  • The file name, size, upload time, and unique ID in the name, size, created_at, and id keys respectively.

  • The hash value of the file contents in the etag key and the algorithm used to calculate this value in the etag_type key.

Objects of files uploaded for notarization contain a unique ID of the created notarization certificate in the certificate_id key and the certificate details in the certificate key.

Empty contract, merkle_proof, merkle_root, sender, and txid keys in the notarization certificate mean that the file notarization is still in progress. If the notarization is complete, the keys will contain the Ethereum transaction details and the timestamp key will contain the Unix time when the file hash was written to the blockchain.

Objects of files uploaded for electronic signature contain a unique ID of the created signature certificate in the document_id key and some of the certificate details in the document key.

An empty array in the signees key of the e-sign document means that the file is uploaded to the storage, but its signing has not started yet. If the array is not empty but the signed_at key is None, then the file is still being signed. If the file is signed, the certificate_id key of the signature certificate will contain the ID of the notarization certificate created for the generated PDF file of the signature certificate. You may track the notarization status of this file by sending the GET request to the /certificates/{certificate_id} endpoint and inspecting the certificate details.

You may fetch the full details of the e-sign document by sending the GET request to the /documents/{doc_id} endpoint. This is the preferred method of tracking the signature status because these details will contain a special key reflecting the status.

Full code example

 1#!/usr/bin/env python3
 2
 3import requests  # Will be used for sending requests to the API.
 4import hashlib   # Will be used for calculating hash values.
 5import os.path   # Will be used for path-related operations.
 6import pprint    # Will be used for formatting the output of JSON objects received in API responses.
 7import json      # Will be used for converting dictionaries into JSON text
 8
 9# Define variables named "LOGIN" and "PASSWORD" and then assign them with your account credentials
10LOGIN = '<your login>'        # Change login here
11PASSWORD = '<your password>'  # Change password here
12
13# Define a variable named "cloud_url" and then assign it with the URL of the cloud platform
14cloud_url = 'https://cloud.acronis.com'
15
16# Fetch the URL of the data center where your account is located by sending a GET request to the "/api/1/accounts" endpoint
17response = requests.get(
18    f'{cloud_url}/api/1/accounts',
19    params={'login': LOGIN}
20)
21response.raise_for_status()
22
23# Convert the JSON text that the response body contains to a dictionary and store the data center URL
24# in a variable that will be used in further requests
25server_url = response.json()['server_url']
26
27# Define a variable named "account_creds", and then assign the username and password to this variable
28account_creds = {
29    'username': LOGIN,
30    'password': PASSWORD
31}
32
33# Generate a token by sending a POST request to the "/api/2/idp/token" with your account credentials to the cloud platform
34response = requests.post(
35    f'{server_url}/api/2/idp/token',
36    headers={'Content-Type': 'application/x-www-form-urlencoded'},
37    data={'grant_type': 'password', **account_creds}
38)
39response.raise_for_status()
40
41# Convert the JSON text that the response body contains to a dictionary and then assign it to a variable named "token_info"
42token_info = response.json()
43
44# Define a variable named "auth" and then assign it with a dictionary with "Authorization" key containing
45# token string formatted as "Bearer <access_token>"
46auth = {
47    'Authorization': 'Bearer ' + token_info['access_token']
48}
49
50# Define a variable named "base_url", and then assign the API base URL using the data center URL
51# to this variable
52base_url = f'{server_url}/api/notary/v2'
53
54# Fetch the information about all files in your notary storage by sending a GET request to the "/stored-files" endpoint
55response = requests.get(f'{base_url}/stored-files', headers=auth)
56response.raise_for_status()