EntwicklerAPI-Ressourcen

Zugangscode-Listen

Eine Zugangscode-Liste enthält Codes, die Familien für ihre Kinder einlösen. In der API ist sie eine access-code-list. Die Phase application_system einer Saison kann eine Liste verlangen: Solange die Phase aktiv ist, dürfen sich nur Teilnehmer:innen anmelden, die einen Code der Liste eingelöst haben. Das passt zu einem Programm, das nur für bestimmte Familien offen ist, etwa für die Kinder einer Schule oder die Beschäftigten einer Firma.

Endpunkte

GET/access-code-listsAlle Zugangscode-Listen abrufen
GET/access-code-lists/{uuid}Eine Zugangscode-Liste abrufen
POST/access-code-listsEine Zugangscode-Liste anlegen
PATCH/access-code-lists/{uuid}Eine Zugangscode-Liste ändern
DELETE/access-code-lists/{uuid}Eine Zugangscode-Liste löschen

Alle Endpunkte der Zugangscode-Listen brauchen ROLE_SUPER_ADMIN, auch das Lesen: Die Codes halten das Programm geschlossen. Im Admin-Panel finden Sie die Listen unter Einstellungen → Anmeldung → Zugangscodes.

So werden Codes verwendet

Sie legen eine Liste an und geben ihre Codes aus, zum Beispiel einen pro Familie.
Im Admin-Panel wählen Sie die Liste für eine Phase application_system: Öffnen Sie die Zeiträume der Saison und wählen Sie bei der Phase Anmeldung die Liste unter Anmeldung nur mit Zugangscode. Die API kann einer Phase keine Liste zuweisen, weil sie keine Phasen verwaltet.
Familien geben auf der Website für jedes Kind einen Code ein, genau so, wie er in der Liste steht, mit Groß- und Kleinschreibung. Der Code wird dann mit dieser Teilnehmer:in verknüpft und gilt als einmal verwendet.
Solange die Phase aktiv ist, dürfen sich nur Teilnehmer:innen mit einem Code der Liste anmelden. Allen anderen erscheint der Hinweis, dass sie einen Zugangscode brauchen.

max legt fest, wie viele Teilnehmer:innen denselben Code einlösen dürfen. Mit 1 gilt jeder Code nur einmal, mit 0 beliebig oft.

Das Modell der Zugangscode-Liste

Name
uuid
Typ
string
Beschreibung
Die Kennung der Liste.
Name
name
Typ
string
Beschreibung
Der Name, an dem Sie die Liste wiedererkennen, zum Beispiel Osterferienpass.
Name
max
Typ
integer
Beschreibung
Wie viele Teilnehmer:innen jeden Code einlösen dürfen. 0 bedeutet: unbegrenzt.
Name
codes
Typ
string[]
Beschreibung
Die Codes der Liste.
Name
createdAt
Typ
timestamp
Beschreibung
Wann die Liste angelegt wurde.

GET/access-code-lists

Alle Zugangscode-Listen abrufen

Liefert eine Seite mit Zugangscode-Listen, sortiert nach Name.

Optionale Filter

Name
q
Typ
string
Beschreibung
Nur Listen, deren Name diesen Text enthält.
Name
page, itemsPerPage
Typ
integer
Beschreibung
Siehe Paginierung.

GET/access-code-lists

curl "https://example.fepli.eu/api/access-code-lists?q=oster" \
  -H "Authorization: Bearer $FEPLI_TOKEN"

Antwort

[
  {
    "uuid": "0195d3e4-f5a6-7b7c-8d9e-0f1a2b3c4d31",
    "name": "Osterferienpass Grundschule Nord",
    "max": 1,
    "codes": ["NORD-4821", "NORD-7735", "NORD-9150"],
    "createdAt": "2026-09-14T09:00:00+02:00"
  }
]

GET/access-code-lists/{uuid}

Eine Zugangscode-Liste abrufen

Liefert eine Zugangscode-Liste mit allen ihren Codes.

GET/access-code-lists/{uuid}

curl https://example.fepli.eu/api/access-code-lists/0195d3e4-f5a6-7b7c-8d9e-0f1a2b3c4d31 \
  -H "Authorization: Bearer $FEPLI_TOKEN"

POST/access-code-lists

Eine Zugangscode-Liste anlegen

