weclapp API Guide: REST, Webhooks & AI-Produktberater bauen

Warum die weclapp API mehr ist als eine Datenschnittstelle

In der modernen ERP-Landschaft ist die weclapp API das zentrale Nervensystem für automatisierte Geschäftsprozesse. Während viele Integrationspartner und Middleware-Lösungen wie Synesty oder Make hervorragende Arbeit leisten, um Daten von A nach B zu schieben, wird ein entscheidender Aspekt oft übersehen: Die intelligente Nutzung von Echtzeitdaten.

Die meisten Dokumentationen und Tutorials konzentrieren sich auf das reine Syncen – Bestellungen importieren, Lagerbestände abgleichen. Das ist wichtig, aber es ist im Grunde dumme Automatisierung. In diesem umfassenden Guide gehen wir einen Schritt weiter. Wir betrachten die weclapp REST API nicht nur als Werkzeug zur Datenübertragung, sondern als Fundament für AI-gestützte Anwendungen, die echten Mehrwert für deine Kunden schaffen.

Stell dir vor, dein KI-gestützter Chatbot könnte nicht nur FAQ beantworten, sondern wüsste genau:

• Welches Produkt der Kunde letzte Woche gekauft hat (via /party und /salesOrder)
• Ob das Zubehörteil, nach dem gefragt wird, kompatibel und tatsächlich auf Lager ist (via /article)
• Und könnte direkt ein Angebot erstellen (via /quotation)

Diese Vision ist keine Zukunftsmusik mehr. Mit der richtigen weclapp Integration und modernen AI-Technologien wie Large Language Models (LLMs) lässt sich genau das umsetzen. Dieser Artikel führt dich von den technischen Grundlagen der weclapp Schnittstelle bis hin zur Architektur eines AI-Produktberaters. Wir schließen die Lücken, die die offizielle weclapp API Dokumentation offen lässt, insbesondere im Hinblick auf moderne Python-Workflows und intelligente Datenabfragen.

Erste Schritte mit der weclapp REST API

Bevor wir komplexe AI-Modelle füttern können, müssen wir die Grundlagen beherrschen. Die weclapp API ist eine RESTful API, die JSON als primäres Datenformat nutzt. Das macht sie kompatibel mit praktisch jeder modernen Programmiersprache und jedem Framework.

Authentifizierung und Sicherheit richtig umsetzen

Der Zugriff auf die API erfolgt über einen API-Token. Dies ist der Standardweg und deutlich sicherer als die Verwendung von Benutzername und Passwort, die bei älteren APIs noch üblich waren.

So erhältst du deinen Token:

1. Logge dich in deine weclapp-Instanz ein
2. Gehe zu Meine Einstellungen > API
3. Kopiere den API-Token und bewahre ihn sicher auf

Der Header für jeden Request:

Jeder Request muss diesen Token im Header AuthenticationToken mitführen. Ein häufiger Fehler ist der Versuch, OAuth-Flows zu nutzen, wo ein einfacher Token-Header ausreicht, oder den Token als Query-Parameter zu übergeben – was laut weclapp Dokumentation ein Sicherheitsrisiko darstellt.

Ein korrekter HTTP-Request sieht so aus:

```http GET /webapp/api/v2/article HTTP/1.1 Host: dein-tenant.weclapp.com AuthenticationToken: 73828347-xxxx-xxxx-xxxx-xxxxxxxxxxxx Accept: application/json ```

Base URL und Versionierung: v1 vs. v2 im Detail

Hier tappen viele Entwickler in die erste Falle. Es existieren zwei Versionen der API, und die Unterschiede sind signifikant für dein Projekt.

Wichtiger Hinweis zur Migration: In v2 wurden diverse Endpunkte zusammengefasst oder umbenannt. Der wichtigste Unterschied ist das Verschwinden der separaten Endpunkte /customer, /contact, /lead und /supplier. Diese sind nun alle unter dem mächtigen Endpunkt /party zusammengefasst, wie die offizielle weclapp Dokumentation bestätigt.

Die korrekte Base URL lautet: `https://<DEIN-TENANT>.weclapp.com/webapp/api/v2`

