API-Dokumentation | petoffice Handbuch

Dieser Artikel beschreibt die Schnittstelle (API) der Homepage-Integration im Detail. Er richtet sich an Entwickler und Agenturen, die petoffice-Anzeigen in eine Homepage einbinden, die nicht auf WordPress basiert, oder die volle Kontrolle über die Darstellung übernehmen möchten. Wenn du eine WordPress-Seite betreibst, brauchst du diese Seite in der Regel nicht. Nutze stattdessen das fertige WordPress-Plugin.

Adresse und Vereinszuordnung

Alle Endpunkte sind vereinsspezifisch. Der Verein wird nicht über einen Parameter übergeben, sondern automatisch aus dem Hostnamen der angefragten Adresse abgeleitet. Maßgeblich ist deine vereinsspezifische Homepage-Domain, die du in petoffice unter Einstellungen → Homepage-Integration im Abschnitt „Domain” findest.

Die Endpunkte liegen unterhalb dieser Domain im Pfad /new-api/homepage/. Alle folgenden Beispiele gehen von einem Verein mit der Homepage-Domain https://beispielverein.petoffice.app aus, der eigentlichen Vereinshomepage unter https://www.beispielverein.de und einer Beispiel-Anzeige mit der ID 6a1f10833723359afd2fb293.

Fertiges HTML und Rohdaten

Die Schnittstelle zwingt dich nicht in einen Modus. Beim Profil einer Anzeige liefert eine einzige Antwort gleichzeitig beides: die fertig aufbereiteten HTML-Bausteine und die zugehörigen Rohdaten unter data. Du entscheidest pro Feld, was du verwendest, und kannst beide Darstellungsformen auch mischen.

Die HTML-Bausteine sind einsatzfertig: Titel, Bildergalerie, Videogalerie und so weiter. Sie enthalten die nötige Grundstruktur, schlanke Layout-Stile und bei den Galerien das vanilla-JavaScript für die Lightbox. Über die mitgelieferten CSS-Klassen (Präfix po-) überschreibst du die Darstellung in deinem eigenen Stylesheet. Diese Bausteine sind auch die Grundlage des WordPress-Plugins.

Die Rohdaten enthalten die reinen Werte einer Anzeige ohne Markup. Mit ihnen baust du die Oberfläche vollständig selbst, wenn du das Layout exakt an dein bestehendes Design anpassen willst.

Bei der Tierliste gibt es für diese beiden Darstellungsformen jeweils einen eigenen Endpunkt (siehe unten): einen, der die fertige Listen-HTML liefert, und einen, der nur die Daten zurückgibt.

Endpunkte

Alle Endpunkte sind über GET erreichbar. Jeder Abschnitt folgt demselben Aufbau: Beschreibung, URL-Format mit Platzhaltern, ein vollständig ausgefülltes Beispiel, die Parameter mit gültigen Beispielwerten und die Antwort. {domain} steht dabei für die Homepage-Domain.

Tierliste als HTML

Liefert die fertig gerenderte Tierliste als HTML-Baustein, verpackt in ein JSON-Objekt.

URL-Format

GET {domain}/new-api/homepage/pet-list/{tierart}/{sortBy}/{sortOrder}

Beispiel

GET https://beispielverein.petoffice.app/new-api/homepage/pet-list/Katze/title/asc?detailsPageUrl=https://www.beispielverein.de/tierprofil/&listPageUrl=https://www.beispielverein.de/tiere/&selectedTag=Notfellchen&showTags=true

Pfad-Parameter

Parameter	Mögliche Werte	Beispielwert	Beschreibung
`tierart`	Anzeigename einer aktiven Tierart	`Katze`	Muss exakt dem Anzeigenamen einer aktiven Tierart des Vereins entsprechen (sonst Fehler `400`).
`sortBy`	`title`, `species`, `createdAt`	`title`	Sortierfeld: `title` (Name), `species` (Tierart) oder `createdAt` (Anlagedatum). Andere Werte werden ignoriert, dann gilt die Standardreihenfolge.
`sortOrder`	`asc`, `desc`	`asc`	Sortierrichtung: `asc` (aufsteigend) oder `desc` (absteigend).

Query-Parameter

