Angebote

Liefert eine Seite mit Angeboten, sortiert nach ihrem ersten Termin.

• Ohne Token: die veröffentlichten, öffentlichen Angebote der Saisons, die online sind, mit den öffentlichen Feldern.
• Mit Token: jedes Angebot, das Sie im Admin-Panel öffnen könnten, in jedem Status und mit allen Feldern. Admins sehen alle Angebote. Veranstalter:innen sehen die Angebote ihrer Veranstalter-Profile und die Angebote, die mit ihnen geteilt wurden. Ein Token, dessen Inhaber:in weder Admin noch Mitglied eines Veranstalter-Profils ist, sieht kein Angebot, auch kein veröffentlichtes. Lassen Sie das Token weg, um die veröffentlichten zu lesen.

Optionale Filter

• Name

  q

  Typ

  string

  Beschreibung

  Nur Angebote, deren Name diesen Text enthält.

• Name

  edition

  Typ

  string

  Beschreibung

  Nur Angebote dieser Saison (UUID oder Alias).

• Name

  key

  Typ

  string

  Beschreibung

  Ein öffentlicher Schlüssel, für eine Seite einer anderen Website. Nur ohne Token.

• Name

  host

  Typ

  string

  Beschreibung

  Nur Angebote dieser Veranstalter:in (UUID oder Alias).

• Name

  category

  Typ

  string

  Beschreibung

  Nur Angebote dieser Kategorie (UUID oder Alias).

• Name

  status

  Typ

  string

  Beschreibung

  Nur Angebote in diesen Status, durch Kommas getrennt: draft, finalized, reviewed, published, cancelled, completed. published trifft auch Angebote, die nach der Veröffentlichung abgesagt wurden.

• Name

  from

  Typ

  date

  Beschreibung

  Nur Angebote mit einem Termin, der an diesem Tag oder später beginnt.

• Name

  until

  Typ

  date

  Beschreibung

  Nur Angebote mit einem Termin, der an diesem Tag oder früher beginnt. Zusammen mit from passt ein Angebot mit mehreren Terminen, wenn ein Termin an oder nach from liegt und ein Termin an oder vor until. Es muss nicht derselbe Termin sein.

• Name

  modifiedSince

  Typ

  timestamp

  Beschreibung

  Nur Angebote, die seit diesem Zeitpunkt geändert wurden.

• Name

  sort

  Typ

  string

  Beschreibung

  begin (Standard, der erste Termin), name, createdAt oder modifiedAt.

• Name

  order

  Typ

  string

  Beschreibung

  asc (Standard) oder desc.

• Name

  page, itemsPerPage

  Typ

  integer

  Beschreibung

  Siehe Paginierung.

Liefert ein Angebot. Es gelten dieselben Regeln der Sichtbarkeit wie bei der Liste: Ohne Token lässt sich nur ein veröffentlichtes, öffentliches Angebot einer Saison abrufen, die online ist. Alles andere ist ein 404.

Eine Seite einer anderen Website übergibt ihren öffentlichen Schlüssel als key, wie bei der Liste.

Mit Token enthält das Angebot die internen Felder, darunter die Zahl der Anmeldungen und die transitions, die Sie anwenden dürfen.

Legt ein Angebot im Status draft an. Admins legen Angebote in jeder Saison an. Veranstalter:innen legen sie für ihre eigenen Veranstalter-Profile an, in Saisons, deren Phase host_editing_stage aktiv ist.

Legt eine Person das Angebot an, erhält sie vor dem Termin die E-Mails mit dem Link auf die Teilnahmeliste (Handbuch). Die API zeigt nicht, wer diese E-Mails erhält, und legt es nicht fest. Das geschieht im Admin-Panel unter Listen-Empfänger:innen. Ist eine Veranstalter:in Mitglied genau eines Veranstalter-Profils, wird dieses automatisch eingetragen.

Ohne contact übernimmt das Angebot den Kontakt aus dem Profil seiner ersten Veranstalter:in: Name, E-Mail-Adresse und Telefonnummer. Hat das Profil weder E-Mail-Adresse noch Telefonnummer, bleibt das Angebot ohne Kontakt. Dasselbe gilt für ein Angebot ohne Veranstalter:innen. Senden Sie contact, um andere Kontaktpersonen zu nennen, oder [] für keine.

Pflichtattribute

• Name

  name

  Typ

  string

  Beschreibung

  Der Titel des Angebots.

• Name

  edition

  Typ

  string

  Beschreibung

  Die Saison, als UUID oder Alias. Veranstalter:innen müssen eine nennen. Sonst ist die Antwort 403.

Optionale Attribute

• Name

  hosts

  Typ

  string[]

  Beschreibung

  Veranstalter:innen, als UUIDs oder Aliasse. Veranstalter:innen dürfen nur ihre eigenen Veranstalter-Profile nennen.

