Zurück zum Hilfecenter

Schnittstelle: Leitfäden

Erste Anfrage an die elyph API

Vom Schlüssel bis zur ersten erfolgreichen Antwort in wenigen Minuten.

Für wen

Entwicklerinnen und Entwickler.

Voraussetzungen

Administrationsrecht im Mandanten oder ein bereits ausgestellter Schlüssel

Schritt für Schritt

  1. 1

    Schlüssel erzeugen

    In der Verwaltung unter „Schnittstelle“ einen Zugang anlegen, Rechte wählen und den Schlüssel kopieren. Er wird genau einmal angezeigt; gespeichert ist nur ein Prüfwert.

  2. 2

    Schlüssel sicher ablegen

    Legen Sie den Schlüssel in den Geheimnisspeicher Ihres Systems und lesen Sie ihn als Umgebungsvariable, hier ELYPH_API_KEY.

    Shell
    export ELYPH_API_KEY="elyph_live_ab12cd34ef.9f…"
  3. 3

    Erste Anfrage senden

    Der Schlüssel wird als Bearer-Token im Kopf `Authorization` mitgeschickt. Ein guter Anfang ist die Liste der Standorte, weil sie klein ist.

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

    Antwort prüfen

    Status 200 mit `data` bedeutet Erfolg. Status 401 heißt: Schlüssel fehlt, ist falsch oder abgelaufen. Status 403 heißt: Der Zugang hat das nötige Recht nicht.

    Fehlerbeispiel
    {
  "error": {
    "code": "missing_scope",
    "message": "Dieser Zugang hat kein Recht 'sites:read'."
  }
}
  5. 5

    In der Konsole ausprobieren

    Die API-Konsole im Hilfebereich baut die Anfrage zusammen, zeigt den passenden Code und führt sie für angemeldete Kunden mit dem eigenen Schlüssel wirklich aus.

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/sites?limit=10

Art der Organisationseinheit, etwa `standort` oder `bereich`.

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/sites?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": "WN",
      "name": "Werk Nord",
      "type": "standort",
      "parent_id": null,
      "country": "DE",
      "jurisdiction": "DE",
      "postal_code": "76131",
      "city": "Karlsruhe",
      "industry": "Metallverarbeitung",
      "employee_count": 240,
      "active": true,
      "updated_at": "2025-12-02T09:00:00Z"
    }
  ],
  "page": {
    "next": null,
    "limit": 10
  },
  "rate": {
    "limit": 120,
    "remaining": 118,
    "reset_at": "2026-02-01T10:31:00Z"
  }
}

Ergebnis

Eine erfolgreiche Antwort mit Status 200 und den ersten Datensätzen Ihres Mandanten.

Häufige Stolpersteine

  • Schlüssel im Quellcode oder in der Adresszeile mitgeben: Er gehört ausschließlich in den Kopf `Authorization`.
  • Schlüssel im Browser einer Kundenanwendung verwenden: Er ist ein Serverschlüssel und darf nie öffentlich werden.

Hintergrund

Jede Anfrage wird protokolliert: Zeitpunkt, Pfad, Status, Trefferzahl und Laufzeit. Das Protokoll ist in der Verwaltung einsehbar und dient als Nachweis der Datenweitergabe.

Verwandte Artikel