Parameter	Pflicht	Beispielwert	Beschreibung
`detailsPageUrl`	empfohlen	`https://www.beispielverein.de/tierprofil/`	Adresse der Profilseite; die Anzeigen-ID wird direkt angehängt.
`listPageUrl`	empfohlen	`https://www.beispielverein.de/tiere/`	Adresse der aktuellen Listenseite, für die Tag-Links.
`selectedTag`	optional	`Notfellchen`	Schränkt die Liste auf einen Tag ein. Der Wert muss einem vorhandenen Tag entsprechen (siehe `tags` in der Antwort der Rohdaten-Liste).
`showTags`	optional	`true`	Nur der Wert `true` blendet die anklickbaren Tag-Filter ein. Jeder andere Wert (oder Weglassen) blendet sie aus.

Antwort

{ "list": "<div class="po-pet-list">…</div>" }

Tierliste als HTML (unverpackt)

Liefert dasselbe HTML wie der vorige Endpunkt, jedoch direkt als Zeichenkette statt in ein { "list": … }-Objekt verpackt. Trotz des Suffix /raw handelt es sich um fertiges HTML, nicht um Rohdaten.

URL-Format

GET {domain}/new-api/homepage/pet-list/{tierart}/{sortBy}/{sortOrder}/raw

Beispiel

GET https://beispielverein.petoffice.app/new-api/homepage/pet-list/Katze/title/asc/raw?detailsPageUrl=https://www.beispielverein.de/tierprofil/&listPageUrl=https://www.beispielverein.de/tiere/&showTags=true

Pfad- und Query-Parameter

Identisch zum Endpunkt Tierliste als HTML.

Antwort

<div class="po-pet-list">…</div>

Tierliste als Rohdaten

Liefert ausschließlich die Daten der Liste ohne Markup, samt der Liste aller verfügbaren Tags.

URL-Format

GET {domain}/new-api/homepage/pet-list

Beispiel

GET https://beispielverein.petoffice.app/new-api/homepage/pet-list?species=Katze&sortBy=title&sortOrder=asc&tag=Notfellchen

Query-Parameter

Parameter	Pflicht	Mögliche Werte	Beispielwert	Beschreibung
`species`	optional	Anzeigename einer aktiven Tierart	`Katze`	Muss exakt dem Anzeigenamen einer aktiven Tierart des Vereins entsprechen (sonst Fehler `400`).
`sortBy`	optional	`title`, `species`, `createdAt`	`title`	Sortierfeld: `title` (Name), `species` (Tierart) oder `createdAt` (Anlagedatum). Andere Werte werden ignoriert.
`sortOrder`	optional	`asc`, `desc`	`asc`	Sortierrichtung: `asc` (aufsteigend) oder `desc` (absteigend).
`tag`	optional	vorhandener Tag	`Notfellchen`	Schränkt die Liste auf einen Tag ein (siehe `tags` in der Antwort).

Antwort

{ "pets": [], "tags": [] }

Jeder Eintrag in pets folgt dem Datenschema der Rohdaten.

Tierprofil

Liefert das vollständige Tierprofil einer Anzeige: alle gerenderten HTML-Bausteine und zusätzlich die Rohdaten unter data.

URL-Format

GET {domain}/new-api/homepage/pet-details/{id}

Beispiel

GET https://beispielverein.petoffice.app/new-api/homepage/pet-details/6a1f10833723359afd2fb293

Pfad-Parameter

Parameter	Beispielwert	Beschreibung
`id`	`6a1f10833723359afd2fb293`	ID der Anzeige.

Antwort

{
  "applyButton": "<div class="po-pet-profile__application-button">…</div>",
  "description": "<div class="po-pet-profile__description">…</div>",
  "extra": "<div class="po-pet-extra">…</div>",
  "gallery": "<div class="po-image-gallery">…</div>",
  "image": "<div class="po-pet-profile__image">…</div>",
  "title": "<div class="po-pet-profile__title">…</div>",
  "videos": "<div class="po-video-gallery">…</div>",
  "data": {}
}

Der Baustein extra gibt die Zusatzfelder als Tabelle aus: leere Werte werden weggelassen, bekannte Feldnamen als Beschriftung verwendet, Datumswerte formatiert und Ja/Nein-Felder als Ja oder Nein dargestellt. Das Feld data.extra bleibt dagegen eine unformatierte Zuordnung von Feld-Kürzel zu Rohwert. Das Feld data folgt dem Datenschema der Rohdaten.

Datenschema der Rohdaten

Das Feld data (sowie jeder Eintrag in pets) verwendet folgendes Schema:

