Taxonomien

Die Taxonomie ordnet Produkte, Artikel und Medien nach Dimensionen: Produktkategorie, Anwendungsbereich, Leistungsklasse und so weiter. Eine Taxonomie ist eine Dimension, ein Term (taxon) ein Eintrag darin.

Die API liefert nur Dimensionen, die im PIM als „Im Frontend nutzbar“ markiert sind. Dimensionen mit Personen, Orten oder Wetter sind aus Datenschutzgründen ausgeschlossen.

Methode	Pfad	Anmeldung
GET	/taxonomies	keine
GET	/taxonomies/{slug}	keine
GET	/content/taxonomies	Token mit content:catalog:read
GET	/content/taxonomies/{slug}	Token mit content:catalog:read

Felder

Taxonomie

Feld	Typ	Bedeutung
id	Integer	ID
slug	String	Kennung der Dimension, z. B. produktkategorie. Wird im Produktfilter als dimension verwendet
labels	String | null	Bezeichnung in der Server-Sprache (derzeit Text, kein Sprach-Objekt)
hierarchical	Boolean	true, wenn die Terme einen Baum bilden
taxons	Term[]	Nur in der Detailansicht

Term

Feld	Typ	Bedeutung
id	Integer	ID
taxonomy_id	Integer	Zu welcher Taxonomie er gehört
taxonomy_slug	String	Nur wo die Taxonomie mitgeladen ist (bei Produkten). In der Taxonomie-Detailansicht fehlt das Feld
parent_id	Integer | null	Übergeordneter Term
slug	String	Kennung des Terms
names	String | null	Bezeichnung in der Server-Sprache (derzeit Text, kein Sprach-Objekt)
position	Integer	Sortierung unter Geschwistern

---

Taxonomien auflisten

GET /taxonomies

Alle frontend-nutzbaren Taxonomien, sortiert nach slug, ohne Terme. Nicht paginiert, keine Parameter.

Beispiel

curl

curl -sS https://admin.matev.eu/api/v1/taxonomies -H 'Accept: application/json'

JavaScript

const { data: taxonomies } = await (await fetch('https://admin.matev.eu/api/v1/taxonomies', {
  headers: { Accept: 'application/json' },
})).json()

PHP

use Illuminate\Support\Facades\Http;

$taxonomies = Http::acceptJson()->get('https://admin.matev.eu/api/v1/taxonomies')->throw()->json('data');

Antwort 200

{
  "data": [
    { "id": 5, "slug": "anwendungsbereich", "labels": "Anwendungsbereich", "hierarchical": true },
    { "id": 6, "slug": "leistungsklasse", "labels": "Leistungsklasse", "hierarchical": false },
    { "id": 3, "slug": "produktkategorie", "labels": "Produktkategorie", "hierarchical": true }
  ]
}

Fehler

Status	code	Wann
405	method_not_allowed	andere Methode als GET

---

Eine Taxonomie mit Termen abrufen

GET /taxonomies/{slug}

Liefert die Taxonomie und alle ihre Terme als flache Liste, sortiert nach parent_id und position. Den Baum baut der Client selbst über parent_id zusammen.

Der Wurzel-Term der Dimension selbst (der Knoten, der im PIM die Taxonomie darstellt) ist nicht in der Liste. Terme der ersten Ebene haben deshalb als parent_id die ID dieses nicht gelieferten Knotens. Behandeln Sie jeden Term, dessen parent_id nicht in der Liste vorkommt, als obersten Eintrag.

Pfad-Parameter

Parameter	Typ	Bedeutung
slug	String	Slug der Taxonomie, z. B. produktkategorie

Beispiel

curl

curl -sS https://admin.matev.eu/api/v1/taxonomies/produktkategorie -H 'Accept: application/json'

JavaScript

const { data: tax } = await (await fetch('https://admin.matev.eu/api/v1/taxonomies/produktkategorie', {
  headers: { Accept: 'application/json' },
})).json()

// Build the tree from the flat list
const ids = new Set(tax.taxons.map((t) => t.id))
const byParent = Object.groupBy(tax.taxons, (t) => (ids.has(t.parent_id) ? t.parent_id : 'root'))
const roots = byParent.root ?? []

PHP

use Illuminate\Support\Facades\Http;

$taxonomy = Http::acceptJson()
    ->get('https://admin.matev.eu/api/v1/taxonomies/produktkategorie')
    ->throw()
    ->json('data');

$ids = array_column($taxonomy['taxons'], 'id');
$roots = array_filter($taxonomy['taxons'], fn (array $t): bool => ! in_array($t['parent_id'], $ids, true));

Antwort 200

{
  "data": {
    "id": 3,
    "slug": "produktkategorie",
    "labels": "Produktkategorie",
    "hierarchical": true,
    "taxons": [
      { "id": 80, "taxonomy_id": 3, "parent_id": 79, "slug": "winterdienst", "names": "Winterdienst", "position": 1 },
      { "id": 81, "taxonomy_id": 3, "parent_id": 79, "slug": "gruenpflege", "names": "Grünpflege", "position": 2 },
      { "id": 88, "taxonomy_id": 3, "parent_id": 80, "slug": "schneepfluege", "names": "Schneepflüge", "position": 2 }
    ]
  }
}

Fehler

Status	code	Wann
404	not_found	Keine Taxonomie mit diesem Slug, oder sie ist nicht frontend-nutzbar
405	method_not_allowed	andere Methode als GET

---

Mit Token: /content/taxonomies

GET /content/taxonomies und GET /content/taxonomies/{slug} sind identisch mit den öffentlichen Endpunkten, brauchen aber ein Token mit content:catalog:read. Kirby nutzt sie für Vorschläge im Feld pimtaxon.

curl

curl -sS https://admin.matev.eu/api/v1/content/taxonomies \
  -H 'Accept: application/json' -H "Authorization: Bearer $MATEV_TOKEN"

curl -sS https://admin.matev.eu/api/v1/content/taxonomies/produktkategorie \
  -H 'Accept: application/json' -H "Authorization: Bearer $MATEV_TOKEN"

JavaScript

const headers = { Accept: 'application/json', Authorization: `Bearer ${process.env.CONTENT_API_TOKEN}` }
const all = await (await fetch('https://admin.matev.eu/api/v1/content/taxonomies', { headers })).json()
const one = await (await fetch('https://admin.matev.eu/api/v1/content/taxonomies/produktkategorie', { headers })).json()

PHP

use Illuminate\Support\Facades\Http;

$api = Http::baseUrl('https://admin.matev.eu/api/v1')->acceptJson()->withToken(config('services.matev.token'));

$all = $api->get('/content/taxonomies')->throw()->json('data');
$one = $api->get('/content/taxonomies/produktkategorie')->throw()->json('data');

Zusätzliche Fehler

Status	code	Wann
401	unauthenticated	Token fehlt oder ist ungültig
403	forbidden	Token hat nicht content:catalog:read