Getting business data via OpenAPI

Obtaining access

Log in to the elven system, navigate to the entity where api access is required, go to the journals page, and click on the integrations button in the top right corner of the journals page.

In the pop-up integrations management window, click the “add new integration” button.

Name the new data type and click the “add” button.

Once the data type is added, you can add new data. click the “add data” button and select “openapi integration” from the drop-down menu.

In the api key/secret management window that pops up, click the “create” button.

In the next window, name the newly created api key.

Click the “create” button to complete the creation of the new api key. You can click the copy icon next to each key/secret to copy the contents to your clipboard for use.

Using api access

Provide the following parameters in the request header:

elven-api-key: obtained api key
elven-api-sign: base64-encoded signature, e.g., LVT5aXA9064gpgZrPXPLJB/Aq9r45yMF10sTZQTteyE=
elven-api-timestamp: timestamp in milliseconds, e.g., 1721209655047, expires after 30 seconds

The sign algorithm as follows: concatenate the timestamp, request method, and request route, then encrypt using hmac sha256 with the secret.

// uses the crypto library from https://github.com/nodejs/node/blob/v16.9.0/lib/crypto.js
/**
 * generate signature
 * apiSecret: BjGiqCWfHGCrl065dlEBWFO5vLj7Hqiexxx,
 * timestamp: 1721205912758
 * method: POST
 * path: /open/v3/businessData
 */
buildSign(apiSecret: string, timestamp: number, method: string, path: string) {
  const str = `${timestamp}${method}${path}`
  return crypto.createHmac('sha256', apiSecret).update(str).digest('base64')
}

Example:

// example parameters
[
  'D7JLJ3awwrTdNXtSrPI1GlYE', // key
  'BjGiqCWfHGCrl065dlEBWFO5vLj7Hqie', // secret
  'POST', // method, must be uppercase
  '/open/v3/businessData' // path, must start with '/'
]

// headers
{
  'elven-api-key': 'D7JLJ3awwrTdNXtSrPI1GlYE',
  'elven-api-sign': 'LVT5aXA9064gpgZrPXPLJB/Aq9r45yMF10sTZQTteyE=',
  'elven-api-timestamp': 1721209655047
}

Uploading business data

// API uses application/json to transmit data, data size is 100KB.
// if it exceeds 100KB, limit the number of data entries or contact elven for resolution.
POST https://openapi.elven.com/open/v3/businessData

header:
{
  elven-api-key: aaaa
  elven-api-sign: bbbbbbbbbbbb
  elven-api-timestamp: 22222222
}

body:
{
  businessDataTypeName: 'Settlement', // created in product
  businessDataSourceName: 'Settlement-2024-07', // created or not in openapi
  businessDataList: [
      {"a": 100, "b": "buy", "c": "2024-07-01 22:33:44"},
      {"a": 100, "b": "sell", "c": "2024-07-01 23:33:44"},
      {"a": 100, "b": "buy", "c": "2024-07-02 06:33:44"},
  ]
}