sumup-cli

English · Deutsch

CLI- und MCP-Server für SumUp: Katalog, Lagerbestand, Verkäufe, Auszahlungen und Bulk-Produktbearbeitungen, einschließlich der Dinge, die die offizielle API überhaupt nicht bereitstellt.

Ein TypeScript-Kern, zwei dünne Wrapper darüber:

• src/cli/ Kommandozeile, für Skripte und Cron

• src/mcp/ MCP-Server, zur Verwendung in Claude und anderen MCP-Clients

Erstellt und getestet gegen ein Live-Schweizer Kiosk-Konto mit etwa 650 Artikeln.

Nicht mit SumUp verbunden. Die Hälfte dessen, was dieses Tool tut, basiert auf der undokumentierten internen API hinter dem Händler-Dashboard, die SumUp jederzeit ohne Vorankündigung ändern oder unterbrechen kann. Es liest Ihr eigenes Konto mit Ihren eigenen Anmeldedaten und wird Ihren Live-Katalog gerne bearbeiten, wenn Sie es dazu auffordern. Halten Sie vor Bulk-Bearbeitungen immer ein Export bereit. MIT-lizenziert, keine Garantie.

Die zwei Hälften

SumUp hat eine dokumentierte öffentliche API und eine undokumentierte interne, und die Dinge, die Sie möchten, leben auf beiden Seiten.

Es gibt keinen Produkt- oder Bestandsendpunkt in der öffentlichen API, weshalb die Kataloghälfte auf einer eingeloggten Dashboard-Sitzung basiert.

Zwei Dinge, die jeweils eine Stunde kosten, wenn Sie sie vergessen

1. Jeder interne Aufruf benötigt accept-version: 4.0.0. Ohne sie gibt der Upstream 404 zurück, was wie ein falscher Pfad aussieht, aber keiner ist.

2. Auth ist das Session-Cookie gegen den Same-Origin Next.js-Proxy, kein Bearer-Token an api.sumup.com.

Beide sind in src/core/session/endpoints.ts kodiert, wo jeder Pfad einen verified / unverified-Status und das Datum der letzten beobachteten Funktion vermerkt.

Daten-Eigenheiten, die man kennen sollte

• Geldbeträge sind in Untereinheiten. value: 290 ist CHF 2.90, cost_price.value: 144 ist CHF 1.44.

• tax_rate ist Prozent mal 1000. 8100 bedeutet 8,1 Prozent, 2600 bedeutet 2,6 Prozent.

• Die Marge wird auf den Nettopreis berechnet, nicht auf den Bruttopreis. SumUps eigener "Gewinn" und "Marge" für einen Artikel mit 2,90 brutto / 2,68 netto / 1,44 Kosten lauten CHF 1,24 und 46,3 Prozent. Dieses Tool stimmt damit überein.

• SKU und Lagerbestand sind nicht in der Artikelliste. Die Artikelsuche hat Preise, aber keine SKU oder Lagerbestand; die Bestandssuche hat SKU und Lagerbestand, aber keine Preise. catalog export verbindet sie über variant_id.

• Der Lagerbestand kann negativ werden. SumUp lässt einen Bestand unter Null fallen, was einfach bedeutet, dass Verkäufe über einen leeren Regalbestand hinaus abgerechnet wurden. Behandeln Sie es als Daten, nicht als Fehler.

• Zeilen sind pro Variante, nicht pro Artikel. Ein Artikel mit zwei Varianten wird zu zwei Zeilen, daher ist die Zeilenanzahl immer mindestens die Artikelanzahl.

Einrichtung

npm install

Katalogzugriff (Sitzung)

sumup auth capture --login    # opens a browser once, you sign in
sumup auth capture            # afterwards, headless, mints a fresh token

Das Zugriffstoken des Dashboards lebt etwa 15 Minuten. Das Laden des Dashboards tauscht das langlebige Refresh-Cookie gegen ein neues aus, sodass die headless-Aktualisierung so lange funktioniert, wie SumUp das Profil angemeldet lässt. Das Cookie wird in ~/.sumup-cli/session-cookie.txt mit Modus 600 geschrieben.

