EntwicklerAPI-Ressourcen

Saisons

Eine Saison ist ein Abschnitt des Programms, etwa die Herbstferien eines Ferienpasses („Herbstferien 2026“) oder ein Kurshalbjahr. In der API ist eine Saison eine edition. Jedes Angebot, jede Anmeldung und jede Zahlung gehört zu einer Saison. Ihre Phasen legen fest, was wann geschieht: wann Veranstalter:innen Angebote eintragen, wann Familien sich anmelden und wann Teilnahmelisten freigegeben werden.

Endpunkte

GET/editionsAlle Saisons abrufen
GET/editions/{uuid}Eine Saison abrufen
POST/editionsEine Saison anlegen
PATCH/editions/{uuid}Eine Saison ändern
DELETE/editions/{uuid}Eine Saison löschen
POST/editions/{uuid}/commit-decisionsZurückgehaltene Entscheidungen festschreiben

Das Modell der Saison

Name
uuid
Typ
string
Beschreibung
Die Kennung der Saison.
Name
name
Typ
string
Beschreibung
Der Name der Saison.
Name
alias
Typ
string
Beschreibung
Ein URL-tauglicher Name. Er gilt überall, wo eine Saison genannt wird, zum Beispiel in ?edition=herbstferien-2026.
Name
emoji
Typ
string
Beschreibung
Ein Emoji, das das Admin-Panel neben dem Namen zeigt, als Kurzcode wie :fallen_leaf:.
Name
archived
Typ
boolean
Beschreibung
Ob die Saison archiviert ist.
Name
online
Typ
boolean
Beschreibung
Ob ihre Angebote jetzt auf der öffentlichen Website erscheinen und damit auch für anonyme Aufrufer der API.
Name
editableForHosts
Typ
boolean
Beschreibung
Ob Veranstalter:innen ihre Angebote jetzt anlegen, ändern und löschen dürfen: solange eine Phase host_editing_stage aktiv ist, nach ihren Terminen oder weil sie alwaysActive ist. Ohne eine Phase host_editing_stage ist die Saison für sie gesperrt.
Name
participantListReleased
Typ
boolean
Beschreibung
Ob Veranstalter:innen ihre Teilnahmelisten jetzt sehen dürfen: solange eine Phase publish_lists aktiv ist, nach ihren Terminen oder weil sie alwaysActive ist. Ohne eine solche Phase bleiben die Listen für sie gesperrt.
Name
hostsCanAssign
Typ
boolean
Beschreibung
Ob Veranstalter:innen Teilnehmer:innen selbst zuweisen dürfen.
Name
hostsCanPublish
Typ
boolean
Beschreibung
Ob Veranstalter:innen ihre eigenen Angebote freigeben und veröffentlichen dürfen.
Name
usePayments
Typ
boolean
Beschreibung
Ob die Beiträge dieser Saison über fepli eingezogen werden.
Name
holiday
Typ
object
Beschreibung
Der Zeitraum, in dem die Angebote stattfinden, mit begin und end.
Name
tasks
Typ
object[]
Beschreibung
Die Phasen der Saison, wie im Admin-Panel eingerichtet. Jede hat eine uuid, einen type (zum Beispiel holiday, host_editing_stage, show_offers, application_system, allocation oder publish_lists), einen title, eine description, periodBegin und periodEnd, alwaysActive und active, ob sie jetzt gilt. Phasen vom type application_system tragen zusätzlich applicationSystem (firstcome oder lot), maxApplications, maxApplicationsDay, maxWaitlist und allowAnonymous. Leere Werte in den Phasen werden als null geliefert.
Name
hosts
Typ
reference[]
Beschreibung
Die Veranstalter:innen, auf die die Saison beschränkt ist. Ist die Liste leer, können alle teilnehmen.
Name
offersCount
Typ
integer
Beschreibung
Die Zahl der Angebote der Saison.
Name
createdAt
Typ
timestamp
Beschreibung
Wann die Saison angelegt wurde.

GET/editions

Alle Saisons abrufen

Liefert eine Seite mit Saisons, die neueste zuerst. Veranstalter:innen sehen ebenfalls alle Saisons.

Optionale Filter

Name
archived
Typ
boolean
Beschreibung
true für nur die archivierten Saisons, false für nur die laufenden.
Name
q
Typ
string
Beschreibung
Nur Saisons, deren Name diesen Text enthält.
Name
page, itemsPerPage
Typ
integer
Beschreibung
Siehe Paginierung.

GET/editions

curl "https://example.fepli.eu/api/editions?archived=false" \
  -H "Authorization: Bearer $FEPLI_TOKEN"

Antwort

