Such-API in einen Headless-Shop einbauen: SDK, Index, erste Ergebnisse

Das Team hat seinen Shop entkoppelt. Das Storefront läuft als React-Anwendung, das PHP-Backend liefert Produktdaten über Endpunkte, und ein Headless-CMS pflegt die Inhalte. Nur die Suche hängt noch am alten Stand. Ein Kunde tippt eine Artikelnummer ein und landet auf einer leeren Trefferliste. Ein Produktmanager möchte einen Aktionsartikel nach oben ziehen und braucht dafür jedes Mal einen Entwickler.

Auf dem Whiteboard steht die Frage, die in solchen Projekten fast immer auftaucht. Suche selbst bauen oder eine fertige Such-API anbinden?

Diese Antwort hängt weniger am Frontend als an der Schicht darunter. Wer die Suche als eigene Infrastruktur behandelt, bindet sie über ein fertiges SDK an und spart sich den monatelangen Eigenbau. Das Frontend bleibt dabei austauschbar. Die Search API und ihr SDK ändern sich nicht, egal ob Sie React, Vue, Angular oder ein Next.js-Storefront einsetzen.

Was eine Such-API im Headless-Kontext leistet

Im Headless-Shop sind Frontend und Backend getrennt. Das Storefront rendert, das Backend liefert Daten, und beide sprechen über definierte Schnittstellen miteinander. Eine Such-API fügt sich genau in dieses Muster ein. Sie ist ein eigener Dienst, den Ihr Backend oder Ihr Storefront über HTTP anspricht, und der strukturierte Treffer zurückgibt. Die Grundlagen dieses Schnittstellen-Stils fasst das REST-Glossar der MDN Web Docs zusammen.

Der Vorteil dieser Bauweise zeigt sich beim ersten Framework-Wechsel. Ein Suchfeld, das direkt in einem Theme verdrahtet ist, wandert bei einem Relaunch mit in die Tonne. Eine API-first angebundene Suche bleibt bestehen. Sie tauschen die Präsentationsschicht, die Suchlogik läuft weiter.

BatteryIncluded liefert diese Suche als entkoppelte Infrastruktur (Decoupled Architecture). Sie läuft als eigenständiger Dienst und zieht ihre Daten aus mehreren Quellen zusammen, aus ERP, PIM, CMS und Shopsystem. Ein einfaches Add-on erreicht nur den vorhandenen Produktkatalog des Shops.

Denken Sie an einen Großhandelskatalog mit 60.000 Artikeln über mehrere Länder und Sprachen. Die Produktdaten liegen im PIM, Preise und Bestände im ERP, redaktionelle Inhalte im CMS. Eine Suche, die nur den Shop-Katalog kennt, sieht immer nur einen Teil davon. Eine aggregierende Such-Infrastruktur bringt alle drei Quellen in einen durchsuchbaren Bestand. Erst dann findet ein Kunde, der eine Herstellernummer eingibt, dasselbe Produkt wie ein Kunde, der eine technische Eigenschaft in eigenen Worten beschreibt, ganz gleich in welchem der angebundenen Systeme diese Information ursprünglich gepflegt wurde.

Such-API oder Plugin: warum die Unterscheidung im Headless-Setup zählt

Plugins sind an ein Shopsystem gebunden. Sie installieren sich in dessen Umgebung, nutzen dessen Datenmodell und sind an dessen Release-Zyklus gekoppelt. Für einen klassischen monolithischen Shop ist das oft der pragmatische Weg. Wer sein Shopware-Projekt schnell aufwerten will, findet mit dem Shopware-6-Plugin einen direkten Einstieg.

Im Headless-Setup verschiebt sich die Rechnung. Das Frontend ist bereits vom Shopsystem gelöst. Eine Suche, die fest im Shop steckt, würde diese Trennung wieder aufweichen. Eine Such-API dagegen bleibt ein eigener Baustein neben Shop, Storefront und CMS.

Der zweite Punkt betrifft die Daten. Ein reines Add-on arbeitet mit dem, was im Shop steht. Eine entkoppelte Infrastruktur aggregiert Produktdaten, Verfügbarkeiten, Content und Katalogattribute aus verschiedenen Systemen zu einem eigenen Suchbestand, wie ihn datenintensive B2B-Kataloge mit mehreren Quellen brauchen.

Der schnelle Weg über ein fertiges SDK

Solche Routinearbeit nimmt Ihnen ein SDK ab. Es kapselt Authentifizierung, die Struktur der Anfragen und das Parsen der Antworten. Statt HTTP-Aufrufe von Hand zu formulieren, rufen Sie typisierte Methoden auf. Kein handgeschriebener HTTP-Client. Warum ein SDK der schnellste Weg zur Nutzung von AI Data Discovery ist, vertieft ein eigener Beitrag.

