Entwickler · API-Referenz

Elemente.ID REST-API v1

Schnittstelle zum Verwalten von Objekten und Elementen (EIDs) sowie zum Auslösen von Test-Webhooks. Alle Requests und Antworten sind JSON (UTF-8).

Basis-URL https://<host>/api/v1Format JSONRate-Limit 60 / min

Authentifizierung

Jeder Request benötigt zwei Header. Zugangsdaten werden pro Kunde vergeben; das Secret wird nur einmal angezeigt und muss sicher hinterlegt werden.

Header	Wert
`X-Api-Key`	Ihr API-Key
`X-Api-Secret`	Ihr API-Secret

Header

X-Api-Key:    abcdef0123456789...
X-Api-Secret: 9876543210fedcba...

Rate-Limit: 60 Requests pro Minute. Bei Überschreitung antwortet die API mit 429.

Fehlerantworten

Fehler kommen als JSON mit passendem HTTP-Status:

JSON

{ "error": "Beschreibung des Fehlers" }

Status	Bedeutung
`200`	OK
`201`	Erfolgreich angelegt
`401`	Zugangsdaten fehlen oder ungültig
`403`	IP-Adresse nicht erlaubt
`404`	Objekt/Element nicht gefunden
`422`	Validierungsfehler / unbekannter Filter-Key
`429`	Rate-Limit überschritten

Validierungsfehler (422) können zusätzlich feldbezogene Details enthalten.

Endpunkte im Überblick

Konvention: Liste = Plural, Einzelressource = Singular.

Methode	Pfad	Zweck
GET	`objects`	Alle Objekte auflisten
POST	`object`	Objekt anlegen
GET	`object/{id}`	Objekt anzeigen (`{id}` = UUID oder `object_id`)
PUT	`object/{id}`	Objekt aktualisieren (partiell)
GET	`elements`	Alle Elemente auflisten (filterbar)
POST	`element`	Element anlegen
GET	`element/{id}`	Element anzeigen (`{id}` = UUID oder `element_id`)
PUT	`element/{id}`	Element aktualisieren (partiell)
POST	`webhooks/test`	Konfigurierte Webhooks mit Testdaten auslösen

Objekte

Ein Objekt ist ein Container (z. B. ein Standort/eine Anlage), dem Elemente zugeordnet sein können.

Felder beim Anlegen (`POST object`)

Feld	Regel	Hinweis
`name`	erforderlich, string ≤255
`object_id`	optional, string	leer → automatisch generiert (`OBJID…`)
`password`	optional, string ≤255	leer → zufälliges 22-Zeichen-Passwort
`address`	optional, Objekt	Schlüssel: `street`, `zip`, `city`, `country`
`other`	optional, Objekt	kundenspezifische Zusatzfelder

Request

POST object

{
  "name": "Lagerhalle Nord",
  "object_id": "PN923423",
  "address": { "street": "Hauptstr. 1", "zip": "10115", "city": "Berlin", "country": "DE" },
  "other": { "abteilung": "Technik" }
}

Antwort (`password` wird nie zurückgegeben)

JSON

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "object_id": "PN923423",
    "name": "Lagerhalle Nord",
    "address": { "street": "Hauptstr. 1", "zip": "10115", "city": "Berlin", "country": "DE" },
    "other": { "abteilung": "Technik" },
    "elements": [ { "id": "…", "element_id": "ELID000001" } ],
    "created_at": "2026-06-02T10:00:00+00:00",
    "updated_at": "2026-06-02T10:00:00+00:00"
  }
}

Update (PUT object/{id}) ist partiell, aber address wird komplett ersetzt, nicht gemerged. Beim Update immer die vollständige Adresse mitsenden.

Elemente

Ein Element (EID) ist die einzelne identifizierte Einheit, optional einem Objekt zugeordnet.

Felder beim Anlegen (`POST element`)

Feld	Regel	Hinweis
`name`	erforderlich, string ≤255
`element_id`	optional, string	leer → automatisch generiert (`ELID…`)
`object_id`	optional, string	UUID eines Objekts desselben Kunden (sonst `422`)
`other`	optional, Objekt	kundenspezifische Zusatzfelder

qr_code (UUID) wird automatisch erzeugt. Antwortfelder (GET/POST/PUT): id, element_id, name, qr_code, object_id, other, created_at, updated_at.