Feld	Typ	Bedeutung
`id`	`string`	ID der Anzeige.
`species`	`string \\| null`	Tierart.
`title`	`string \\| null`	Öffentlicher Titel.
`reserved`	`boolean \\| null`	Ob das Tier als reserviert markiert ist.
`inGermany`	`boolean \\| null`	Ob sich das Tier in Deutschland befindet.
`imageId`	`string \\| null`	ID des Hauptbilds.
`tags`	`string[]`	Öffentliche Tags für die Filterung.
`imageIds`	`string[]`	Alle öffentlichen Bild-IDs der Galerie.
`youtubeIds`	`string[]`	IDs der YouTube-Videos.
`prospectUrl`	`string \\| null`	Pfad zum Bewerbungsformular.
`publicHeadline`	`string \\| null`	Optionale Überschrift.
`publicDescription`	`string \\| null`	Öffentlicher Beschreibungstext.
`extra`	`Record<string, value>`	Rohwerte der Zusatzfelder, je Feld-Kürzel.

CSS-Klassen

Alle ausgegebenen Klassen tragen das Präfix po-. Über sie passt du das Aussehen an, ohne dass dich künftige Updates aus dem Tritt bringen.

Tierliste

Klasse	Zweck
`po-pet-list`	Umfassung der Tierliste.
`po-pet`	Ein einzelnes Tier in der Liste.
`po-pet__link`	Link zur Profilseite.
`po-pet__reserved`	Reserviert-Hinweis.
`po-pet__image`	Vorschaubild.
`po-pet__title`	Titel des Tieres.
`po-pet-filters`	Umfassung der Tag-Filter.
`po-pet-filters__tags`	Container der Filter-Links.
`po-pet-filters__tag`	Ein einzelner Tag-Filter.

Profil-Bausteine

Klasse	Zweck
`po-pet-profile__title`	Titel-Baustein.
`po-pet-profile__image`	Hauptbild-Baustein.
`po-pet-profile__description`	Beschreibungs-Baustein.
`po-pet-profile__application-button`	Baustein für den Bewerbungs-Button.
`po-pet-profile__application-link`	Der Bewerbungs-Link selbst.

Zusatzfelder

Klasse	Zweck
`po-pet-extra`	Umfassung der Zusatzfelder.
`po-pet-extra__table`	Tabelle der Felder.
`po-pet-extra__row`	Eine Feldzeile.
`po-pet-extra__key`	Feldbeschriftung.
`po-pet-extra__value`	Formatierter Wert.

Galerien

Klasse	Zweck
`po-image-gallery`	Umfassung der Bildergalerie.
`po-image-gallery__button`	Klickfläche eines Bildes.
`po-image-gallery__thumbnail`	Vorschaubild.
`po-video-gallery`	Umfassung der Videogalerie.
`po-video-gallery__button`	Klickfläche eines Videos.
`po-video-gallery__thumbnail`	Video-Vorschaubild.
`po-video-gallery__play`	Abspiel-Symbol.

Bild- und Videogalerie teilen sich eine gemeinsame Lightbox. Deren Gestaltungspunkte tragen das Präfix po-homepage-lightbox, zum Beispiel po-homepage-lightbox, po-homepage-lightbox--open, po-homepage-lightbox__media, po-homepage-lightbox__close und po-homepage-lightbox__nav.

Häufige Fragen

Brauche ich eine Authentifizierung, um die Schnittstelle aufzurufen?
Nein. Die über die Schnittstelle ausgelieferten Daten sind genau die Inhalte, die ihr ohnehin bewusst auf eurer Homepage veröffentlicht (Anzeigen mit gesetztem Häkchen „Homepage”). Da diese Inhalte öffentlich zugänglich sein sollen, ist keine Authentifizierung erforderlich.

Hinweise zur Einbindung

Die Galerie-Bausteine enthalten neben dem Markup auch das JavaScript und die data-po-*-Attribute, die für die Lightbox nötig sind. Wenn du die fertigen HTML-Bausteine direkt einsetzt, dürfen Skripte, data-po-*-Attribute und das hidden-Attribut nicht entfernt werden. Entfernt dein System diese Bestandteile, binde stattdessen eigene, vertrauenswürdige Skripte und Stile ein und nutze die po--Klassen als stabile Ankerpunkte. Für volle Kontrolle über die Darstellung verwende die Rohdaten und baue die Oberfläche selbst.