Für PHP-Backends ist der Einstieg eine Zeile. Das offizielle PHP-SDK liegt als Composer-Paket vor.

composer require batteryincluded/batteryincluded-php-sdk

Das Paket setzt PHP 8.2 oder höher voraus und benötigt die Erweiterungen ext-curl und ext-mbstring. Es steht unter der MIT-Lizenz und ist auf Packagist mit getaggten Stable-Releases gelistet, sodass keine Dev-Version für den Install nötig ist. Ihr Composer-Setup und die üblichen CI-Prüfungen (siehe die Composer-Dokumentation) greifen unverändert.

Danach hinterlegen Sie Ihre Zugangsdaten und setzen den ersten Aufruf gegen die Such-API ab. Das SDK übernimmt die Authentifizierung und gibt Ihnen die Treffer als strukturiertes Objekt zurück, mit dem Ihr Code direkt weiterarbeitet, ohne dass Sie sich um Header, Fehlercodes oder das Format der Antwort selbst kümmern müssen. Ein einziger, sauber dokumentierter Aufruf reicht, um zu sehen, dass die Verbindung steht.

Für ein TypeScript-Frontend oder ein Node-Backend steht ein TypeScript-SDK bereit, ebenfalls unter MIT-Lizenz. Damit sprechen React-, Vue- oder Angular-Storefronts dieselbe Such-API an wie das PHP-Backend, ohne dass Sie die Integration doppelt schreiben.

Gängige Stacks haben fertige Integrationen. Ein Sylius-Shop bindet die Suche über composer require eiling-io/sylius-battery-included-plugin ein, ausgelegt auf Sylius 2.0 und höher sowie PHP 8.2 aufwärts. Für Symfony steht das Bundle batteryincluded/batteryincluded-bundle (Typ symfony-bundle) bereit, kompatibel mit den Symfony-Komponenten 7 und 8 und ab PHP 8.2, intern auf dem PHP-SDK aufbauend. Wie ein Bundle im Framework eingebunden wird, beschreibt die Symfony-Dokumentation.

Go bleibt vorerst außen vor. Das Repository ist zwar angelegt, enthält aber noch keinen nutzbaren Code, deshalb ist eine produktive Anbindung damit heute nicht möglich.

Den Index aufbauen: Datenquellen und die erste Synchronisation

Nach der Installation folgt der Schritt, der über die Qualität der ersten Ergebnisse entscheidet. Die Suche braucht einen eigenen Suchbestand, einen Index. Die naheliegende Frage im Team lautet meist, ob dafür ein eigener Index nötig ist oder ob die Shop-Datenbank reicht. Ohne Index keine Treffer.

Für eine schnelle, belastbare Suche läuft die Abfrage nicht direkt gegen die Live-Datenbank Ihres Shops. Ein dedizierter Suchindex ist auf Lesezugriffe und Relevanzberechnung optimiert. Er hält die Performance des Shops frei und liefert Antwortzeiten, die ein Datenbank-Query über viele verknüpfte Tabellen nicht erreicht.

Dieser Index wird aus Ihren Quellen gefüllt. Multi-Source Datenaggregation bringt Produkte, Preise, Bestände, Kategorien und Content zusammen. Über Echtzeit-Synchronisation (Real-time Sync) bleibt der Bestand aktuell, wenn sich im ERP ein Preis ändert oder im PIM ein neues Attribut hinzukommt. Warum es sinnvoll ist, Produkte und Content in einem Bestand zu vereinen, zeigt der Beitrag zur Unified Search über Content und Produkte.

Am Anfang steht ein vollständiger Import des Katalogs. Danach genügen inkrementelle Updates, die nur noch Änderungen nachziehen. Fällt im ERP ein Artikel weg oder ändert sich ein Preis, wandert diese eine Änderung in den Index, ohne dass der gesamte Bestand neu aufgebaut wird. So bleibt die Suche aktuell, ohne bei jedem Lauf das komplette Sortiment zu verarbeiten.

Mit der ersten Synchronisation wird aus einer leeren Suche eine arbeitende. Danach spricht Ihr Frontend die Such-API an und bekommt Treffer zurück, die auf dem aktuellen Katalog beruhen.

Erste Ergebnisse: was nach der Integration sichtbar wird

Sobald der Index steht, zeigt die Suche Verhalten, das eine mitgelieferte Shopsuche selten von Haus aus bietet.

