API

Tipp zur Entschlüsselung: Auf dieser Website können Sie die Systematik der Codierung nachlesen. Wenn Sie dort auf ein Medium klicken, sehen Sie, für was die Ziffern des Codes jeweils stehen.

Authentifizierung

Basic Auth

smart-me verwendet API "Basic Authentication". Jeder Aufruf der API muss die Authentifizierung beinhalten. Die HTTP-Basisauthentifizierung ermöglicht die Übertragung von Anmeldeinformationen (z. B. Benutzername und Passwort oder ein API-Token) in HTTP-Headern. Das secret wird mit Base64 kodiert.

OAuth 2.0

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 finden Sie weiter unten.

Migration für Partner welche OAuth vor dem 22.05.2023 genützt haben

Wenn Sie keine OAuth Authentifizierung mehr benötigen, müssen Sie nichts unternehmen.

Vor dem 22.05.2023 hat smart-me jeweils die OAuth Clients ID für unsere Partner erstellt.

Ab dem 22.05.2023 muss der Partner die OAuth Client ID selber erzeugen.

Welche Schritte sind nötige für einer erfolgreiche Migration am 22.05.2023

Warum stellen wir um:

Neue Sicherheitsanforderungen erfüllen. u.a. wird eine Redirect URL benötigt.
Berechtigungen können bei der Erstellung definiert werden
Partner können Client ID selbständig erzeugen
smart-me muss die Client Secret nicht mehr übertragen

Einschränkungen:

Nach der Big Bang Umstellung vom 22.05.2023:

Ist die Nutzung des alten (bestehenden) OAuth Client ID nicht mehr möglich.
Eine neuen Client ID muss erzeugt werden.

Vor dem 22.05.2023:

Stellen Sie sicher, dass Sie über eine smart-me Konto mit dem Lizenzmodell professional verfügen. smart-me Login
Prüfen Sie die Abostufe des Konto wie folgt:
- Login im smart-me Portal
- Oben Rechts User wählen
- Einstellungen
- Abostufe muss auf Professional sein.
Hinweis: Wenn Sie bereits vor dem 22.05.2023 OAuth benützt haben und kein smart-me Konto mit dem Lizenzmodell professional haben nehmen Sie bitte mit support@smart-me.com Kontakt auf, damit wir Ihnen auf dem angegebenen Konto (E-Mail) 1 Lizenz gratis freischalten können.

Am / Ab dem 22.05.2023

Stellen Sie sicher, dass Sie über eine smart-me Konto mit dem Lizenzmodell professional verfügen. smart-me Login (Wenn nicht bereits vor dem 22.05.2023 erfolgt)
Wir senden Euch ein E-Mail dass die Umstellung erfolgt ist, damit Sie die Schritte wie unten im Abschnitt "Einrichtung OAuth im smart-me Portal" beschrieben sind befolgen können. Dieser Schritt ist nicht vor der Migration.

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. Sollten Sie noch kein Konto mit dem Lizenmodell professional haben, müssen Sie 1 Lizenz erwerben.

Login im smart-me Portal
Oben Rechts User wählen
Einstellungen
API & Access Ändern

oAuth Applikationen hinzufügen

Vertrauchlich (Begrenzt auf 3 Client ID)
- Client ID und Client secret wird erzeugt
Öffentlich (Begrenzt auf 3 Client ID)
- Client ID wird erzeugt
Gerät (Begrenzt auf 50 Client ID)
- Client ID und Client secret wird erzeugt

Benötige Informationen

- Name
- Redirect Urls
- Benötigte Berechtigungen

Grants & Endpoints

Die Implementierung von OAuth wird auf unserem Wiki nicht beschrieben. Sie finden z.B. 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

- 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 Ihnen, neue Daten eines Gerätes zu abonnieren. Sie können sich 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 finden Sie hier.

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;

}

Beispiele

API Beispiele

REST API Samples

Damit können Sie beliebige Datensätze abholen die wir zur Verfügung stellen. https://smart-me.com/swagger/ui/index

HTML / Javascript (jquery) Beispiele

Alle Geräte abrufen

<html>

<head>

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

</head>

<body>

<h1>Get all devices</h1>

</ul>

var smartmeUserName = "YOUR_USERNAME";

var smartmePassword = "YOUR_PASSWORD";

function GetAllDevices() {

var targetUrl = "https://api.smart-me.com/api/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) {

json.forEach(function(element) {

// Do something

$("#DeviceList").append($("<li>").text(element.Name + ": " + element.CounterReadingImport + " " + element.CounterReadingUnit));

});

}

});

}

// On document load

$(document).ready(function() {

// Get all smart-me devices

GetAllDevices();

});

</script>

</body>

</html>

Gerät erstellen und aktualisieren

<html>

<head>

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

</head>

<body>

<h1>Create and update devices</h1>

<button type="button" id="CreateNewDeviceButton">Create new device</button>

var smartmeUserName = "YOUR_USERNAME";

var smartmePassword = "YOUR_PASSWORD";

var counterValueImport = 0.0;

var counterValueExport = 0.0;

var activePowerTempValue = 0.1;

// The ID of the device

var deviceID = null;

function GetElectricityDevice(id, power, energyImport, energyExport) {

var deviceObject = new Object();

if (id != null) {

// Object with an ID updates the existing device. Object without an ID creates a new one

deviceObject.ID = id;

}

// Add all data

deviceObject.Name = "My test device";

deviceObject.Serial = 12345678;

deviceObject.DeviceEnergyType = "MeterTypeElectricity"; // MeterTypeWater for Water, MeterTypeGas for Gas, MeterTypeHeat for Heat

// Set active power in kW

deviceObject.ActivePower = power;

// Set countervalues import (in kWh)

deviceObject.CounterReading = energyImport;

// Set countervalues export (in kWh)

deviceObject.CounterReadingExport = energyExport;

return deviceObject;

}

function CreateUpdateDevice(deviceObject) {

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

var postData = JSON.stringify(deviceObject);

$.ajax({

url: targetUrl,

type: "post",

cache: false,

headers: {

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

},

dataType: "json",

contentType: "application/json; charset=utf-8",

data: postData,

error: function(jqXHR, exception) {

alert(exception);

},

success: function(json) {

// The device was created or updated

deviceID = json.Id;

$('#CreateNewDeviceButton').text("Update device");

alert("OK! device ID: " + json.Id);

}

});

}

// On document load

$(document).ready(function() {

$('#CreateNewDeviceButton').click(function(e) {

// No Postback

e.preventDefault();

// Add some random values

activePowerTempValue += 0.1;

counterValueImport += 1.0;

counterValueExport += 0.5;

var electricityDevice = GetElectricityDevice(deviceID, activePowerTempValue, counterValueImport, counterValueExport);

// Send to cloud

CreateUpdateDevice(electricityDevice);

});

</script>

</body>

</html>

Geräte erstellen oder aktualisieren

https://smart-me.com/swagger/ui/index

Wärmezähler

API Method: 'POST /api/devices'

Hinweis: Um ein Gerät zu erstellen, wird keine ID gesendet.

Nutzlast:

{

"Id": "b0ec0030-9f97-4c3c-897f-8175074177bc",

"Name": "Wärme Zähler Test",

"Serial": 2233445566,

"DeviceEnergyType": "MeterTypeHeat",

"ActivePower": 5.89,

"CounterReading": 1234.56,

}

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