​

Lightspeed K-Series

Verwende die Lightspeed-K-Series-Integration, um dein Lightspeed-POS mit Mathership zu verbinden. Die Integration importiert Lightspeed-Standorte und POS-Artikel, ermöglicht dir die Zuordnung von POS-Artikeln zu Zutaten oder Rezepten und erstellt Lagerbuchungen aus POS-Verkäufen.

​

Was die Integration kann

Die Integration kann:

• Lightspeed über OAuth verbinden
• Lightspeed Access- und Refresh-Tokens sicher speichern
• Lightspeed-Tokens automatisch erneuern
• Eine bestehende Verbindung bei Bedarf erneut autorisieren
• Lightspeed-Geschäftsstandorte synchronisieren
• Lightspeed-POS-Artikel synchronisieren
• Lightspeed-Standorte mit Mathership-Lagereinheiten verknüpfen
• Lightspeed-Artikel Zutaten oder Rezepten zuordnen
• Eine historische 90-Tage-Migration ausführen
• Automatische tägliche Übertragungen ausführen
• Manuelle Ein-Tages-Übertragungen ausführen
• Lagerbuchungen aus POS-Verkäufen erstellen
• Übertragungsprotokolle für Prüfung und Fehlerbehebung speichern

​

Was die Integration macht

Wenn eine Lightspeed-Übertragung läuft, führt Mathership Folgendes aus:

1. Lightspeed-Verkäufe für einen Standort und ein Datum abrufen
2. Die rohen Lightspeed-Verkäufe und Verkaufspositionen speichern
3. Die Namen und Mengen der verkauften POS-Artikel auslesen
4. Passende POS-Zuordnungen in Mathership finden
5. Zugeordnete Zutaten direkt abbuchen
6. Zugeordnete Rezepte in Rezeptzutaten auflösen
7. Lagermengen berechnen
8. Lagerbuchungen erstellen
9. Erstellte Lagerbuchungen mit den Lightspeed-Verkaufspositionen verknüpfen
10. Ein Übertragungsprotokoll mit Statistiken, Fehlern, übersprungenen Positionen und nicht zugeordneten Artikeln speichern

​

Was die Integration nicht macht

Die Lightspeed-Integration macht nicht Folgendes:

• Zutaten automatisch erstellen
• Rezepte automatisch erstellen
• Artikelzuordnungen automatisch erraten
• Lagerbestand für nicht zugeordnete Artikel abbuchen
• Lagerbestände optimieren
• Lightspeed-Verkaufsdaten ändern
• Lagerbestände zurück an Lightspeed übertragen
• Bestellungen erstellen
• Lieferrouten berechnen

​

Empfohlene Einrichtungsreihenfolge

Verwende diese Reihenfolge für eine saubere Lightspeed-Einrichtung:

​

Bevor du beginnst

Bereite vor der Verbindung mit Lightspeed diese Mathership-Lagerobjekte vor.

​

Lagereinheiten

Jeder Lightspeed-Standort muss mit einer Mathership-Lagereinheit verknüpft werden. Die Lagereinheit definiert, wo der Bestand abgebucht werden soll.

​

Zutaten

Zutaten sind die Lagerobjekte, die abgebucht werden.

​

Rezepte

Rezepte werden verwendet, wenn ein verkaufter POS-Artikel aus mehreren Zutaten besteht. Wenn der Lightspeed-Artikel verkauft wird, bucht Mathership die Zutaten innerhalb des Rezepts ab.

​

Lightspeed verbinden

Mathership speichert Access- und Refresh-Tokens sicher. Tokens werden automatisch erneuert, wenn sie ablaufen.

​

Erforderliche Verbindungsdaten

Wenn die Integration erstellt wird, benötigt Mathership:

​

Was während der Verbindung passiert

Während der Verbindung führt Mathership Folgendes aus:

1. Den OAuth-Autorisierungscode empfangen
2. Den Code an den Lightspeed-Token-Endpunkt senden
3. Ein Access-Token und ein Refresh-Token empfangen
4. Die Tokens vor dem Speichern verschlüsseln
5. Die Integration erstellen und als aktiv markieren

​

Token-Verarbeitung

Token-Laufzeiten werden aus der Lightspeed-Token-Antwort gelesen. Sie sind nicht fest im Code hinterlegt.

​

Verbindungsfehler

​

Häufige Verbindungsprobleme

​

Lightspeed erneut autorisieren