Die Instance ID Falle bei Multi-Tenant-Apps

Einige Integrationen, besonders bei Multi-Tenant-Apps, stolpern über die dynamische Natur der Tenant-URL. Wenn du eine App für Dritte baust – etwa eine Shopware ERP Integration – musst du sicherstellen, dass die Tenant-Subdomain konfigurierbar ist.

Es gibt keine zentrale API, die alle meine weclapp Instanzen auflistet. Der Nutzer muss seine Instanz-URL kennen und diese in deiner Anwendung hinterlegen. Das ist ein wichtiger Punkt für dein Onboarding-Design.

Schlüssel-Endpunkte für Produktlogik und Vertrieb

Für unser Ziel – einen intelligenten Produktberater – benötigen wir nicht alle hunderte Endpunkte. Wir konzentrieren uns auf die strategisch wichtigen Ressourcen, die Kontext für eine AI liefern und echte Beratungslogik ermöglichen.

GET /article: Das komplette Produktwissen abrufen

Der /article Endpunkt ist das Herzstück jeder KI-Produktberatung. Für eine AI-Beratung sind hier nicht nur Name und Preis relevant, sondern vor allem technische Daten und Beschreibungen, die dem Sprachmodell Kontext liefern.

Wichtige Felder für den AI-Kontext:

• articleNumber: Die eindeutige SKU für die Kommunikation mit Kunden und Systemen
• description & descriptionLong: Hier steckt das Wissen, das ein LLM benötigt, um Fragen präzise zu beantworten
• customAttributes: Oft speichern Unternehmen hier technische Spezifikationen wie Kompatibilität oder Material. In v2 werden diese konsistenter behandelt
• salesPrice: Der Verkaufspreis für Angebotskalkulationen
• manufacturerId: Wichtig für Hersteller-spezifische Abfragen

Cheatsheet: Kritische Felder für E-Commerce-Integrationen

Entwickler lieben copy-pasteable Referenzen. Hier sind die exakten technischen Feldnamen, die du für E-Commerce-Logik am häufigsten benötigst:

GET /party: Kundenkontext verstehen (ehemals /customer)

Wie bereits erwähnt, nutzt du in v2 den Endpunkt /party. Um nur Kunden zu finden, musst du filtern. Das ist zunächst ungewohnt, bietet aber mehr Flexibilität für komplexe Abfragen.

Beispiel-Filter für Organisationen: `GET /party?partyType-eq=ORGANIZATION`

Beispiel-Filter für Einzelpersonen: `GET /party?partyType-eq=PERSON`

Warum ist das für AI wichtig? Eine intelligente Integration – etwa für KI im E-Commerce – schaut sich die Bestellhistorie an. Wenn ein Kunde fragt: Habt ihr Zubehör für meine Maschine?, muss die AI wissen, welche Maschine der Kunde vor 6 Monaten gekauft hat. Diese Verknüpfung zwischen Party und salesOrder ist der Schlüssel zur Personalisierung.

GET /quotation und POST /salesOrder für Conversions

Das Ziel jeder Beratung ist letztendlich der Verkauf. Die weclapp API bietet dir die Tools, um diesen Prozess zu automatisieren und so deinen KI-gestützten Vertrieb auf das nächste Level zu heben.

• GET /quotation: Um bestehende Angebote zu prüfen und Duplikate zu vermeiden
• POST /salesOrder: Um aus der Beratung direkt einen Auftragsentwurf zu generieren
• POST /quotation: Um nach einer Produktempfehlung automatisch ein Angebot zu erstellen

weclapp Webhooks: Das ERP zum Echtzeit-System machen

Polling – das ständige Abfragen der API mit Gibt es was Neues? – ist ineffizient und führt schnell in Rate Limits. weclapp Webhooks sind die elegante Lösung für Echtzeit-Integrationen.

Warum Polling der Feind der Performance ist

Wenn du alle 5 Minuten alle Artikel abrufst, um Bestandsänderungen zu finden, belastest du sowohl deinen Server als auch die weclapp-Instanz unnötig. Bei 10.000 Artikeln und 12 Abfragen pro Stunde sind das 120.000 API-Calls am Tag – für Informationen, die sich vielleicht nur bei 50 Artikeln geändert haben.

