Eziwan-REST-API

Mit der REST-API von Eziwan können Sie die Plattform in Ihre bestehenden Tools – SCADA, ERP, ITSM, BI – integrieren oder eigene Überwachungsanwendungen erstellen.

Basis-URL und Authentifizierung​

Endpunkt​

https://api.eziwan.com/v1

Bearer-Authentifizierung​

Für alle Anfragen ist ein Bearer-API-Token erforderlich:

Authorization: Bearer np_api_xxxxxxxxxxxxxxxxxxxxxxxx

Erstellen Sie ein Token unter Einstellungen → API → Token erstellen.

Verfügbare Berechtigungsstufen pro Token:

  • Nur Lesen: ausschließlich GET — Dashboard, Daten, Status
  • Lesen/Schreiben: GET + POST/PUT — Benachrichtigungen, Neustart, Konfiguration
  • Admin: Vollzugriff einschließlich Benutzerverwaltung und Abrechnung

Wichtigste Endpunkte​

Vorrichtungen​

# Alle Geräte auflisten
GET /v1/devices

# Detailansicht einer Vorrichtung
GET /v1/devices/{device_id}

# Echtzeitstatus (Signal, VPN, aktive SIM-Karte)
GET /v1/devices/{device_id}/status

# Verbindungshistorie
GET /v1/devices/{device_id}/connectivity?from=2026-01-01&to=2026-06-01

Sensordaten​

# Aktuelle Werte aller Variablen eines Geräts
GET /v1/devices/{device_id}/data/latest

# Zeitreihe für eine Variable
GET /v1/devices/{device_id}/data?metric=active_power&from=2026-06-01T00:00:00Z&to=2026-06-01T23:59:59Z&interval=5m

# Export CSV
GET /v1/devices/{device_id}/data/export?format=csv&from=2026-01-01&to=2026-06-30

Warnmeldungen​

# Aktive Benachrichtigungen zur Organisation
GET /v1/organization/alarms/active

# Historique des alertes
GET /v1/organization/alarms?from=2026-06-01&severity=critical

# Eine Warnmeldung quittieren
POST /v1/alarms/{alarm_id}/acknowledge
Body: { "comment": "Technicien en route" }

# Eine Warnmeldung beheben
POST /v1/alarms/{alarm_id}/resolve
Body: { "comment": "Pompe réparée, retour à la normale" }

Maßnahmen im Rahmen der Programme​

# Neustart eines Geräts (Lese-/Schreibberechtigung erforderlich)
POST /v1/devices/{device_id}/reboot

# Forcer un failover SIM
POST /v1/devices/{device_id}/failover
Body: { "target_sim": 2 }

# Logs d'audit
GET /v1/audit-logs?from=2026-01-01&to=2026-06-30&format=csv

Praktische Beispiele​

Python – Offline-Geräte abrufen​

import requests

API_TOKEN = "np_api_xxxxxxxxxxxxxxxxxxxxxxxx"
BASE_URL = "https://api.eziwan.com/v1"

headers = {"Authorization": f"Bearer {API_TOKEN}"}

# Geräte offline auflisten
response = requests.get(f"{BASE_URL}/devices", headers=headers)
devices = response.json()["data"]

offline = [d for d in devices if d["status"] == "offline"]
print(f"{len(offline)} dispositifs hors ligne :")
for d in offline:
    print(f"  - {d['name']} ({d['id']}) — hors ligne depuis {d['last_seen']}")

Python – Daten von einem Sensor abrufen​

import requests
from datetime import datetime, timedelta

API_TOKEN = "np_api_xxxxxxxxxxxxxxxxxxxxxxxx"
DEVICE_ID = "d_a1b2c3d4"

headers = {"Authorization": f"Bearer {API_TOKEN}"}

# Letzte 24 Stunden – Wirkleistung
response = requests.get(
    f"https://api.eziwan.com/v1/devices/{DEVICE_ID}/data",
    headers=headers,
    params={
        "metric": "active_power",
        "from": (datetime.utcnow() - timedelta(days=1)).isoformat() + "Z",
        "to": datetime.utcnow().isoformat() + "Z",
        "interval": "5m"
    }
)

data = response.json()["data"]
print(f"{len(data)} points retournés")
for point in data[:5]:
    print(f"  {point['timestamp']}: {point['value']} {point['unit']}")

curl — CSV-Export für den Monatsbericht​

curl -H "Authorization: Bearer np_api_xxxx" \
  "https://api.eziwan.com/v1/devices/d_a1b2c3d4/data/export?format=csv&from=2026-06-01&to=2026-06-30" \
  -o donnees_juin_2026.csv

Webhooks​

Webhooks senden Ereignisse per Push an Ihren HTTP-Endpunkt.

Konfiguration​

Dashboard → Benachrichtigungen → Webhooks → Webhook hinzufügen