Vertippt sich ein Kunde, landet er nicht mehr auf einer leeren Seite. Fehlertoleranz (Typo-Tolerance) fängt die Eingabe ab und liefert trotzdem passende Produkte. Aus "schaubendreher" wird der Schraubendreher, den der Kunde meint.

Filter erscheinen als Facettensuche (Faceted Search). Marke, Preisbereich, Verfügbarkeit oder technische Attribute lassen sich kombinieren, und die Trefferzahl passt sich mit jedem gesetzten Filter an.

Über die reine Zeichenkette hinaus greift semantische Suche (semantic search). Sie versteht den Sinn einer Anfrage, nicht nur die getippten Buchstaben. Eine Suche nach "leiser Laptop fürs Büro" findet Geräte, deren Beschreibung diese Eigenschaften trägt, auch ohne wörtliche Übereinstimmung. Was dahinter steckt, erklärt der Grundlagenbeitrag Was ist semantische Suche.

Hybride Suche (Hybrid Search) verbindet die exakte Treffer-Logik für eine Artikelnummer mit dem semantischen Verständnis für eine unscharfe Frage. BatteryIncluded fasst diese Kombination im Produkt Volt Search® zusammen, das die klassische Textrelevanz mit Hybrid LLM Search verbindet.

Welches SDK zu welchem Frontend passt

Nicht das Frontend entscheidet über das passende SDK. Ausschlaggebend ist die Sprache, in der Sie die Anbindung schreiben. Das ist der Kern des API-first-Ansatzes. Ein React-Storefront kann die Such-API direkt über das TypeScript-SDK ansprechen oder die Suche über Ihr PHP-Backend laufen lassen, das seinerseits das PHP-SDK nutzt. In beiden Fällen bleibt der Vertrag zwischen Frontend und Suche derselbe, sodass ein späterer Wechsel des Storefronts von React zu Vue oder zu einem serverseitig gerenderten Next.js-Setup die Anbindung der Suche nicht mehr anfasst.

Welches Frontend Sie einsetzen, bleibt Ihre Entscheidung. Die Suche wandert nicht mit dem Framework. Eine framework-spezifische Suchkomponente bietet gegenüber einer API, die jedes Frontend gleich anspricht, deshalb kaum einen zusätzlichen Vorteil.

Öffentlich einsehbar ist die vollständige Referenz der Endpunkte im Postman-Workspace von BatteryIncluded. Dort sehen Sie die verfügbaren Routen, bevor Sie die erste Zeile schreiben. Das SDK ruft dieselben Endpunkte auf, nur eben typisiert und gekapselt.

Wie lange dauert es bis zum ersten Ergebnis

Ehrlich beantwortet, verlangt das eine Rückfrage. Wie viele Datenquellen sollen in den Index, und wie sauber liegen die Daten dort vor? Die Installation des SDK ist eine Sache von Minuten. Der erste erfolgreiche Aufruf gegen die Such-API folgt kurz danach.

Aufwand entsteht bei der Datenanbindung. Ein Katalog aus einer einzigen, gepflegten Quelle ist schneller im Index als ein B2B-Sortiment aus ERP, PIM und mehreren Länder-Shops. Ein Referenzkunde betreibt über 50.000 Produkte über die Suche, was zeigt, dass die Größe des Katalogs kein Ausschlusskriterium ist. Wie viele Systeme angebunden werden, wie einheitlich die Attribute dort gepflegt sind und wie oft sich die Daten ändern, das bestimmt den Abstimmungsaufwand weit stärker als die reine Produktzahl.

Konkrete Zeit- und Zielwerte für Ihr Projekt bleiben TBD im Termin. Sie hängen vor allem an Ihren eigenen Systemen und deren Datenqualität. Der Weg vom composer require bis zum ersten Treffer im Testsystem ist kurz, während die Feinarbeit an Relevanz und Datenqualität die eigentliche Aufmerksamkeit verlangt.

Grenzen: was das SDK nicht für Sie entscheidet

So viel ein SDK abnimmt, fachliche Entscheidungen trifft es nicht. Den Rest bestimmen Sie. Nach dem Install passt eben nicht alles von allein. An mehreren Stellen bleibt der Mensch im Spiel, als Entwickler und als Merchandiser.

• Welche Attribute stärker wiegen, ob ein neues Produkt nach vorn rückt und wie eine Kategorie sortiert erscheint, entscheiden Sie über die Hebel, die das SDK bereitstellt.
• Merchandising-Regeln wie ein Aktionsartikel nach oben oder ausverkaufte Ware nach unten definiert das Marketing, oft über ein Backend und ohne Entwicklereinsatz.
• Branchenwörter, Abkürzungen und Hausbegriffe, die nur in Ihrem Sortiment gelten, kennt keine Suche von Anfang an, sie werden gezielt als Synonyme gepflegt.
• Fehlende Attribute oder uneinheitliche Bezeichnungen im PIM schlagen bis in die Trefferliste durch, und die Suche macht sichtbar, was in den Quelldaten fehlt.