Verwende die erneute Autorisierung, wenn eine bestehende Lightspeed-Verbindung eine neue Autorisierung benötigt, ohne deine Einrichtung zu verlieren. Dies ist erforderlich, wenn:

• Das Refresh-Token abgelaufen ist
• Lightspeed das Token ungültig gemacht hat
• Die Token-Erneuerung wiederholt fehlgeschlagen ist
• Der Integrationsstatus auf getrennt geändert wurde

Die erneute Autorisierung erhält:

• Synchronisierte Standorte und Lagereinheiten-Verknüpfungen
• Synchronisierte Artikel und Artikelzuordnungen
• Übertragungshistorie und Migrationshistorie
• Bestehende Protokolle

​

Verhalten bei Token-Erneuerung

Wenn ein Lightspeed-API-Aufruf 401 zurückgibt, versucht Mathership, das Token automatisch zu erneuern, und wiederholt die Anfrage einmal.

​

Standorte synchronisieren

Die Standort-Synchronisierung ruft Geschäftsstandorte aus Lightspeed ab und überführt sie in eine Mathership-Standortliste.

​

Spalten der Standortliste

Filtere die Liste über die Toolbar nach Aktivierungsstatus, Auto-issue-Status oder Lagereinheit.

​

Gespeicherte Standortdaten

​

Standorte, die aus Lightspeed verschwinden

Wenn ein Standort nicht mehr in der Lightspeed-API erscheint, löscht Mathership ihn bei der Synchronisierung nicht automatisch. Dies verhindert den versehentlichen Verlust von:

• Lagereinheiten-Verknüpfungen
• Zuordnungskontext
• Übertragungshistorie
• Migrationshistorie

​

Häufige Probleme bei der Standort-Synchronisierung

​

Lagereinheit verknüpfen

Jeder Lightspeed-Standort muss mit einer Mathership-Lagereinheit verknüpft werden, bevor Übertragungen Lagerbestand abbuchen können. Derselbe verkaufte Artikel kann je nach Standort Bestand aus verschiedenen Lagereinheiten abbuchen. Du kannst eine Lagereinheiten-Verknüpfung jederzeit entfernen. Wenn ein Standort während einer Migration entknüpft wird, kann die Migration abgebrochen werden.

​

Lagereinheit entknüpfen

Du kannst die Lagereinheiten-Verknüpfung wieder entfernen. Tue dies nur, wenn der Standort keinen Bestand mehr aus dieser Lagereinheit abbuchen soll. Wenn ein Standort während einer Migration entknüpft wird, kann die Migration abgebrochen werden.

​

Lagereinheiten-Fehler

​

Artikel synchronisieren

Mathership ruft Artikel für jeden synchronisierten Lightspeed-Standort ab und dedupliziert sie standortübergreifend anhand der Lightspeed-Artikel-ID.

​

Spalten der Artikelliste

Filtere die Artikelliste mit den Toolbar-Chips nach Zuordnungsstatus, Aktivstatus oder Standort.

​

Gespeicherte Artikeldaten

Mathership versucht, den Preis aus gängigen Lightspeed-Preisfeldern wie prices.amount, prices.value, prices.price, price und costPrice zu lesen. Wenn kein verwendbarer Preis gefunden wird, wird der Artikel ohne Preis gespeichert.

​

Artikelstatus

​

Häufige Probleme bei der Artikel-Synchronisierung

​

Lightspeed-Artikel zuordnen

Klicke auf eine beliebige Artikelzeile, um das Zuordnungs-Sheet zu öffnen. Jeder Lightspeed-Artikel muss zugeordnet werden, bevor er Lagerbewegungen erstellen kann. Du kannst einen Artikel zuordnen zu:

• Einer Zutat — die Zutat wird pro Verkauf direkt abgebucht
• Einem Rezept — das Rezept wird in seine Zutaten aufgelöst und alle Positionen werden abgebucht

​

Warum die Zuordnung erforderlich ist

Ohne Zuordnung kann Mathership den Verkauf speichern, aber nicht die korrekte Lagerabbuchung erstellen.

​

Zuordnungsbeispiele

Wenn ein Rezept verkauft wird, liest Mathership alle Rezeptpositionen, berücksichtigt Putzverluste/Trim-Prozentsätze, löst verschachtelte Unterrezepte auf und erstellt eine Lagerbuchung pro Zutat.

​

Zuordnungsmenge

Die Zuordnungsmenge steuert, wie viel Bestand pro verkauftem POS-Artikel abgebucht wird.

