Zurück zum Hilfecenter

Schnittstelle: Leitfäden

Überblick: Was die elyph API kann

Aufbau, Adressen, Ressourcen und Grundregeln der Schnittstelle in einer Übersicht.

Für wen

IT, Integrationsverantwortliche und Entwicklerinnen und Entwickler.

Voraussetzungen

Zugang zur Verwaltung oder Kontakt zu Ihrer Administration

Schritt für Schritt

  1. 1

    Adresse und Fassung verstehen

    Alle Aufrufe laufen über https://api.elyph.io/v1. Die Fassung steht im Pfad; neue Felder kommen ohne Ankündigung hinzu, bestehende Felder werden innerhalb einer Fassung nicht entfernt oder umbenannt.

    curl
    curl -sS https://api.elyph.io/v1
# Antwort: Name, Fassung, Verzeichnis aller Ressourcen und Adresse der OpenAPI-Datei
  2. 2

    Ressourcen kennen

    Verfügbar sind Beurteilungen (/v1/assessments), Gefährdungen (/v1/hazards), Risiken (/v1/risk-scenarios), Barrieren (/v1/barriers), Barrierenprüfungen (/v1/barrier-checks), Maßnahmen (/v1/actions), Qualifikationen (/v1/qualifications), Dokumente (/v1/documents), Behördenvorgänge (/v1/correspondence), Kennzahlen (/v1/metrics), Standorte (/v1/sites). Lesend sind alle Bereiche erreichbar; schreibend nur Gefährdungen, Barrierenprüfungen, Maßnahmen und Qualifikationen.

  3. 3

    Antwortform erwarten

    Jede Liste antwortet mit `data`, `page` und `rate`. Einzelabrufe antworten nur mit `data`. Fehler antworten mit `error.code` und `error.message`.

    Form
    {
  "data": [ /* Objekte */ ],
  "page": { "next": "eyJ1IjoiMjAy…", "limit": 50 },
  "rate": { "limit": 120, "remaining": 118, "reset_at": "2026-02-01T10:31:00Z" }
}
  4. 4

    Maschinenlesbare Beschreibung nutzen

    Unter https://api.elyph.io/v1/openapi.json liegt die OpenAPI-3.1-Datei. Daraus lassen sich Clients für nahezu jede Sprache erzeugen.

    Client erzeugen
    curl -sS https://api.elyph.io/v1/openapi.json -o elyph-openapi.json
npx @openapitools/openapi-generator-cli generate \
  -i elyph-openapi.json -g typescript-fetch -o ./elyph-client

API-Konsole

Anfrage zusammenstellen, Code kopieren und — angemeldet und mit eigenem Schlüssel — wirklich ausführen. Die Konsole führt ausschließlich lesende Aufrufe aus.

GET https://api.elyph.io/v1/assessments?limit=10

Statuswert exakt wie im Feld `status`.

Kennung des Standorts (UUID der Organisationseinheit).

Nur Objekte, die seit diesem Zeitpunkt geändert wurden (ISO 8601). Grundlage jeder Synchronisation.

Anzahl der Objekte je Seite, 1 bis 200. Standard 50.

Fortsetzungsmarke aus `page.next` der vorherigen Antwort. Keine Seitenzahl.

curl
curl -sS "https://api.elyph.io/v1/assessments?limit=10" \
  -H "Authorization: Bearer $ELYPH_API_KEY"

Echttest

Nach der Anmeldung führen Sie dieselbe Anfrage hier mit Ihrem eigenen Schlüssel aus. So sieht eine echte Antwort aus:

Beispielantwort
{
  "data": [
    {
      "reference": "GBU-2026-014",
      "title": "Instandhaltung Presse 3",
      "status": "approved",
      "version": 2,
      "scope": "Werk Nord, Halle 2",
      "activity": "Störungsbeseitigung an der Presse",
      "owner": {
        "name": "Sabine Kern",
        "email": "sabine.kern@example.com"
      },
      "site": {
        "reference": "WN",
        "name": "Werk Nord"
      },
      "legal_basis": "§ 5 ArbSchG, § 3 BetrSichV",
      "valid_from": "2026-02-01",
      "valid_until": "2028-01-31",
      "approved_at": "2026-01-28T09:12:44Z",
      "review_interval_months": 24,
      "updated_at": "2026-01-28T09:12:44Z"
    }
  ],
  "page": {
    "next": null,
    "limit": 10
  },
  "rate": {
    "limit": 120,
    "remaining": 118,
    "reset_at": "2026-02-01T10:31:00Z"
  }
}

Ergebnis

Sie wissen, welche Daten die Schnittstelle liefert und wie eine Antwort aussieht.

Häufige Stolpersteine

  • Die Oberflächen-Adresse elyph.io für Aufrufe nutzen: Die Schnittstelle antwortet ausschließlich unter api.elyph.io.
  • Feste Feldreihenfolge annehmen: Werten Sie JSON nach Feldnamen aus, nicht nach Position.

Hintergrund

Die Schnittstelle ist mandantengetrennt: Ein Schlüssel sieht ausschließlich Daten des Mandanten, für den er ausgestellt wurde. Zusätzlich kann ein Zugang auf einzelne Standorte begrenzt werden.

Verwandte Artikel