English Version

Zurück zur Übersicht

Sylius SEO Suite Pro: Shop API

Das Plugin arbeitet im Dual Mode: Ein Twig-Storefront bekommt seine SEO-Tags über einen Twig Hook im <head>, ein Headless-Frontend holt dieselben Daten über die Shop API. Beide Wege fragen denselben Service (SeoDataProviderInterface) und können deshalb nicht auseinanderlaufen. Zusätzlich lassen sich die SEO-Felder pro Produkt und Kategorie über die Sylius Admin API lesen und schreiben.

Inhalt

• Dual Mode im Überblick
• Endpunkte
• Felder der Antwort
• Beispiel: Produkt
• Beispiel: Kategorie
• Zuordnung: Storefront-Tag zu API-Feld
• Fehler und Statuscodes
• Channel, Sprache und Zugriff
• Admin API: SEO-Felder lesen und schreiben
• Nicht über die API verfügbar

Dual Mode im Überblick

graph TD
    A["Storefront: Twig Hook metatags in sylius_shop.base"] --> B["Twig-Funktion mmd_seo_suite_pro_seo"]
    C["Headless: GET /api/v2/shop/seo/products/code"] --> D["SeoResourceProvider"]
    B --> E["SeoDataProviderInterface"]
    D --> E
    E --> F["SeoData"]
    F --> G["Template metatags.html.twig: Meta-Tags, Canonical, hreflang, JSON-LD im head"]
    F --> H["SeoResource: JSON-Antwort"]

Das Plugin liefert die Daten, aber kein Frontend: Ein Headless-Client baut aus der JSON-Antwort selbst seine <head>-Tags. Die Antwort enthält bewusst fertige Werte (Titel, Canonical, Robots-Direktiven, JSON-LD-Knoten), damit der Client keine SEO-Logik nachbauen muss.

Endpunkte

Die Ressource heißt Seo und ist rein lesend. Die Pfade liegen unter dem Präfix der Sylius Shop API (/api/v2).

Beim Taxon-Endpunkt gibst Du die Filter- und Sortier-Parameter der Listing-Seite einfach an die Query-String weiter, zum Beispiel ?sorting[name]=asc. Das Plugin wendet darauf dieselbe Facet-Regel an wie im Storefront: Ein gefilterter oder sortierter Listing-Aufruf bekommt noindex, follow und ein Canonical ohne Filter-Parameter. Details dazu stehen auf der Seite Konfiguration.

Es gibt keinen Endpunkt für die Startseite, keine Listen-Endpunkte und keine Schreib-Operationen.

Felder der Antwort

Alle Felder gehören zur Serialisierungsgruppe mmd_seo:read.

Aufbau von openGraph:

Aufbau von twitterCard:

Größe und Typ des Bildes (imageWidth, imageHeight, imageType) sind nur bei einem generierten OG-Bild bekannt. Ohne generierte Karte fehlen diese drei Schlüssel komplett, sie stehen nicht als null in der Antwort. Mehr zu den Karten auf der Seite OG-Bilder.

Die Seiten Strukturierte Daten und hreflang beschreiben, welche Knoten bzw. Alternativen wann entstehen.

Beispiel: Produkt

Die Beispiele verwenden Accept: application/ld+json. Das ist das Format, in dem Sylius die API standardmäßig ausliefert, und die Schlüssel @context, @id und @type kommen von API Platform. Die Werte sind frei gewählt, die Struktur entspricht der echten Antwort.

curl -s "https://shop.example/api/v2/shop/seo/products/BLUE-SOFA" \
  -H "Accept: application/ld+json" \
  -H "Accept-Language: de_DE"

