Mit der öffentlichen API starten

Was die API ermöglicht

Die öffentliche sdai.ch-API gibt Ihren eigenen Werkzeugen lesenden Zugriff auf Ihre Daten: Gebäude, Meldergruppen, gesteuerte Endgeräte, Einrichtungen und Steuermatrizen. Genau das braucht es, um eine Instandhaltungssoftware, ein internes Dashboard oder einen regelmässigen Export ohne Doppelerfassung zu versorgen.

Sie ist schreibgeschützt. Nichts, was über die API läuft, verändert Ihre Daten: die Erfassung bleibt in der Anwendung und in der mobilen App.

Was Sie brauchen

• Den Pro-Plan für Ihre Organisation.
• Die Rolle Administrator. Ein Schlüssel sieht die gesamte Organisation, auch Gebäude, die ein Konto mit der Rolle Kunde nicht sehen würde: ein Schlüssel hat keine Rolle. Deshalb ist seine Erstellung dem Administrator vorbehalten.

Einen Schlüssel erstellen

1. Öffnen Sie Einstellungen, Reiter API.
2. Klicken Sie auf Schlüssel erstellen und vergeben Sie einen Namen, der daran erinnert, wo er eingesetzt wird, zum Beispiel «GMAO-Export».
3. Kopieren Sie den Schlüssel sofort. Er wird nur einmal angezeigt: wir bewahren nur einen Fingerabdruck auf, er ist danach nicht wiederherstellbar. Wenn Sie ihn verlieren, widerrufen Sie ihn und erstellen einen neuen.

Sie können bis zu fünf aktive Schlüssel gleichzeitig haben. Ein widerrufener Schlüssel gibt seinen Platz frei.

Ihr erster Aufruf

Der Schlüssel wird im Header Authorization übergeben:

curl -H "Authorization: Bearer sdai_live_ihr_schluessel" \
  https://sdai.ch/api/v1/me

Die Antwort bestätigt, zu welcher Organisation der Schlüssel gehört:

{ "data": { "organization_id": "...", "organization_name": "Ihr Büro AG",
            "plan": "PRO", "scopes": ["read"], "key_label": "GMAO-Export" } }

Danach die Liste Ihrer Gebäude:

curl -H "Authorization: Bearer sdai_live_ihr_schluessel" \
  "https://sdai.ch/api/v1/batiments?limit=20"

Die Antworten lesen

Jede Antwort ist in ein Objekt data verpackt. Listen tragen zusätzlich ein next_cursor.

Das Feld error.code ist das, was programmatisch behandelt wird: unauthorized, plan_required, not_found, rate_limited. Der Satz ist für den Menschen gedacht, der die Logs liest.

Die Grenze liegt bei 120 Aufrufen pro Minute und Schlüssel. Ein sauber geschriebener nächtlicher Export kommt ihr nicht nahe.

Eine zweite Grenze gegen Missbrauch gilt pro IP-Adresse und betrifft Aufrufe ohne gültigen Schlüssel. Eine Integration, die sich korrekt authentifiziert, kann sie nicht erreichen. Die Antwort ist in beiden Fällen dieselbe: 429, Code rate_limited, Header Retry-After in Sekunden.

Ihren Schlüssel schützen

• Er entspricht einem Lesezugriff auf Ihre gesamte Organisation: behandeln Sie ihn wie ein Passwort.
• Setzen Sie ihn nie in eine URL. Er landete in den Zugriffsprotokollen und im Referer-Header, der an Drittseiten gesendet wird. Die API akzeptiert ihn nur im Header Authorization.
• Committen Sie ihn nicht in ein Code-Repository, auch nicht in ein privates.
• Zweifel an einem Schlüssel? Widerrufen Sie ihn über Einstellungen > API. Die Wirkung ist sofort.

Und danach

• API-Referenz: alle Endpunkte, die Paginierung und die Formate.
• Die technische Spezifikation ist öffentlich: openapi.json. Sie lässt sich direkt in Postman, Bruno oder einen Client-Generator importieren.