Developer docs

GraphQL-Schnittstelle

• Die Pluvo-API ist eine GraphQL-basierte Schnittstelle zur Verwaltung von Benutzern, Schulungen, Veranstaltungen und mehr.
• Die Authentifizierung erfolgt über ein OAuth-Token auf Basis von client_id und client_secret.
• Webhooks bieten Echtzeit-Updates zu Anmeldungen, Statusänderungen und mehr.
• Endpoint: https://[organization].pluvo.com/graphql/

Die Pluvo-API ermöglicht es externen Systemen wie HRM-Plattformen und Integrationstools, programmatisch mit der Pluvo-Plattform zu kommunizieren.

Authentifizierung

Der Zugriff auf die API erfordert ein OAuth-Token, das Sie wie folgt anfordern:

POST https://[organization].pluvo.com/oauth/token/

Wichtig:

• Der Endpoint erfordert einen abschließenden Schrägstrich (Trailing Slash) /
• Header: Content-Type: application/x-www-form-urlencoded
• Body-Parameter: grant_type=client_credentials, client_id, client_secret, scope

Ein gültiges Token wird als Bearer-Token eingebunden:

Authorization: Bearer <your_token>

Zugriffstokens sind 24 Stunden lang gültig. Nach Ablauf muss ein neues Token angefordert werden. Es gibt keinen Refresh-Token-Flow für client_credentials.

Scopes und Zugriffsebenen

Scopes steuern, worauf Ihr API-Client zugreifen kann. Verfügbare Scopes:

• users.read / users.write — Benutzerprofile, Rollen und Gruppen anzeigen/verwalten
• trainings.read / trainings.write — Lernpfade, Module und Fortschritte anzeigen/verwalten
• groups.read / groups.write — Gruppen, Mitglieder und Manager anzeigen/verwalten
• events.read / events.write — Angebote und Anmeldungen anzeigen/verwalten
• extra_categories.write — Benutzerdefinierte Felder erstellen und aktualisieren

Mehrere Scopes können durch Leerzeichen getrennt angefordert werden: scope=users.read users.write trainings.read

API-Endpunkt

Alle Anfragen werden an folgende Adresse gesendet:

https://[organization].pluvo.com/graphql/

Der abschließende Schrägstrich ist erforderlich.

GraphQL: Kurzer Überblick

Sie bestimmen, welche Felder Sie abrufen oder aktualisieren, was für minimale Payloads und maximale Flexibilität sorgt.

query user($ref: String!) {
  user(ref: $ref) {
    ref
    name
    email
    isActive
  }
}

Die ref dient als eindeutige Kennung innerhalb Ihres eigenen Systems.

Fehlerbehandlung

GraphQL-Fehler werden im Antwort-Body mit dem HTTP-Status 200 zurückgegeben. Überprüfen Sie immer das errors Array:

{
  "data": null,
  "errors": [
    {
      "message": "User not found",
      "locations": [{"line": 2, "column": 3}],
      "path": ["user"]
    }
  ]
}

Häufige Fehler: Ungültiges/abgelaufenes Token (HTTP 401), unzureichende Berechtigung, Objekt nicht gefunden (null mit Fehler), Validierungsfehler (detaillierte Nachricht).

Webhooks

Pluvo unterstützt Webhooks für Echtzeit-Benachrichtigungen bei Benutzeränderungen, Abschluss von Schulungen/Kursen, Änderungen des Anmeldestatus, Portfolio-/Zertifikatsereignissen und Gruppenänderungen. Die Konfiguration erfolgt über die Admin-Oberfläche. Jede Anfrage enthält eine HMAC-Signatur zur Überprüfung. Weitere Details finden Sie auf der Seite Webhooks.