Zur Startseite
Kontakt

Blog

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 sollten Sie 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.

Cookie-Einstellungen