{
  "@context": "/api/v2/contexts/Seo",
  "@id": "/api/v2/shop/seo/products/BLUE-SOFA",
  "@type": "Seo",
  "code": "BLUE-SOFA",
  "title": "Blaues Sofa kaufen | Beispiel-Shop",
  "description": "Das blaue Sofa mit Stoffbezug, direkt ab Lager lieferbar.",
  "canonicalUrl": "https://shop.example/de_DE/products/blaues-sofa",
  "robots": "index, follow",
  "openGraph": {
    "title": "Blaues Sofa kaufen | Beispiel-Shop",
    "description": "Das blaue Sofa mit Stoffbezug, direkt ab Lager lieferbar.",
    "url": "https://shop.example/de_DE/products/blaues-sofa",
    "type": "product",
    "image": "https://shop.example/media/image/blue-sofa.jpg",
    "imageAlt": "Blaues Sofa",
    "siteName": "Beispiel-Shop",
    "locale": "de_DE"
  },
  "twitterCard": {
    "card": "summary_large_image",
    "title": "Blaues Sofa kaufen | Beispiel-Shop",
    "description": "Das blaue Sofa mit Stoffbezug, direkt ab Lager lieferbar.",
    "image": "https://shop.example/media/image/blue-sofa.jpg",
    "imageAlt": "Blaues Sofa",
    "site": "@beispielshop",
    "creator": null
  },
  "structuredData": [
    {
      "@context": "https://schema.org",
      "@type": "Product",
      "name": "Blaues Sofa kaufen | Beispiel-Shop",
      "description": "Das blaue Sofa mit Stoffbezug, direkt ab Lager lieferbar.",
      "sku": "BLUE-SOFA",
      "image": ["https://shop.example/media/image/blue-sofa.jpg"],
      "offers": {
        "@type": "Offer",
        "url": "https://shop.example/de_DE/products/blaues-sofa",
        "sku": "BLUE-SOFA",
        "price": "799.00",
        "priceCurrency": "EUR",
        "availability": "https://schema.org/InStock"
      }
    },
    {
      "@context": "https://schema.org",
      "@type": "BreadcrumbList",
      "itemListElement": [
        { "@type": "ListItem", "position": 1, "name": "Sofas", "item": "https://shop.example/de_DE/taxons/sofas" },
        { "@type": "ListItem", "position": 2, "name": "Blaues Sofa", "item": "https://shop.example/de_DE/products/blaues-sofa" }
      ]
    }
  ],
  "alternates": [
    { "hreflang": "de-DE", "href": "https://shop.example/de_DE/products/blaues-sofa" },
    { "hreflang": "en-US", "href": "https://shop.example/en_US/products/blue-sofa" },
    { "hreflang": "x-default", "href": "https://shop.example/en_US/products/blue-sofa" }
  ]
}

Beispiel: Kategorie

Ein sortierter Listing-Aufruf wird als Facet erkannt: robots ist dann noindex, follow, das Canonical bleibt die parameterfreie Listing-URL, und es gibt keine alternates.

curl -s "https://shop.example/api/v2/shop/seo/taxons/SOFAS?sorting%5Bname%5D=asc" \
  -H "Accept: application/ld+json"

{
  "@context": "/api/v2/contexts/Seo",
  "@id": "/api/v2/shop/seo/taxons/SOFAS",
  "@type": "Seo",
  "code": "SOFAS",
  "title": "Sofas | Beispiel-Shop",
  "description": "Alle Sofas im Überblick.",
  "canonicalUrl": "https://shop.example/de_DE/taxons/sofas",
  "robots": "noindex, follow",
  "openGraph": {
    "title": "Sofas | Beispiel-Shop",
    "description": "Alle Sofas im Überblick.",
    "url": "https://shop.example/de_DE/taxons/sofas",
    "type": "website",
    "image": null,
    "imageAlt": null,
    "siteName": "Beispiel-Shop",
    "locale": "de_DE"
  },
  "twitterCard": {
    "card": "summary",
    "title": "Sofas | Beispiel-Shop",
    "description": "Alle Sofas im Überblick.",
    "image": null,
    "imageAlt": null,
    "site": null,
    "creator": null
  },
  "structuredData": [
    {
      "@context": "https://schema.org",
      "@type": "BreadcrumbList",
      "itemListElement": [
        { "@type": "ListItem", "position": 1, "name": "Sofas", "item": "https://shop.example/de_DE/taxons/sofas" }
      ]
    }
  ],
  "alternates": []
}

Die Beispiele zeigen die Struktur der Antwort. Welche Knoten in structuredData stehen und welche Werte title, description und canonicalUrl bekommen, hängt von Deinen SEO-Templates, Channel-Einstellungen und Produktdaten ab.

Zuordnung: Storefront-Tag zu API-Feld

Das Template metatags.html.twig rendert dieselben SeoData, aus denen die API ihre Felder füllt. Der <title> ist die Ausnahme: Er wird im Storefront nicht über das Template ausgegeben, sondern per Response-Listener im fertigen HTML ersetzt. Die API liefert den Wert trotzdem in title.

