Store API

Diese Seite richtet sich an Entwickler:innen. Sie beschreibt die Store-API-Endpunkte des Plugins PremsBlog für Headless-Frontends und externe Integrationen.

Allgemeines

• Basis-URL: https://<shop>/store-api

• Authentifizierung: via sw-access-key-Header des Verkaufskanals

• Datenformat: JSON mit Content-Type: application/json

• Routen-Scope: store-api

• Sprachbehandlung: Antworten respektieren den per sw-language-id gesetzten Sprachkontext. Übersetzbare Felder stehen zusätzlich im Block translated.

Endpunkte im Überblick

Methode	Pfad	Routen-Name
GET POST	/store-api/prems-blog/articles	store-api.prems-blog.article.list
GET POST	/store-api/prems-blog/article/{articleId}	store-api.prems-blog.article.detail
GET POST	/store-api/prems-blog/authors	store-api.prems-blog.author.list
GET POST	/store-api/prems-blog/author/{authorId}	store-api.prems-blog.author.detail
GET POST	/store-api/prems-blog/category/{categoryId}	store-api.prems-blog.category.detail
GET POST	/store-api/prems-blog/tag/{tagId}	store-api.prems-blog.tag.detail
POST	/store-api/prems-blog/article/{articleId}/review	store-api.prems-blog.review.save

Beiträge auflisten

GET /store-api/prems-blog/articles

Liefert eine paginierte Liste aller aktiven Beiträge im aktuellen Sichtbarkeitsfenster.

Parameter

Name	Typ	In	Beschreibung
page	int	Query oder Body	Seitenzahl. Standard ist 1.
limit	int	Query oder Body	Treffer pro Seite. Standard ist 12. Das IAP-Feature numberOfBlogPosts kann den Wert nach oben begrenzen.
categoryId	string	Query oder Body	Filtert nach Blog-Kategorie.
tagId	string	Query oder Body	Filtert nach Tag.
authorId	string	Query oder Body	Filtert nach Autor:in.
sort	string	Query oder Body	displayDate absteigend oder title aufsteigend.

Filter

Die Route liefert nur Beiträge mit status = 'active'.

Zusätzlich muss das Sichtbarkeitsfenster erfüllt sein:

• activeFrom IS NULL oder activeFrom <= NOW()

• activeTo IS NULL oder activeTo >= NOW()

Assoziationen

author, categories, tags, previewMedia

Response

{
  "apiAlias": "blog_article_list_route_response",
  "elements": [
    {
      "id": "…",
      "title": "…",
      "translated": {
        "title": "…",
        "shortDescription": "…"
      },
      "displayDate": "2026-05-12T08:00:00+00:00",
      "author": { "…": "…" },
      "categories": [{ "…": "…" }],
      "tags": [{ "…": "…" }],
      "previewMedia": { "url": "…" }
    }
  ],
  "total": 42,
  "aggregations": []
}

Beispiel

curl -X GET \
  "https://<shop>/store-api/prems-blog/articles?page=1&limit=10&sort=displayDate" \
  -H "sw-access-key: <SALES_CHANNEL_ACCESS_KEY>"

Beitragsdetail

GET /store-api/prems-blog/article/{articleId}

Liefert einen einzelnen Beitrag mit allen relevanten Assoziationen.

Parameter

Name	Typ	In	Beschreibung
articleId	string	Pfad	UUID des Blog-Beitrags. Pflicht.

Assoziationen

author, author.media, categories, tags, media.media, reviews, products, products.cover, products.cover.media, products.options.group, products.seoUrls, previewMedia

Sichtbarkeit

Die Route liefert den Beitrag nur aus, wenn status = 'active' gesetzt ist und das Zeitfenster über activeFrom und activeTo erfüllt ist.

Andernfalls antwortet die Route mit 500 und RuntimeException: Article not found or not active.

Response

{
  "apiAlias": "blog_article_detail_route_response",
  "id": "…",
  "title": "…",
  "translated": { "…": "…" },
  "author": { "…": "…" },
  "categories": [/* … */],
  "tags": [/* … */],
  "media": [/* gallery items (pivot) */],
  "reviews": [/* alle Reviews inkl. inaktiver */],
  "products": [/* … */],
  "previewMedia": { "…": "…" }
}

Das Array reviews enthält auch noch nicht freigeschaltete Bewertungen mit active = false. In eigenen Storefronts solltest du clientseitig auf active = true filtern.

Autor:innen auflisten

GET /store-api/prems-blog/authors

Liefert eine paginierte Liste aller Blog-Autor:innen.

Parameter

Name	Typ	In	Beschreibung
page	int	Query oder Body	Seitenzahl. Standard ist 1.
limit	int	Query oder Body	Treffer pro Seite. Standard ist 12. Das IAP-Feature numberOfAuthors kann den Wert nach oben begrenzen.
letter	string	Query oder Body	A–Z-Filter auf lastName.

Sortierung

lastName aufsteigend, danach firstName aufsteigend

Assoziationen

media, articles

Response

{
  "apiAlias": "blog_author_list_route_response",
  "elements": [
    {
      "id": "…",
      "firstName": "…",
      "lastName": "…",
      "media": { "…": "…" },
      "articles": [/* … */]
    }
  ],
  "total": 12
}