Webhooks drehen das Prinzip um: weclapp informiert deine Anwendung aktiv, sobald ein Ereignis eintritt. Das spart Ressourcen und ermöglicht echte Echtzeit-Reaktionen.

Webhooks in weclapp einrichten: Schritt für Schritt

Der Prozess ist in der weclapp Knowledge Base beschrieben, aber hier ist die Kurzfassung für Entwickler, die schnell starten wollen:

1. Gehe zu Einstellungen > Integration > Webhooks in deiner weclapp-Instanz
2. Erstelle einen neuen Webhook mit dem Plus-Button
3. Wähle das Event, auf das du reagieren willst (z.B. article.updated, salesOrder.created, party.created)
4. Hinterlege deine Callback URL – das ist die API deines Systems, die die Daten empfängt
5. Aktiviere den Webhook und teste ihn mit einem manuellen Trigger

Use Case: Der proaktive AI-Berater mit Webhooks

Stell dir folgendes Szenario vor, das zeigt, wie du Conversational AI mit weclapp-Daten verbindest:

Dies ist mit reinen Connector-Tools oft schwer abzubilden, da hier echte Geschäftslogik benötigt wird. Die Kombination aus weclapp Webhooks und einer AI-Schicht schafft einen massiven Wettbewerbsvorteil.

Fortgeschrittene Integration: AI-Produktberater bauen

Hier verlassen wir die Standard-Pfade der weclapp Integration und schaffen echten Mehrwert. Wir bauen konzeptionell und mit Code-Beispielen eine Brücke zwischen weclapp und einem LLM wie GPT-4.

Das Problem statischer Chatbots verstehen

Herkömmliche Chatbots greifen auf statische FAQs zu. Sie werden einmal trainiert und wissen danach nichts mehr von der echten Welt. Das führt zu frustrierenden Kundenerlebnissen:

• Der Bot empfiehlt ein Produkt, das seit Wochen ausverkauft ist
• Er kennt keine individuellen Kundenkonditionen oder Rabatte
• Er kann keine personalisierten Empfehlungen basierend auf früheren Käufen geben
• Er verlinkt nur auf generische Produktseiten statt konkret zu helfen

Für echten Shopware Kundensupport – oder jede andere E-Commerce-Plattform – reicht das nicht aus. Kunden erwarten heute mehr.

Die Lösung: RAG mit weclapp-Daten

RAG steht für Retrieval-Augmented Generation. Das Konzept ist simpel: Statt das Sprachmodell mit veralteten Daten zu trainieren, geben wir ihm bei jeder Anfrage den aktuellen Kontext aus der weclapp API mit. So entsteht eine KI-gestützte Produktberatung, die immer up-to-date ist.

Der komplette Datenfluss einer AI-Consultation

Hier ist der detaillierte Ablauf, wenn ein Kunde eine Frage stellt:

1. User Query: Welches Netzteil brauche ich für den Drucker, den ich letztes Jahr gekauft habe?
2. AI Analyse: Extrahiert Intent (Zubehörsuche) und Entitäten (Drucker, letztes Jahr)
3. API Lookup Schritt 1: Suche via /party und /salesOrder nach den Käufen des Users → Ergebnis: Drucker Modell X500
4. API Lookup Schritt 2: Suche via /article nach Netzteil mit Filter auf Kompatibilität zu X500 (via Tags oder customAttributes)
5. API Lookup Schritt 3: Prüfen des availableStock für das gefundene Netzteil
6. AI Antwort: Für deinen Drucker Modell X500 benötigst du das Netzteil NT-500. Wir haben davon noch 3 Stück auf Lager. Soll ich es für dich reservieren?

Code-Beispiel: Semantische Suche mit Python

Dieses Beispiel zeigt, wie du mit Python und der requests-Library Daten für den AI-Kontext holst. Wir nutzen modernes Python mit Type Hinting und f-strings – etwas, das in den PHP-lastigen Beispielen der Konkurrenz fehlt und für Shopware API Automatisierung und ähnliche Projekte essentiell ist.

