API Schnellstart - Parq User Provisioning API

🎉 Neu in Version 3.2

Vollständige API-Konsistenz

Alle drei Entitätstypen (Organisationen, Teamleiter, Lernende) haben jetzt 100% identisches Verhalten:

✓ "Already Active" Prüfung für alle Aktivierungs-Endpunkte
✓ deleted_at wird bei Aktivierung gelöscht
✓ Kompaktes Antwortformat für alle Deaktivierungen
✓ Konsistenter ALREADY_ACTIVE Fehlercode

🚀 Erste Schritte

1. API-Schlüssel einrichten

Fügen Sie Ihren API-Schlüssel zu allen Anfragen hinzu:

Authorization: Bearer IHR_API_SCHLÜSSEL

2. Verbindung testen

Listen Sie Ihre Organisationen auf:

curl -X GET "https://api.parq-app.com/api/v1/organizations" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL"

✨ RESTful Path Parameter Support (v2.2)

Die API unterstützt beide Formate für maximale Flexibilität:

✅ Empfohlen: Path Parameter

GET /api/v1/users/learners/EMP-67890
DELETE /api/v1/organizations/ORG-100

✅ Auch möglich: Query Parameter

GET /api/v1/users/learners?id=EMP-67890
DELETE /api/v1/organizations?id=ORG-100

🔗 External ID Unterstützung

Verwenden Sie Ihre eigenen internen IDs statt UUIDs:

• external_id ist optional bei Erstellung von Organisationen, Teamleitern und Lernenden
• Statt UUID 660e8400-... können Sie EMP-67890 verwenden
• UUID hat Vorrang - wenn ein Wert wie UUID aussieht, wird er als UUID behandelt
• Eindeutigkeit pro Firma - verschiedene Firmen können gleiche external_id verwenden

📚 Verfügbare Endpunkte

Organisationen

Methode	Endpunkt	Beschreibung
`POST`	`/api/v1/organizations`	Organisation erstellen
`GET`	`/api/v1/organizations/:id`	Organisation abrufen
`GET`	`/api/v1/organizations`	Organisationen auflisten
`PUT`	`/api/v1/organizations/:id`	Organisation aktualisieren
`PATCH`	`/api/v1/organizations/:id/activate`	Organisation aktivieren
`PATCH`	`/api/v1/organizations/:id/deactivate`	Organisation deaktivieren
`DELETE`	`/api/v1/organizations/:id`	Organisation soft-löschen
`DELETE`	`/api/v1/organizations/:id?permanent=true`	Organisation permanent löschen

Teamleiter

Methode	Endpunkt	Beschreibung
`POST`	`/api/v1/users/team-leads`	Teamleiter erstellen
`GET`	`/api/v1/users/team-leads/:id`	Teamleiter abrufen
`GET`	`/api/v1/users/team-leads`	Teamleiter auflisten
`PUT`	`/api/v1/users/team-leads/:id`	Teamleiter aktualisieren
`PATCH`	`/api/v1/users/team-leads/:id/activate`	Teamleiter aktivieren
`PATCH`	`/api/v1/users/team-leads/:id/deactivate`	Teamleiter deaktivieren
`DELETE`	`/api/v1/users/team-leads/:id`	Teamleiter soft-löschen (kaskadiert!)
`DELETE`	`/api/v1/users/team-leads/:id?permanent=true`	Teamleiter permanent löschen
`POST`	`/api/v1/users/team-leads/:id/transfer-learners`	Alle Lernende übertragen

Lernende

Methode	Endpunkt	Beschreibung
`POST`	`/api/v1/users/learners`	Lernenden erstellen
`GET`	`/api/v1/users/learners/:id`	Lernenden abrufen
`GET`	`/api/v1/users/learners`	Lernende auflisten
`PUT`	`/api/v1/users/learners/:id`	Lernenden aktualisieren
`PATCH`	`/api/v1/users/learners/:id/activate`	Lernenden aktivieren
`PATCH`	`/api/v1/users/learners/:id/deactivate`	Lernenden deaktivieren
`DELETE`	`/api/v1/users/learners/:id`	Lernenden soft-löschen
`DELETE`	`/api/v1/users/learners/:id?permanent=true`	Lernenden permanent löschen

Organisationszuweisungen

Methode	Endpunkt	Beschreibung
`POST`	`/api/v1/users/learner-organizations/:id/add`	Organisationen hinzufügen
`DELETE`	`/api/v1/users/learner-organizations/:id/:org_id`	Organisation entfernen

💡 Häufigste Szenarien

Organisation erstellen

curl -X POST "https://api.parq-app.com/api/v1/organizations" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Deutsches Rotes Kreuz",
    "description": "Humanitäre Organisation",
    "external_id": "ORG-100"
  }'

Teamleiter erstellen

curl -X POST "https://api.parq-app.com/api/v1/users/team-leads" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Anna",
    "surname": "Schmidt",
    "email": "anna.schmidt@firma.de",
    "external_id": "TL-12345"
  }'

Lernenden erstellen

curl -X POST "https://api.parq-app.com/api/v1/users/learners" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Max",
    "surname": "Mustermann",
    "email": "max@example.de",
    "external_id": "EMP-67890",
    "team_lead_id": "TL-12345",
    "organizations": ["ORG-100", "Rotes Kreuz"]
  }'

Tipp: organizations akzeptiert UUIDs, external_ids oder Namen (Namen werden automatisch erstellt)

Organisationen zu Lernendem hinzufügen

curl -X POST "https://api.parq-app.com/api/v1/users/learner-organizations/EMP-67890/add" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL" \
  -H "Content-Type: application/json" \
  -d '{ "organizations": ["ORG-200", "Neue Organisation"] }'

Lernende zwischen Teamleitern übertragen (Bulk)

100x schneller als einzelne Updates - alle Lernende mit einem Aufruf übertragen!

curl -X POST "https://api.parq-app.com/api/v1/users/team-leads/TL-12345/transfer-learners" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL" \
  -H "Content-Type: application/json" \
  -d '{ "to_team_lead_id": "TL-67890" }'

⚠️ Wichtige Hinweise

API-Schlüssel geheim halten - Niemals in öffentlichen Repositories speichern
Rate Limits beachten - Max. 100 Anfragen/Minute
HTTPS verwenden - Nur verschlüsselte Verbindungen
Soft Delete bevorzugen - Deaktivieren statt löschen
external_id nutzen - Empfohlen für einfachere Integration

Vollständige Dokumentation

Für detaillierte Informationen, Beispiele und alle Endpunkte lesen Sie bitte die vollständige API-Dokumentation.

Vollständige API-Dokumentation

Support

Bei Fragen kontaktieren Sie: support@parq-app.com

User Provisioning API - Schnellstart