Ein Headless-Client schreibt die JSON-LD-Knoten als JSON.stringify(node) in ein <script type="application/ld+json">. Das Storefront maskiert dabei Zeichenfolgen, die das Script-Element vorzeitig beenden würden (Twig-Funktion mmd_seo_suite_pro_json_ld). Wenn Du die Knoten selbst serialisierst, übernimmst Du dieses Escaping.

Fehler und Statuscodes

Alle Fälle antworten mit derselben Meldung Not found.. Das Format des Fehlerkörpers bestimmt API Platform anhand des angefragten Formats. Ein Client, der 404 bekommt, rendert einfach keine zusätzlichen SEO-Tags.

Das Plugin selbst löst keine weiteren Statuscodes aus, auch keine 401 oder 403.

Channel, Sprache und Zugriff

Das Plugin ermittelt Channel und Sprache nicht selbst. Es fragt den ChannelContextInterface und den LocaleContextInterface von Sylius und verwendet das Ergebnis. Welche Merkmale der Anfrage (Hostname, Header) dort den Ausschlag geben, hängt von der Channel- und Locale-Konfiguration Deiner Sylius-Installation ab. Die API-Pfade selbst enthalten weder Channel noch Locale.

Ein Produkt wird nur im aktuellen Channel ausgeliefert, in dem es verkauft wird. Prüfe bei einem Headless-Setup, dass die Anfrage an die Shop API den richtigen Channel trifft, sonst bekommst Du für gültige Produkte ein 404.

Die Endpunkte liegen unter /api/v2/shop und sind im Standard-Setup von Sylius öffentlich zugänglich (PUBLIC_ACCESS). Das Plugin ergänzt keine eigene Authentifizierung. Wenn Du die Shop API absicherst, gilt das auch für diese Endpunkte.

Die hreflang-URLs in alternates verwenden die Hostnamen der Channels und das Schema der API-Anfrage. Ein Headless-Frontend auf einem anderen Host muss diese URLs selbst auf seine Adressen abbilden.

Admin API: SEO-Felder lesen und schreiben

Die Felder pro Produkt und Kategorie (metaTitle, canonicalPathOverride, robotsIndex, robotsFollow und bei Kategorien metaDescription) hängen an den Übersetzungs-Objekten der Sylius Admin API. So kann ein Katalog-Client (Automatisierung, MCP-Server) sie ohne das Admin-Formular lesen und setzen. Das Plugin bringt dafür keine eigenen Admin-API-Endpunkte mit.

Technisch funktioniert das über Serialisierungsgruppen (sylius:admin:product:*, sylius:admin:taxon:*, sylius:admin:taxon_translation:show), die direkt an den Eigenschaften der Traits SeoAwareTranslationTrait und MetaDescriptionAwareTranslationTrait hängen. Es gibt keine Konfiguration im Plugin, die Sylius' Admin API erweitert. Die Felder erscheinen deshalb nur, wenn Deine Übersetzungs-Klassen die Traits verwenden (Opt-in, siehe Erweiterbarkeit).

{
  "translations": {
    "en_US": {
      "@id": "/api/v2/admin/products/P1/translations/en_US",
      "metaTitle": "Blue sofa | Shop",
      "canonicalPathOverride": "/sofas/blue",
      "robotsIndex": false
    }
  }
}

• Eine bestehende Übersetzung braucht ihre @id (aus dem GET), genau wie Sylius' eigene übersetzte Felder. Ohne sie antwortet Sylius mit der Meldung, dass für den Locale-Code bereits eine Übersetzung existiert.
• Felder, die Du weglässt, behalten ihren Wert. Ein PUT ohne robotsIndex oder robotsFollow setzt sie nicht zurück.
• canonicalPathOverride wird wie im Admin validiert: ein Pfad mit genau einem führenden Slash. Eine vollständige URL oder //host/... ergibt ein 422. Höchstens 255 Zeichen.
• metaTitle ist auf 255 Zeichen begrenzt, metaDescription (Kategorie) auf 512.
• Die metaDescription der Kategorie gibt es nur, wenn Deine TaxonTranslation den MetaDescriptionAwareTranslationTrait verwendet. Die Meta Description des Produkts ist Sylius' eigenes Feld.
• Der Zugriff folgt der Admin-API-Absicherung von Sylius (Token, Rolle ROLE_API_ACCESS).

Nach dem Update des Plugins oder dem Einbau der Traits einmal bin/console cache:clear ausführen: Der Serializer hält seine Metadaten im Cache.

Nicht über die API verfügbar

Fragen und typische Fehlerbilder findest Du auf der Seite Fehlerbehebung.