KaliCart Bridge

Ein kostenloses WooCommerce-Plugin, das Ihren Live-Katalog als strukturierte REST-API für KI-Shopping-Agenten verfügbar macht. Kein LLM, keine Cloud, kein externer Dienst — alles läuft auf Ihrem Server.

Alle Katalog-Endpunkte lesen zum Zeitpunkt der Abfrage direkt aus der WooCommerce-Datenbank. Preisänderungen, Lagerbestandsaktualisierungen und neue Produkte werden sofort widergespiegelt — keine Synchronisierung, kein Snapshot, keine Verzögerung.

Installation

1. kalicart-bridge-1.0.114.zip herunterladen
2. Hochladen und aktivieren über WP Admin → Plugins → Neu hinzufügen → Hochladen
3. WooCommerce muss aktiv sein — das Plugin prüft dies und warnt, falls nicht
4. Bei der Aktivierung sind standardmäßig alle Signale aktiviert (Badge, robots.txt, Sitemap)
5. Besuchen Sie WP Admin → KaliCart, um das Katalog-Gesundheits-Dashboard zu sehen

Endpunkte

Alle Endpunkte unter /wp-json/kalicart/v1/.

Discovery-Dokument

Der einzige Einstiegspunkt. Wichtige Felder, die ein Agent lesen muss:

• kalicart_agent_catalog.taxonomy — immer merchant_native_woocommerce. /catalog/categories lesen, um sie aufzuzählen.
• public_catalog.query_construction — kritische Regeln für den korrekten Aufbau von Suchanfragen.
• public_catalog.search_filters — akzeptierte Parameter mit erlaubten Werten.
• merchant_shipping_policy — deklarative Versandzonen, Methoden und Schwellenwerte für kostenlosen Versand.
• coupon_policy.price_rule — Coupons sind immer bedingte Checkout-Ersparnisse; ersetzen niemals price.current.
• agent_instructions — geordnete Schritte, die der Agent befolgen muss.

// Minimal agent bootstrap
GET /wp-json/kalicart/v1/discovery
→ read public_catalog.* for all endpoint URLs
→ read merchant_shipping_policy for shipping reasoning
→ read agent_instructions for query rules

Suche & Filter

Die wichtigste Regel: q darf nur das reine Produkt-Substantiv enthalten. Jedes andere Attribut muss in seinen eigenen strukturierten Filter.

Verfügbare Filter

Richtig vs. falsch

✓ richtig
GET /catalog/search?q=sneakers&gender=male&max_price=120&in_stock=true
GET /catalog/search?q=jacket&category=outerwear&color=black

✗ falsch — Attribute in q gestapelt → 0 Ergebnisse
GET /catalog/search?q=blue+men+sneakers+under+100

Wiederherstellung bei null Ergebnissen

• Erneut versuchen mit nackterem q — Attribute aus q in ihre Filter verschieben
• GET /catalog/categories, um den korrekten Kategorie-Slug zu finden
• „Nicht verfügbar" erst melden, nachdem sowohl reiner Kern als auch Kategorie-Browse 0 zurückgegeben haben

Produkt-Payload

Preis

