API

English

Voraussetzungen

Die Grundfunktionen der API sind im Basic-Model für nicht kommerzielle Nutzung verfügbar.
Für kommerzielle Nutzung und höherem Rate-Limit ist die Professional Lizenz nötig.

API Beschreibung

OAuth 2.0 (empfohlen)

Echtzeit-API (Webhook)

Goldpartner - API

Beispiele

API Beschreibung

Die API-Schnittstelle ermöglicht den einfachen und sicheren Zugriff auf die Daten von smart-me Geräten und der Plattform. Über diese Schnittstelle können Verbrauchsdaten, Gerätestatus, Messwerte und weitere Informationen in Echtzeit abgerufen und in externe Systeme integriert werden.

Alle API Calls sind auf folgender Seite dokumentiert: smart-me API

Obis Codes

Obis Codes sind standardisierte Kennzeichnungen für Messwerte in Energiezählern. Jeder Obis Code beschreibt eindeutig, welcher Wert gemessen wird (z.B. aktueller Stromverbrauch, Zählerstand, Spannung pro Phase).

Obis Codes (Excel)

Tipp zur Entschlüsselung: Auf dieser Website kannst du die Systematik der Codierung nachlesen. Wenn du dort auf ein Medium klickst, siehst du, für was die Ziffern des Codes jeweils stehen.

Authentifizierung

Basic Auth (nicht empfohlen / veraltet)

Aktuell ist Basic Auth als Authentifizierung möglich. Diese Option wird aber mittelfristig aufgrund mangelnder Sicherheit entfernt. Als Alternative bieten sich API Keys an.
Das Client secret ist username:password im Base64 encodiert.

Jeder Aufruf der API muss die Authentifizierung im HTTP Header enthalten: Authorization: Basic <client secret>

Beispiel:
curl -X "PUT" "https://api.smart-me.com/Devices/6a7fae30-c598-4778-8f1f-a14620550274" -H "accept: */*" -H "Authorization: Basic d2VyX2Rhc19sZXNlbl9rYW5uOmhhdF96dXZpZWxfemVpdA=="

API Keys (empfohlen)

API-Keys erlauben eine ähnliche Authentifizierung wie Basic Auth für einen einfachen Zugang zu einem Konto. Hierbei wird ein Key im Smart-me Portal erstellt und gewisse Berechtigungen (Claims (siehe unten)) gegeben. Der Key kann dann ähnlich dem Basic Auth secret im HTTP Header hinzugefügt werden.

Jeder Aufruf der API muss die Authentifizierung im HTTP Header enthalten: Authorization: ApiKey <api key>

Beispiel:
curl -X "PUT" "https://api.smart-me.com/Devices/6a7fae30-c598-4778-8f1f-a14620550274" -H "accept: */*" -H "Authorization: ApiKey MTRH5eUjFXV8U4i1viZF2jHNoUNsnDTx"

Key können im Web Portal unter API, Api Keys erstellt werden:

Claims

Sowohl ApiKeys wie auch oAuth 2.0 unterstützen Claims um nur limitierte Berechtigungen frei zu geben.

Eine Liste der Endpunkte zu Claims mapping, finden sie hier:

Claims

OAuth 2.0 (empfohlen)

smart-me unterstützt das Autorisierungsframework OAuth 2.0. Externe Anwendungen können den Zugriff auf ein Konto beantragen, ohne die Anmeldedaten zu kennen. Weitere Informationen findest du weiter unten.

OAuth Informationen

smart-me unterstützt das Autorisierungsframework OAuth 2.0. Externe Anwendungen können den Zugriff auf ein Konto beantragen, ohne die Anmeldedaten zu kennen.

Einrichtung OAuth im smart-me Portal

Voraussetzungen für die Nutzung von oAuth ist ein Konto mit dem Lizenzmodell professional. Solltest du noch kein Konto mit dem Lizenzmodell Professional haben, musst du 1 Lizenz erwerben.

Login im smart-me Portal
Links auf API

oAuth Applikationen hinzufügen

Vertrauchlich (Begrenzt auf 3 Client ID)
- Client ID und Client secret wird erzeugt
- Für vertrauliche Applikationen welche das Passwort (Secret) sicher verwahren können.
- Wir empfehlen die Verwendung vom "Authorization Code Flow mit PKCE" und "Device Code Flow".
Öffentlich (Begrenzt auf 3 Client ID)
- Client ID wird erzeugt
- Für öffentliche Applikationen welche das Secret nicht Geheim behalten können, z.B. Web oder Mobile Apps.
- Wir empfehlen die Verwendung vom "Authorization Code Flow mit PKCE" und "Device Code Flow"
Gerät (Begrenzt auf 50 Client ID)
- Client ID und Client secret wird erzeugt
- Kann als Ersatz für Basic Authentication in embedded Geräten verwendet werden welche kein grafisches Interface haben.
- Unterstützt nur den OAuth Flow "client credentials".