[
  {
    "uuid": "01913e5c-2b4a-7d10-9f3e-6a1c2e7b4d01",
    "name": "Herbstferien 2026",
    "alias": "herbstferien-2026",
    "emoji": ":fallen_leaf:",
    "archived": false,
    "online": true,
    "editableForHosts": false,
    "participantListReleased": false,
    "hostsCanAssign": false,
    "hostsCanPublish": false,
    "usePayments": true,
    "holiday": {
      "begin": "2026-10-12T00:00:00+02:00",
      "end": "2026-10-24T23:59:59+02:00"
    },
    "tasks": [
      {
        "uuid": "01913e5d-7a8b-7c9d-8e0f-1a2b3c4d5e17",
        "type": "application_system",
        "title": "Anmeldephase",
        "description": null,
        "periodBegin": "2026-09-01T08:00:00+02:00",
        "periodEnd": "2026-09-30T23:59:59+02:00",
        "alwaysActive": false,
        "active": true,
        "applicationSystem": "firstcome",
        "maxApplications": 5,
        "maxApplicationsDay": null,
        "maxWaitlist": 2,
        "allowAnonymous": false
      }
    ],
    "hosts": [],
    "offersCount": 86,
    "createdAt": "2026-05-04T09:30:00+02:00"
  }
]

GET/editions/{uuid}

Eine Saison abrufen

Liefert eine Saison. Der Pfad nimmt die UUID, nicht den Alias. Jedes Angebot und jede Anmeldung trägt die UUID ihrer Saison in edition.

GET/editions/{uuid}

curl https://example.fepli.eu/api/editions/01913e5c-2b4a-7d10-9f3e-6a1c2e7b4d01 \
  -H "Authorization: Bearer $FEPLI_TOKEN"

POST/editions

Eine Saison anlegen

Legt eine Saison an. Nur für Admins. Der Alias entsteht aus dem Namen. Hat schon eine andere Saison diesen Alias, lautet die Antwort 409. Wählen Sie dann einen anderen Namen.

Eine neue Saison hat keine Phasen. Sie richten die Phasen anschließend im Admin-Panel ein, unter Zeiträume der Saison. Bis dahin gilt:

Die Saison ist sofort online, ihre veröffentlichten Angebote erscheinen also auf der Website und für anonyme Aufrufer.
Familien können sich noch nicht anmelden, weil es keine Phase application_system gibt.
Veranstalter:innen können noch keine Angebote anlegen, ändern oder löschen, weil es keine Phase host_editing_stage gibt.
Veranstalter:innen können noch keine Teilnahmelisten sehen, weil es keine Phase publish_lists gibt.

Die Beiträge werden eingezogen (usePayments ist true), die übrigen Schalter sind aus, das Emoji wird zufällig gewählt, und alle Veranstalter:innen können teilnehmen (hosts ist leer). Eine Saison auf einige Veranstalter:innen zu beschränken, geschieht im Admin-Panel. Das Aktivitätsprotokoll der Saison im Admin-Panel hält fest, wer sie angelegt hat.

Pflichtattribute

Name
name
Typ
string
Beschreibung
Der Name, bis zu 255 Zeichen.

Optionale Attribute

Name
emoji
Typ
string
Beschreibung
Das Emoji als Kurzcode, zum Beispiel :sunflower:. null für keines.
Name
archived
Typ
boolean
Beschreibung
Ob die Saison archiviert beginnt. Standard: false.
Name
hostsCanAssign
Typ
boolean
Beschreibung
Ob Veranstalter:innen Teilnehmer:innen selbst zuweisen dürfen. Standard: false.
Name
hostsCanPublish
Typ
boolean
Beschreibung
Ob Veranstalter:innen ihre eigenen Angebote freigeben und veröffentlichen dürfen. Standard: false.
Name
usePayments
Typ
boolean
Beschreibung
Ob die Beiträge über fepli eingezogen werden. Standard: true.

POST/editions

curl -X POST https://example.fepli.eu/api/editions \
  -H "Authorization: Bearer $FEPLI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Sommerferien 2027", "emoji": ":sunflower:"}'

Antwort (201 Created)

{
  "uuid": "0196b2c4-8d1e-7f20-a3b4-5c6d7e8f9a10",
  "name": "Sommerferien 2027",
  "alias": "sommerferien-2027",
  "emoji": ":sunflower:",
  "archived": false,
  "online": true,
  "editableForHosts": false,
  "participantListReleased": false,
  "hostsCanAssign": false,
  "hostsCanPublish": false,
  "usePayments": true,
  "holiday": null,
  "tasks": [],
  "hosts": [],
  "offersCount": 0,
  "createdAt": "2026-09-22T10:15:00+02:00"
}

PATCH/editions/{uuid}

Eine Saison ändern

Ändert die allgemeinen Einstellungen einer Saison. Nur für Admins. Die tasks verwalten Sie im Admin-Panel.

