Create a new reading - Enectiva REST API

This endpoint enables clients to add new readings to Enectiva. Each reading is sent in a separate HTTP request. The client can send the readings with any frequency but there really is no point in sending more than one reading per minute per meter. Sending readings from multiple servers might hit rate limiting limits.

Readings should be sent in chronological order and at constant intervals if possible. Older readings will be accepted, but might not be used by Enectiva.

Each reading is validated against these rules:

time, state and import_id are required fields and must be non-empty

time must conform to format defined in RFC3339, the time will be truncated to whole seconds

import_id is limited to 255 characters, it is case-sensitive, must not contain spaces

state has to be a floating point number; we recommend sending only reasonable number of digits after the decimal point

unit is an optional attribute limited to 50 case-sensitive characters; we recommend sending it when available because it is useful when debugging

sender is a case-sensitive string limited to 255 characters used for debugging and verification

suit is an optional string identifying the series of readings, if not provided default will be used, must not contain spaces

reading must be in the past

Each reading might be flagged as suspicious by the API and not processed further to avoid problems further down the line. The typical cause for flagging is an unexpected unit or a sudden growth of the state (by orders of magnitude). If readings are flagged incorrectly, please let us know.

Readings can be sent for any meter without any prior setup. The client is responsible for keeping the meter IDs unique. The same meter IDs are then used in Enectiva to identify the source of readings. In case multiple series of values are associated with a single meter ID, they can be differentiated with suit field.

For testing integration of a new client, we recommend using dummy meter IDs (e.g. test).

Repeated attempts to insert an identical reading (the same import_id, suit, time and state) result in 409 status code. Client must stop sending the same reading over and over again (and move to the next one), not doing so would result in a stuck import series and potentially rate limiting.

This endpoint requires an import token, not an access token.

Request

Authorization

OAuth 2.0

Authorization Code

Add the parameter

Authorization

to Headers，whose value is to concatenate the Token after the Bearer.

Example:

Authorization: Bearer ********************

Authorize URL: https://app.enectiva.cz/en/api/dashboard

Token URL: No token URL is provided. Use "Import token" from the Auth URL

Path Params

Header Params

Body Params application/vnd.api+json

Example

{
  "data": {
    "id": 1,
    "attributes": {
      "time": "2015-11-18T09:54:23+01:00",
      "state": 123456.78,
      "import_id": "40AABB_007",
      "unit": "kW",
      "suspicious": false,
      "customer_uuid": "11e7e767-6f74-4994-b607-158ff7f7445e",
      "sender": "test_script_01",
      "suit": "default"
    },
    "type": "readings"
  }
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢201Created

application/vnd.api+json

Created

Body

Example

{
    "data": {
        "attributes": {
            "customer_uuid": "11e7e767-6f74-4994-b607-158ff7f7445e",
            "import_id": "40AABB_007",
            "sender": "test_script_01",
            "state": 123456.78,
            "suit": "default",
            "suspicious": false,
            "time": "2015-11-18T09:54:23+01:00",
            "unit": "kW"
        },
        "id": 1,
        "type": "readings"
    }
}

🟠400Bad Request

🟠401Unauthorized

🟠406Not Acceptable

🟠409Conflict

🟠415Unsupported Media Type

🟠429Too Many Requests

🔴500Server Error