FreeScout-Integration

Die FreeScout-Integration verbindet euer Ticketsystem mit Flowkom, sodass Kunden- und Bestelldaten direkt in der FreeScout-Ticket-Sidebar angezeigt werden. Kein Wechsel mehr zwischen zwei Systemen — alle relevanten Informationen sind sofort im Ticket sichtbar.

Was die Integration kann

• Automatische Kundenerkennung: FreeScout matcht die Absender-E-Mail gegen Flowkom-Kundendaten
• Bestellnummer-Erkennung: Erkennt automatisch Bestellnummern im Ticket-Betreff (Amazon, eBay, Shopify, etc.)
• Bestelldetails anzeigen: Status, Positionen, Tracking-Nummern direkt in der Sidebar
• Deeplinks: Mit einem Klick die Bestellung in Flowkom oder auf dem Marktplatz öffnen
• Live-Daten: Daten werden bei jedem Ticket-Wechsel frisch geladen — immer aktuell

Die Integration ist read-only — FreeScout liest Daten aus Flowkom, kann aber nichts ändern.

Voraussetzungen

• Flowkom-Account mit Admin-Rechten
• FreeScout (Self-Hosted) mit Zugriff auf das Dateisystem
• Netzwerkverbindung zwischen FreeScout-Server und Flowkom (HTTPS)

So funktioniert es

Die Einrichtung besteht aus zwei Teilen:

1. Flowkom-Seite: FreeScout-Integration anlegen und API-Key generieren
2. FreeScout-Seite: Modul installieren und mit dem API-Key verbinden

Teil 1: Flowkom einrichten

Schritt 1: Integration anlegen

1. Öffne Einstellungen → Integrationen in Flowkom
2. Klicke auf Integration hinzufügen
3. Wähle FreeScout aus der Liste
4. Vergib einen Namen (z.B. “FreeScout Ticketsystem”)

Schritt 2: API-Key generieren

1. Nach dem Anlegen der Integration siehst du das Feld API Key
2. Generiere einen neuen API-Key oder gib einen eigenen ein
3. Kopiere den API-Key — du brauchst ihn gleich in FreeScout

Wichtig: Der API-Key wird verschlüsselt gespeichert (AES-256-GCM). Bewahre ihn sicher auf — du kannst ihn später nicht mehr einsehen, nur neu generieren.

Schritt 3: Flowkom-URL notieren

Notiere die URL eurer Flowkom-Instanz, z.B.:

• https://app.flowkom.de (gehostet)
• https://wms.euer-unternehmen.de (self-hosted)

Teil 2: FreeScout-Modul installieren

Schritt 1: Modul herunterladen

Lade das Modul von GitHub herunter:

cd /pfad/zu/freescout/Modules/
git clone https://github.com/erorplex/flowkom-freescout-connector.git FlowkomConnector

Oder als ZIP herunterladen und nach Modules/FlowkomConnector/ entpacken.

Wichtig: Der Ordner muss exakt FlowkomConnector heißen (Groß-/Kleinschreibung beachten).

Schritt 2: Assets publizieren

cd /pfad/zu/freescout/
php artisan module:publish FlowkomConnector

Dieser Befehl kopiert CSS und JavaScript in den öffentlichen Bereich.

Schritt 3: Modul aktivieren

1. Öffne FreeScout Admin → Verwalten → Module
2. Suche FlowkomConnector in der Liste
3. Klicke auf Aktivieren

Schritt 4: Verbindung konfigurieren