• price.encoding: decimal_major_units — Werte sind Dezimalzahlen in vollen Währungseinheiten (z.B. 29.99 = 29,99 EUR). Keine ISO-4217-Untereinheiten.
• price.display: als reiner Text formatierte Zeichenkette (z.B. „29,99 €") — eindeutig, zur Darstellung verwenden.
• price.vat_included: ob die Preise laut WooCommerce-Steuereinstellungen die MwSt. enthalten.
• price.price_type: STATIC für Standardprodukte. Abgestimmt auf das KaliCart-Global-Format.
• list_price: ursprünglicher Listenpreis vor Rabatten (nur einfache Produkte).

• price.current — der maßgebliche Katalogpreis. Immer für Handelsentscheidungen verwenden.
• price.on_sale, price.discount_pct — Verkaufsstatus und Rabattprozentsatz auf den regulären Preis.
• Variable Produkte liefern price.type: "range" mit min_regular, max_regular, min_sale, max_sale.

Stock

• stock.in_stock — boolescher Wert, vor jedem Angebot prüfen.
• stock.availability_status — UCP-Standardwerte: in_stock, out_of_stock, backorder.
• stock.quantity — numerisch, wenn der Merchant die Lagermenge verwaltet; sonst null.
• stock.quantity_tracked — boolescher Wert, ob der Merchant die numerische Lagermenge verwaltet.
• stock.backorder_allowed — boolescher Wert, true, wenn Nachbestellung notify oder yes ist.
• stock.confidence — numeric_stock_quantity (exakte Anzahl), availability_status_only (Merchant zeigt die Menge nicht — als verfügbar behandeln, nicht als bestätigten Bestand) oder variant_dependent (zuerst eine Variante auswählen).
• stock.agent_note — vorhanden, wenn die Konfidenz nicht numeric_stock_quantity ist. Vor der Meldung der Verfügbarkeit lesen.

Berechnete Attribute

• gender — abgeleitet aus dem Attribut pa_gender, Schlüsselwörtern im Kategoriepfad, Tags, Produktname. null, wenn unbestimmbar.
• colors[] — Farbfamilien, gemappt aus pa_color / pa_colore. Jeder Eintrag hat family und raw.
• sizes — extrahiert aus pa_size / pa_taglia. Typ automatisch erkannt: clothing, numeric oder shoes.

Kaufbereitschaft

• purchase_readiness.status — direct_cart_possible (einfaches vorrätiges Produkt, checkout_url direkt verwenden) oder variant_selection_required (variables Produkt, Nutzer muss zuerst eine Variante auswählen).
• purchase_readiness.blocking_fields[] — Attribute, die der Nutzer vor dem Checkout wählen muss (z.B. ["size"]).
• purchase_readiness.can_add_to_cart_directly — boolesche Abkürzung.

Varianten & Variationen

• variants[] — immer ein Array, nie null. Produktdetail: variable Produkte zeigen alle Variationen mit attributes, price, in_stock, availability_status, sku, barcodes; einfache Produkte zeigen einen einzigen Eintrag mit den eigenen Daten des Produkts. Listen- und Suchantworten: einfache Produkte behalten ihren einzelnen Eintrag, variable Produkte liefern aus Performance-Gründen ein leeres Array — /catalog/product/{id} abrufen für die vollständige Variantenliste.
• variations[] — Alias nur für variable Produkte (Abwärtskompatibilität).
• variation_id im Checkout-Session-Payload übergeben, wenn eine Sitzung für ein variables Produkt erstellt wird.
• availability_status — UCP-Standardwerte: in_stock, out_of_stock, backorder. Vorhanden sowohl beim Produktbestand als auch bei jeder Variante.
• list_price — ursprünglicher Listenpreis vor Rabatten (durchgestrichen). Vorhanden bei einfachen Produkten; null bei variablen (Preis variiert pro Variante).
• barcodes[] — branchenübliche Kennungen (EAN, GTIN, UPC), gelesen aus den WooCommerce-Produkt-Metadaten. Leeres Array, wenn vom Merchant nicht gesetzt.

Metadata

• metadata.purchase_readiness — dasselbe wie das übergeordnete purchase_readiness, hier für UCP-kompatible Agenten bereitgestellt, die metadata lesen.
• metadata.stock_confidence — Konfidenzniveau der Lagerbestandsdaten.
• metadata.bridge_version — Plugin-Version, die diese Antwort erzeugt hat.

Versandzonen

shipping.zones[] zeigt die vollständige WooCommerce-Versandkonfiguration: Zonenname, Länder-/Regionscodes, Methoden (free_shipping, flat_rate, local_pickup) mit Kosten und Schwellenwert für kostenlosen Versand. Einmal pro Anfrage berechnet und gecacht. Der maßgebliche Versandpreis ist immer der WooCommerce-Checkout.

Checkout

checkout_url — direkte Warenkorb-Zufügung für einfache vorrätige Produkte. Produktseite für variable Produkte, bei denen eine Variantenauswahl erforderlich ist.

Für Multi-Produkt-Abläufe die Checkout-Sitzungen weiter unten verwenden.

Versand & Coupons

Versand

Das Discovery-Dokument enthält merchant_shipping_policy — einen Snapshot der WooCommerce-Versandzonen, -methoden und Schwellenwerte für kostenlosen Versand. Jedes Produkt trägt zudem ein shipping-Feld mit Kontext auf Produktebene (Klasse, Gewicht, Berechtigung zum kostenlosen Versand beim aktuellen Preis). Der WooCommerce-Checkout ist die letzte Instanz für zielortspezifische Kosten.

Coupons

Jedes Produkt trägt active_coupons[] — aktive Coupons, die auf dieses Produkt oder diese Kategorie anwendbar sind. Ersetzen Sie price.current niemals durch einen coupon-angepassten Wert. Zeigen Sie den Katalogpreis; bieten Sie den Code als bedingte Ersparnis beim Checkout an.

Jeder Coupon-Eintrag enthält combinable_with_sale: "unknown — verify at checkout" und verification_required: true. Ein Coupon wird erst bestätigt, nachdem der WooCommerce-Warenkorb/-Checkout ihn akzeptiert und die Summen ändert. Coupons können mit Verkaufspreisen kombinierbar sein, aber nur der Checkout kann dies bestätigen.

// Korrekte Agentendarstellung
"Price is €89. Use code SAVE20 at checkout for 20% off (≈ €17 saving)."

// Falsch
"Price is €71.20"  ← Coupon niemals in den Preis einrechnen

Checkout-Sitzungen (optional)

Wenn vom Merchant aktiviert, können Agenten Checkout-Sitzungen mit einem oder mehreren Produkten erstellen. Jede Sitzung liefert zwei URLs für den Nutzer zurück — kein OAuth, keine PII, keine Zahlung auf Agentenseite.

Sitzungsantwort

• cart_url — ein Klick: fügt alle Artikel dem Warenkorb hinzu, landet auf der WooCommerce-Warenkorbseite. Nutzer prüft vor der Zahlung.
• checkout_url — ein Klick: fügt alle Artikel dem Warenkorb hinzu, leitet direkt zum Checkout weiter.
• subtotal — Summe aller Artikelgesamtbeträge zu Katalogpreisen. Enthält keinen Versand und keine Coupons.
• Die Sitzung läuft nach 30 Minuten ab. Statusübergänge: pending → cart_loaded.

// Mehrprodukt-Sitzung
POST /checkout/session
{
  "items": [
    { "product_id": 1326, "quantity": 1, "variation_id": 1477 },  // erforderlich für variable Produkte
    { "product_id": 1307, "quantity": 2 }
  ]
}
→ { "cart_url": "...", "checkout_url": "...", "subtotal": 651 }

Agentensignale

Alle vier Signale werden bei der Aktivierung automatisch injiziert — kein manueller Code erforderlich.

Föderierter Katalog

Ein optionales, offenes Discovery-Netzwerk. Der Bridge macht Ihren Katalog für Agenten lesbar, die bereits auf Ihrer Domain sind; der Föderierte Katalog macht ihn auffindbar für Agenten, die Ihren Shop noch nicht kennen. Opt-in, separater Dienst, jederzeit widerrufbar.

Zwei unterschiedliche Discovery-Pfade — leicht zu verwechseln, daher hier klar dargestellt:

So funktioniert es, Schritt für Schritt:

Der Widerruf ist symmetrisch: Häkchen bei der Zustimmung entfernen, und das Plugin signalisiert KaliCart Global die Abmeldung; Ihr Katalog wird geparkt und verlässt die föderierten Ergebnisse, während der direkte Agentenzugriff auf Ihren Shop aktiv bleibt.

Katalog-Gesundheits-Dashboard

Echtzeit-Qualitätsbericht des Katalogs über WP Admin → KaliCart.

• Quality score — 0–100 gewichteter Durchschnitt über alle Produkte basierend auf der Schwere der Probleme.
• Quality signals — Produkte mit hoher oder mittlerer Problemschwere (fehlende Beschreibung, Nullpreis, keine Kategorie). Nichts wird blockiert: Diese Produkte werden weiterhin vollständig an Agenten ausgeliefert, aber die Probleme werden als deklarierte Qualitäts-Flags mitgeführt und senken den Score. Jeder Eintrag verlinkt direkt zum WP-Produktbearbeitungsbildschirm.
• Soft alerts — fehlende Bilder und fehlende SKUs erscheinen als Vorschläge mit niedriger Priorität und zählen nicht als Quality Signals.
• Suggestions — priorisierte Liste von Katalogverbesserungen mit betroffener Produktanzahl.