sumup auth status gibt genau aus, wie viele Sekunden noch übrig sind.

Die headless-Aktualisierung hängt davon ab, welchen Browser das Profil verwendet. Ein echter Chrome oder Edge kommt durch; Brave nicht, weil Cloudflare die Auth-Weiterleitung auf einem headless Brave blockiert, daher benötigt auth capture dort --login und ein sichtbares Fenster jedes Mal, wenn das Token abläuft. In jedem Fall wird ein angemeldetes Profil dennoch über auth.sumup.com umgeleitet, um sein Refresh-Cookie auszutauschen, daher wartet der Code auf diesen Bounce, anstatt die URL direkt nach der Navigation zu lesen und fälschlicherweise zu schließen, dass man ausgeloggt ist.

playwright-core wird bewusst verwendet: Es liefert keine Browser mit und verwendet stattdessen einen bereits auf dem Rechner vorhandenen Chromium-Build, anstatt einen 150 MB großen Download zu ziehen. Setzen Sie SUMUP_CHROMIUM_PATH auf eine Binärdatei, wenn keine gefunden wird.

Öffentlicher API-Zugriff (Schlüssel)

Der Schlüssel, den SumUp standardmäßig anzeigt, ist ein öffentlicher Schlüssel (sup_pk_*) und ihre Dokumentation sagt, man solle ihn nicht verwenden. Er gibt 401 auf /v0.1/me zurück. Sie benötigen einen geheimen Schlüssel:

me.sumup.com → Profil → Für Entwickler → Toolkit → API-Schlüssel → Erstellen

Kopieren Sie ihn sofort, SumUp speichert ihn nicht. Dann:

sumup auth login --api-key sup_sk_xxxxx

Verwendung

sumup auth status                       # credentials, session expiry, endpoint health

# Catalog (session only, no API key needed)
sumup catalog export -f csv -o out/inventar.csv    # one row per variant, price/cost/margin/stock
sumup catalog export -f csv --all-columns
sumup catalog native-export -o out/sumup.csv       # SumUp's own 47-column CSV
sumup catalog validate out/sumup.csv               # check an edited file before import
sumup catalog restock --sku 1-0004=48 --sku 1-0008=48 -o out/lieferung.csv
                                                   # book a delivery, stock only
sumup catalog import out/lieferung.csv --yes        # upload it through the dashboard
sumup catalog categories
sumup catalog stock --low               # at or below the low-stock threshold
sumup catalog stock --negative          # sold past zero
sumup catalog taxes
sumup catalog item <item_id>            # full raw payload

# Download Center reports, all ten (session only)
sumup reports list

# range reports, --from / --to
sumup reports get sales        --from 2026-08-01 --to 2026-08-17 -o out/verkaeufe.csv
sumup reports get transactions --from 2026-08-01 --to 2026-08-17 -o out/transaktionen.csv
sumup reports get cashbook     --from 2026-08-01 --to 2026-08-17 -o out/kassenbuch.csv
sumup reports get items        --from 2026-08-01 --to 2026-08-17 -o out/artikel.csv
sumup reports get invoicing    --from 2026-07-01 --to 2026-07-31 --doc-type invoices
sumup reports get revenue      --from 2026-08-01 --to 2026-08-17   # PDF
sumup reports get fiscal       --from 2026-08-01 --to 2026-08-17   # KassenSichV zip

# monthly statements, --month (or --day for a single date)
sumup reports get payouts  --month 2026-07                 # Auszahlungsbericht PDF
sumup reports get fees     --month 2026-07                 # Gebührenabrechnung PDF
sumup reports get payments --month 2026-07                 # Zahlungsbericht PDF
sumup reports get payments --month 2026-07 --format xls    # same as legacy .xls
sumup reports get payouts  --day 2026-07-15

# Profit
sumup profit --from 2026-07-01 --to 2026-07-31
sumup profit --from 2026-07-01 --to 2026-07-31 --by-item -f csv -o out/marge.csv