Benötige Informationen:

- Name
- Redirect Urls
- Benötigte Berechtigungen

Grants & Endpoints

Die Implementierung von OAuth wird auf unserem Wiki nicht beschrieben. Du findest auf dieser Seite die nötigen Informationen, um oAuth zu implementieren: https://oauth.net/2/

Supported Grants (Flows) for oAuth Confidential and Public Applications:

- Authorization Code without PKCE (deprecated)

- Authorization Code with PKCE

- Implicit Flow (deprecated)

- Device Code

- Refresh Token

Supported Grants (Flows) for oAuth Device (Client Credentials) Applications:

- Client Credentials

smart-me Endpoints

- Authorization: /api/oauth/authorize/

- Token: /api/oauth/token/

- Device Code: /api/oauth/device

Echtzeit-API (Webhook)

Die smart-me Echtzeit-API (Webhooks) ermöglicht es dir, neue Daten eines Gerätes zu abonnieren. Du kannst dich für ein einzelnes Gerät oder für alle Geräte eines Benutzers anmelden. Wenn ein Gerät neue Daten an die Cloud sendet, sendet ein Webhook diese Daten als POST-Anfrage an eine neu konfigurierte URL. Weitere Informationen findest du hier.

Proto-Datei

syntax = "proto3";

import "google/protobuf/timestamp.proto";

import "bcl.proto";

message DeviceDataArray {

repeated DeviceData DeviceDataItems = 1;

}

message DeviceData {

Guid DeviceId = 1;

.bcl.DateTime DateTime = 2;

repeated DeviceValue DeviceValues = 3;

}

message DeviceValue {

bytes Obis = 1;

double Value = 2;

}

Proto-Datei ohne BCL

syntax = "proto2";

package com.company;