Einstellungen:

  • URL: Ihr HTTPS-Endpunkt (z. B.: https://your-app.com/eziwan-events)
  • Secret: HMAC-SHA256-Schlüssel zur Überprüfung der Signatur (optional, wird jedoch empfohlen)
  • Ereignisse: Wählen Sie die Typen aus (device.offline, alarm.triggered, failover usw.)

Payload-Format​

{
  "event": "device.offline",
  "severity": "critical",
  "timestamp": "2026-06-15T02:14:33.412Z",
  "device": {
    "id": "d_a1b2c3d4",
    "name": "GW-Valenciennes-03",
    "group": "Région Nord / Site Valenciennes",
    "tags": ["env:production", "criticite:haute"]
  },
  "detail": {
    "last_seen": "2026-06-15T02:12:01.000Z",
    "sim_active": 2,
    "rsrp_dbm": -108
  },
  "dashboard_url": "https://app.eziwan.com/devices/d_a1b2c3d4"
}

Überprüfung der Signatur​

import hmac, hashlib

def verify_eziwan_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = "hmac-sha256=" + hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

# In Ihrem Flask/FastAPI-Handler:
# signature = request.headers.get("X-Eziwan-Signature")
# valid = verify_eziwan_webhook(request.body, signature, WEBHOOK_SECRET)

Verfügbare Veranstaltungen​

EreignisAuslöser
device.offlineGerät offline
device.onlineWieder online
alarm.triggeredAlarmschwelle überschritten
alarm.resolvedAlarm behoben
failover.activatedUmschaltung von SIM1 auf SIM2
failover.recoveredRückkehr zu SIM1
firmware.updatedFirmware-Update erfolgreich
provisioning.completedZTP abgeschlossen – Gateway online

ITSM-Integrationen über Webhooks​

ServiceNow​

// Transformationsskript für den ServiceNow Integration Hub
(function process(/*RESTAPIRequest*/ request) {
    var body = JSON.parse(request.body.dataString);
    
    if (body.event === "device.offline" && body.severity === "critical") {
        var incident = new GlideRecord("incident");
        incident.short_description = "Gateway Eziwan hors ligne : " + body.device.name;
        incident.description = "Site : " + body.device.group + "\nDernier vu : " + body.detail.last_seen;
        incident.urgency = "1"; // Haute
        incident.impact = "2"; // Moyen
        incident.insert();
    }
})(request);

Jira Service Management​

# Automatische Erstellung eines Tickets über die Jira-API
curl -X POST \
  -H "Authorization: Bearer JIRA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "project": { "key": "OPS" },
      "summary": "Gateway hors ligne : GW-Valenciennes-03",
      "description": "Site : Région Nord\nDernier contact : 2026-06-15T02:12:01Z",
      "issuetype": { "name": "Incident" },
      "priority": { "name": "High" }
    }
  }' \
  "https://„Ihre-Instanz.atlassian.net/rest/api/3/issue“

Grenzwerte und Kontingente​

TarifAPI-Anfragen/TagWebhooksCSV-Export
Starter1.0002 Endpunkte90 Tage
Growth10.00010 Endpunkte1 Jahr
Scale100.00050 Endpunkte3 Jahre
EnterpriseUnbegrenztUnbegrenztUnbegrenzt
Vollständige Dokumentation

Die vollständige OpenAPI-Dokumentation (Swagger) ist unter api.eziwan.com/docs verfügbar.

Kontakt zum technischen Support → | Schnellstartanleitung →

Häufig gestellte Fragen​

Wie kann man sich bei der API authentifizieren?​

Über ein über die Konsole generiertes Bearer-Token (Gültigkeitsdauer und Ablaufzeit konfigurierbar). Die Token werden sofort widerrufen, und jeder Aufruf wird zusammen mit seinem Absender protokolliert.

Welche Daten sind über die API abrufbar?​

Die Bestandsliste der Geräte und deren Status (Signal, SIM, VPN, Firmware), die erfassten Messwerte (Modbus, Sensoren), der Alarmverlauf und die Verwaltungsmaßnahmen (Neustart, Konfigurationsübertragung).

Kann man Benachrichtigungen per Push statt per Polling erhalten?​

Ja, über Webhooks: Die Plattform ruft bei jedem ausgewählten Ereignis (Warnung, Verbindungsabbruch, Überschreitung eines Schwellenwerts) Ihren HTTP-Endpunkt auf – ideal, um ITSM-Tickets zu erstellen oder Ihre bestehende Überwachungslösung zu versorgen.

Gibt es Datenvolumenbeschränkungen?​

Ja, eine Ratenbegrenzung schützt die Plattform; die Standardkontingente decken die üblichen Integrationen mehr als ausreichend ab und lassen sich bei Bedarf für intensive Nutzung anpassen.

Weiterführende Ressourcen​