# Umsätze and Auszahlungen (session only, no API key needed)
sumup sales list --from 2026-08-01 --to 2026-08-17 -f csv -o out/aug.csv
sumup sales movers --from 2026-08-01 --to 2026-08-17
sumup sales payouts --limit 30

# Same data via the public API (needs the secret key)
sumup transactions list --from 2026-08-01 --to 2026-08-17 -f csv
sumup transactions items --from 2026-08-01 --to 2026-08-17 -f csv
sumup payouts list --from 2026-07-01 --to 2026-07-31 --native-csv

sumup endpoints                         # what is mapped and what is verified

reports get sales ist der detaillierte Buchhaltungsexport: eine Zeile pro Position mit Datum, Transaktionsnummer, Zahlungsmethode, Beschreibung, Kategorie, Artikelnummer, Preis (brutto), Preis (netto), Steuer, Steuersatz. Spaltenüberschriften folgen --locale, also übergeben Sie --locale en-GB für Englisch.

Alle zehn Download-Center-Berichte sind angebunden. Der Ausgabetyp wird aus der Antwort erkannt, daher werden PDFs, Legacy-.xls und ZIPs als Bytes geschrieben, während CSVs einen UTF-8-BOM für Excel erhalten. Übergeben Sie -o oder eine Datei wird automatisch unter out/ benannt.

Es gibt bewusst zwei Wege zu Verkäufen und Auszahlungen. Die Gruppe sales verwendet die Dashboard-Sitzung und funktioniert heute ohne Schlüssel. Die Gruppen transactions und payouts verwenden die dokumentierte öffentliche API, die stabiler und für Cron geeignet ist, aber einen sup_sk_-geheimen Schlüssel benötigt.

CSV-Ausgabe ist semikolongetrennt mit einem UTF-8-BOM, sodass Excel in einem Schweizer Gebietsschema es mit Umlauten und Emojis intakt und ohne Importdialog öffnet.

Wie der Gewinn berechnet wird

sumup profit kombiniert zwei Berichte, da keiner beide Seiten hat:

MwSt. muss nicht abgezogen werden: SumUp berechnet den Gewinn bereits auf dem Nettopreis.

Drei Fallstricke, alle durch Abgleich mit SumUps eigenen Zahlen gefunden:

1. Der Transaktionsbericht listet jede Kartenzahlung zweimal, einmal als Zahlung und einmal als Auszahlung, mit derselben Gebühr. Unbedachtes Summieren verdoppelt die Gebühren. Nur Zahlung-Zeilen zählen.

2. Dieser Bericht deckt nur Kartenzahlungen ab. Bargeld erscheint nie darin, daher stammt der Gesamtumsatz aus dem Artikelbericht und es fällt keine Gebühr für Bargeld an.

3. Artikel ohne Einkaufspreis melden einen leeren Gewinn. Sie werden als revenueWithoutCost angezeigt, anstatt als reiner Gewinn oder reiner Verlust gezählt zu werden.

Das Ergebnis ist ein operativer Deckungsbeitrag, kein endgültiger Nettogewinn: Er steht vor Miete, Löhnen und allem im Ausgaben-Modul.

Produkte bearbeiten

Verwenden Sie den CSV-Rundlauf. Es ist SumUps eigener Bulk-Bearbeitungsmechanismus, daher benötigt er keinen rückentwickelten Schreibendpunkt:

sumup catalog native-export -o out/sumup.csv   # 47 columns, one row per variant
# edit prices, cost prices, SKUs, stock, categories in Excel or a script
sumup catalog validate out/sumup.csv           # catch problems before SumUp does

Laden Sie es dann hoch, entweder mit Importieren auf der Artikelseite oder mit sumup catalog import (unten). Berühren Sie niemals die Spalten Item id (Do not change) oder Variant id (Do not change); so ordnet SumUp Zeilen wieder Datensätzen zu.

Eine Lieferung buchen

