Website-Kursanmeldung (Familienformular)

Mit der passwortlosen Familien-/Kurs-Anmeldung können Vereine ein Formular auf der eigenen Website betreiben (z. B. Kinderkurs oder Karate-Kids). Eltern tragen sich und ihre Kinder ein — ohne Aktivoo-Login und ohne Passwort. aktivoo legt daraus Kontaktperson, Kinder als Mitglieder und die Kurszuweisung an.

Das ist der richtige Weg, wenn Interessenten sich direkt für einen konkreten Kurs melden sollen und erst später (oder gar nicht) einen App-Zugang brauchen. Die klassische Selbstregistrierung mit Vereinscode bleibt für den Beitritt mit Freigabe und Login.

Was passiert bei einer Anmeldung?

Familienanmeldung (Kontaktperson und Kind haben unterschiedliche Namen):

1. Die Kontaktperson wird als Kontakt ohne App-Login angelegt.
2. Jedes Kind wird als Mitglied angelegt und mit der Kontaktperson verknüpft.
3. Alle Kinder werden dem angegebenen Kurs zugewiesen.

Selbstanmeldung (Vor- und Nachname von Kontakt und einzigem Kind identisch, z. B. Erwachsenen-Kurs):

1. Es wird nur ein Mitglied angelegt (kein separater Kontaktperson-Datensatz).
2. Das Mitglied wird dem Kurs zugewiesen.

Das Startdatum der Zuweisung ist standardmäßig der Anmeldetag (Zeitzone Europe/Berlin), optional überschreibbar.

E-Mails, die bereits in einer anderen Organisation vorkommen, sind unproblematisch: In der Ziel-Organisation wird einfach ein neues Mitglied (bzw. Kontakt+Kinder) angelegt.

Voraussetzungen

• Organisation mit bekanntem Slug (z. B. fc-bohmfeld)
• Bestehender Kurs (UUID aus der Kursverwaltung)
• Service-Token (akt_…) der Organisation

Service-Token erzeugen

Als Owner/Admin unter Einstellungen → KI-Assistent den Bereich Website-Integrations-Token (Service-Token) öffnen und den Token erzeugen bzw. kopieren.

Den Token nur serverseitig speichern (z. B. als Umgebungsvariable AKTIVOO_SERVICE_TOKEN in einem Website-Proxy). Niemals im Browser-JavaScript oder in öffentlichen Repositories ablegen. Nach dem Neu-Generieren ist der alte Token sofort ungültig — den Wert auf der Website dann aktualisieren.

API-Aufruf

POST https://api.aktivoo.de/api/organizations/by-slug/{slug}/family-course-registrations
Authorization: Bearer akt_…
Content-Type: application/json

{slug} ist der Organisations-Slug (Groß-/Kleinschreibung egal; serverseitig normalisiert).

Request-Body

Feld	Typ	Pflicht	Beschreibung
contact	Objekt	ja	Kontaktperson (Elternteil)
contact.firstName	string	ja	Vorname (1–100 Zeichen)
contact.lastName	string	ja	Nachname (1–100 Zeichen)
contact.email	string | null	bedingt	E-Mail; entweder email oder mobileNumber muss gesetzt sein
contact.mobileNumber	string | null	bedingt	Telefon (max. 50 Zeichen)
children	Array	ja	Mindestens ein Kind
children[].firstName	string	ja	Vorname
children[].lastName	string	ja	Nachname
children[].dateOfBirth	string	ja	Geburtsdatum als ISO-Datum YYYY-MM-DD
children[].primaryContactRelationship	string	nein	mother | father | guardian (Default: guardian)
courseId	string (UUID)	ja	Kurs der Organisation
startDate	string	nein	Startdatum der Kurszuweisung YYYY-MM-DD; Default: heutiger Tag (Europe/Berlin)

Beispiel

{
  "contact": {
    "firstName": "Anna",
    "lastName": "Muster",
    "email": "anna.muster@example.com",
    "mobileNumber": "+491701234567"
  },
  "children": [
    {
      "firstName": "Max",
      "lastName": "Muster",
      "dateOfBirth": "2016-04-12",
      "primaryContactRelationship": "mother"
    },
    {
      "firstName": "Lea",
      "lastName": "Muster",
      "dateOfBirth": "2018-09-03",
      "primaryContactRelationship": "mother"
    }
  ],
  "courseId": "8d14e8d8-95ef-4e27-af51-704fcb831a22",
  "startDate": "2026-10-23"
}

Erfolgreiche Antwort (201 Created)

{
  "contactId": "…",
  "children": [
    {
      "memberId": "…",
      "assignmentId": "…",
      "firstName": "Max",
      "lastName": "Muster"
    }
  ]
}

Bestehende E-Mail in der Organisation

Wenn die Kontakt-E-Mail bereits in derselben Organisation als Mitglied, Kontaktperson oder Org-Anwender existiert, legt aktivoo keinen zweiten Datensatz an. Stattdessen wird das bestehende Mitglied dem Kurs zugewiesen (Zuweisung ist idempotent). Die Antwort enthält dann "reusedExisting": true.

Optionales clubNotify

Zusatzinfos für die Vereinswebsite (Anzug, Ort, …), die aktivoo per SMTP an clubNotify.notifyEmail schickt — nicht als Mitgliederfelder gespeichert.

Typische Fehler

Status	Bedeutung
401	Bearer-Header fehlt, Token ungültig oder kein akt_…-Service-Token
404	Unbekannter Slug oder courseId gehört nicht zu dieser Organisation
400	Validierung (z. B. weder E-Mail noch Telefon bei der Kontaktperson; ungültige Felder)

Empfohlene Einbindung

Das Formular auf der Vereinswebsite sollte nicht direkt von Browser aus gegen die aktivoo-API posten. Stattdessen:

1. Browser → eigener Backend-/Serverless-Proxy (z. B. Vercel Function)
2. Proxy setzt Authorization: Bearer akt_… und leitet den Body an den Endpoint weiter
3. Antwort bzw. Fehlermeldung zurück an das Formular

So bleibt der Service-Token geheim, und Sie können Spam-Schutz (Captcha, Rate-Limit) auf der eigenen Seite belassen.

Abgrenzung

	Website-Kursanmeldung	Selbstregistrierung (Vereinscode)
Ziel	Kinder in einen Kurs bringen	Person erhält (nach Freigabe) Login
Passwort / App-Konto	nein	ja, nach Admin-Freigabe
Authentifizierung	org-gebundener Service-Token	Vereinscode / öffentliche Register-Route
Typische Nutzung	Anmeldeformular auf der Vereinswebsite	QR-Code, App „Organisation beitreten“

Mitglieder und Kurszuweisungen erscheinen danach wie manuell angelegte Datensätze unter Mitglieder & Kontakte bzw. im Kurs.