Autorendetail

GET /store-api/prems-blog/author/{authorId}

Liefert eine Autorin oder einen Autor sowie deren oder dessen aktive Beiträge.

Parameter

Name	Typ	In	Beschreibung
authorId	string	Pfad	UUID des Autors. Pflicht.
page	int	Query oder Body	Seite der Artikelliste. Standard ist 1.
limit	int	Query oder Body	Treffer pro Seite. Standard ist 12.

Verhalten

• Der Datensatz wird mit media geladen.

• Beiträge werden auf status = 'active', Sichtbarkeitsfenster und authorId gefiltert.

• Sortiert wird nach displayDate absteigend.

Response

{
  "apiAlias": "blog_author_detail",
  "author": {
    "id": "…",
    "firstName": "…",
    "lastName": "…",
    "media": { "…": "…" }
  },
  "articles": {
    "elements": [/* Artikelkarten mit author, categories, tags, previewMedia */],
    "total": 8
  }
}

Existiert authorId nicht, antwortet die Route mit 500 und RuntimeException: Author not found.

Kategorie mit Beiträgen

GET /store-api/prems-blog/category/{categoryId}

Liefert eine Blog-Kategorie und alle aktiven Beiträge dieser Kategorie.

Parameter

Name	Typ	In	Beschreibung
categoryId	string	Pfad	UUID der Blog-Kategorie. Pflicht.
page	int	Query oder Body	Seite der Artikelliste. Standard ist 1.
limit	int	Query oder Body	Treffer pro Seite. Standard ist 12.

Response

{
  "apiAlias": "blog_category_article",
  "category": {
    "id": "…",
    "translated": { "name": "…" }
  },
  "articles": {
    "elements": [/* … */],
    "total": 17
  }
}

Existiert categoryId nicht, antwortet die Route mit 500 und RuntimeException: Category not found.

Tag mit Beiträgen

GET /store-api/prems-blog/tag/{tagId}

Liefert ein Blog-Tag und alle aktiven Beiträge mit diesem Tag.

Parameter

Name	Typ	In	Beschreibung
tagId	string	Pfad	UUID des Blog-Tags. Pflicht.
page	int	Query oder Body	Seite der Artikelliste. Standard ist 1.
limit	int	Query oder Body	Treffer pro Seite. Standard ist 12.

Response

{
  "apiAlias": "blog_tag_article",
  "tag": {
    "id": "…",
    "translated": { "name": "…" }
  },
  "articles": {
    "elements": [/* … */],
    "total": 5
  }
}

Existiert tagId nicht, antwortet die Route mit 500 und RuntimeException: Tag not found.

Bewertung speichern

POST /store-api/prems-blog/article/{articleId}/review

Speichert eine Beitragsbewertung. Neue Reviews werden immer mit active = false angelegt und erscheinen erst nach manueller Freigabe in der Storefront.

Voraussetzungen

Voraussetzung	Verhalten bei Verstoß
Aktiver IAP premsBlogPremium mit Feature RATING_FEATURE_ENABLED	404 Not Found mit „Blog reviews are not available on the current plan."
Eingeloggter Kunde ohne Gastmodus	403 Forbidden mit Fehlercode CHECKOUT__CUSTOMER_NOT_LOGGED_IN
articleId existiert	404 Not Found mit „Blog article with id … not found."

Parameter

Name	Typ	In	Pflicht	Beschreibung
articleId	string	Pfad	ja	UUID des Beitrags.
title	string	Body	ja	Titel der Bewertung mit 5 bis 255 Zeichen.
content	string	Body	ja	Inhalt der Bewertung mit mindestens 40 Zeichen.
stars	int	Body	ja	Sternebewertung zwischen 1 und 5.
name	string	Body	nein	Anzeigename. Bei leerem Wert wird firstName + lastName des eingeloggten Kunden verwendet.
email	string	Body	nein	E-Mail-Adresse. Bei leerem Wert wird die E-Mail des eingeloggten Kunden verwendet.

Response

204 No Content

Fehlercodes

Status	Ursache
204	Bewertung wurde gespeichert und wartet auf Freigabe.
400	Validierung fehlgeschlagen.
403	Kunde ist nicht eingeloggt oder befindet sich im Gastmodus.
404	Premium-IAP fehlt oder articleId ist unbekannt.

Beispiel

curl -X POST \
  "https://<shop>/store-api/prems-blog/article/<ARTICLE_ID>/review" \
  -H "sw-access-key: <SALES_CHANNEL_ACCESS_KEY>" \
  -H "sw-context-token: <LOGGED_IN_CONTEXT_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Sehr informativ",
    "content": "Der Beitrag erklärt das Thema verständlich und mit guten Beispielen. Klare Empfehlung.",
    "stars": 5
  }'

Plan-Limits über IAPs

Einige Endpunkte respektieren die im aktiven Plan gesetzten Feature-Limits.

Feature	Wirkung
numberOfBlogPosts	Begrenzt limit bei GET /articles.
numberOfAuthors	Begrenzt limit bei GET /authors.
RATING_FEATURE_ENABLED	Aktiviert POST /article/{articleId}/review.

Ist ein Feature unbegrenzt, hat es keinen Einfluss auf den übergebenen limit-Wert.