```python import requests import json from typing import Optional, List, Dict # Konfiguration API_URL = "https://dein-tenant.weclapp.com/webapp/api/v2" API_TOKEN = "DEIN_API_TOKEN" HEADERS = { "AuthenticationToken": API_TOKEN, "Accept": "application/json" } def get_product_context(query_term: str, max_results: int = 10) -> str: """ Sucht Artikel basierend auf einem Suchbegriff und gibt relevante Daten für die AI zurück. Args: query_term: Der Suchbegriff vom User max_results: Maximale Anzahl Ergebnisse Returns: JSON-String mit Produktkontext für das LLM """ # weclapp Filter-Syntax: property-operator=value # ilike = case insensitive like endpoint = f"{API_URL}/article" params = { "name-ilike": f"%{query_term}%", "active-eq": "true", "pageSize": max_results } try: response = requests.get( endpoint, headers=HEADERS, params=params ) response.raise_for_status() articles = response.json().get('result', []) # Nur relevante Felder für AI extrahieren (Token sparen!) context_data = [] for art in articles: info = { "name": art.get("name"), "art_nr": art.get("articleNumber"), "desc": art.get("description", "Keine Beschreibung"), "desc_long": art.get("descriptionLong", ""), "price": art.get("salesPrice"), "stock": art.get("availableStock", 0), "attributes": art.get("customAttributes", []) } context_data.append(info) return json.dumps(context_data, ensure_ascii=False, indent=2) except requests.exceptions.HTTPError as err: if err.response.status_code == 429: return json.dumps({"error": "Rate Limit erreicht. Bitte warten."}) return json.dumps({"error": f"API Fehler: {err}"}) def get_customer_history(customer_id: str) -> Optional[List[Dict]]: """ Holt die Bestellhistorie eines Kunden für Personalisierung. """ endpoint = f"{API_URL}/salesOrder" params = { "customerId-eq": customer_id, "orderBy": "-createdDate", # Neueste zuerst "pageSize": 20 } try: response = requests.get(endpoint, headers=HEADERS, params=params) response.raise_for_status() return response.json().get('result', []) except: return None # Beispielaufruf if __name__ == "__main__": ai_context = get_product_context("Netzteil") print(f"Kontext für LLM:\n{ai_context}") ```

Vergleich: Statischer Bot vs. API-Connected AI

Die folgende Tabelle verdeutlicht den fundamentalen Unterschied zwischen herkömmlichen Chatbots und einer weclapp-integrierten AI-Lösung, wie sie auch für KI Beratung im Guided Selling relevant ist:

Häufige Fallstricke und Best Practices

Bei der Entwicklung mit der weclapp API gibt es einige Hürden, die in der Standard-Dokumentation oft nur am Rande erwähnt werden. Hier erfährst du, wie du sie meisterst.

Rate Limiting: HTTP 429 richtig handhaben

weclapp schützt seine Cloud-Infrastruktur durch Rate Limits. Wenn du zu viele Anfragen in kurzer Zeit sendest, erhältst du den HTTP Status Code 429 Too Many Requests. Laut tyk.io ist das ein Standard-Mechanismus moderner APIs, den du unbedingt in deiner Anwendung berücksichtigen musst.

Strategie 1: Exponential Backoff implementieren

Wenn ein 429 kommt, warte 1 Sekunde, dann 2, dann 4, bevor du es erneut versuchst. Hier ein Python-Beispiel:

```python import time import requests def request_with_backoff(url: str, headers: dict, max_retries: int = 5): for attempt in range(max_retries): response = requests.get(url, headers=headers) if response.status_code == 429: wait_time = 2 ** attempt # 1, 2, 4, 8, 16 Sekunden print(f"Rate Limit. Warte {wait_time}s...") time.sleep(wait_time) continue return response raise Exception("Max Retries erreicht") ```

Strategie 2: Intelligentes Caching einsetzen

Frage Stammdaten wie Artikelkategorien, Steuersätze oder Zahlungsbedingungen nicht bei jedem Request ab. Cache diese lokal und aktualisiere sie nur einmal täglich oder via Webhook bei Änderungen.

Datenhygiene ist AI-Hygiene