JSON

{
  "data": {
    "id": "…",
    "element_id": "ELID000123",
    "name": "Brandschutztür 3.OG",
    "qr_code": "…",
    "object_id": "550e8400-e29b-41d4-a716-446655440000",
    "other": { "auftragsnummer": "2630856", "abgabedatum": "2026-05-01" },
    "created_at": "2026-06-02T10:00:00+00:00",
    "updated_at": "2026-06-02T10:00:00+00:00"
  }
}

Elemente filtern (`GET elements`)

Die Element-Liste lässt sich serverseitig filtern:

GET

GET /api/v1/elements?filter[<key>]=<wert>

Regeln

<key> wird zuerst als echte Spalte geprüft, sonst als other-Feld behandelt.
- Plain-Spalten: element_id, name, object_id, qr_code
- other-Keys: die für Ihren Account konfigurierten Element-Felder (z. B. auftragsnummer, abgabedatum). Welche Keys gültig sind, sehen Sie im other-Objekt jeder Element-Antwort.
Mehrere filter[...] werden UND-verknüpft.
Vergleich ist exakt (Gleichheit).
Unbekannter Key → 422 { "error": "Unbekannter Filter-Key: <key>" }.
Gültiger Key ohne Treffer → 200 mit leerer Liste { "data": [] }.

Beispiele

Aufruf	Wirkung
`?filter[element_id]=ELID000123`	exaktes Element über `element_id`
`?filter[auftragsnummer]=2630856`	alle Elemente mit `other.auftragsnummer = "2630856"`
`?filter[object_id]=<uuid>&filter[auftragsnummer]=2630856`	Schnittmenge (UND)

Kompatibilität: Der bestehende Kurz-Parameter ?object_id=<uuid> funktioniert weiterhin und entspricht ?filter[object_id]=<uuid>.

Beispiele (curl)

bash

# Variablen setzen
API="https://<host>/api/v1"
KEY="…"; SECRET="…"

# Alle EIDs zu einer Auftragsnummer
curl -g "$API/elements?filter[auftragsnummer]=2630856" \
  -H "X-Api-Key: $KEY" -H "X-Api-Secret: $SECRET"

# Einzelnes Element über element_id
curl -g "$API/elements?filter[element_id]=ELID000123" \
  -H "X-Api-Key: $KEY" -H "X-Api-Secret: $SECRET"

# Element anlegen
curl "$API/element" \
  -H "X-Api-Key: $KEY" -H "X-Api-Secret: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{"name":"Brandschutztür 3.OG","other":{"auftragsnummer":"2630856"}}'

# Objekt aktualisieren (partiell)
curl -X PUT "$API/object/<id>" \
  -H "X-Api-Key: $KEY" -H "X-Api-Secret: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{"address":{"city":"Berlin"}}'

Hinweis: Bei curl ist -g (globoff) nötig, damit die eckigen Klammern [] in Filter-URLs nicht als Zeichenbereich interpretiert werden. Alternativ die Klammern URL-kodieren: filter%5Bauftragsnummer%5D=2630856.

Webhooks (Test)

POST webhooks/test löst die für Ihren Account aktivierten Webhooks mit Beispieldaten aus und meldet zurück, welche gesendet wurden:

JSON

{
  "success": true,
  "message": "Test-Webhooks gesendet.",
  "sent": ["Element erstellt"],
  "failed": []
}

Welche Webhooks aktiv sind und an welche Ziel-URL sie senden, wird vom Betreiber im Backend konfiguriert.

Zugang zur API anfragen

API-Key und -Secret werden pro Kunde vergeben. Sprechen Sie uns an, wir richten Ihren Zugang ein und zeigen Ihnen die Anbindung in einer kurzen Live-Demo.

Zur API-Funktion Zugang anfragen

Authentifizierung

Fehlerantworten

Endpunkte im Überblick

Objekte

Felder beim Anlegen (POST object)

Request

Antwort (password wird nie zurückgegeben)

Elemente

Felder beim Anlegen (POST element)

Elemente filtern (GET elements)

Regeln

Beispiele

Beispiele (curl)

Webhooks (Test)

Zugang zur API anfragen

Felder beim Anlegen (`POST object`)

Antwort (`password` wird nie zurückgegeben)

Felder beim Anlegen (`POST element`)

Elemente filtern (`GET elements`)