API-Referenz

Basis-URL und Authentifizierung

Alle Endpunkte liegen unter https://sdai.ch/api/v1 und erwarten den Header Authorization: Bearer <Schlüssel>. Die vollständige Spezifikation ist unter openapi.json veröffentlicht.

Die Endpunkte

Die Filter type und etat der Einrichtungen vergleichen den Wert exakt, auf freien Zeichenketten: ein unbekannter Wert ergibt eine leere Liste, ein leerer Wert einen 400. Eine batiment_id, die nicht Ihnen gehört, ergibt einen 404, nie eine leere Liste.

Paginierung

Listen werden über einen Cursor durchlaufen, nie über eine Seitennummer:

• ?limit= zwischen 1 und 100, standardmässig 50. Ein Wert ausserhalb der Grenzen ergibt einen 400, nie einen stillen Rückfall auf den Standardwert.
• ?cursor= erhält den Wert next_cursor der vorherigen Antwort, unverändert.
• next_cursor ist null auf der letzten Seite.

# erste Seite
curl -H "Authorization: Bearer $SCHLUESSEL" "https://sdai.ch/api/v1/batiments?limit=50"
# nächste Seite
curl -H "Authorization: Bearer $SCHLUESSEL" "https://sdai.ch/api/v1/batiments?limit=50&cursor=cmr8kd..."

Der Cursor ist undurchsichtig: versuchen Sie nicht, ihn zu bauen oder zu deuten. Er schützt Sie vor einem klassischen Fehler der Seitennummerierung, bei dem eine gleichzeitige Erstellung die Folgeseiten verschiebt und Sie eine Zeile überspringen, ohne dass etwas darauf hinweist.

Wertformate

• Englische Hülle (data, next_cursor), französische Fachfelder in Kleinbuchstaben mit Unterstrichen: batiment_id, type_detection, is_example.
• Daten im Format ISO 8601 UTC, zum Beispiel 2026-05-12T09:00:00.000Z. Ein fehlendes Datum ist null, nie eine leere Zeichenkette.
• Geschlossene Wertelisten: nur categorie_test_integral (CAT_I, CAT_II, CAT_III) und die action einer Matrixzelle (FERME, OUVERT, ACTIVE, ARRETE, DEBLOQUE, RAPPEL) haben einen garantierten Wertebereich.
• Freie Felder: statut, type, etat, categorie, type_detection, etat_securite, type_commande und categorie_asservissement werden in der Anwendung erfasst. Behandeln Sie jeden unerwarteten Wert als normal, statt ihn abzulehnen.

Zwei Punkte zu den Gebäuden

• nombre_detecteurs, nombre_zones und nombre_boucles sind deklarative Felder des Gebäudedatenblatts, von Hand erfasst. Es sind keine berechneten Zähler. Für eine echte Zählung paginieren Sie /zones oder /equipements.
• is_example ist true beim Demo-Gebäude, das bei der Registrierung erstellt wird. Es ist in den Listen enthalten: filtern Sie es selbst heraus, wenn Sie es nicht möchten.

Das Raster einer Matrix

GET /matrices/{id} liefert die Matrix mit ihren expliziten Achsen:

{ "data": {
  "id": "...", "batiment_id": "...", "nom": "Matrice principale", "version": 3,
  "statut": "APPROUVEE",
  "zones":     [ { "id": "...", "code": "Z01", "type_detection": "FUMEE", "ordre": 1 } ],
  "terminaux": [ { "id": "...", "code": "T01", "etat_securite": "FERME", "ordre": 1 } ],
  "asservissements": [
    { "zone_id": "...", "terminal_id": "...", "type_commande": "AUTO_SIMPLE",
      "action": "FERME", "delai_secondes": 30, "critere": null, "remarque": null }
  ],
  "truncated": false
} }

Daraus folgen drei Dinge:

1. Die Achsen stammen vom Gebäude, nicht von den Zellen. Eine Meldergruppe, die kein Endgerät steuert, erscheint trotzdem in zones. Das ist gewollt: eine leere Zeile der Matrix ist eine Information, kein Fehlen.
2. Das Raster ist dünn besetzt. Nur gesteuerte Schnittpunkte erscheinen in asservissements. Bauen Sie das Raster auf, indem Sie zones und terminaux kreuzen und dann die Zellen einsetzen.
3. Die Obergrenze wird angekündigt. Höchstens 5000 Zellen werden geliefert. Darüber hinaus wird truncated zu true. Es gibt nie eine stille Kürzung.

Die hier gelieferten Achsen sind bewusst auf das reduziert, was zur Beschriftung einer Zeile oder Spalte nötig ist. Für das vollständige Datenblatt einer Meldergruppe oder eines Endgeräts rufen Sie /batiments/{id}/zones oder /batiments/{id}/terminaux auf.

Fehler

Alle Fehler haben dieselbe Form:

{ "error": { "code": "not_found", "message": "Resource not found.", "request_id": "req_..." } }

Behandeln Sie den code programmatisch: bad_request, unauthorized, plan_required, not_found, rate_limited, server_error. Die request_id wird auch im Header X-Request-Id zurückgegeben: nennen Sie sie, wenn Sie uns an support@sdai.ch schreiben.

Zwei Antworten sind bewusst nicht unterscheidbar:

• Der 401 sagt nicht, ob der Schlüssel unbekannt, widerrufen oder abgelaufen ist.
• Der 404 sagt nicht, ob die Ressource nicht existiert oder ob sie einer anderen Organisation gehört.

In beiden Fällen würde eine Unterscheidung einem Dritten verraten, was er nicht wissen darf.

Grenzen der Version 1

• Schreibgeschützt.
• Mängel, Berichte und Kontrollen sind noch nicht verfügbar.
• Die Organisation wird immer aus dem Schlüssel abgeleitet: kein Endpunkt akzeptiert eine Organisations-Kennung.

Ein Bedarf, der nicht in diesen Rahmen passt? Schreiben Sie uns an support@sdai.ch, das lenkt die weitere Entwicklung.