Der häufigste Fall ist keine freie Bearbeitung, sondern eine Lieferantenrechnung: n Kartons sind angekommen, erhöhen Sie den Bestand, ändern Sie nichts anderes. Das ist ein Befehl.

sumup catalog restock --sku 1-0004=48 --sku 1-0014=48 \
                      --sku 1-0008=48 --sku 1-0002=48 \
                      -o out/lieferung-1808.csv

base: live export, 646 items
  1-0004    Coca-Cola Zero 0.5L PET             34 + 48 -> 82
  1-0014    Valser Kohlensäure 0.5L PET         14 + 48 -> 62
  1-0008    Evian 0.50L PET                     26 + 48 -> 74
  1-0002    Coca-Cola Zero 0.33L DOSE            7 + 48 -> 55

Vier Dinge, die es absichtlich tut:

• Nur die Mengenzelle wird bewegt. Ein bereits vorhandener Artikel wird bei einer Nachbestellung nie neu bepreist, selbst wenn der Nettopreis des Lieferanten abgewichen ist. Kosten und Verkaufspreis werden unverändert übernommen.

• Der Bestand wird live gelesen, sodass die Lieferung auf dem aufsetzt, was der Katalog jetzt sagt, und nicht auf einem Export von letzter Woche. --base <file> überschreibt dies, wenn Sie bereits einen frischen Export in der Hand haben.

• Die Ausgabe ist eine partielle Datei, Kopfzeile plus nur die betroffenen Zeilen. SumUp gleicht über Item id ab, daher bleiben die anderen 680-odd Varianten vollständig außerhalb der Transaktion und nichts kann durch eine veraltete Spalte überschrieben werden.

• Unberührte Bytes bleiben unberührt. Zeilen werden eingefügt, nicht neu serialisiert, sodass SumUps eigene Zitierung überlebt, einschließlich der mit Leerzeichen versehenen Artikelnamen, die es zitiert und die ein einfacher CSV-Schreiber nicht tun würde. Ausgabe ist LF, kein BOM, genau das, was der Exporteur ausgibt.

Alles, was nicht sicher gebucht werden kann, wird gemeldet und übersprungen, anstatt geraten zu werden: eine SKU, die nicht im Katalog ist, eine SKU, die auf mehr als einer Zeile sitzt (was wirklich vorkommt: zwei verschiedene Produkte mit derselben SKU eingegeben), oder ein Artikel mit deaktivierter Bestandsverfolgung. --dry-run zeigt die Tabelle ohne Schreiben, --set behandelt die Zahlen als resultierenden Bestand statt als Lieferung, und das Ergebnis wird durch validate laufen gelassen, bevor es geschrieben wird.

Hochladen

sumup catalog import out/lieferung.csv --dry-run   # open the flow, upload nothing
sumup catalog import out/lieferung.csv --yes       # actually import

Es gibt immer noch keinen Import-Endpunkt zum Aufrufen, daher steuert dies den eigenen Dialog des Dashboards in einem Browser: Weitere Optionen in der Symbolleiste, den Import-Eintrag in diesem Menü, die Dateieingabe dahinter, dann SELECTORS.IMPORT.CONTINUE_BUTTON. SumUp liefert diese data-selector-Attribute selbst, die Übersetzung und Klassenname-Churn überleben, daher wird der Ablauf durch sie gesteuert und nicht durch Schaltflächenbeschriftungen. Beachten Sie, dass jede Produktzeile auch eine "Aktionen"-Schaltfläche hat; das Abgleichen auf diesen Text trifft auf ein Zeilenmenü anstelle der Symbolleiste.

Drei Dinge, die man wissen sollte:

• Es benötigt ein sichtbares Fenster, es sei denn, das Profil läuft auf einem echten Chrome oder Edge, da Cloudflare einen headless Brave nicht durch den Auth-Bounce lässt. --headless ist für die Browser da, die es schaffen.

• Ohne --yes wird es zu einem Probelauf herabgestuft. Ein Import verändert einen Live-Katalog, daher ist Schweigen keine Zustimmung. Die Datei wird validiert, bevor der Browser überhaupt gestartet wird.