Eine AI ist nur so schlau wie die Daten, die sie liest. Wenn deine Artikelbeschreibungen in weclapp voller Abkürzungen und interner Codes sind (Kbl. 5m schw. f. ext. Ger.), wird die AI Schwierigkeiten haben, sinnvolle Antworten zu generieren.

Filter-Syntax korrekt anwenden

Die weclapp API nutzt eine eigene Syntax für Filter, nicht den OData-Standard. Das ist ein häufiger Stolperstein für Entwickler, die von anderen APIs kommen.

Performance-Tipp: Filtere so früh wie möglich auf der API-Seite. Lade nicht 1000 Artikel und filtere dann im Code, sondern lass die weclapp-Datenbank die Arbeit machen. Das spart Bandbreite und Verarbeitungszeit.

Erweiterte Architektur für High-Traffic-Szenarien

Caching-Strategie für Beratungs-Bots

Wenn dein Shopware KI Guide oder Berater-Bot in einem Shop mit hohem Traffic läuft, brauchst du eine durchdachte Caching-Strategie:

• Redis für Produktdaten: Cache Artikelinformationen für 15-60 Minuten. Bei Bestandsänderungen invalidiert der Webhook den Cache.
• Session-basierter Kundenkontext: Speichere die Kundenhistorie für die Dauer einer Beratungssession, nicht bei jedem Request neu laden.
• Precomputed Embeddings: Für semantische Suche kannst du Artikel-Embeddings vorberechnen und in einer Vektordatenbank speichern, statt sie bei jeder Anfrage neu zu generieren.

Fehlerbehandlung für robuste Integrationen

Eine produktionsreife Integration muss mit verschiedenen Fehlerszenarien umgehen können. Das ist besonders wichtig für Shopware CRM Integration und ähnliche unternehmenskritische Systeme.

• Timeout-Handling: Setze angemessene Timeouts (5-10 Sekunden) und implementiere Fallback-Antworten
• Graceful Degradation: Wenn die weclapp API nicht erreichbar ist, kann der Bot trotzdem mit gecachten Daten oder generischen Antworten helfen
• Logging und Monitoring: Protokolliere alle API-Calls mit Latenz und Statuscode für Debugging und Optimierung
• Circuit Breaker Pattern: Nach mehreren Fehlern temporär auf Fallback umschalten, um das System zu entlasten

FAQ zur weclapp API

Hier beantworten wir Fragen, die Entwickler und Projektmanager häufig stellen – optimiert für die Suche nach weclapp API Dokumentation und verwandten Begriffen.

Fazit: Von der Datenschnittstelle zur AI-Plattform

Die weclapp API ist weit mehr als ein Werkzeug für den nächtlichen Datenabgleich. Sie ist der Schlüssel zu modernen, AI-getriebenen Kundenerlebnissen. Indem du von der reinen Synchronisation zur intelligenten Abfrage – zur echten Consultation – übergehst, hebst du dein ERP-System auf die nächste Stufe.

Die wichtigsten Takeaways aus diesem Guide:

• Nutze v2: Die aktuelle API-Version mit /party-Endpunkt und strikter JSON-Validierung ist der Standard für neue Projekte
• Webhooks statt Polling: Reagiere in Echtzeit auf ERP-Events, ohne Rate Limits zu riskieren
• RAG für AI-Beratung: Gib deinem Sprachmodell aktuellen Kontext aus weclapp, statt es mit veralteten Daten zu trainieren
• Datenhygiene: Saubere Produktbeschreibungen sind die Grundlage für erfolgreiche AI-Integration
• Caching und Fehlerbehandlung: Baue robuste Integrationen, die auch unter Last funktionieren

Starte mit der sauberen Authentifizierung in v2, nutze Webhooks für Echtzeit-Reaktivität und experimentiere mit Python-Skripten, um deinem ERP-System das Sprechen beizubringen. Die Zukunft der Unternehmenssoftware ist nicht statisch – sie ist integriert, intelligent und kundenorientiert.

Wenn du tiefer in das Thema intelligente E-Commerce-Lösungen einsteigen möchtest, findest du in unserem Guide zu Intercom Shopify Integration weitere Anregungen für nahtlose Kundenkommunikation.