message TimeSpan {

required sint64 value = 1; // the size of the timespan (in units of the selected scale)

optional TimeSpanScale scale = 2; // the scale of the timespan [default = DAYS]

enum TimeSpanScale {

DAYS = 0;

HOURS = 1;

MINUTES = 2;

SECONDS = 3;

MILLISECONDS = 4;

TICKS = 5;

MINMAX = 15; // dubious

}

message DateTime {

optional sint64 value = 1; // the offset (in units of the selected scale) from 1970/01/01

optional TimeSpanScale scale = 2; // the scale of the timespan [default = DAYS]

optional DateTimeKind kind = 3; // the kind of date/time being represented [default = UNSPECIFIED]

enum TimeSpanScale {

DAYS = 0;

HOURS = 1;

MINUTES = 2;

SECONDS = 3;

MILLISECONDS = 4;

TICKS = 5;

MINMAX = 15; // dubious

}

enum DateTimeKind

{

// The time represented is not specified as either local time or Coordinated Universal Time (UTC).

UNSPECIFIED = 0;

// The time represented is UTC.

UTC = 1;

// The time represented is local time.

LOCAL = 2;

}

message Guid {

required fixed64 lo = 1; // the first 8 bytes of the guid (note:crazy-endian)

required fixed64 hi = 2; // the second 8 bytes of the guid (note:crazy-endian)

}

message DeviceData {

required Guid DeviceId = 1;

required DateTime DateTime = 2;

repeated DeviceValue DeviceValues = 3;

}

message DeviceDataArray {

repeated DeviceData DeviceDataItems = 1;

}

message DeviceValue {

required bytes Obis = 1;

required double Value = 2;

}

Goldpartner - API

Um unsere API - Goldparner zu nutzen zu können, musst du über das Lizenzmodell smart-me Goldpartner verfügen. Weitere Infos zu diesem Lizenzmodell können über den Verkauf verlangt werden.

Endpoints

Get all devices

Gets all devices assigned to the partner
GET /PartnerAllDevices

Get all devices from one Account

Gets all devices assigned to one of the users assigned to the partner (Get Id with "Get users" )
GET /PartnerAllDevices/{id} - only for one device

Get all device informations

Gets all information for all devices assigned to the partner user or to a sub-user of the partner
GET /PartnerAllDeviceInformations
GET /PartnerAllDeviceInformations/{id} - only for one device

Get fast send device values

Force a device to send the data every second (if supported). This for about 30s

GET /partner/fastsenddevicevalues

Get Folder menu

Gets the folder menu items for a user of a partner

GET /partner/foldermenu/{id}

Update folder menu

Creates and updates the folder menu items for a user. Attention: All existing configuration (folder, billing, export, ...) is deleted!!
POST /partner/foldermenu/{id}

Get users

Get the information about all users of the partner
GET /partner/user

Update user

Updates the email and/or the password of a user. The user must be created by the partner.

POST /partner/user/{id}

Creates a new user and assign it to the partner user
POST /SignUpPartner

Get values in past multiple

Gets multiple values of a device. The device must be installed in an account assigned to your partner account.
GET /partner/ValuesInPastMultiple/{id}

Get values in past multiple interpolated

Gets multiple interpolated Values of device
GET /partner/ValuesInPastMultipleInterpolated/{id}

Get visualization configuration

Gets the visualization configuration for all folders of a user
GET /partner/visualizationconfiguration/{id}

Update firmware

Update the Firmware (if available) for the given devices
POST /UpdateFirmwarePartner

PartnerVisualization

Gets the visualization configuration for all folders of a user
GET /partner/visualizationconfiguration/{id}

Beispiele

API Beispiele

REST API Samples

Damit kannst du beliebige Datensätze abholen die wir zur Verfügung stellen. https://api.smart-me.com/swagger/index.html

HTML / Javascript (Alle Geräte mit Zählerstand und letzter Verbindung anzeigen)

<html>

<style>

table, th, td {

border:1px solid black;

}

</style>

<head>

<title>smart-me REST API Sample</title>

</head>

<body>

<div>

<label for="username">Username:</label>

</div>

<div>

<label for="pass">Password:</label>

</div>

<button id="myButton">Start Request</button>

<h1>Get all devices</h1>

</ul>

function GetAllDevices() {

var smartmeUserName = document.getElementById("username").value;

var smartmePassword = document.getElementById("pass").value;

//var smartmeUserName = "xxx";

//var smartmePassword = "xxx";

var targetUrl = "https://api.smart-me.com/Devices/";

$.ajax({

url: targetUrl,

type: "get",

cache: false,

headers: {

"Authorization": "Basic " + btoa(smartmeUserName + ":" + smartmePassword)

dataType: "json",

error: function(jqXHR, exception) {

alert(exception);

success: function(json) {

$("#DeviceList").append(("<table>"))

$("#DeviceList").append(("<tr align=left><th>Serial</th><th>Name</th><th>CounterReading</th><th>CounterReadingUnit</th><th>Last Connection (Zulu Time) </th></tr>"))

json.forEach(function(element) {

$("#DeviceList").append(("<tr><td>") + element.Serial + "</td><td>" + element.Name + "</td><td>" + element.CounterReading + "</td><td>" + element.CounterReadingUnit + "</td><td>" + element.ValueDate + "</td></tr>");

});

$("#DeviceList").append(("</table>"))

}

});

}

myButton.onclick = GetAllDevices;

</script>

</body>

<p>DISCLAIMER: This script is provided as-is, without any warranty or guarantee of any kind. The author accepts no liability for any issues, damages, or consequences that may arise from the use of this script. Users are responsible for reviewing and understanding the script before implementation. Additionally, no support or assistance will be provided for the installation, customization, or troubleshooting of this script. Use at your own risk.</p>

<p>HAFTUNGSAUSSCHLUSS: Dieses Skript wird im Ist-Zustand ohne jegliche Garantie oder Gewährleistung bereitgestellt. Der Autor übernimmt keine Haftung für Probleme, Schäden oder Folgen, die sich aus der Verwendung dieses Skripts ergeben können. Die Benutzer sind dafür verantwortlich, das Skript vor der Implementierung zu überprüfen und zu verstehen. Außerdem wird keine Unterstützung oder Hilfe bei der Installation, Anpassung oder Fehlerbehebung dieses Skripts geleistet. Die Verwendung erfolgt auf eigene Gefahr..</p>

</footer>

</html>

Python (Authorisierungsbeispiele)

import requests

from requests.auth import HTTPBasicAuth

# --- Endpoint ---

endpoint_url = 'https://api.smart-me.com/Devices'

# --- Basic Auth ---

basicAuth_user = 'max.musterman@smart-me.com'

basicAuth_pass = 'supersecretpassword'

basicAuth_response = requests.get(

endpoint_url,

auth=HTTPBasicAuth(basicAuth_user, basicAuth_pass)

)

print('Basic Auth:', basicAuth_response.status_code) #Returns 200 if successful

# --- API Key ---

api_key = 'secretapikey1234567890'

apikey_headers = {'Authorization': f'ApiKey {api_key}'}

apikey_response = requests.get(endpoint_url, headers=apikey_headers)

print('API Key:', apikey_response.status_code) #Returns 200 if successful

# --- OAuth 2.0: Get Token with Client ID and Secret ---

token_url = 'https://api.smart-me.com/oauth/token'

client_id = 'client_id_1234567890'

client_secret = 'client_secret_1234567890'

token_data = {

'grant_type': 'client_credentials',

'scope': 'device.read'

}

token_response = requests.post(

token_url,

data=token_data,

auth=HTTPBasicAuth(client_id, client_secret)

)

access_token = token_response.json().get('access_token')

# --- OAuth 2.0 Bearer Token ---

oauth_headers = {'Authorization': f'Bearer {access_token}'}

oauth_response = requests.get(endpoint_url, headers=oauth_headers)

print('OAuth:', oauth_response.status_code) #Returns 200 if successful

API-Client-Bibliothek für .Net

Um die smart-me API-Funktionalität in Ihre .Net-Anwendung zu integrieren, können Sie diese Bibliothek verwenden. Sie stellt HTTP-Anfragen an die smart-me REST API Alle HTTP-Anfrage- und Antwortkörper werden auf .Net-Klassen abgebildet.

Echtzeit-API (Webhook) Beispiele

Die smart-me Realtime API sendet die Daten serialisiert mit google protobuffer

Proto-Datei

package RealtimeApi.Containers;

import "bcl.proto"; // schema for protobuf-net's handling of core .NET types

message DeviceData {

required bcl.Guid DeviceId = 1;

required bcl.DateTime DateTime = 2;

repeated DeviceValue DeviceValues = 3;

}

message DeviceDataArray {

repeated DeviceData DeviceDataItems = 1;

}

message DeviceValue {

required bytes Obis = 1;

required double Value = 2;

}

Proto-Datei ohne BCL

syntax = "proto2";

package com.company;

message TimeSpan {

required sint64 value = 1; // the size of the timespan (in units of the selected scale)

optional TimeSpanScale scale = 2; // the scale of the timespan [default = DAYS]

enum TimeSpanScale {

DAYS = 0;

HOURS = 1;

MINUTES = 2;

SECONDS = 3;

MILLISECONDS = 4;

TICKS = 5;

MINMAX = 15; // dubious

}

message DateTime {

optional sint64 value = 1; // the offset (in units of the selected scale) from 1970/01/01

optional TimeSpanScale scale = 2; // the scale of the timespan [default = DAYS]

optional DateTimeKind kind = 3; // the kind of date/time being represented [default = UNSPECIFIED]

enum TimeSpanScale {

DAYS = 0;

HOURS = 1;

MINUTES = 2;

SECONDS = 3;

MILLISECONDS = 4;

TICKS = 5;

MINMAX = 15; // dubious

}

enum DateTimeKind

{

// The time represented is not specified as either local time or Coordinated Universal Time (UTC).

UNSPECIFIED = 0;

// The time represented is UTC.

UTC = 1;

// The time represented is local time.

LOCAL = 2;

}

message Guid {

required fixed64 lo = 1; // the first 8 bytes of the guid (note:crazy-endian)

required fixed64 hi = 2; // the second 8 bytes of the guid (note:crazy-endian)

}

message DeviceData {

required Guid DeviceId = 1;

required DateTime DateTime = 2;

repeated DeviceValue DeviceValues = 3;

}

message DeviceDataArray {

repeated DeviceData DeviceDataItems = 1;

}

message DeviceValue {

required bytes Obis = 1;

required double Value = 2;

}

Parsing-Beispiel

Beispieldaten

0A5A0A1209E9FCD03B8E9F834111B3D10C1622A22CA1120B08C0C9EAD3A98FE93710051A110A060100010800FF11333333331FAE3C411A110A060100020800FF1100000000000000001A110A060100010700FF11713D0AD7A3303840

Device ID (UUID / GUID)

UUID Data: 0xE9, 0xFC, 0xD0, 0x3B, 0x8E, 0x9F, 0x83, 0x41, 0xB3, 0xD1, 0x0C, 0x16, 0x22, 0xA2, 0x2C, 0xA1

GUID: 3bd0fce9-9f8e-4183-b3d1-0c1622a22ca1

Datetime (UTC)

Das Feld 1 enthält den Offset in Ticks seit dem 01.01.1970

Sekunden seit 01.01.1970: 15712284449788512 / 10000000 = 1571228444 (Unix time stamp UTC)

-> 16.10.2019 12:20:44 (UTC)

Device values

Feld 1 enthält den OBIS-Code, Feld 2 enthält den Wert.

01-00-01-08-00-FF: (1-0:1.8.0*255):Wirkenergie Gesamtimport: 1879583.2 mWh = 1879.5832 Wh

Page updated

Report abuse