Angebote auf Ihrer Website

Die veröffentlichten Angebote Ihres Programms lassen sich ohne Token lesen. Dieser Leitfaden zeigt, wie Sie sie auf Ihre eigene Website, die Seite eines Partners oder in eine App bringen und wie Sie sie aktuell halten.

Was Sie erhalten

Ohne Token liefert GET /offers die Angebote, die auch die öffentliche fepli-Website zeigt:

• Angebote, die veröffentlicht sind,
• in einer Saison, die online ist,
• und öffentlich, also nicht nur über einen privaten Link erreichbar.

Jedes Angebot enthält seine öffentlichen Felder: Name, Teaser, Beschreibung, Termine, Beitrag, Altersgrenzen, Treffpunkt, freie Plätze, Bilder, Kategorien, Veranstalter:innen und den Link auf seine Seite auf der fepli-Website. Felder, die Aufrufern mit Token vorbehalten sind, etwa die Kontaktperson oder die Zahl der Anmeldungen, fehlen.

Auf dem Server abrufen

Anonyme Anfragen sind auf 5 pro Stunde und IP-Adresse begrenzt (siehe Rate-Limits). Würden Sie die API aus den Browsern Ihrer Besucher:innen aufrufen, funktionierte das nur für die ersten Besucher:innen eines Büronetzes. Danach schlügen die Anfragen fehl. Gehen Sie deshalb so vor:

1. Rufen Sie die Angebote auf Ihrem Server ab.
2. Speichern Sie das Ergebnis zwischen, in einer Datei, einer Datenbank oder im Cache Ihres CMS.
3. Liefern Sie Ihre Seiten aus dem Cache aus und aktualisieren Sie ihn alle paar Stunden.

Ein vollständiger Abruf stellt außerdem sicher, dass die Daten stimmen: Angebote, die zurückgezogen oder gelöscht wurden, kommen nicht wieder.

Wenn Sie auf Ihrem Server nichts betreiben möchten, zeigen die Bausteine die Angebote ohne eigenen Code, und mit einem öffentlichen Schlüssel kann Ihr eigenes JavaScript die API aus dem Browser aufrufen.

import { readFile, writeFile } from 'node:fs/promises'

const API = 'https://example.fepli.eu/api'
const CACHE = './offers.json'
const MAX_AGE = 3 * 60 * 60 * 1000 // drei Stunden

export async function getOffers() {
  try {
    const cached = JSON.parse(await readFile(CACHE, 'utf8'))
    if (Date.now() - cached.fetchedAt < MAX_AGE) return cached.offers
  } catch {}

  const offers = []
  for (let page = 1; ; page++) {
    const query = new URLSearchParams({
      edition: 'herbstferien-2026',
      itemsPerPage: 200,
      page,
    })
    const response = await fetch(`${API}/offers?${query}`)
    if (!response.ok) throw new Error(`fepli API: ${response.status}`)
    const batch = await response.json()
    offers.push(...batch)
    if (batch.length < 200) break
  }

  await writeFile(CACHE, JSON.stringify({ fetchedAt: Date.now(), offers }))
  return offers
}

Bei 200 Angeboten pro Seite braucht eine Saison mit 350 Angeboten zwei Anfragen pro Aktualisierung, weit unter dem Limit.

Auswählen, was angezeigt wird

Grenzen Sie die Liste mit Filtern ein. Sie lassen sich kombinieren:

Die Aliasse von Saisons, Kategorien und Veranstalter:innen finden Sie in den Angeboten selbst: Jedes Angebot trägt edition, categories und hosts als Referenzen mit uuid, name und alias.

Eine Angebotskarte bauen

Die Felder, die Sie am ehesten brauchen:

Familien melden sich auf der fepli-Website an, nicht auf Ihrer. Verlinken Sie jede Karte auf ihre url, dann landen die Familien auf der Seite des Angebots mit dem Anmeldeformular.

{
  "uuid": "0192a4f1-6e3b-7c85-b1d2-8f4e6a9c3b03",
  "name": "Fahrradtour durch den Stadtpark",
  "alias": "fahrradtour-durch-den-stadtpark",
  "edition": {
    "uuid": "01913e5c-2b4a-7d10-9f3e-6a1c2e7b4d01",
    "name": "Herbstferien 2026",
    "alias": "herbstferien-2026"
  },
  "hosts": [
    {
      "uuid": "01905a7e-8c21-7b3f-a0d4-3e9f1c6b2a02",
      "name": "Stadtjugendring Elmsbrück e.V.",
      "alias": "stadtjugendring-elmsbrueck"
    }
  ],
  "status": ["published"],
  "teaser": "Mit dem Rad durch den Park – mit Picknick am See.",
  "description": "Eine **geführte Fahrradtour** für Kinder ab 8 Jahren.\n\nBitte mitbringen:\n\n- Fahrrad\n- Helm",
  "dates": [
    {
      "uuid": "0192a4f2-0a11-7e6c-9d38-2b7f5c1e8a04",
      "begin": "2026-10-14T09:00:00+02:00",
      "end": "2026-10-14T12:00:00+02:00"
    }
  ],
  "fee": 750,
  "minAge": 8,
  "maxAge": 12,
  "maxParticipants": 15,
  "vacancies": 4,
  "fullyBooked": false,
  "requiresApplication": true,
  "onlineApplication": true,
  "applicationDeadline": "2026-09-30T23:59:59+02:00",
  "meetingPoint": "Haupteingang Stadtpark",
  "meetingAddress": "Parkstraße 1, 12345 Elmsbrück",
  "meetingLat": 52.520008,
  "meetingLng": 13.404954,
  "bring": "Fahrrad und Helm",
  "wheelchairAccessible": false,
  "categories": [
    {
      "uuid": "018f2c3d-4e5f-7a6b-8c7d-9e0f1a2b3c12",
      "name": "Sport & Bewegung",
      "alias": "sport-bewegung"
    }
  ],
  "url": "https://example.fepli.eu/angebote/herbstferien-2026/1C8wV6pQk2Tz9RfXh4MbNd-fahrradtour-durch-den-stadtpark",
  "media": [
    "https://example.fepli.eu/assets/images/f/fahrradtour-3000x2000.jpg"
  ],
  "createdAt": "2026-08-03T10:12:44+02:00",
  "modifiedAt": "2026-09-15T16:40:02+02:00"
}

Felder ohne Wert fehlen in der Antwort. Behandeln Sie ein fehlendes Feld als leer. Siehe Konventionen.

Abgesagte, nicht fertige und private Angebote

Ein veröffentlichtes Angebot, das abgesagt wird, bleibt in der Liste, und sein status lautet ["published", "cancelled"]. So können Familien, die es gesehen haben, erfahren, dass es abgesagt wurde.

Angebote, die noch in Vorbereitung sind, und Angebote, die nur über einen privaten Link veröffentlicht sind, liefert die API ohne Token nie. Brauchen Sie sie in Ihrer Integration, etwa weil die Website einer Veranstalter:in ihre Entwürfe zeigt, verwenden Sie ein Token mit Lesezugriff.