Zum Inhalt springen
Esc
↑↓navigieren↵öffnen⌘Jvorschau
Auf dieser Seite

Erste Schritte

Erstellen Sie eine Fuxam-API-v4-Integration, bauen Sie Basic Auth auf, rufen Sie GET /users auf, lesen Sie das Response-Envelope und paginieren Sie Ihre erste Liste.

Dieser Leitfaden führt Sie von null zu einer funktionierenden authentifizierten Anfrage an die Fuxam API v4. Am Ende haben Sie eine Integration erstellt, einen Authorization-Header gebaut, GET /users aufgerufen, das Envelope { data, meta } interpretiert und mit einem Cursor eine zweite Seite abgerufen.

Base URL: https://fuxam.app/api/v4

Warum das wichtig ist

Ein erster erfolgreicher Aufruf beweist drei Dinge zugleich: Ihre Zugangsdaten funktionieren, Ihr Netzwerkpfad zu fuxam.app ist offen, und Ihr Client parst die gemeinsame Antwortform korrekt. Diese Grundlagen früh richtig zu setzen, verhindert stundenlanges Debuggen, wenn Sie später Writes, Retries und mehrseitige Sync-Jobs hinzufügen.

Bevor Sie beginnen

Sie benötigen:

  • Zugriff auf die Organisationseinstellungen Ihrer Institution in Fuxam Web, um eine API-Integration zu erstellen.
  • Ein Terminal mit curl (oder einem beliebigen HTTP-Client, der Basic Auth senden kann).
  • Einen sicheren Ort zur Speicherung des clientSecret — behandeln Sie ihn wie ein Passwort.

Weiterführende Lektüre: Authentifizierung zur Sicherheit von Zugangsdaten, Übersicht für die vollständige Konventionsübersicht und Nutzerverwaltung dazu, wie Nutzer in der Produkt-UI erscheinen.

So erstellen Sie eine Integration

Öffnen Sie in Fuxam Web Organisation → API-Integrationen.

Erstellen Sie eine neue Integration und notieren Sie clientId und clientSecret, sobald sie angezeigt werden. Speichern Sie das Secret sofort — Sie brauchen es für jede Anfrage.

Bestätigen Sie, dass die Integration für Ihre Institution aktiv ist, bevor Sie Aufrufe machen. Zugangsdaten sind institutionsbezogen; sie sehen nur die Daten dieser Institution.

So bauen Sie den Authorization-Header

HTTP Basic Auth kodiert clientId:clientSecret als Base64 und sendet es im Authorization-Header:

Authorization: Basic <base64(clientId:clientSecret)>

Erzeugen Sie den Wert in Ihrer Shell (Platzhalter ersetzen):

CLIENT_ID="your_client_id"
CLIENT_SECRET="your_client_secret"
AUTH=$(printf '%s:%s' "$CLIENT_ID" "$CLIENT_SECRET" | base64 | tr -d '\n')
echo "Authorization: Basic $AUTH"

So machen Sie Ihre erste Anfrage

Listen Sie Nutzer mit GET /users. Das ist ein sicherer Nur-Lese-Aufruf und ein guter Smoke-Test.

curl -sS \
  -u "${CLIENT_ID}:${CLIENT_SECRET}" \
  -H "Accept: application/json" \
  "https://fuxam.app/api/v4/users?limit=25"

Äquivalentes Raw-HTTP:

GET /api/v4/users?limit=25 HTTP/1.1
Host: fuxam.app
Authorization: Basic <base64(clientId:clientSecret)>
Accept: application/json

Eine erfolgreiche Antwort sieht so aus:

{
  "data": [
    { "id": "usr_123", "email": "user@example.com" },
    { "id": "usr_456", "email": "another@example.com" }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6MTIzfQ==",
    "has_more": true,
    "limit": 25
  },
  "meta": {
    "requestId": "req_1700000000000_abc123",
    "timestamp": "2026-01-15T10:30:00.000Z",
    "version": "v4"
  }
}

Das Envelope lesen