Diese Human-in-the-Loop-Punkte sind kein Mangel, sondern der Ort, an dem Ihr Wissen über den eigenen Shop einfließt. Das SDK sorgt dafür, dass Sie diese Arbeit an einer Stelle erledigen und nicht in der Wartung einer selbstgebauten Suchmaschine versinken. Eine eigene Suchmaschine zu betreiben bedeutet, Tokenizer, Ranking-Formeln, Synonyme und Sprachanalyse dauerhaft selbst zu pflegen, einen Suchcluster mit Monitoring und Skalierung am Laufen zu halten und dafür genau die Entwicklerzeit zu binden, die anderswo am Produkt fehlt.

Zum Datenschutz gehört ein klares Wort. Die Suche arbeitet 100 Prozent cookieless und DSGVO-konform, ohne Tracking der einzelnen Nutzer. Personalisierung entsteht aus dem Kontext der Anfrage, nicht aus einem persönlichen Verlauf. Das ist eine bewusste Grenze, keine fehlende Funktion.

BatteryIncluded entwickelt diese Infrastruktur Made in Germany, bootstrapped und profitabel seit dem ersten Tag.

Häufige Fragen

Was ist eine Such-API im E-Commerce?
Eine Such-API ist ein eigenständiger Dienst, den Ihr Shop oder Storefront über HTTP anspricht, um Suchtreffer zu erhalten. Sie liefert strukturierte Ergebnisse zurück und ist unabhängig vom Frontend, das die Anfrage stellt.

Wie integriere ich eine Search API in einen Headless-Shop?
Der schnelle Weg führt über ein fertiges SDK. Für PHP genügt composer require batteryincluded/batteryincluded-php-sdk, für ein TypeScript-Frontend gibt es ein eigenes SDK. Danach füllen Sie den Suchindex aus Ihren Datenquellen und rufen die API auf.

Welches SDK passt zu welchem Framework?
Maßgeblich ist die Sprache Ihrer Anbindung im Backend. PHP-Backends nutzen das PHP-SDK, Node- und TypeScript-Umgebungen das TypeScript-SDK. Für Sylius und Symfony gibt es zusätzlich ein Plugin und ein Bundle.

Braucht eine Headless-Suche einen eigenen Index oder reicht die Shop-Datenbank?
Empfehlenswert ist ein eigener Suchindex. Er ist auf Relevanz und schnelle Antwortzeiten optimiert und hält die Performance des Shops frei. Über Echtzeit-Synchronisation bleibt er mit Ihren Quellsystemen aktuell.

Was unterscheidet eine Such-API von einem Plugin?
Plugins laufen im Shopsystem und sind an dessen Datenmodell gebunden. Eine Such-API ist ein eigener Baustein neben Shop, Storefront und CMS und aggregiert Daten aus mehreren Quellen. Im Headless-Setup bleibt die Trennung von Frontend und Backend so erhalten.

Muss ich für React, Vue und Angular jeweils eine eigene Suche bauen?
Das ist der Punkt, an dem der API-first-Ansatz Aufwand spart. Die Such-API und das SDK bleiben gleich, egal welches Frontend darauf zugreift. Ein Wechsel des Frameworks erzwingt keine Neuanbindung der Suche.

Kann eine fertige Such-API exakte Artikelnummern und vage Fragen zugleich bedienen?
Hybride Suche verbindet beide Modi in einem Feld. Eine getippte Artikelnummer trifft exakt, eine unscharfe Beschreibung greift über semantisches Verständnis. Der Kunde merkt davon nur, dass er findet, was er sucht.

Nächster Schritt

Eine Such-API über ein fertiges SDK anzubinden, ist der schnellste Weg von einer schwachen Shopsuche zu belastbaren Ergebnissen, ohne die Suche selbst zu bauen. Die Technik steht bereit. Der Aufwand steckt in Ihren Daten und in den fachlichen Regeln, die nur Sie kennen.

Am schnellsten sehen Sie den Unterschied an Ihrem eigenen Katalog. In einer kostenlosen Demo zeigen wir Ihnen, wie Fehlertoleranz, Facettensuche und hybride Suche an Ihren Produkten wirken. Bei technischen Fragen zur Integration erreichen Sie uns direkt über den Kontakt.