1. Gehe zu Verwalten → Einstellungen
2. Klicke auf den neuen Abschnitt Flowkom in der linken Navigation
3. Trage ein:
   • Flowkom API-URL: Die URL aus Teil 1, Schritt 3 (z.B. https://app.flowkom.de)
   • API-Key: Der API-Key aus Teil 1, Schritt 2
4. Klicke auf Verbindung testen
5. Bei Erfolg: Speichern

Sidebar im Einsatz

Nach der Einrichtung erscheint der Flowkom-Block automatisch in der rechten Sidebar jedes Tickets — unterhalb der Kunden-E-Mail-Adresse.

Was angezeigt wird

Kundendaten:

• Name, Adresse, Telefonnummer
• Gesamtanzahl der Bestellungen

Aktuelle Bestellung (hervorgehoben):

• Bestellnummer und Status (farbkodiert)
• Marktplatz und Bestelldatum
• Alle Positionen mit SKU
• Tracking-Nummer mit Carrier-Erkennung (DHL, UPS, DPD, Deutsche Post, GLS, Hermes) — klickbar zur Sendungsverfolgung
• Flowkom-Button — öffnet den Kundenauftrag direkt in Flowkom
• Marktplatz-Button — öffnet die Bestellung auf Amazon, eBay, Shopify oder Kaufland

Weitere Bestellungen (aufklappbar):

• Die letzten 10 Bestellungen des Kunden in kompakter Ansicht

Automatische Zuordnung

Die Zuordnung nutzt mehrere Strategien in einer festen Reihenfolge. Sobald ein Treffer gefunden wird, stoppt die Suche.

Schritt 1: E-Mail-Lookup (Primär)

Die Absender-E-Mail des Tickets wird gegen die Kunden-E-Mails in Flowkom abgeglichen. Funktioniert zuverlässig bei:

• Shopify-Bestellungen — Kunden schreiben mit ihrer echten E-Mail
• Amazon-Bestellungen — die anonymisierte @marketplace.amazon.de-Adresse wird beim Import in Flowkom gespeichert und ist immer gleich pro Käufer

Warum funktioniert das bei eBay nicht? eBay generiert für jede Transaktion und Konversation eine andere zufällige Proxy-E-Mail (z.B. sebakn_gsi6156ncfg@members.ebay.de). Die E-Mail auf der Bestellung in Flowkom ist eine andere als die E-Mail auf dem Ticket in FreeScout — ein Abgleich ist daher nicht möglich.

Schritt 2: eBay-Username-Lookup (eBay-Fallback)

Wenn der E-Mail-Lookup fehlschlägt, prüft das Widget ob es sich um ein eBay-Ticket handelt. Dazu wird der Kundenname in FreeScout ausgewertet:

• Erkennt das Muster “eBay - {username}” (z.B. “eBay - erorplex” → Username erorplex)
• Sucht in Flowkom nach Bestellungen, deren Import-Notizen den Eintrag Buyer's eBay Username: erorplex enthalten
• Über die gefundene Bestellung wird der zugehörige Kunde aufgelöst

Voraussetzung: Die eBay-Bestellungen müssen über Magnalister importiert worden sein — nur dann sind die Import-Notizen mit dem eBay-Benutzernamen vorhanden.

Schritt 3: Bestellnummer aus Betreff (Zusätzlich)

Unabhängig von der Kundenerkennung wird der Ticket-Betreff nach Bestellnummern durchsucht. Die erkannte Nummer wird als zusätzlicher Suchparameter mitgesendet und dient zur Hervorhebung der relevanten Bestellung.

Unterstützte Bestellnummer-Formate:

Zusammenfassung Matching-Priorität

Datenaktualisierung

• Automatisch: Bei jedem Ticket-Wechsel (Klick, Pfeile ◀ ▶, Seite laden)
• Manuell: Refresh-Button (↻) im Flowkom-Header für Updates ohne Seitenwechsel

Fehlerbehebung

”Kein Kunde in Flowkom gefunden”

Ursache: Keiner der Matching-Schritte hat einen Treffer ergeben.

Lösungen je nach Marktplatz:

”Flowkom nicht erreichbar”

Ursache: Netzwerkproblem zwischen FreeScout und Flowkom.

Lösungen:

• Prüfe ob die Flowkom-URL korrekt ist (Einstellungen → Flowkom)
• Firewall/Netzwerk: FreeScout-Server muss HTTPS-Zugriff auf Flowkom haben
• Flowkom-Server läuft? Prüfe unter der konfigurierten URL
• Klicke “Erneut versuchen” in der Sidebar

Sidebar erscheint nicht

Mögliche Ursachen:

• Modul nicht aktiviert → Verwalten → Module → FlowkomConnector aktivieren
• API-URL oder API-Key leer → Einstellungen → Flowkom prüfen
• Assets nicht publiziert → php artisan module:publish FlowkomConnector ausführen
• Browser-Cache → Hard-Refresh (Ctrl+Shift+R)

Daten sind veraltet

Die Sidebar lädt Daten live bei jedem Ticket-Wechsel. Falls trotzdem veraltete Daten angezeigt werden:

• Klicke den Refresh-Button (↻) im Flowkom-Header
• Prüfe ob die Änderung in Flowkom selbst sichtbar ist

Sicherheit

Modul aktualisieren

Wenn eine neue Version des FreeScout-Moduls verfügbar ist:

cd /pfad/zu/freescout/Modules/FlowkomConnector/
git pull
cd /pfad/zu/freescout/
php artisan module:publish FlowkomConnector

Anschließend Browser-Cache leeren.