Legt eine Zugangscode-Liste an. Nur für Super-Admins. Damit die Liste wirkt, wählen Sie sie im Admin-Panel für eine Phase application_system (siehe So werden Codes verwendet).

Jeder Code wird von Leerzeichen am Anfang und Ende befreit. Ein leerer Code oder ein Code, der zweimal in der Liste steht, ist ein 422. Codes, die sich nur in Groß- und Kleinschreibung unterscheiden, gelten als derselbe Code.

Pflichtattribute

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

Optionale Attribute

Name
max
Typ
integer
Beschreibung
Wie viele Teilnehmer:innen jeden Code einlösen dürfen: 0 oder mehr, wobei 0 unbegrenzt bedeutet. Der Standard ist 1.
Name
codes
Typ
string[]
Beschreibung
Die Codes, jeweils bis zu 255 Zeichen. Standardmäßig keine.

POST/access-code-lists

curl -X POST https://example.fepli.eu/api/access-code-lists \
  -H "Authorization: Bearer $FEPLI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Osterferienpass Grundschule Nord",
    "codes": ["NORD-4821", "NORD-7735", "NORD-9150"]
  }'

Antwort (201 Created)

{
  "uuid": "0195d3e4-f5a6-7b7c-8d9e-0f1a2b3c4d31",
  "name": "Osterferienpass Grundschule Nord",
  "max": 1,
  "codes": ["NORD-4821", "NORD-7735", "NORD-9150"],
  "createdAt": "2026-09-14T09:00:00+02:00"
}

PATCH/access-code-lists/{uuid}

Eine Zugangscode-Liste ändern

Ändert eine Zugangscode-Liste. Nur für Super-Admins. Die Attribute und ihre Regeln sind dieselben wie beim Anlegen einer Liste. Senden Sie nur, was Sie ändern wollen. Ein leerer Body ist ein 422.

codes ersetzt die ganze Liste. Um einen Code hinzuzufügen, senden Sie die vorhandenen Codes und den neuen:

Ein Code, der noch in der Liste steht, behält seine Einlösungen: Die Teilnehmer:innen, die ihn eingelöst haben, behalten ihn. Ein Code, den Sie in anderer Groß- und Kleinschreibung senden, ist derselbe Code mit neuer Schreibweise.
Ein Code, der nicht mehr in der Liste steht, wird gelöscht. Teilnehmer:innen, die ihn eingelöst haben, verlieren ihn. Solange sie keinen anderen Code einlösen, können sie sich nicht anmelden, wenn eine aktive Phase die Liste verlangt.
"codes": [] (oder null) löscht alle Codes.

Wenn Sie max senken, nehmen Sie Teilnehmer:innen, die einen Code schon eingelöst haben, den Code nicht weg. Es verhindert nur weitere Einlösungen.

PATCH/access-code-lists/{uuid}

curl -X PATCH https://example.fepli.eu/api/access-code-lists/0195d3e4-f5a6-7b7c-8d9e-0f1a2b3c4d31 \
  -H "Authorization: Bearer $FEPLI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"codes": ["NORD-4821", "NORD-7735", "NORD-9150", "NORD-2264"]}'

Antwort

{
  "uuid": "0195d3e4-f5a6-7b7c-8d9e-0f1a2b3c4d31",
  "name": "Osterferienpass Grundschule Nord",
  "max": 1,
  "codes": ["NORD-4821", "NORD-7735", "NORD-9150", "NORD-2264"],
  "createdAt": "2026-09-14T09:00:00+02:00"
}

DELETE/access-code-lists/{uuid}

Eine Zugangscode-Liste löschen

Löscht eine Zugangscode-Liste mit allen ihren Codes. Nur für Super-Admins. Die Antwort ist 204 No Content.

Solange eine Phase application_system die Liste verlangt, lässt sie sich nicht löschen (409): Sonst stünde die Phase allen offen. Die Meldung nennt die Saisons. Wählen Sie im Admin-Panel zuerst eine andere Liste für diese Phasen oder keine.

Teilnehmer:innen, die einen Code der Liste eingelöst haben, verlieren ihn.

DELETE/access-code-lists/{uuid}

curl -X DELETE https://example.fepli.eu/api/access-code-lists/0195d3e4-f5a6-7b7c-8d9e-0f1a2b3c4d31 \
  -H "Authorization: Bearer $FEPLI_TOKEN"