​

Zuordnungsfelder

​

Subtraktionszuordnung

Verwende is_subtraction vorsichtig für Sonderfälle wie Umkehrlogik, negative Verkäufe oder Korrekturen.

​

Eine Zuordnung aktualisieren oder löschen

Um eine Zuordnung zu aktualisieren, öffne den Artikel, wähle eine neue Zutat oder ein neues Rezept aus, passe die Menge an und speichere. Mathership ersetzt die bestehende Zuordnung. Um eine Zuordnung zu löschen, öffne den Artikel, entferne die Zuordnung und speichere. Der Artikel erstellt dann keine Lagerabbuchungen mehr.

​

Zuordnungsfehler

​

Standort aktivieren

Ein Lightspeed-Standort muss aktiviert werden, bevor Migration und reguläre Übertragungsverarbeitung laufen können. Stelle vor der Aktivierung sicher:

• Der Standort hat eine Lagereinheit
• Wichtige Lightspeed-Artikel sind zugeordnet
• Rezepte und Zutaten sind korrekt eingerichtet
• Du verstehst, welche Lagereinheit die Abbuchungen erhält

​

Standortdetailseite

Das Öffnen eines Standorts zeigt eine Live-Übersicht über Zustand, Aktivität und Konfiguration.

​

Zustandsindikatoren

Wenn einer der folgenden Punkte erkannt wird, erscheint oben auf der Seite ein Warnbanner:

• Keine Lagereinheit verknüpft
• Kürzliche Übertragungen sind fehlgeschlagen
• Kürzliche Übertragungen enthalten nicht zugeordnete Artikel
• Eine Migration läuft derzeit

​

Statistiken

​

Konfiguration

​

90-Tage-Migration

Wenn ein Standort aktiviert wird, erstellt Mathership eine historische 90-Tage-Migration, die vergangene Lightspeed-Verkäufe verarbeitet und Lagerbewegungen erstellt, sofern Zuordnungen vorhanden sind.

​

Datumsbereich der Migration

Der Standard-Migrationsbereich umfasst die letzten 90 abgeschlossenen Tage und endet gestern. Wenn für ein Datum bereits ein erfolgreiches Übertragungsprotokoll existiert, wird dieser Tag in der initialen Migration als übersprungen markiert.

​

Erstellung des Migrationsjobs

Wenn ein Migrationsjob erstellt wird, erstellt Mathership für jedes Datum im 90-Tage-Zeitraum einen Tagesstatus. Jeder Tag kann einen eigenen Status haben. Wenn für ein Datum bereits ein erfolgreiches Übertragungsprotokoll existiert, kann dieser Tag für die initiale Migration als übersprungen markiert werden.

​

Status von Migrationsjobs

​

Status von Migrationstagen

​

Fortschrittsfelder der Migration

​

Migrationsaktionen

​

Festhängende Migrationen wiederherstellen

Mathership kann festhängende Migrationsjobs zurücksetzen. Ein laufender Job gilt als festhängend, wenn er zu lange läuft. Bei der Wiederherstellung wird der Job zurück auf pending gesetzt, damit die Verarbeitung fortgesetzt werden kann.

​

Fehlgeschlagene Migrationstage erneut versuchen

Mathership kann fehlgeschlagene Migrationstage automatisch erneut versuchen. Wiederholungen sind durch die Anzahl der Versuche begrenzt. Wenn alle fehlgeschlagenen Tage später erfolgreich sind, wird der Migrationsjob als completed markiert. Migration erneut ausführen ist nützlich, wenn:

• Während der ersten Migration viele Artikel nicht zugeordnet waren
• Zutaten- oder Rezeptzuordnungen korrigiert wurden
• Lager- oder Rezepteinrichtung korrigiert wurde
• Fehlgeschlagene Tage erneut verarbeitet werden müssen

Mathership kann auch festhängende Migrationen zurücksetzen. Ein laufender Job, der zu lange als festhängend gilt, kann zurück auf pending gesetzt werden, damit die Verarbeitung fortgesetzt werden kann.

​

Migrationsfehler

​

Automatische Übertragung

Sobald ein Standort aktiviert ist, verarbeitet Mathership Lightspeed-Verkäufe automatisch täglich. Verwende den Schalter Auto issue im Konfigurationsbereich, um sie zu pausieren oder fortzusetzen. Pausiere die automatische Übertragung, wenn:

• Zuordnungen unvollständig sind oder korrigiert werden
• Eine Lagereinheiten-Verknüpfung falsch ist
• Du unerwartete Lagerbewegungen untersuchst
• Die Lightspeed-Autorisierung repariert werden muss
• Du automatische Abbuchungen vorübergehend verhindern möchtest

​

Manuelle Übertragung

Verwende die manuelle Übertragung, wenn du einen bestimmten Tag verarbeiten möchtest. Die manuelle Übertragung ist nützlich, um:

• Die Integration zu testen, bevor die automatische Übertragung aktiviert wird
• Einen Tag nach Zuordnungsänderungen erneut zu verarbeiten
• Lagerbestand nach einer fehlgeschlagenen Übertragung zu korrigieren
• Ein bestimmtes Lightspeed-Verkaufsdatum zu prüfen

​

Force-Refresh-Verhalten

Manuelle Übertragungen rufen standardmäßig frische Daten von Lightspeed ab. Wenn Force Refresh aktiv ist, führt Mathership Folgendes aus:

1. Frische Verkaufsdaten von Lightspeed abrufen
2. Zwischengespeicherte Lightspeed-Verkäufe und Verkaufspositionen aktualisieren
3. Bestehende Lagerbuchungen für dieselben Lightspeed-Verkaufspositionen und die aktuelle Lagereinheit löschen
4. Lagerbuchungen aus den neuesten Daten neu erstellen

Wenn Verkäufe bereits zwischengespeichert sind und Force Refresh nicht aktiv ist, verwendet Mathership die zwischengespeicherten Daten erneut. Positionen, die bereits auf die aktuelle Lagereinheit gebucht wurden, werden übersprungen, um doppelte Lagerabbuchungen zu vermeiden.

​

Idempotenz

Lightspeed-Übertragungen sind darauf ausgelegt, doppelte Lagerbuchungen zu vermeiden. Mathership verknüpft erstellte Lagerbuchungen mit Lightspeed-Verkaufspositionen. Bei späteren Läufen werden bereits gebuchte Verkaufspositionen für die aktuelle Lagereinheit übersprungen, außer force_refresh wird verwendet.

​

Was während der Übertragung passiert

Wenn eine Lightspeed-Übertragung läuft, führt Mathership Folgendes aus:

1. Prüfen, ob der Standort eine Lagereinheit hat
2. Ein Übertragungsprotokoll erstellen
3. Lightspeed-Verkäufe für das ausgewählte Datum abrufen oder wiederverwenden
4. Lightspeed-Verkäufe und Verkaufspositionen speichern
5. Namen und Mengen der verkauften Artikel auslesen
6. Positionen überspringen, die bereits auf die aktuelle Lagereinheit gebucht wurden
7. Verkaufte Artikelnamen mit POS-Zuordnungen abgleichen
8. Zugeordnete Zutaten direkt abbuchen
9. Zugeordnete Rezepte in Zutaten auflösen
10. Gewichtete Durchschnittskosten berechnen
11. Lagerbuchungen erstellen
12. Lagerbuchungen mit Lightspeed-Verkaufspositionen verknüpfen
13. Zeitpunkt des letzten Laufs der POS-Integration aktualisieren
14. Übertragungsstatistiken und Fehler speichern

​

Verkaufsdatumsfenster

Mathership fordert Lightspeed-Verkäufe für das ausgewählte Berichtsdatum über ein ganztägiges UTC-Fenster an.

​

Verarbeitung von Verkaufspositionen

Nur positive Verkaufspositionen mit einem Namen werden verarbeitet. Eine Verkaufsposition wird übersprungen, wenn:

• Menge fehlt, null oder negativ ist
• Artikelname fehlt
• Die Position bereits gebucht wurde
• Der Artikel nicht zugeordnet ist
• Die zugeordnete Zutat oder das zugeordnete Rezept nicht aufgelöst werden kann

​

POS-Zuordnungsabgleich

Die Übertragung gleicht Lightspeed-Verkaufspositionen anhand des POS-Artikelnamens mit POS-Zuordnungen ab. Der Name der Lightspeed-Verkaufsposition muss exakt mit dem zugeordneten POS-Artikelnamen übereinstimmen.

​

Übertragungsergebnis

Eine manuelle Übertragung gibt eine Zusammenfassung mit den folgenden Informationen zurück:

​

Übertragungsstatistiken

​

Ergebnis ohne Daten