• Der Dialog sagt nichts bei Erfolg, daher liest der Befehl den Katalog danach zurück und prüft, ob er jetzt das sagt, was die Datei sagte. Diese Prüfung ist die eigentliche Bestätigung; --no-verify schaltet sie aus.

Verifiziert Ende-zu-Ende am 2026-08-18 durch Import einer einzeiligen Datei, Auslesen der Änderung aus dem Live-Katalog und erneutes Importieren des ursprünglichen Werts.

Die direkte Schreib-API pro Artikel ist immer noch nicht aktiviert. Die Leseendpunkte wurden aus echtem Traffic abgeleitet, aber die Schreibform wurde nie erfasst, und sowohl das CLI als auch das MCP-Tool lehnen ab, anstatt ein geratenes PUT auf einen Live-Katalog abzufeuern.

Um direkte Schreibvorgänge zu aktivieren, speichern Sie ein Produkt im Dashboard, während Sie den Traffic aufzeichnen, führen Sie dann sumup discover auf der Aufzeichnung aus und füllen Sie src/core/session/endpoints.ts aus. Schreibvorgänge würden dann standardmäßig immer noch als Probelauf ausgeführt, benötigen --yes (CLI) oder confirm: true (MCP).

Neuabbildung der API, wenn SumUp sie ändert

1. Melden Sie sich bei me.sumup.com an, DevTools → Netzwerk → Protokoll erhalten aktivieren

2. Klicken Sie durch die Bildschirme, die Sie interessieren

3. Rechtsklick auf die Anfrageliste → Alle mit Inhalt als HAR speichern

sumup discover capture.har --catalog-only

Es gruppiert Traffic nach Methode und Pfadvorlage, kollabiert IDs und meldet Abfrageparameter, Anforderungstextschlüssel und Antwortform. Ein HAR enthält ein Live-Sitzungstoken; .gitignore schließt *.har bereits aus.

Beispiel-Payloads aus der Abbildung vom 2026-08-17 befinden sich in captures/ (gitignored).

MCP-Server

{
  "mcpServers": {
    "sumup": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/sumup-cli/src/mcp/server.ts"]
    }
  }
}

17 Werkzeuge:

sumup_catalog_stock mit low: true passt gut mit sumup_sales_list für Nachbestellungsentscheidungen zusammen, und sumup_catalog_restock wandelt die resultierende Bestellung nach Eintreffen in eine Importdatei um.

Vollständige API-Übersicht

docs/api-map.md dokumentiert die gesamte Oberfläche, die durch das Durchgehen jeder Dashboard-Seite entdeckt wurde: etwa 60 Endpunkte in den Bereichen Katalog, Verkäufe, Auszahlungen, Bargeldmanagement, Kunden, Mitglieder, Ausgaben, Online-Shop, Rechnungsstellung und Zahlungslinks, plus die Einheitenkonventionen und die bekannten Lücken.

Hinweise

• Node 20 oder neuer, verwendet integriertes fetch.

• Das offizielle @sumup/sdk wird bewusst nicht verwendet: es ist noch als änderungsanfällig markiert, und die interne Hälfte benötigt ohnehin eine benutzerdefinierte HTTP-Schicht, daher teilen sich beide Hälften einen Client in src/core/http.ts mit Wiederholungs- und Ratenbegrenzungs-Backoff.

• Committen Sie niemals .env, .session-cookie.txt, *.har oder captures/. Eine HAR-Datei und ein Session-Cookie enthalten beide ein Live-Token für Ihr Konto.

Mitwirken

Issues und Pull-Requests sind willkommen, insbesondere für Endpunkte, die dieses Tool noch nicht erfasst hat, andere Gebietsschemata und Dashboard-Änderungen, die einen Selektor beschädigen. Wenn SumUp etwas verschiebt, ist sumup discover auf einer frischen HAR-Datei der schnellste Weg, um herauszufinden, was, und src/core/session/endpoints.ts ist der Ort, an den die Antwort gehört.

Lizenz

MIT, siehe LICENSE.