InsightSearch - Suche
Content-Type: application/json
Hilfreiche Downloads
Postmann (Beide Files auf einmal Importieren)
1. Übersicht & Authentifizierung
API-Endpunkte
InsightSearch betreibt zwei separate Services:
API
https://api.insightsearch.de/api
Feed-Verwaltung, Konfiguration, Tracking, Auth
Search Engine
https://search.insightsearch.de/api
Suche, Suggest (Autocomplete)
Token-Typen
accountSecret
Identifiziert den Account (wird einmalig von InsightSearch bereitgestellt, beginnt mit A)
String, min. 10 Zeichen
installationToken
Identifiziert die Plugin-Installation (wird einmalig von InsightSearch bereitgestellt, beginnt mit I)
String, min. 10 Zeichen
sessionToken
Kurzlebiger Token für Frontend-Anfragen (Suche, Suggest, Empfehlungen). Wird serverseitig aus accountSecret + installationToken erzeugt.
Hex-String, 40–128 Zeichen
accountSecret und installationToken werden vom Cogi-Team bereitgestellt und sollten nie im Frontend exponiert werden. Nur der sessionToken wird an den Browser weitergegeben.
Backend-Requests (Feed & Push): Im Request-Body heißen die Felder installation_secret und account_secret (snake_case) und es wird zusätzlich das Feld shop_type benötigt (für Shopware: Shopware). Praktische Anleitung inkl. Postman: siehe 14. Postman & Fehlersuche.
Kernkonzept: Feed, Index & Index-ID
Ein Feed ist die Produktdatenquelle eines Shops. Beim Registrieren eines Feeds erstellt InsightSearch daraus einen Index: den durchsuchbaren Produktdatenbestand.
Pull oder Push — zwei Wege, die Produktdaten zu liefern:
Pull (Feed-URL)
Push (API)
Prinzip
InsightSearch ruft die Feed-URL des Shops selbst ab
Der Shop überträgt seine Produkte aktiv in Batches per API
Voraussetzung
Öffentlich erreichbare XML/CSV-Feed-URL (Format siehe 6.5)
Keine — der Shop muss nicht von außen erreichbar sein
Aktualisierung
Automatisch 1× täglich (Uhrzeit konfigurierbar) sowie manuell per feed/reindex
Der Shop bestimmt Zeitpunkt und Häufigkeit selbst (Zyklus start → batch → finish)
Geeignet für
Einfachste Integration, wenn der Shop bereits einen Produkt-Feed bereitstellt
Volle Kontrolle über den Indexierungszeitpunkt, nicht öffentlich erreichbare Systeme
Der Modus wird bei der Registrierung festgelegt und gilt dauerhaft für den Index: Ein Pull-Index kann nicht per Push befüllt werden und umgekehrt — feed/reindex auf einem Push-Index antwortet mit 409 push_index_requires_push_reindex. Für Suche, Suggest, Konfiguration und Tracking verhalten sich beide Varianten identisch.
Die Register-Response enthält das Feld index.id — diese ID ist die zentrale Kennung des Index und wird in allen weiteren Endpunkten benötigt. Historisch bedingt heißt der Parameter je nach Endpunkt-Gruppe unterschiedlich:
Suche / Suggest
searchIndexId
Empfehlungen
searchIndexId
Feed-Verwaltung (reindex, delete)
index_id
Konfiguration (Synonyme, Filter, Attribute)
indicesId
Tracking / Statistiken
searchIndexId
Alle diese Parameter bezeichnen dieselbe ID — die index.id aus der Feed- bzw. Push-Registrierung. Die ID sollte nach der Registrierung dauerhaft gespeichert werden (z.B. in der Plugin-Konfiguration des Shops).
Ein Account kann mehrere Indizes besitzen (z.B. pro Sprache/Verkaufskanal je ein Index. z.b hat ein Shop 5 Sprachen, so wird für jede Sprache ein Index bereitgestellt. Jenachdem welche Sprache der Kunde in der Storefront nutzt, wird der entsprechende Index in den API Request für die Suche verwendet).
Integrations-Ablauf (Quick Start)
Der typische Weg von der Einrichtung bis zur ersten Suche:
Wichtig dabei:
Schritt 1 ist einmalig — die
index.idbleibt über die gesamte Lebensdauer des Feeds stabil, auch bei Re-Indexierungen.Suchanfragen sind erst nach erfolgreicher Indexierung möglich. Vorher antwortet die Suche mit
409 ERR_INDEX_MISSING_KEY.Suche/Suggest laufen gegen
search.insightsearch.de, alle übrigen Endpunkte gegenapi.insightsearch.de.
Caching
InsightSearch cacht auf mehreren Ebenen. Relevante Auswirkungen für die Integration:
Suchergebnisse
~60 Sekunden
Identische Anfragen (Query + Seite + Sortierung + searchMode + Filter) liefern serverseitig gecachte Antworten. Das Feld cache_unix im Response zeigt den Erzeugungszeitpunkt der Antwort
Suggest-Ergebnisse
max. 60 Sekunden
Wie Suchergebnisse
Index-Konfiguration
bis ~5 Minuten
Änderungen an Filtern, Attributen, Gewichtungen oder Synonymen werden von der Suche erst nach Ablauf dieses Caches berücksichtigt
Session-Token-Validierung
bis ~5 Minuten
Token-Prüfungen werden serverseitig gecacht
Nach einer Re-Indexierung (Feed oder Push) ist der neue Datenbestand sofort live; einzelne Suchantworten können wegen des Ergebnis-Caches aber noch bis zu ~60 Sekunden den alten Stand zeigen.
Der
sessionTokenselbst ist 1 Stunde gültig und sollte im Shop-Backend gecacht werden — nicht pro Suchanfrage neu erzeugen (siehe Abschnitt 2).
2. Session Token
Ablauf
Der sessionToken ist das zentrale Auth-Element für alle Frontend-Anfragen (Suche, Suggest, Empfehlungen). Der typische Ablauf:
Der Token ist 1 Stunde gültig (
ttlSeconds: 3600).Der Token sollte serverseitig gecacht werden und erst kurz vor Ablauf neu erzeugt werden.
Ein abgelaufener oder ungültiger
sessionTokenresultiert in401 ERR_SESSION_TOKEN_INVALID.
Session Token erzeugen
Request Body:
accountSecret
string
✅
Account-Secret (min. 10 Zeichen)
installationToken
string
✅
Installations-Token (min. 10 Zeichen)
Beispiel Request:
Response (200):
token
Der Session-Token, der für Suche/Suggest/Empfehlungen verwendet wird
expiresAt
Ablaufzeitpunkt (ISO 8601)
ttlSeconds
Gültigkeitsdauer in Sekunden (Standard: 3600)
3. Suche
Führt eine Volltextsuche mit Natural-Language-Parsing, automatischer Filter-Erkennung, Facettierung und Paginierung durch.
Request Body
sessionToken
string
✅
Gültiger Session-Token (40–128 Hex-Zeichen)
searchIndexId
integer
✅
Die index.id aus der Feed-/Push-Registrierung (siehe Kernkonzept). Alias: engineId
query
string
✅
Suchbegriff (max. 512 Zeichen). Unterstützt Natural-Language-Queries, z.B. "jeans unter 50€"
locale
string
✅
Sprachcode des Shops, z.B. de-DE oder en-US
page
integer
❌
Seite (Default: 1, min. 1)
perPage
integer
❌
Ergebnisse pro Seite (Default: 24, min. 1, max. 60)
sort
string
❌
Sortierung (Default: relevance)
searchMode
string
❌
Such-Modus: standard, precise oder explorative (Default: standard, siehe unten)
filter
object | array
❌
Filter-Objekt oder Filter-Liste (siehe unten). Alias: filters. Kann auch als JSON-String übergeben werden
isoCode
string
❌
ISO-Währungscode für Statistiken, z.B. EUR
Sortier-Optionen (sort):
relevance
Nach Relevanz (Standard)
price_asc
Preis aufsteigend
price_desc
Preis absteigend
newest
Neueste zuerst
oldest
Älteste zuerst
title_asc
Titel A–Z
title_desc
Titel Z–A
Such-Modi (searchMode):
Der Such-Modus steuert die Suchstrategie pro Anfrage. Requests ohne searchMode verhalten sich exakt wie bisher (standard) — der Parameter ist vollständig abwärtskompatibel.
standard
Ausgewogene Suche (Default): Tippfehler-Toleranz (Fuzzy), Teilwort-/Präfix-Treffer und automatische Artikelnummern-Erkennung
precise
Exakte Suche: keine Tippfehler-Toleranz, alle Suchbegriffe müssen vorkommen (UND-Verknüpfung). Artikelnummern/SKUs treffen ausschließlich Code-Felder. Empfohlen für Shops mit artikelnummern-lastigen Suchen
explorative
Maximale Trefferbreite: aggressive Tippfehler-Toleranz und zusätzliche Teilwort-Indizes (N-Gramme). Empfohlen für Discovery-orientierte Sortimente
searchMode gilt nur für /api/search. Suggest (/api/suggest) wird davon nicht beeinflusst.
Filter-Objekt (filter) — Format A: Objekt:
Beispiel Request
Response (200)
Response-Felder:
q
Bereinigter Suchbegriff nach NLP-Verarbeitung
took_ms
Verarbeitungszeit in Millisekunden (OpenSearch)
products
Array der Treffer (alle Feed-Felder werden durchgereicht)
products[].id
Produkt-ID
products[].title
Produkttitel
products[].url
Produkt-URL
products[].image
Bild-URL
products[].price
Verkaufspreis (bei Sale: Sale-Preis; sonst regulärer Preis)
products[].listPrice
Regulärer Preis / UVP (bei Sale: regulärer Preis; sonst ggf. list_price)
products[].referencePrice
Referenzpreis (Grundpreis)
products[].currency
Währungscode
products[].brand
Marke
products[].badge
Badges (Array mit title und color), null wenn keine vorhanden
products[].unit
Einheit
products[].purchaseUnit
Kaufmenge
products[].referenceUnit
Referenzmenge
filters.config
Filter-Konfiguration des Index (Kategorien, Terms, Attribute, Ranges)
filters.groups
Aufbereitete Filter-Gruppen für das Rendering
filters.applied
Aktuell angewandte Filter
filters.appliedById
Angewandte Filter, indiziert nach ID
filters.filtered
Filter-Optionen mit aktiven Filtern
filters.all
Filter-Optionen ohne Filter (alle verfügbaren Werte)
suggest
"Meinten Sie?"-Vorschlag (aus OpenSearch)
pagination
Paginierungsinformationen
pagination.total
Gesamttreffer
pagination.totalPages
Gesamtseiten
pagination.hasNext
Weitere Seiten verfügbar
pagination.hasPrev
Vorherige Seiten verfügbar
cache_unix
Unix-Timestamp der Antwort-Erzeugung. Antworten werden serverseitig gecacht — hieran lässt sich das Alter eines Cache-Treffers erkennen
broken_filter_fields
Nur vorhanden, wenn einzelne Filter-Felder bei der Facettierung fehlschlagen: Liste der betroffenen Feldnamen. Diese Filter werden für die Anfrage automatisch übersprungen
Fehlercodes
401
ERR_SESSION_TOKEN_INVALID
Session-Token fehlt, ungültig oder abgelaufen
404
ERR_INDEX_NOT_FOUND
Index-ID existiert nicht oder gehört nicht zum Account
409
ERR_INDEX_MISSING_KEY
Index noch nicht vollständig initialisiert
502
ERR_SEARCH_BACKEND
Interner Fehler
4. Suggest / Autocomplete
Liefert Suchvorschläge in Echtzeit während der Eingabe (Autocomplete / Search-as-you-type). Kombiniert Prefix-Matching, Popularity-Scoring und optionale Fuzzy-Suche.
Request Body
sessionToken
string
✅
Gültiger Session-Token (40–128 Hex-Zeichen)
searchIndexId
integer
✅
Die index.id aus der Feed-/Push-Registrierung (siehe Kernkonzept). Alias: engineId
query
string
✅
Suchbegriff (max. 512 Zeichen)
locale
string
❌
Sprachcode, z.B. de-DE (empfohlen)
isoCode
string
❌
ISO-Währungscode, z.B. EUR
limit
integer
❌
Anzahl Vorschläge (Default: 5, min. 1, max. 5)
Beispiel Request
Response (200)
Response-Felder:
suggestions
Array der Vorschläge (max. limit Einträge)
suggestions[].text
Anzeigetext des Vorschlags
suggestions[].type
Quelle: query, brand, category, attribute, product, synonym
suggestions[].score
Interner Relevanz-Score
suggestions[].meta.source_type
Quelle des Vorschlags
suggestions[].meta.highlighted
Text mit Hervorhebung des Eingabe-Matches
suggestions[].meta.target
Zielaktion: type (search oder category), query, filter
dym.text
"Did you mean?"-Text, null wenn nicht vorhanden
dym.active
true wenn ein DYM-Vorschlag aktiv ist
Fehlercodes
401
ERR_SESSION_TOKEN_INVALID
Session-Token fehlt, ungültig oder abgelaufen
404
ERR_INDEX_NOT_FOUND
Index nicht gefunden
409
ERR_INDEX_MISSING_KEY
Index noch nicht initialisiert
5. Empfehlungen
DOKU folgt.
6. Feed-Verwaltung
Die Feed-Verwaltung ist die Pull-Variante der Indexierung (siehe Pull vs. Push): Der Shop stellt eine öffentlich erreichbare XML/CSV-Feed-URL bereit, InsightSearch ruft diese ab — automatisch einmal täglich (Uhrzeit konfigurierbar) sowie auf Anforderung per reindex. Die Registrierung liefert die index.id, mit der der Index anschließend in Suche, Suggest, Konfiguration und Tracking referenziert wird (siehe Kernkonzept und Integrations-Ablauf).
Alle Feed-Endpunkte liegen unter https://api.insightsearch.de/api/plugin/feed/... und erfordern account_secret + installation_secret.
6.1 Feed registrieren
Erstellt einen neuen Produkt-Feed und startet die erste Indexierung.
Request Body:
installation_secret
string
✅
Installations-Token
account_secret
string
✅
Account-Secret
shop_type
string
✅
Shop-Typ (z.B. Shopware, max. 100 Zeichen)
name
string
✅
Name des Feeds (max. 255 Zeichen)
feed_url
string (URL)
✅
URL zum Produkt-Feed (XML/CSV)
language_code
string
✅
Sprachcode(s), kommagetrennt (z.B. de-DE oder de-DE,en-US)
currency
string
✅
Währungscode (max. 8 Zeichen, z.B. EUR)
index_type
string
❌
SEARCH oder RECOMMENDATIONS (Default: SEARCH)
Beispiel Request:
Response (201):
index.id ist die zentrale Index-ID für alle weiteren Endpunkte — sie wird als searchIndexId (Suche, Suggest, Tracking), indicesId (Konfiguration) bzw. index_id (Feed-Verwaltung) verwendet und sollte dauerhaft gespeichert werden. Siehe Kernkonzept.
6.2 Feed-Status prüfen
Prüft den Indexierungs-Status eines Feeds.
Request Body:
installation_secret
string
✅
Installations-Token
account_secret
string
✅
Account-Secret
shop_type
string
✅
Shop-Typ
feed_url
string (URL)
❌
Feed-URL (wenn nicht angegeben: erster Feed des Accounts)
Response (200):
Mögliche message-Werte:
feed_not_found
Kein Feed gefunden
feed_index_pending
Indexierung läuft
feed_index_error
Indexierung fehlgeschlagen
feed_index_retry_started
Automatischer Retry gestartet (nach Fehler > 15 Min.)
feed_index_success
Indexierung erfolgreich abgeschlossen
6.3 Feed neu indexieren
Startet die Neuindexierung eines bestehenden Feeds.
Request Body:
installation_secret
string
✅
Installations-Token
account_secret
string
✅
Account-Secret
shop_type
string
✅
Shop-Typ
index_id
integer
✅
ID des Index (min. 1)
Beispiel Request:
Response (200):
Fehlercodes:
404
Installation, Account oder Index nicht gefunden
409
Indexierung läuft bereits
409
Index ist ein Push-Index (push_index_requires_push_reindex) — Aktualisierung erfolgt über den Push-Zyklus (Abschnitt 7)
6.4 Feed löschen
Löscht einen Feed inkl. aller zugehörigen Daten (OpenSearch-Indizes, Tracking, Attribute, Synonyme, Filter).
Request Body:
installation_secret
string
✅
Installations-Token
account_secret
string
✅
Account-Secret
shop_type
string
✅
Shop-Typ
index_id
integer
✅
ID des Index (min. 1)
Response (200):
6.5 Feed-Format: Beispiel (XML)
InsightSearch liest Produkt-Feeds im RSS-2.0-Format mit Google-Merchant-Namespace (xmlns:g="http://base.google.com/ns/1.0"). Jedes Produkt ist ein <item>-Element (Atom-Feeds mit <entry> werden ebenfalls unterstützt).
Hinweise zum Format:
g:id
Eindeutige Produkt-ID. Fallback-Reihenfolge bei der Erkennung: g:id → id → g:sku → sku
title
Produkttitel — wird zusätzlich für Suggest/Autocomplete verwendet
link
Produkt-URL im Shop
g:image_link
Bild-URL
g:price
Preis inkl. Währung, z.B. 49.99 EUR — der numerische Wert wird automatisch extrahiert
g:sale_price
Optionaler Aktionspreis. Ist er gesetzt, liefert die Suche ihn als price und den regulären Preis als listPrice
g:brand
Marke — wird zusätzlich für Suggest verwendet
g:product_type
Kategoriepfad mit > als Hierarchie-Trenner (z.B. Bekleidung > Hosen > Jeans). Daraus werden Kategorien und Kategorie-Filter aufgebaut. Alternativ werden auch g:google_product_category und g:category gelesen; mehrere Pfade pro Produkt sind möglich
Weitere Felder
Alle übrigen Felder (z.B. g:size, g:color, g:material, Eigenfelder ohne Namespace) werden beim ersten Import automatisch als Attribute erkannt und können anschließend als Suchfelder und Filter konfiguriert werden (siehe Abschnitt 10)
Der
g:-Prefix ist optional — Felder werden mit und ohne Namespace erkannt, der Prefix wird bei der Indexierung entfernt (g:price→price).Leere Elemente (z.B.
<g:gtin/>) sind erlaubt und werden ignoriert.Varianten werden als eigenständige
<item>-Einträge mit jeweils eigenerg:idübertragen.
7. Push-Indexierung
Die Push-Indexierung ist die Push-Variante der Indexierung (siehe Pull vs. Push): Der Shop überträgt seine Produkte aktiv per API in den Index, ohne dass eine öffentlich erreichbare Feed-URL nötig ist. InsightSearch stößt für Push-Indizes keine automatische Indexierung an — Zeitpunkt und Häufigkeit der Aktualisierung bestimmt allein der Shop, indem er den Push-Zyklus erneut durchläuft. Alle Endpunkte liegen unter https://api.insightsearch.de/api/plugin/push/....
Ablauf
Bei Fehlern oder Abbruch: abort verwenden, um die Session aufzuräumen.
7.1 Push-Index registrieren
Request Body:
installation_secret
string
✅
Installations-Token
account_secret
string
✅
Account-Secret
shop_type
string
✅
Shop-Typ (z.B. Shopware)
name
string
✅
Name des Index (max. 255 Zeichen)
language_code
string
✅
Sprachcode(s), kommagetrennt (z.B. de-DE)
currency
string
✅
Währungscode (max. 8 Zeichen)
index_type
string
❌
SEARCH oder RECOMMENDATIONS (Default: SEARCH)
Response (201):
index.id ist die zentrale Index-ID für alle weiteren Endpunkte (Suche, Suggest, Konfiguration, Tracking) und sollte dauerhaft gespeichert werden — siehe Kernkonzept. Die Registrierung erfolgt einmalig; für jede Aktualisierung der Produktdaten wird anschließend nur der Zyklus start → batch → finish wiederholt.
7.2 Push-Session starten
Legt einen neuen versionierten Index an und startet eine Push-Session. Die Session ist 2 Stunden gültig.
Request Body:
installation_secret
string
✅
Installations-Token
account_secret
string
✅
Account-Secret
shop_type
string
✅
Shop-Typ
index_id
integer
✅
ID des Index (aus register)
Response (200):
Fehlercodes:
404
PUSH_ERR_2001
Index nicht gefunden
409
PUSH_ERR_2002
Session läuft bereits
500
PUSH_ERR_2003
Index-Erstellung fehlgeschlagen
7.3 Produkt-Batch übertragen
Überträgt einen Batch von Produkten. Kann beliebig oft aufgerufen werden. Beim ersten Batch werden Attribute automatisch erkannt und das Mapping aktualisiert.
Request Body:
installation_secret
string
✅
Installations-Token
account_secret
string
✅
Account-Secret
shop_type
string
✅
Shop-Typ
session_id
string (UUID)
✅
Session-ID (aus start)
products
array
✅
Array von Produkt-Objekten (min. 1, id Pflichtfeld)
Jedes Produkt muss mindestens ein id-Feld enthalten. Alle weiteren Feed-Felder werden übergeben. Felder mit g:-Prefix werden automatisch normalisiert (Prefix entfernt).
Beispiel Request:
Response (200):
Fehlercodes:
404
PUSH_ERR_3001
Session nicht gefunden
409
PUSH_ERR_3003
Session nicht aktiv
410
PUSH_ERR_3002
Session abgelaufen (> 2 Stunden)
500
PUSH_ERR_3004
Indexierung fehlgeschlagen
7.4 Push-Session abschließen
Schließt die Indexierung ab und neuer Index wird live geschaltet. Ein Deviation Guard prüft, ob die Produktanzahl stark vom Vorwert abweicht.
Request Body:
installation_secret
string
✅
Installations-Token
account_secret
string
✅
Account-Secret
shop_type
string
✅
Shop-Typ
session_id
string (UUID)
✅
Session-ID (aus start)
Response (200) — Erfolgreich:
Response (422) — Deviation Guard ausgelöst:
7.5 Push-Session abbrechen
Bricht eine laufende Push-Session ab und räumt den temporären Index auf.
Request Body: Identisch mit 7.4
Response (200):
8. Konfiguration: Synonyme
Synonyme werden pro Index konfiguriert und ermöglichen es, alternative Schreibweisen oder gleichbedeutende Begriffe zu verknüpfen. Alle Endpunkte liegen unter https://api.insightsearch.de/api/plugin/config/synonyms/....
Gemeinsame Authentifizierungsfelder (in jedem Request):
accountSecret
string
✅
Account-Secret
installationSecret
string
✅
Installations-Token
indicesId
string
✅
Index-ID
8.1 Synonym erstellen
Request Body:
accountSecret
string
✅
Account-Secret
installationSecret
string
✅
Installations-Token
indicesId
string
✅
Index-ID
terms
string
✅
Kommagetrennte Synonyme (min. 2 Begriffe, z.B. "Hose, Jeans, Pants")
Beispiel Request:
Response (201):
8.2 Synonym aktualisieren
Request Body:
accountSecret
string
✅
Account-Secret
installationSecret
string
✅
Installations-Token
indicesId
string
✅
Index-ID
synonymeId
string
✅
ID des Synonyms
terms
string
✅
Neue kommagetrennte Synonyme
Response (200):
8.3 Synonym löschen
Request Body:
accountSecret
string
✅
Account-Secret
installationSecret
string
✅
Installations-Token
indicesId
string
✅
Index-ID
synonymeId
string
✅
ID des zu löschenden Synonyms
Response (200):
Fehlercodes (alle Synonym-Endpunkte):
404
Account, Installation oder Index nicht gefunden
404
Synonym nicht gefunden
422
Ungültiges Format (weniger als 2 Begriffe)
9. Konfiguration: Filter
Filter definieren, welche Produktattribute als Facetten in der Suche verfügbar sind. Alle Endpunkte liegen unter https://api.insightsearch.de/api/plugin/config/filters/....
9.1 Filter erstellen
Request Body:
accountSecret
string
✅
Account-Secret
installationSecret
string
✅
Installations-Token
indicesId
string
✅
Index-ID
attribute_id
string
✅
ID des Attributs (muss zum Index gehören)
position
integer
✅
Anzeigereihenfolge
name
string
✅
Anzeigename des Filters
type
string
✅
Filter-Typ (z.B. terms, range)
active
boolean
❌
Aktiv-Status (Default: true)
nlp_keywords
string
❌
Kommagetrennte Keywords für Natural-Language-Erkennung
Beispiel Request:
Response (201):
9.2 Filter aktualisieren
Request Body:
accountSecret
string
✅
Account-Secret
installationSecret
string
✅
Installations-Token
indicesId
string
✅
Index-ID
filterId
string
✅
ID des Filters
attribute_id
string
✅
Attribut-ID
position
integer
✅
Neue Position
name
string
✅
Neuer Anzeigename
type
string
✅
Filter-Typ
active
boolean
❌
Aktiv-Status
nlp_keywords
string
❌
NLP-Keywords (kommagetrennt)
Response (200):
9.3 Filter löschen
Request Body:
accountSecret
string
✅
Account-Secret
installationSecret
string
✅
Installations-Token
indicesId
string
✅
Index-ID
filterId
string
✅
ID des zu löschenden Filters
Response (200):
Fehlercodes (alle Filter-Endpunkte):
404
Account, Installation, Index oder Attribut nicht gefunden
404
Filter nicht gefunden
422
Filter-ID fehlt
10. Konfiguration: Attribute
Attribute sind die indizierten Produkteigenschaften eines Index. Sie werden automatisch aus dem Feed erkannt und können über die API gesteuert werden. Endpunkte liegen unter https://api.insightsearch.de/api/plugin/config/attributes/....
Automatische Erkennung
Bei jeder Feed-Indexierung (bzw. beim ersten Push-Batch) scannt InsightSearch alle Felder des Feeds. Für jedes neue Feld wird automatisch ein Attribut angelegt:
Datentyp: wird aus Feldname und Beispielwerten abgeleitet (
text,keyword,integer,long,float,boolean,date).Such-Gewichtung (
search_wight): wird anhand des Feldnamens vorbelegt:
Titel / Beschreibung
10
Marke / Kategorie
8
Artikelnummern (sku, mpn, gtin, …)
5
Preis
4
IDs
3
Alle übrigen Felder
1
Aktiv-Status: Nur Kernfelder werden automatisch aktiviert (
id,title,brand,price,mpn,gtin,link,image_link,keywords,mark_as_topseller). Alle übrigen Felder werden inaktiv angelegt und müssen bei Bedarf perupdateaktiviert werden.
Re-Indexierungen überschreiben keine manuelle Konfiguration: Gewichtung, Aktiv-Status und Auto-Filter-Einstellungen bestehender Attribute bleiben erhalten — nur der erkannte Datentyp wird bei Bedarf aktualisiert.
Wirkung der Einstellungen
active
Nur aktive Attribute werden indexiert und stehen für Suche, Filter und Auto-Filter zur Verfügung
Nächste (Re-)Indexierung — die Felddaten müssen in den Index geschrieben werden
search_wight
0 = Feld wird nicht durchsucht. Werte > 0 gewichten das Feld in der Relevanzberechnung (feldname^gewichtung). Nur Text-/Keyword-Felder fließen in die Volltextsuche ein
Ohne Re-Indexierung (Konfigurations-Cache bis ~5 Min., siehe Caching)
type
Datentyp des Felds. Numerische Typen ermöglichen Range-Filter (Slider), sind aber nicht volltext-durchsuchbar
Vollständig erst nach Re-Indexierung (Index-Mapping)
auto_filter_enabled
Erkennt Attributwerte direkt in der Suchanfrage und wendet sie automatisch als Filter an (z.B. Suche jeans blau → Filter auf den Farbwert blau)
Nach der nächsten (Re-)Indexierung (der dafür nötige Werteindex wird beim Indexieren aufgebaut)
auto_filter_match
Matching-Modus der Auto-Filter-Erkennung: exact (exakte Übereinstimmung) oder partial (Teil-Übereinstimmung)
Wie auto_filter_enabled
10.1 Attribute abrufen
Request Body:
accountSecret
string
✅
Account-Secret
installationSecret
string
✅
Installations-Token
indicesId
string
✅
Index-ID
Beispiel Request:
Response (200):
10.2 Attribut aktualisieren
Request Body:
accountSecret
string
✅
Account-Secret
installationSecret
string
✅
Installations-Token
indicesId
string
✅
Index-ID
attributeId
string
✅
Attribut-ID
search_wight
integer
❌
Such-Gewichtung (min. 0). Höhere Werte = stärkerer Einfluss auf Relevanz, 0 = Feld wird nicht durchsucht
active
boolean
❌
Attribut aktiv/inaktiv (inaktive Attribute werden nicht indexiert)
type
string
❌
Datentyp: text, keyword, integer, long, float, boolean, date
auto_filter_enabled
boolean
❌
Automatische Filter-Erkennung aus der Suchanfrage
auto_filter_match
string
❌
Matching-Modus für Auto-Filter: exact oder partial
Beispiel Request:
Response (200):
Fehlercodes:
404
Account, Installation, Index oder Attribut nicht gefunden
422
Attribut-ID fehlt
11. User-Tracking
Tracking-Endpunkte erfassen Nutzerinteraktionen für Statistiken, personalisierte Empfehlungen und Suchoptimierungen. Alle Endpunkte liegen unter https://api.insightsearch.de/api/plugin/tracking/....
Gemeinsame Authentifizierungsfelder:
accountSecret
string
✅
Account-Secret
installationToken
string
✅
Installations-Token
11.1 Nutzer-Event erfassen
Erfasst generische Nutzerinteraktionen wie Klicks, Produktansichten, Suchen etc.
Request Body:
accountSecret
string
✅
Account-Secret
installationToken
string
✅
Installations-Token
eventType
string
✅
Event-Typ (max. 64 Zeichen)
sessionId
string
❌
Shop-Session-ID (max. 190 Zeichen)
customerId
string
❌
Kunden-ID (max. 190 Zeichen)
timestamp
date
❌
Zeitpunkt des Events (ISO 8601)
pageUrl
string
❌
Aktuelle Seiten-URL
searchTerm
string
❌
Suchbegriff
searchResultsCount
integer
❌
Anzahl Suchergebnisse
searchResultPosition
integer
❌
Position des angeklickten Ergebnisses
clickedIdentifier
string
❌
Kennung des angeklickten Elements
clickedUrl
string
❌
URL des angeklickten Elements
productId
string
❌
Produkt-ID
category
string
❌
Kategorie
brand
string
❌
Marke
price
numeric
❌
Preis
searchIndexId
integer
❌
Index-ID
clientUserAgent
string
❌
User-Agent (für Bot-Erkennung)
widgetId
string
❌
Widget-ID für Empfehlungs-Tracking
intentStage
string
❌
Kaufabsicht: explore, consideration, ready_to_buy
Event-Typen (eventType):
Das Feld ist ein freier String (max. 64 Zeichen). Die folgenden Typen werden vom System erkannt und für Statistiken sowie personalisierte Empfehlungen ausgewertet:
CLICK_SEARCH_RESULT
Klick auf ein Suchergebnis
Für Statistiken und Such-Attribution
CLICK_PRODUKTPAGE
Aufruf einer Produktdetailseite
Basis für personalisierte Empfehlungen
CLICK_KATEGORIE
Aufruf einer Kategorieseite
CLICK_LANDINGPAGE
Aufruf der Startseite
CLICK_CHECKOUT
Aufruf einer Checkout-Seite
CLICK_PAGEVIEW
Sonstiger Seitenaufruf (Fallback)
Beispiel Request:
Response (200):
Bots werden automatisch erkannt und ignoriert — Response bleibt
{"status":"ignored"}.
11.2 Bestellung erfassen
Erfasst Bestellungen zur Conversion-Analyse und Empfehlungsoptimierung.
Request Body:
accountSecret
string
✅
Account-Secret
installationToken
string
✅
Installations-Token
customerNumber
string
✅
Kundennummer (max. 190 Zeichen)
orderTotal
numeric
✅
Bestellsumme (min. 0)
items
array
✅
Bestellpositionen (min. 1)
items[].productId
string
✅
Produkt-ID
items[].quantity
integer
❌
Menge
items[].unitPrice
numeric
❌
Stückpreis
items[].listPrice
numeric
❌
Listenpreis
items[].discountPct
numeric
❌
Rabatt in Prozent (0–100)
items[].category
string
❌
Kategorie
items[].brand
string
❌
Marke
items[].addedFromCogiSearch
boolean
❌
Über InsightSearch-Suche hinzugefügt
items[].cogiSearchTerm
string
❌
Suchbegriff bei Hinzufügen
items[].addedFromCogiRecommendation
boolean
❌
Über Empfehlung hinzugefügt
items[].cogiRecommendationType
string
❌
Empfehlungstyp bei Hinzufügen
orderId
string
❌
Bestell-ID
orderCurrency
string
❌
Währungscode
sessionId
string
❌
Shop-Session-ID
userId
string
❌
Nutzer-ID
isPaid
boolean
❌
Bezahlstatus
searchIndexId
integer
✅*
Such-Index-ID
Beispiel Request:
Response (200):
11.3 Bezahlstatus aktualisieren
Aktualisiert den Bezahlstatus einer bereits erfassten Bestellung.
Request Body:
accountSecret
string
✅
Account-Secret
installationToken
string
✅
Installations-Token
orderId
string
✅
Bestell-ID (max. 128 Zeichen)
isPaid
boolean
✅
Neuer Bezahlstatus
searchIndexId
integer
❌
Index-ID
Response (200):
Response (404) — Bestellung nicht gefunden:
11.4 Warenkorb-Event erfassen
Erfasst "In den Warenkorb"-Events.
Request Body:
accountSecret
string
✅
Account-Secret
installationToken
string
✅
Installations-Token
sessionId
string
✅
Shop-Session-ID (max. 190 Zeichen)
type
string
✅
Derzeit nur: add_to_cart
items
array
✅
Produkte (min. 1)
items[].productId
string
✅
Produkt-ID
items[].quantity
integer
❌
Menge
items[].unitPrice
numeric
❌
Stückpreis
searchIndexId
integer
✅*
Index-ID
customerId
string
❌
Kunden-ID
intentStage
string
❌
Kaufabsicht: explore, consideration, ready_to_buy
Response (200):
12. Statistiken
Alle Statistik-Endpunkte liegen unter https://api.insightsearch.de/api/plugin/statistics/....
12.1 Such-Statistiken
Liefert aggregierte Statistiken zu Suchen, Impressionen und Conversions.
Request Body: Enthält accountSecret, installationToken sowie Filterzeitraum (from, to, period).
12.2 Produkt-Statistiken
Liefert produktbezogene Kennzahlen (Impressionen, Klicks, Conversions pro Produkt).
12.3 Widget-Statistiken
Liefert Statistiken zu Empfehlungs-Widgets.
12.4 Suchvorschläge-Statistiken
Liefert Top-Suchbegriffe, Null-Treffer-Suchen und ähnliche Insights.
12.5 Nutzungsstatistiken
Liefert Nutzungsdaten zur Abrechnung und Quotenverwaltung.
13. Status & Probleme
Liefert alle offenen Probleme des Accounts — gedacht für Status- und Warnanzeigen im Shop-Backend (z.B. im Plugin-Dashboard). Beim Aufruf prüft das System zusätzlich aktiv, ob mindestens ein Index existiert und ob die Plugin-Installationen noch KeepAlive-Signale senden — entsprechende Probleme werden dabei direkt erzeugt bzw. geschlossen.
Behobene Probleme werden automatisch aufgelöst und erscheinen nicht mehr in der Liste.
Request Body:
account_secret
string
✅
Account-Secret
installation_secret
string
✅
Installations-Token
Response (200):
problems[].type
Problem-Typ (siehe Tabelle unten)
problems[].message
Menschenlesbare Beschreibung des Problems
problems[].indices_id
Betroffener Index, null wenn accountweit
problems[].plugin_installations_id
Betroffene Installation, null wenn nicht installationsbezogen
problems[].data
Zusätzliche Detail-Daten je nach Problem-Typ
Problem-Typen (type):
no_index_present
Für den Account wurde noch kein Index angelegt
feed_index_failed
Die letzte Feed-Indexierung ist fehlgeschlagen (message enthält den Grund)
feed_bulk_item_errors
Einzelne Produkte konnten bei der Indexierung nicht übernommen werden
plugin_keepalive
Die Plugin-Installation sendet keine KeepAlive-Signale mehr (über 72 Stunden kein Kontakt oder noch nie)
broken_filter
Ein Filter-Feld verursacht Fehler in der Suche — wird von der Suche automatisch gemeldet (vgl. broken_filter_fields im Such-Response, Abschnitt 3)
Fehlercodes:
404
account_secret_not_found
Account-Secret unbekannt
404
user_not_found
Zugehöriger Account nicht gefunden
404
installation_not_found
Installations-Token unbekannt oder gehört nicht zum Account
Allgemeine Fehlercodes
401
Authentifizierung fehlgeschlagen (ungültige Tokens)
404
Ressource nicht gefunden (Account, Installation, Index, Synonym, Filter etc.)
409
Konflikt (z.B. Session läuft bereits, Indexierung aktiv)
410
Session abgelaufen
422
Validierungsfehler (fehlende oder ungültige Felder)
500 / 502
Interner Serverfehler
14. Postman & Fehlersuche
So wird die API mit Postman (oder einem beliebigen HTTP-Client) korrekt angesprochen — und was die typischen Fehler bedeuten.
14.1 Grundregeln
Methode: Alle Plugin-Endpunkte sind
POST.Pfad immer mit
/api-Prefix: z.B.https://api.insightsearch.de/api/plugin/feed/validate— nicht.../plugin/feed/validateohne/api.Header:
Content-Type: application/jsonAccept: application/json(empfohlen)
Body:
raw/JSON.
14.2 Authentifizierung (Feed- & Push-Endpunkte)
Jeder Request an die Feed- und Push-Endpunkte braucht drei Felder im JSON-Body:
installation_secret
Installations-Token
beginnt mit I
account_secret
Account-Secret
beginnt mit A
shop_type
Shop-Typ
für Shopware-Shops: Shopware
Häufigster Fehler: installation_secret und account_secret vertauscht. Merkhilfe: I = Installation, A = Account.
shop_type: Die Admin-UI zeigt nur die beiden Keys, nicht den shop_type. Für Shopware-Installationen ist der Wert Shopware. Der serverseitige Vergleich ist case-insensitiv — Shopware, shopware und SHOPWARE lösen alle dieselbe Installation auf.
14.3 Schnellstart (feed/validate)
Eine fertige Postman-Collection inkl. Environment liegt im Repo:
docs/InsightSearch.postman_collection.jsondocs/InsightSearch.postman_environment.json
In Postman über Import beide Dateien laden, das Environment „InsightSearch" auswählen und die Variablen installation_secret, account_secret und shop_type mit den Werten aus der Admin-UI füllen. Alle Requests nutzen dann {{api_base}} + Variablen.
14.4 Fehler → Ursache
404 {"message":"Installation secret not found"}
installation_secret falsch oder mit account_secret vertauscht (A statt I), oder shop_type passt nicht zur Installation. shop_type ist case-insensitiv — bei Shopware Shopware senden.
404 {"message":"Account or Installation secret not found"}
account_secret gehört nicht zur gefundenen Installation (z.B. nach Neuinstallation mit neuem Installations-Secret).
401 {"code":"PUSH_ERR_1001"}
Push-Endpunkt: Installation/Account nicht auflösbar (gleiche Ursachen wie 404 oben — Push antwortet generisch mit 401).
422 mit errors-Objekt
Pflichtfeld fehlt oder ungültig (Validierung). Sind alle drei Auth-Felder plus die endpunkt-spezifischen Felder gesetzt?
HTML-Seite / Login-Formular als Antwort
Der Request lief nicht unter /api/... (Pfad falsch, /api-Prefix fehlt). Unter /api/* liefert die API immer JSON — eine HTML-/Login-Antwort heißt: falscher Pfad.
404 {"error_code":"route_not_found"}
Route existiert nicht (Tippfehler im Pfad).
14.5 Config-Endpunkte (Synonyme / Filter / Attribute)
Die Konfigurations-Endpunkte (Abschnitt 8–10) akzeptieren die Auth-Felder sowohl in camelCase (accountSecret, installationSecret, indicesId) als auch in snake_case (account_secret, installation_secret). Beide Schreibweisen funktionieren.
Zuletzt aktualisiert
War das hilfreich?