Wenn Lightspeed für das ausgewählte Datum keine Daten hat, gibt die Übertragung no_data zurück. Das bedeutet normalerweise:

• Für diesen Standort und dieses Datum wurden keine Verkäufe gefunden
• Es wurde ein falsches Datum eingegeben
• Es wurde ein falscher Standort ausgewählt
• Lightspeed hat für diesen Tag keine Berichtsdaten zurückgegeben

​

Übertragungsfehler

​

Wiederholungsverhalten

Bei temporären Lightspeed-API-Fehlern wiederholt Mathership die Übertragung automatisch mit folgender Verzögerungsfolge: Wiederholbare Fälle umfassen Lightspeed-API-Serverfehler und HTTP-429-Rate-Limit-Antworten.

​

Verarbeitungslogik

​

Zutatenzuordnung

Wenn die Zuordnung auf eine Zutat verweist, bucht Mathership diese Zutat direkt ab.

​

Rezeptzuordnung

Wenn die Zuordnung auf ein Rezept verweist, löst Mathership das Rezept auf und bucht alle Rezeptzutaten ab. Rezepte können Unterrezepte enthalten. Wenn ein zugeordnetes Rezept ein Unterrezept enthält, löst Mathership das Unterrezept als Teil der Übertragung auf. Rezeptpositionen können einen Putzverlust-/Trim-Prozentsatz enthalten. Wenn ein Trim-Prozentsatz konfiguriert ist, passt Mathership die benötigte Zutatenmenge an. Wenn der Trim-Prozentsatz ungültig ist, protokolliert die Übertragung eine invalid_trim_pct-Ausnahme. Wenn Rezepte sich zyklisch gegenseitig referenzieren, stoppt Mathership die rekursive Auflösung und protokolliert eine recipe_cycle-Ausnahme.

​

Nicht zugeordnete Artikel

Wenn ein verkaufter Lightspeed-Artikel keine Zuordnung hat, protokolliert Mathership den Artikelnamen als nicht zugeordnet und erstellt keine Lagerabbuchung. Beispiel-Ausnahme: unmapped_pos_name:Espresso

​

Gewichtete Durchschnittskosten

Mathership berechnet die Stückkosten aus Wareneingangs-Lagerbuchungen mit: Gesamtwert der Eingänge / Gesamtmenge der Eingänge Wenn keine Eingangsmenge verfügbar ist, beträgt der Stückpreis 0.

​

Lagerbuchungen

Lightspeed-Übertragungen erstellen Lagerbuchungen vom Typ ISSUE. Jede Buchung ist verknüpft mit:

• Unternehmen und Zutat
• Lagereinheit
• Abgebuchter Menge
• Stückkosten und Gesamtwert
• Datum
• Lightspeed-Standort
• Übertragungsprotokoll
• Lightspeed-Verkaufsposition

Siehe Ledger für eine detaillierte Lagerhistorie.

​

Übertragungsprotokolle

Jeder Übertragungsversuch erstellt ein Übertragungsprotokoll. Öffne Protokolle über den Button See all logs auf der Standortdetailseite. Die Standortdetailseite zeigt außerdem die letzten 10 fehlgeschlagenen Übertragungen direkt an, einschließlich Berichtsdatum, Versuchsnummer, Startzeit und Fehlermeldung.

​

Integrationswarnungen

Mathership erstellt Integrationswarnungen bei Lightspeed-Fehlern. Warnungen werden dedupliziert — wiederholte Fehler aktualisieren die bestehende offene Warnung, anstatt Duplikate zu erstellen. Wenn sich die Integration erholt, werden offene Warnungen automatisch gelöst.

​

Test-Checkliste

Bevor du dich auf automatische Übertragungen verlässt, teste einen Tag manuell und prüfe, dass:

• Der richtige Lightspeed-Standort verwendet wurde
• Der Standort die richtige Lagereinheit hat
• Das richtige Datum verarbeitet wurde
• Verkaufte Artikel gefunden wurden
• Wichtige Artikel zugeordnet sind
• Rezeptzutaten korrekt abgebucht wurden
• Mengen korrekt sind
• Lagerbuchungen in der richtigen Lagereinheit erscheinen
• Nicht zugeordnete Artikelnamen erwartet sind
• Der Status des Übertragungsprotokolls erfolgreich ist
• Keine unerwarteten Ausnahmen erscheinen

​

Empfohlener Testprozess

​

Best Practices

​

Häufige Probleme

​

Verwandte Seiten