API-Schnittstelle

Elemente.ID bietet eine REST-API (Version 1), mit der Sie Objekte und Elemente aus Ihren eigenen Systemen anbinden. So halten Sie Stamm- und Auftragsdaten synchron, ordnen Elemente automatisch dem richtigen Objekt zu und befüllen eigene Felder, ohne Daten doppelt zu pflegen. Typische Partner sind ERP-, PIM- oder Branchensoftware.

Die vollständige Referenz mit allen Feldern, Beispielen und Fehlercodes finden Sie in der API-Dokumentation. Diese Seite gibt Ihnen den praktischen Überblick.

Was Sie über die API tun können

• Objekte anlegen, abrufen und aktualisieren.
• Elemente anlegen, abrufen, aktualisieren und serverseitig filtern, auch über Ihre eigenen Zusatzfelder.
• Test-Webhooks auslösen, um Ihre Anbindung zu prüfen.

Reicht der Standard nicht aus (eigene Endpunkte, individuelle Webhook-Ziele, Anbindung an Ihr ERP oder PIM), erweitern wir die Schnittstelle kundenspezifisch.

Zugang anfragen

API-Key und API-Secret werden pro Kunde vergeben. Das Secret wird nur einmal angezeigt, bewahren Sie es daher sicher auf. Den Zugang richten wir für Sie ein. Wenden Sie sich an unseren Support oder über die Kontaktseite. Auf Wunsch hinterlegen wir eine IP-Allowlist, sodass nur Ihre Server zugreifen dürfen.

Authentifizierung

Jeder Aufruf braucht zwei Kopfzeilen (Header):

Weitere Eckdaten:

• Basis-URL: https://<ihr-host>/api/v1. Den genauen Host erhalten Sie zusammen mit Ihren Zugangsdaten.
• Rate-Limit: 60 Anfragen pro Minute. Darüber antwortet die API mit Status 429.
• IP-Allowlist (optional): Ist sie gesetzt und Ihre Adresse nicht enthalten, antwortet die API mit 403.
• Format: Anfragen und Antworten sind JSON.

Endpunkte im Überblick

Konvention: Listen sind Plural (objects, elements), Einzelressourcen Singular (object, element).

Beim Anlegen ist nur wenig Pflicht: Ein Objekt wie auch ein Element braucht eine Angabe im Feld name. Die Kennungen object_id, element_id und der qr_code werden automatisch erzeugt, wenn Sie sie leer lassen. Eigene Zusatzfelder übergeben Sie im Feld other. Ein PUT aktualisiert partiell; bei Objekten wird die address allerdings komplett ersetzt, senden Sie sie daher immer vollständig mit. Die genauen Feldregeln stehen in der API-Dokumentation.

Elemente filtern

Die Element-Liste filtern Sie serverseitig über filter[...]:

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

• Als <key> gelten echte Spalten (element_id, name, object_id, qr_code) und Ihre eigenen other-Felder, zum Beispiel auftragsnummer.
• Mehrere filter[...] werden mit UND verknüpft, der Vergleich ist exakt.
• Ein unbekannter Key liefert 422, ein gültiger Key ohne Treffer eine leere Liste.

Beispiel (curl)

API="https://<ihr-host>/api/v1"
KEY="…"; SECRET="…"

# Alle Elemente zu einer Auftragsnummer
curl -g "$API/elements?filter[auftragsnummer]=2630856" \
  -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"}}'

Hinweis: Bei curl ist die Option -g nötig, damit die eckigen Klammern in den Filter-URLs nicht als Zeichenbereich interpretiert werden.

Fehlercodes im Überblick

Die vollständige Beschreibung aller Endpunkte, Felder und Antworten finden Sie in der API-Dokumentation.