Der Alias folgt immer dem Namen. Benennen Sie eine Saison um, ändert sich ihr Alias, und Links oder Filter mit dem alten Alias, etwa ?edition=herbstferien-2026, funktionieren nicht mehr. Integrationen, die eine Referenz speichern, sollten die uuid ablegen. Hat schon eine andere Saison den Alias, der zum neuen Namen gehört, lautet die Antwort 409.

Optionale Attribute

Name
name
Typ
string
Beschreibung
Der Name, bis zu 255 Zeichen.
Name
emoji
Typ
string
Beschreibung
Das Emoji. null entfernt es.
Name
archived
Typ
boolean
Beschreibung
Archiviert die Saison oder stellt sie wieder her.
Name
hostsCanAssign
Typ
boolean
Beschreibung
Ob Veranstalter:innen Teilnehmer:innen selbst zuweisen dürfen.
Name
hostsCanPublish
Typ
boolean
Beschreibung
Ob Veranstalter:innen ihre eigenen Angebote freigeben und veröffentlichen dürfen.
Name
usePayments
Typ
boolean
Beschreibung
Ob die Beiträge über fepli eingezogen werden.

PATCH/editions/{uuid}

curl -X PATCH https://example.fepli.eu/api/editions/01913e5c-2b4a-7d10-9f3e-6a1c2e7b4d01 \
  -H "Authorization: Bearer $FEPLI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"hostsCanPublish": true}'

Die Antwort enthält die geänderte Saison.

DELETE/editions/{uuid}

Eine Saison löschen

Löscht eine Saison. Nur für Admins. Antwortet mit 204 No Content.

Solange die Saison noch Angebote hat, lässt sie sich nicht löschen (409). Verschieben Sie die Angebote in eine andere Saison (senden Sie edition, wenn Sie ein Angebot ändern) oder löschen Sie sie zuerst. Das Admin-Panel löscht anders als die API die Angebote einer Saison mit.

Mit der Saison werden ihre Phasen, ihr Aktivitätsprotokoll, ihre Kommentare und die für sie eingerichteten Benachrichtigungstexte gelöscht. Einverständniserklärungen der Saison bleiben ohne die Saison erhalten.

DELETE/editions/{uuid}

curl -X DELETE https://example.fepli.eu/api/editions/0196b2c4-8d1e-7f20-a3b4-5c6d7e8f9a10 \
  -H "Authorization: Bearer $FEPLI_TOKEN"

POST/editions/{uuid}/commit-decisions

Zurückgehaltene Entscheidungen festschreiben

Schreibt jede in der Saison zurückgehaltene Entscheidung fest, wie Anmeldungen festschreiben im Admin-Panel. Nur für Admins.

Das im Admin-Panel durchgeführte Losverfahren hält seine Entscheidungen zurück. Das gilt auch für jede Anmeldung, die mit commit: false angelegt, per Übergang geändert, verschoben oder aufgefüllt wird. Solche Anmeldungen zeigen heldBack: true, und GET /attendances?edition=…&heldBack=true listet sie auf.

Der Aufruf schreibt alle auf einmal fest, für die ganze Saison und nicht je Angebot. Bei Anmeldungen mit Zusage wird der Beitrag fällig. Es wird keine E-Mail verschickt. Um die Familien zu informieren, senden Sie ihnen eine Rundmail mit "to": "attendances" und den attendances, die der Aufruf zurückgibt. Jede Familie erhält dann eine E-Mail mit Ihrem Text und dem Status jeder ihrer Anmeldungen.

Die Anmeldungen werden sofort freigegeben und zeigen nach dem Aufruf heldBack: false. Der Rest läuft kurz danach im Hintergrund. Die API antwortet mit 202 Accepted. Wie im Admin-Panel beendet das Festschreiben auch die Phase allocation der Saison: Eine aktive Phase endet damit jetzt.

Ist in der Saison nichts zurückgehalten, lautet die Antwort 409.

Die Anfrage braucht einen JSON-Body. Senden Sie {}.

Antwort

Name
edition
Typ
reference
Beschreibung
Die festgeschriebene Saison.
Name
attendances
Typ
array
Beschreibung
Die UUIDs der Anmeldungen, die jetzt festgeschrieben wurden. Übergeben Sie sie als attendances an POST /mailings.

POST/editions/{uuid}/commit-decisions

curl -X POST https://example.fepli.eu/api/editions/01913e5c-2b4a-7d10-9f3e-6a1c2e7b4d01/commit-decisions \
  -H "Authorization: Bearer $FEPLI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Antwort (202 Accepted)

{
  "edition": {
    "uuid": "01913e5c-2b4a-7d10-9f3e-6a1c2e7b4d01",
    "name": "Herbstferien 2026",
    "alias": "herbstferien-2026"
  },
  "attendances": [
    "0192d0e8-3a4b-7c5d-9e6f-7a8b9c0d1e07",
    "0192d0e8-3a4b-7c5d-9e6f-7a8b9c0d1e08"
  ]
}