• Name

  dates

  Typ

  object[]

  Beschreibung

  Termine, jeder mit begin und wahlweise mit end und recurrence.

• Name

  categories

  Typ

  string[]

  Beschreibung

  Kategorien, als UUIDs oder Aliasse.

• Name

  publish

  Typ

  string

  Beschreibung

  public (Standard), oder private_link für ein Angebot, das nur über seinen privaten Link erreichbar ist.

• Name

  contact

  Typ

  object[]

  Beschreibung

  Kontaktpersonen: Objekte mit name, email und phone. Standard sind die Kontaktdaten aus dem Profil der ersten Veranstalter:in.

Außerdem lassen sich teaser, description, fee, minAge, maxAge, minParticipants, maxParticipants, requiresApplication, onlineApplication, applicationDeadline, meetingPoint, meetingAddress, meetingLat, meetingLng, bring, applyText, wheelchairAccessible, accessibility, comment, collectDateOfBirth und disableOnlinePayment senden, wie im Modell beschrieben.

Altersangaben reichen von 0 bis 99. Beiträge und Teilnehmerzahlen dürfen nicht negativ sein. Kurze Texte wie meetingPoint, bring, applyText und comment sind auf 255 Zeichen begrenzt.

Ändert ein Angebot. Senden Sie nur die Attribute, die Sie ändern wollen. Es sind dieselben Attribute wie beim Anlegen eines Angebots. null leert ein Feld. name, edition, hosts, dates, categories, publish und die Ja/Nein-Felder ignorieren null. Ein leerer Body ist ein 422.

Termine werden als Ganzes ersetzt, wenn Sie dates senden. Um einen bestehenden Termin zu behalten, senden Sie seine uuid mit. Termine, die Sie weglassen, werden gelöscht, und Termine ohne uuid kommen hinzu.

Admins ändern jedes Angebot. Veranstalter:innen ändern ihre Angebote, bis diese freigegeben oder veröffentlicht sind, und nur, solange die Saison zur Bearbeitung offen ist (siehe editableForHosts der Saison). Sonst ist die Antwort 403.

Veranstalter:innen ändern nicht, wer ein Angebot durchführt: hosts muss dieselben Veranstalter-Profile nennen wie bisher, in beliebiger Reihenfolge, sonst ist die Antwort 403. Wechselt edition, müssen sie in der neuen Saison Angebote anlegen dürfen, wie beim Anlegen eines Angebots. Sonst ist die Antwort 403.

Löscht ein Angebot mit seinen Anmeldungen. Die Antwort ist 204 No Content.

Die API lehnt das Löschen mit 409 ab, solange sich ein bezahlter Beleg auf eine Anmeldung des Angebots bezieht. Stornieren Sie zuerst den Beleg, oder sagen Sie das Angebot ab. Veranstalter:innen löschen nur Angebote, die weder freigegeben noch veröffentlicht sind und noch keine Anmeldungen haben, und nur, solange die Saison zur Bearbeitung offen ist (siehe editableForHosts der Saison).

Hat das Angebot Varianten, tritt die nächste als Hauptangebot an seine Stelle.

Führt das Angebot durch seinen Workflow. Die transitions des Angebots nennen die Übergänge, die Sie jetzt anwenden dürfen. Alles andere ist ein 409, das die möglichen Übergänge nennt. Das gilt auch für einen Übergang, für den Ihnen die Berechtigung fehlt.

cancel und relaunch benachrichtigen die Familien mit Platz per E-Mail, wenn Sie einen notifyText übergeben, wie im Admin-Panel. Ohne notifyText wird keine E-Mail verschickt.

Pflichtattribute

• Name

  transition

  Typ

  string

  Beschreibung

  Einer von finalize, to_draft, approve, unapprove, publish, unpublish, cancel, relaunch, complete.

Optionale Attribute

• Name

  notifyText

  Typ

  string

  Beschreibung

  Für cancel und relaunch: der Text der E-Mail an die Familien mit Platz. Ohne ihn wird keine E-Mail verschickt.

Kopiert ein Angebot in ein neues Angebot im Status draft, wie Angebot kopieren im Admin-Panel. Die Antwort ist 201 Created mit der Kopie. Das Original bleibt unverändert.

Ohne edition entsteht die Kopie in der Saison des Angebots, mit den Terminen. Mit edition entsteht sie in dieser Saison, und die Termine und der Anmeldeschluss bleiben zurück: Sie gehörten zu den alten Ferien. Die neuen ergänzen Sie mit PATCH /offers/{uuid}. Das gilt auch, wenn Sie die Saison des Angebots selbst nennen.

Sie müssen das Original sehen dürfen, sonst ist die Antwort 404. Außerdem müssen Sie in der Saison der Kopie ein Angebot anlegen dürfen: Admins dürfen das immer, Veranstalter:innen, solange die Phase host_editing_stage dieser Saison aktiv ist. Sonst ist die Antwort 403. Eine edition, die es nicht gibt, ist ein 422.