Feld Rolle
data Die Ressource oder Liste von Ressourcen. Bei Listen ist das immer ein Array.
pagination Bei Listenantworten vorhanden: next_cursor, has_more, limit.
meta.requestId Diese Antwort bei der Fehleranalyse mit Server-Logs korrelieren.
meta.timestamp Serverzeit der Antwort.
meta.version Auf dieser API immer "v4".

Bewahren Sie meta.requestId auf, wenn Sie ein Support-Ticket öffnen — so finden Sie die Anfrage am schnellsten.

So paginieren Sie

Wenn pagination.has_more true ist, fordern Sie die nächste Seite mit dem undurchsichtigen next_cursor-Wert an:

curl -sS \
  -u "${CLIENT_ID}:${CLIENT_SECRET}" \
  -H "Accept: application/json" \
  "https://fuxam.app/api/v4/users?limit=25&cursor=${NEXT_CURSOR}"
GET /api/v4/users?limit=25&cursor=eyJpZCI6MTIzfQ== HTTP/1.1
Host: fuxam.app
Authorization: Basic <base64(clientId:clientSecret)>
Accept: application/json

Stoppen Sie, wenn has_more false ist. Erfinden oder bearbeiten Sie Cursor nicht — sie sind HMAC-signiert und an Ihre Institution und Integration gebunden. Ein ungültiger Cursor liefert 400 mit dem Code invalid_cursor.

Vollständige Details (einschließlich einer kompletten Schleife über alle Seiten) finden Sie unter Paginierung und Filterung.

Checkliste nach dem ersten Aufruf

Prüfung Erwartung
HTTP-Status 200
Body-Form data-Array plus meta (und meist pagination)
meta.version "v4"
Auth-Fehler 401 bei falschen Zugangsdaten — Secret neu erzeugen oder erneut kopieren
Leeres data Gültig, wenn Ihre Institution noch keine passenden Nutzer hat

Best Practices für erste Integrationen

  • Beginnen Sie mit Listen-Reads (GET /users, GET /courses), bevor Sie erstellen oder aktualisieren.
  • Loggen Sie meta.requestId bei jeder Antwort in Ihrem Integrationsclient.
  • Nutzen Sie während der Entwicklung ein moderates limit (zum Beispiel 25); erhöhen Sie erst bei Syncs im großen Maßstab Richtung 100.
  • Speichern Sie Zugangsdaten in einem Secrets-Manager, nicht in der Quellkontrolle. Siehe Authentifizierung.
  • Wenn Sie schreiben möchten, folgen Sie Fehler und Idempotenz und den Mustern in Rezepte.

Häufige Fallstricke

Symptom Wahrscheinliche Ursache Was tun
401 Unauthorized Falsches clientId/clientSecret oder kaputtes Base64 Zugangsdaten erneut kopieren; -u mit curl statt Handkodierung nutzen
Leeres data-Array Keine passenden Ressourcen oder unerwartete Filter Bestätigen Sie, dass Nutzer in der Nutzerverwaltung existieren
400 invalid_cursor Cursor über Integrationen hinweg wiederverwendet oder bearbeitet Neue Liste von der ersten Seite starten
Client parst nur data pagination / meta ignoriert Modellieren Sie das volle Envelope in Ihren Typen

FAQ

Welchen Endpunkt sollte ich zuerst aufrufen?

GET /users ist ein zuverlässiger Smoke-Test: er ist nur lesend und liefert das Standard-Listen-Envelope. Öffnen Sie die Referenz Nutzer für die vollständigen Operationsdetails.

Brauche ich eine andere Base URL für Staging?

Dieses Handbuch dokumentiert die Produktions-Base-URL https://fuxam.app/api/v4. Verwenden Sie Host und Pfad, die Ihrer Institution für jede Nicht-Produktionsumgebung mitgeteilt wurden.

Kann ich eine Integration auf Nur-Lesen beschränken?

v4 Basic Auth ist für die Integration Alles-oder-nichts — API-Key-Berechtigungs-Scopes sind nicht implementiert. Steuern Sie den Zugriff darüber, wer Integrationen erstellen darf und was Ihr Client-Code aufrufen darf.

Verwandte Seiten

War diese Seite hilfreich?