> ## Documentation Index
> Fetch the complete documentation index at: https://help.mathership.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Lightspeed K-Series
> Verbinde Lightspeed K-Series mit Mathership, um POS-Verkäufe in Lagerbewegungen zu übertragen
# 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.
Verbinde Lightspeed über OAuth und speichere Access- und Refresh-Tokens sicher.
Ordne Lightspeed-Artikel Mathership-Zutaten oder -Rezepten zu.
Übertrage POS-Verkäufe als Lagerentnahmen in das Ledger.
## 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
Lightspeed-Verkäufe wirken sich erst dann auf den Lagerbestand aus, wenn die entsprechenden Lightspeed-Artikel Zutaten oder Rezepten zugeordnet wurden.
## Empfohlene Einrichtungsreihenfolge
Verwende diese Reihenfolge für eine saubere Lightspeed-Einrichtung:
Richte die Mathership-Lagereinheiten ein, von denen Lagerentnahmen abgebucht werden sollen.
Stelle sicher, dass die Zutaten vorhanden sind, die für POS-Artikel- und Rezeptabbuchungen verwendet werden.
Erstelle Rezepte für POS-Artikel, die mehrere Zutaten abbuchen sollen.
Autorisiere die Lightspeed-K-Series-Verbindung über OAuth.
Importiere Lightspeed-Geschäftsstandorte in Mathership.
Weise jedem Lightspeed-Standort die richtige Mathership-Lagereinheit zu.
Importiere Lightspeed-POS-Artikel.
Beginne mit häufig verkauften Artikeln und Artikeln, die den Lagerbestand stark beeinflussen.
Aktiviere den Standort, sobald Lagereinheiten und Zuordnungen bereit sind.
Prüfe die 90-Tage-Migration nach der Aktivierung.
Teste ein Datum manuell, bevor du dich auf die automatische Übertragung verlässt.
Prüfe die erstellten Lagerbuchungen und korrigiere Zuordnungen bei Bedarf.
Die wichtigste Einrichtungsregel lautet: Standorte benötigen Lagereinheiten, und Lightspeed-Artikel benötigen Zuordnungen. Ohne beides können Verkäufe nicht zuverlässig Lagerbewegungen erstellen.
## Bevor du beginnst
Bereite vor der Verbindung mit Lightspeed diese Mathership-Lagerobjekte vor.
| Erforderliche Einrichtung | Warum sie benötigt wird |
| ------------------------- | ------------------------------------------------------------------------- |
| Lagereinheiten | Lagerabbuchungen benötigen eine Ziel-Lagereinheit |
| Zutaten | POS-Artikel oder Rezeptpositionen buchen Zutaten ab |
| Rezepte | Rezeptzugeordnete POS-Artikel werden in Zutaten aufgelöst |
| POS-Zuordnungen | Lightspeed-Artikelnamen müssen mit Zutaten oder Rezepten verknüpft werden |
## Lagereinheiten
Jeder Lightspeed-Standort muss mit einer Mathership-Lagereinheit verknüpft werden.
Die Lagereinheit definiert, wo der Bestand abgebucht werden soll.
| Lightspeed-Standort | Mathership-Lagereinheit |
| ------------------- | ----------------------- |
| Restaurant Main POS | Main Kitchen |
| Bar POS | Bar Storage |
| Terrace POS | Terrace Storage |
## Zutaten
Zutaten sind die Lagerobjekte, die abgebucht werden.
| Zutat | Einheit |
| ------------------- | ------- |
| Kaffeebohnen | kg |
| Cola-Flasche 0,33 l | Flasche |
| Burgerbrötchen | Stück |
| Tomate | kg |
## 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-Artikel | Mathership-Rezept |
| ------------------ | ----------------------- |
| Classic Burger | Classic Burger recipe |
| Pizza Margherita | Pizza Margherita recipe |
| Espresso Martini | Espresso Martini recipe |
## 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:
| Feld | Bedeutung |
| ------------ | ------------------------------------------- |
| `company_id` | Das Unternehmen, dem die Integration gehört |
| `name` | Interner Name der Integration |
| `code` | OAuth-Autorisierungscode von Lightspeed |
### 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 | Verwendung |
| ----------------------------- | ----------------------------------------------------- |
| Access-Token | Wird für Lightspeed-API-Aufrufe verwendet |
| Refresh-Token | Wird verwendet, um ein neues Access-Token zu erhalten |
| Ablaufzeit des Access-Tokens | Wird aus der Lightspeed-Antwort gespeichert |
| Ablaufzeit des Refresh-Tokens | Wird aus der Lightspeed-Antwort gespeichert |
Token-Laufzeiten werden aus der Lightspeed-Token-Antwort gelesen. Sie sind nicht fest im Code hinterlegt.
### Verbindungsfehler
| Fehler | Bedeutung |
| ---------------------------------- | -------------------------------------------------------------------- |
| `lightspeed_integration_exists` | Für dieses Unternehmen existiert bereits eine Lightspeed-Integration |
| `lightspeed_oauth_exchange_failed` | Der Autorisierungscode konnte nicht ausgetauscht werden |
| `lightspeed_not_configured` | Lightspeed OAuth ist nicht korrekt konfiguriert |
| `unauthorized_company_access` | Das Unternehmen gehört nicht zum aktuellen Benutzer |
### Häufige Verbindungsprobleme
Mathership erlaubt eine Lightspeed-Integration pro Unternehmen.
Verwende die bestehende Integration oder autorisiere sie erneut, anstatt eine weitere zu erstellen.
Starte den Lightspeed-Autorisierungsprozess erneut und übermittle einen neuen Autorisierungscode.
Dies erfordert, dass ein Administrator die Lightspeed-OAuth-Konfiguration prüft.
## 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.
| Ergebnis der Erneuerung | Ergebnis |
| -------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Erfolg | Neue Tokens gespeichert, Integration bleibt aktiv, offene Warnungen werden gelöst |
| Fehler mit `invalid_grant` | Integration wird als getrennt markiert, erneute Autorisierung erforderlich |
| Fehler mit Serverfehler | Integration wird als Erneuerung fehlgeschlagen markiert, Warnung wird erstellt, kann erneut versucht werden |
## Standorte synchronisieren
Die Standort-Synchronisierung ruft Geschäftsstandorte aus Lightspeed ab und überführt sie in eine Mathership-Standortliste.
### Spalten der Standortliste
| Spalte | Beschreibung |
| ---------------------- | ----------------------------------------------------------------- |
| Standort-ID | Lightspeed-Geschäftsstandort-ID |
| Name | Standortname mit Land und Zeitzone |
| Lagereinheit | Verknüpfte Mathership-Lagereinheit oder **Nicht zugeordnet** |
| Währung | Währungscode aus Lightspeed |
| Aktiviert | Ob der Standort für tägliche Entnahmen aktiviert ist |
| Auto issue | Ob die automatische tägliche Verarbeitung aktiv oder pausiert ist |
| Zuletzt synchronisiert | Wann der Standort zuletzt synchronisiert wurde |
Filtere die Liste über die Toolbar nach Aktivierungsstatus, Auto-issue-Status oder Lagereinheit.
### Gespeicherte Standortdaten
| Feld | Bedeutung |
| ---------------------- | ----------------------------------------------- |
| `business_location_id` | Lightspeed-Geschäftsstandort-ID |
| `name` | Lightspeed-Standortname |
| `country` | Standortland aus Lightspeed |
| `timezone` | Standort-Zeitzone aus Lightspeed |
| `currency_code` | Währungscode aus Lightspeed |
| `last_synced_at` | Zeitpunkt der letzten Standort-Synchronisierung |
### 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
Synchronisiere die Standorte erneut, prüfe, ob die Autorisierung noch gültig ist, autorisiere bei Bedarf erneut und prüfe die Lightspeed-Kontoberechtigungen.
Führe die Standort-Synchronisierung erneut aus. Mathership aktualisiert gespeicherte Standortdaten anhand der neuesten Lightspeed-Antwort.
## 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.
| Lightspeed-Standort | Lagereinheit | Ergebnis |
| ------------------- | --------------- | ---------------------------------------------- |
| Bar POS | Bar Storage | Getränke werden aus dem Barbestand abgebucht |
| Restaurant POS | Main Kitchen | Speisen werden aus dem Küchenbestand abgebucht |
| Terrace POS | Terrace Storage | Terrassenverkäufe buchen Terrassenbestand ab |
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
| Fehler | Bedeutung |
| ------------------------------- | --------------------------------------------------------------------------- |
| `storage_unit_required` | Vor Aktivierung oder Übertragung muss eine Lagereinheit verknüpft sein |
| `storage_unit_company_mismatch` | Die ausgewählte Lagereinheit gehört zu einem anderen Unternehmen |
| `location_has_no_storage_unit` | Die Übertragung kann nicht laufen, weil der Standort keine Lagereinheit hat |
Verknüpfe nur Lagereinheiten, die zum selben Unternehmen gehören wie die Lightspeed-Integration.
## 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
| Spalte | Beschreibung |
| ------------- | --------------------------------------------------------------------------------------------------------- |
| Name | POS-Artikelname und Lightspeed-Artikel-ID |
| SKU | SKU aus Lightspeed, falls verfügbar |
| Preis | Aus Lightspeed synchronisierter Artikelpreis |
| Aktiv | Ob der Artikel in Lightspeed aktiv ist |
| Zugeordnet | Ob der Artikel eine Mathership-Zuordnung hat |
| Zugeordnet zu | Die Zutat oder das Rezept, der bzw. dem der Artikel zugeordnet ist, mit Menge und Subtraktionskennzeichen |
| Standorte | In welchen Lightspeed-Standorten dieser Artikel erscheint |
Filtere die Artikelliste mit den Toolbar-Chips nach Zuordnungsstatus, Aktivstatus oder Standort.
### Gespeicherte Artikeldaten
| Feld | Bedeutung |
| ---------------- | ---------------------------------------------- |
| `item_id` | Lightspeed-Artikel-ID |
| `name` | Lightspeed-Artikelname |
| `sku` | SKU aus Lightspeed, falls verfügbar |
| `active` | Ob der Artikel aktiv ist |
| `price` | Artikelpreis, falls verfügbar |
| `last_synced_at` | Zeitpunkt der letzten Artikel-Synchronisierung |
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
| Status | Bedeutung |
| ---------------- | -------------------------------------------------------- |
| Nicht zugeordnet | Der Artikel hat noch keine Lagerzuordnung |
| Zugeordnet | Der Artikel ist einer Zutat oder einem Rezept zugeordnet |
### Häufige Probleme bei der Artikel-Synchronisierung
Synchronisiere Artikel erneut, prüfe, ob Standorte zuerst synchronisiert wurden, prüfe die Lightspeed-Kontoberechtigungen und autorisiere die Integration bei Bedarf erneut.
Führe die Artikel-Synchronisierung erneut aus. Prüfe Zuordnungen nach größeren Artikelnamensänderungen, da die Zuordnung vom POS-Artikelnamen abhängt.
POS-Zuordnungen werden anhand des POS-Artikelnamens abgeglichen. Wenn sich Lightspeed-Artikelnamen ändern, passen bestehende Zuordnungen möglicherweise nicht mehr zu übertragenen Verkaufspositionen.
## 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.
| Lightspeed-Verkauf | Erforderliche Mathership-Bedeutung |
| ------------------ | -------------------------------------- |
| Espresso | Kaffeebohnen abbuchen |
| Cola 0,33 l | Eine Cola-Flasche abbuchen |
| Classic Burger | Alle Zutaten im Burger-Rezept abbuchen |
### Zuordnungsbeispiele
| Lightspeed-Artikel | Zugeordnet zu | Zuordnungsmenge | Verkaufsmenge | Lagerauswirkung |
| ------------------ | ------------- | --------------- | ------------- | -------------------- |
| Cola 0,33 l | Cola-Flasche | 1 | 2 | 2 Flaschen |
| Espresso | Kaffeebohnen | 0.009 | 10 | 0.09 kg Kaffeebohnen |
| Burger | Burger-Rezept | 1 | 3 | 3 Rezeptportionen |
| Lightspeed-Artikel | Zugeordnet zu | Verkaufsmenge | Ergebnis |
| ------------------ | ----------------------- | ------------- | ----------------------- |
| Classic Burger | Classic Burger recipe | 5 | Alle Burger-Zutaten × 5 |
| Pizza Margherita | Pizza Margherita recipe | 3 | Alle Pizza-Zutaten × 3 |
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.
| Lightspeed-Artikel | Zuordnungsziel | Zuordnungsmenge | Verkaufsmenge | Lagerauswirkung |
| ------------------ | -------------- | --------------: | ------------: | -------------------- |
| Cola 0,33 l | Cola-Flasche | 1 | 2 | 2 Flaschen |
| Espresso | Kaffeebohnen | 0.009 | 10 | 0.09 kg Kaffeebohnen |
| Burger | Burger-Rezept | 1 | 3 | 3 Rezeptportionen |
### Zuordnungsfelder
| Feld | Bedeutung |
| -------------------- | ------------------------------------------------------------ |
| `mapped_object_type` | `ingredient` oder `recipe` |
| `mapped_object_id` | ID der Zutat oder des Rezepts |
| `quantity` | Multiplikator, der für das zugeordnete Objekt verwendet wird |
| `is_subtraction` | Ob die Zuordnung Umkehr-/Subtraktionslogik verwendet |
### Subtraktionszuordnung
Verwende `is_subtraction` vorsichtig für Sonderfälle wie Umkehrlogik, negative Verkäufe oder Korrekturen.
Prüfe Subtraktionszuordnungen sorgfältig. Falsche Subtraktionslogik kann Lagerbewegungen in die falsche Richtung erzeugen.
### 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
| Fehler | Bedeutung |
| ----------------------------- | -------------------------------------------------------------------- |
| `recipe_not_found` | Das ausgewählte Rezept existiert für dieses Unternehmen nicht |
| `ingredient_not_found` | Die ausgewählte Zutat existiert für dieses Unternehmen nicht |
| `unauthorized_company_access` | Der Artikel oder die Integration gehört nicht zum aktuellen Benutzer |
## 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
| Statistik | Beschreibung |
| -------------------- | -------------------------------------------------------------------------------------------------- |
| Entnahmen (gesamt) | Alle jemals verarbeiteten Entnahmen mit Fehleranzahl |
| Entnahmen (7d / 30d) | In den letzten 7 und 30 Tagen verarbeitete Entnahmen |
| Katalog zugeordnet | Wie viele Lightspeed-Artikel von insgesamt zugeordnet sind — zum Öffnen der Produktseite anklicken |
| Verkäufe (7d / 30d) | Lightspeed-Verkaufspositionen, die in den letzten 7 und 30 Tagen erkannt wurden |
### Konfiguration
| Einstellung | Beschreibung |
| ------------------- | ----------------------------------------------------------------------------------------- |
| Lagereinheit | Die Lagereinheit, aus der Bestand abgebucht wird — nach Änderung **Speichern** klicken |
| Standort aktivieren | Einweg-Schalter, um den Standort für tägliche Entnahmen zu aktivieren |
| Auto issue | Schalter zum Pausieren oder Fortsetzen der automatischen täglichen Verarbeitung |
| Manuelle Entnahme | Datumsauswahl, um eine einmalige Entnahme für ein bestimmtes vergangenes Datum auszulösen |
## 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.
| Beispiel | Datum |
| --------------- | ---------- |
| Wenn heute ist | 2026-05-08 |
| Startdatum | 2026-02-07 |
| Enddatum | 2026-05-07 |
| Gesamtzahl Tage | 90 |
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 | Bedeutung |
| ----------- | ----------------------------------------------------------------------- |
| `pending` | Migration wurde erstellt, aber noch nicht gestartet |
| `running` | Migration wird derzeit verarbeitet |
| `completed` | Migration wurde erfolgreich abgeschlossen |
| `cancelled` | Migration wurde abgebrochen |
| `failed` | Migration wurde beendet, aber ein oder mehrere Tage sind fehlgeschlagen |
### Status von Migrationstagen
| Status | Bedeutung |
| --------------- | ---------------------------------------------------------------------------- |
| `pending` | Tag wartet auf Verarbeitung |
| `processing` | Tag wird derzeit verarbeitet |
| `success` | Tag wurde erfolgreich verarbeitet |
| `no_data` | Lightspeed hat für diesen Tag keine Verkaufsdaten zurückgegeben |
| `failed` | Tag ist während der Verarbeitung fehlgeschlagen |
| `retry_pending` | Fehlgeschlagener Tag wartet auf erneuten Versuch |
| `skipped` | Tag wurde übersprungen, weil bereits eine erfolgreiche Übertragung existiert |
### Fortschrittsfelder der Migration
| Feld | Bedeutung |
| ------------------ | --------------------------------------------------------------- |
| `total_days` | Anzahl der Tage in der Migration |
| `days_processed` | Erfolgreich verarbeitete Tage |
| `days_failed` | Fehlgeschlagene Tage |
| `days_skipped` | Tage, die aufgrund eines vorherigen Erfolgs übersprungen wurden |
| `current_date` | Datum, das derzeit verarbeitet wird |
| `start_date` | Erstes Datum der Migration |
| `end_date` | Letztes Datum der Migration |
| `progress_percent` | Migrationsfortschritt in Prozent |
| `started_at` | Startzeitstempel |
| `completed_at` | Abschlusszeitstempel |
| `error_message` | Fehlermeldung für fehlgeschlagene oder abgebrochene Jobs |
### Migrationsaktionen
| Aktion | Wann verwenden |
| -------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Migration starten | Wenn für den Standort keine Migration existiert |
| Migration erneut ausführen | Nach dem Hinzufügen oder Korrigieren von Zuordnungen — verarbeitet den vollständigen 90-Tage-Zeitraum erneut |
| Migration abbrechen | Wenn du eine ausstehende oder laufende Migration stoppen musst |
### 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
| Fehler | Bedeutung |
| ------------------------------- | ------------------------------------------------ |
| `location_not_activated` | Der Standort muss zuerst aktiviert werden |
| `storage_unit_required` | Der Standort hat keine verknüpfte Lagereinheit |
| `migration_already_in_progress` | Eine Migration ist bereits ausstehend oder läuft |
## 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.
| Status | Bedeutung |
| -------- | ---------------------------------------------------------------------------- |
| Aktiv | Tägliche Lightspeed-Verkäufe werden automatisch verarbeitet |
| Pausiert | Keine automatische Verarbeitung — manuelle Entnahmen funktionieren weiterhin |
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
Das Pausieren der automatischen Übertragung löscht nicht die Integration, Standorte, Zuordnungen oder Übertragungshistorie.
## 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.
Die Zeitzone des Standorts wird gespeichert, aber das aktuelle Übertragungsfenster verwendet ein UTC-Tagesfenster.
### 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.
Wenn sich Artikelnamen in Lightspeed ändern, müssen Zuordnungen möglicherweise geprüft oder neu erstellt werden.
## Übertragungsergebnis
Eine manuelle Übertragung gibt eine Zusammenfassung mit den folgenden Informationen zurück:
| Feld | Bedeutung |
| ------------ | ------------------------------------------------------- |
| `date` | Verarbeitetes Berichtsdatum |
| `success` | Ob die Übertragung erfolgreich war |
| `no_data` | Ob Lightspeed keine Verkaufsdaten zurückgegeben hat |
| `log_id` | Referenz des Übertragungsprotokolls |
| `ledger_ids` | IDs der erstellten Lagerbuchungen |
| `stats` | Verarbeitungsstatistiken |
| `error` | Fehlermeldung, wenn die Verarbeitung fehlgeschlagen ist |
### Übertragungsstatistiken
| Feld | Bedeutung |
| ------------------------ | --------------------------------------------------------------------------------- |
| `sales_count` | Anzahl der verarbeiteten Lightspeed-Verkäufe |
| `lines_processed` | Anzahl der verarbeiteten Verkaufspositionen |
| `lines_skipped` | Anzahl der übersprungenen Verkaufspositionen |
| `ledger_entries_created` | Anzahl der erstellten Lagerbuchungen |
| `exceptions` | Probleme bei Zuordnung oder Rezeptverarbeitung |
| `used_cache` | Ob zwischengespeicherte Verkäufe verwendet wurden |
| `idempotent` | Ob keine neuen Einträge erforderlich waren, weil Positionen bereits gebucht waren |
| `recipes_used` | Zusammenfassung der verwendeten zugeordneten Rezepte oder Zutaten |
| `unmapped_names` | POS-Artikelnamen ohne Zuordnungen |
| `api_response_summary` | Zusammenfassung der abgerufenen oder zwischengespeicherten Lightspeed-Daten |
### 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
| Fehler | Bedeutung |
| ------------------------------ | ---------------------------------------------------------------- |
| `date_required` | Es wurde kein Datum angegeben |
| `invalid_date_format` | Das Datumsformat ist ungültig |
| `storage_unit_required` | Der Standort hat keine verknüpfte Lagereinheit |
| `location_has_no_storage_unit` | Der ausgewählte Standort kann keinen Bestand abbuchen |
| `lightspeed_auth_failed` | Lightspeed-Authentifizierung fehlgeschlagen |
| `lightspeed_api_error` | Lightspeed-API hat einen Fehler zurückgegeben |
| `max_retries_exhausted` | Übertragung ist nach allen Wiederholungsversuchen fehlgeschlagen |
### Wiederholungsverhalten
Bei temporären Lightspeed-API-Fehlern wiederholt Mathership die Übertragung automatisch mit folgender Verzögerungsfolge:
| Wiederholungsversuch | Verzögerung |
| -------------------- | ------------ |
| 1 | 30 Sekunden |
| 2 | 60 Sekunden |
| 3 | 120 Sekunden |
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.
| Lightspeed-Artikel | Verkaufte Menge | Zuordnungsmenge | Lagerabbuchung |
| ------------------ | --------------: | --------------: | -------------------- |
| Cola 0,33 l | 12 | 1 | 12 Flaschen |
| Espresso | 20 | 0.009 | 0.18 kg Kaffeebohnen |
### Rezeptzuordnung
Wenn die Zuordnung auf ein Rezept verweist, löst Mathership das Rezept auf und bucht alle Rezeptzutaten ab.
| Lightspeed-Artikel | Verkaufte Menge | Zuordnung | Lagerabbuchung |
| ------------------ | --------------: | ------------- | -------------------- |
| Burger | 5 | Burger-Rezept | Zutaten für 5 Burger |
| Pizza Margherita | 3 | Pizza-Rezept | Zutaten für 3 Pizzen |
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
| Lightspeed-Verkauf | Zuordnung | Lagerergebnis |
| ------------------ | ------------- | ---------------------------- |
| 1 × Espresso | Kaffeebohnen | Kaffeebohnen abbuchen |
| 2 × Cola 0,33 l | Cola-Flasche | 2 Flaschen abbuchen |
| 1 × Burger | Burger-Rezept | Alle Burger-Zutaten abbuchen |
Siehe [Ledger](/en/restaurants/inventory/ledger) für eine detaillierte Lagerhistorie.
## Übertragungsprotokolle
Jeder Übertragungsversuch erstellt ein Übertragungsprotokoll.
Öffne Protokolle über den Button **See all logs** auf der Standortdetailseite.
| Feld | Bedeutung |
| ------------------------ | ----------------------------------------------------- |
| Standort | Lightspeed-Standort |
| Berichtsdatum | Datum, das verarbeitet wird |
| Request UUID | Gemeinsame Kennung für die Übertragungsanfrage |
| Versuchsnummer | Nummer des Wiederholungsversuchs |
| Status | Verarbeitung, Erfolg oder fehlgeschlagen |
| Ledger-IDs | Erstellte Lagerbuchungen |
| Verarbeitete Verkäufe | Anzahl der Verkäufe |
| Verarbeitete Positionen | Anzahl der verarbeiteten Positionen |
| Übersprungene Positionen | Anzahl der übersprungenen Positionen |
| Nicht zugeordnete Namen | POS-Namen ohne Zuordnungen |
| Fehlermeldung | Fehlergrund |
| Antwortzusammenfassung | Ausnahmen, verwendete Rezepte und API-Zusammenfassung |
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.
| Warncode | Bedeutung |
| ---------------------- | ----------------------------------------------------------------------------------------- |
| `disconnected` | Refresh-Token ist ungültig und erneute Autorisierung ist erforderlich |
| `token_refresh_failed` | Token-Erneuerung ist aufgrund eines Authentifizierungs- oder Serverfehlers fehlgeschlagen |
## 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
Wähle ein aktuelles Lightspeed-Verkaufsdatum mit bekannten Verkäufen.
Stelle sicher, dass der ausgewählte Standort die richtige Lagereinheit hat.
Ordne zuerst eine kleine Anzahl wichtiger POS-Artikel zu.
Führe eine manuelle Übertragung mit Force Refresh aus.
Prüfe erstellte Ledger-IDs, nicht zugeordnete Namen und Übertragungsstatistiken.
Bestätige Zutatenmengen und Lagereinheit im Ledger.
Korrigiere fehlende oder falsche Zuordnungen.
Bestätige, dass korrigierte Artikel nun Ledger-Einträge erstellen.
## Best Practices
Erstelle Lagereinheiten, Zutaten und Rezepte, bevor du dich auf Lightspeed-Übertragungen verlässt.
Verbinde und teste zuerst einen Lightspeed-Standort. Wenn dieser funktioniert, fahre mit weiteren Standorten fort.
Beginne mit den am häufigsten verkauften Artikeln. So entsteht schnell der größte Nutzen für den Lagerbestand.
Teste immer einen Tag manuell, bevor du die automatische Übertragung aktivierst.
Nicht zugeordnete Artikel sind während der Einrichtung normal. Verwende sie als Arbeitsliste für fehlende Zuordnungen.
Die Zuordnung hängt von POS-Artikelnamen ab. Wenn sich Lightspeed-Artikelnamen ändern, prüfe die Zuordnungen.
Wenn die Autorisierung fehlschlägt, autorisiere die bestehende Integration erneut. Löschen entfernt Einrichtungsdaten.
Prüfe nach Übertragungen das Ledger, um Mengen, Lagereinheiten und Zutaten zu bestätigen.
## Häufige Probleme
Verwende die bestehende Integration oder autorisiere sie erneut, anstatt eine zweite zu erstellen.
Starte den Lightspeed-Autorisierungsprozess erneut und übermittle einen neuen Autorisierungscode.
Lightspeed hat das Refresh-Token abgelehnt.
Öffne die Integration, starte die erneute Autorisierung, autorisiere Mathership erneut in Lightspeed und bestätige, dass der Integrationsstatus aktiv wird.
Synchronisiere Standorte erneut, prüfe die Lightspeed-Autorisierung, autorisiere bei Bedarf erneut und prüfe die Lightspeed-Kontoberechtigungen.
Synchronisiere Artikel erneut, prüfe, ob Standorte zuerst synchronisiert wurden, prüfe Lightspeed-Berechtigungen und autorisiere erneut, falls die Autorisierung abgelaufen sein könnte.
Prüfe, ob eine Lagereinheit verknüpft und gespeichert ist und ob mindestens ein Artikel zugeordnet ist.
Prüfe, ob der Standort aktiviert ist, eine verknüpfte Lagereinheit hat und keine andere Migration bereits ausstehend ist oder läuft.
Prüfe das ausgewählte Datum, ob Lightspeed für dieses Datum Verkäufe mit positiven Mengen hat, ob Artikel zugeordnet sind, ob Artikelnamen mit POS-Zuordnungen übereinstimmen, ob Rezepte Zutaten enthalten, ob der Standort eine Lagereinheit hat und ob die Positionen bereits gebucht wurden.
Öffne das Übertragungsergebnis, prüfe `unmapped_names`, erstelle oder korrigiere Zuordnungen, prüfe Rezeptzutaten, führe die manuelle Übertragung mit Force Refresh erneut aus und führe die Migration erneut aus, wenn historische Daten korrigiert werden sollen.
1. Automatische Übertragung pausieren
2. Lagereinheiten-Verknüpfung korrigieren und speichern
3. Bestehende Lagerbuchungen für die betroffenen Daten prüfen
4. Entscheiden, ob betroffene Tage storniert oder erneut verarbeitet werden sollen
5. Manuelle Übertragung nach der Korrektur sorgfältig ausführen
Prüfe, ob der Name der Verkaufsposition exakt mit dem zugeordneten POS-Artikelnamen übereinstimmt, ob die zugeordnete Zutat oder das zugeordnete Rezept noch existiert, ob das Rezept Zutatenpositionen enthält, ob die verkaufte Menge größer als null ist und ob die Übertragung nach Erstellung der Zuordnung ausgeführt wurde.
Prüfe das Datum, den Lightspeed-Standort, ob der ausgewählte Tag abgeschlossene Verkäufe hat und ob Lightspeed für diesen Tag Berichtsdaten zurückgegeben hat.
## Verwandte Seiten
Zurück zur Integrationsübersicht.
Ordne POS-Artikel Zutaten oder Rezepten zu.
Verwalte Lagereinheiten, die für Lightspeed-Abbuchungen verwendet werden.
Prüfe Lagerbewegungen, die durch Lightspeed-Übertragungen erstellt wurden.