Was eine Kopie übernimmt

Die Kopie übernimmt die Texte und Einstellungen des Originals: Name, Teaser, Beschreibung, Beitrag, Altersangaben, Teilnehmerzahlen, die Einstellungen zur Anmeldung und die Zusatzfragen, Treffpunkt, Mitzubringendes, Barrierefreiheit, Kategorien, Veranstalter:innen, Kontaktpersonen, die Konten, die die E-Mails zur Teilnahmeliste erhalten, den internen comment, publish und die Einverständniserklärungen. Bilder und Anhänge werden ebenfalls übernommen. Die Kopie verweist auf dieselben Dateien.

Sie übernimmt nicht, was das Original gesammelt hat: Anmeldungen, Kommentare, den Verlauf, Varianten und die Konten, mit denen das Angebot direkt geteilt wurde. Eine Kopie ist immer ein eigenes Angebot, auch wenn das Original eine Variante ist. Sie erhält eine neue uuid und einen eigenen privaten Link. createdAt und modifiedAt nennen den Zeitpunkt der Kopie.

Optionale Attribute

• Name

  edition

  Typ

  string

  Beschreibung

  Die Saison, in die kopiert wird, als UUID oder Alias. Ohne sie entsteht die Kopie in der Saison des Angebots, mit den Terminen.

Die Anfrage braucht einen JSON-Body: Senden Sie {}, um innerhalb der Saison zu kopieren.

Eine ganze Saison kopieren

Dafür gibt es keinen eigenen Endpunkt. Rufen Sie die Angebote mit GET /offers?edition=… ab und kopieren Sie jedes in die neue Saison. Aus Vorjahr kopieren im Admin-Panel lässt die Varianten aus, also Angebote mit variantOf, damit aus ihnen keine eigenen Angebote werden. Verfahren Sie ebenso, wenn Sie dasselbe Ergebnis wollen.

Legt eine Variante eines Angebots an: dieselbe Aktivität für eine andere Gruppe von Teilnehmer:innen, meist an anderen Terminen. Das entspricht Neuen Termin erstellen im Admin-Panel. Die Antwort ist 201 Created mit der neuen Variante.

Eine Variante ist eine Kopie im Status draft, in derselben Saison und mit denselben Terminen, die mit dem Hauptangebot verknüpft ist: Ihr variantOf nennt das Hauptangebot, und das Hauptangebot führt sie in variants. Ihre Termine ändern Sie mit PATCH /offers/{uuid}. Die Variante einer Variante ist mit demselben Hauptangebot verknüpft.

Die Anfrage hat keinen Body. Es gelten dieselben Berechtigungen wie für eine Kopie: 404, wenn Sie das Angebot nicht sehen, und 403, wenn Sie in seiner Saison kein Angebot anlegen dürfen.

Füllt die freien Plätze eines Angebots von seiner Warteliste auf, wie Teilnahmeliste auffüllen im Admin-Panel. Familien rücken in der Reihenfolge der Warteliste nach, unabhängig vom Anmeldeverfahren der Saison. Jede Familie, die nachrückt, erhält eine Zusage, und ihr Beitrag wird fällig wie bei jeder Zusage.

Die Arbeit geschieht im Hintergrund, kurz nach der Anfrage. Die API antwortet mit 202 Accepted und dem Angebot im Stand dieses Augenblicks. Rufen Sie etwas später seine Teilnahmeliste ab, um zu sehen, wer nachgerückt ist.

Um Plätze hinzuzufügen, erhöhen Sie maxParticipants mit PATCH /offers/{uuid} und rufen dann diesen Endpunkt auf. Das entspricht Anzahl Plätze erhöhen im Admin-Panel.

Die API lehnt die Anfrage mit 409 ab, wenn es nichts zu tun gibt: Das Angebot hat keine Termine oder sein erster Termin hat begonnen, niemand steht auf der Warteliste, oder jeder Platz ist vergeben. Die Anfrage braucht die Berechtigung, das Angebot zu ändern. Admins haben sie immer. Veranstalter:innen haben sie nur, bis das Angebot freigegeben oder veröffentlicht ist und solange die Saison zur Bearbeitung offen ist. Sonst ist die Antwort 403.

Optionale Attribute

Die Anfrage braucht einen JSON-Body: Senden Sie {} für die Standardwerte.

• Name

  notify

  Typ

  boolean

  Beschreibung

  Teilt den Familien, die nachrücken, per E-Mail mit, dass sie einen Platz haben. Standard ist false.

• Name

  commit

  Typ

  boolean

  Beschreibung

  Schreibt die Zusagen sofort fest. Standard ist true. Mit false bleiben sie zurückgehalten, bis die Entscheidungen der Saison festgeschrieben werden. notify muss dann ebenfalls false sein, sonst ist die Antwort 422.