sumup-cli

英語 · Deutsch

SumUp用のCLIおよびMCPサーバー：カタログ、在庫、売上、支払い、一括商品編集。公式APIがまったく公開していないものも含みます。

1つのTypeScriptコアと、その上に2つの薄いラッパーがあります：

• src/cli/ コマンドライン（スクリプトやcron用）

• src/mcp/ MCPサーバー（Claudeや他のMCPクライアント内で使用）

約650アイテムの実際のスイスのキオスクアカウントに対して構築・テスト済み。

SumUpとは提携していません。 このツールの機能の半分は、マーチャントダッシュボードの背後にある文書化されていない内部APIに依存しており、SumUpは予告なくいつでも変更または破損する可能性があります。このツールはあなた自身の認証情報であなた自身のアカウントを読み取り、要求すればライブカタログを喜んで編集します。一括編集を行う前にエクスポートを保存しておいてください。MITライセンス、無保証。

2つの部分

SumUpには文書化された公開APIと文書化されていない内部APIがあり、必要なものは両方に存在します。

公開APIには商品や在庫のエンドポイントはどこにもありません。そのため、カタログ部分はログインしたダッシュボードセッションに依存しています。

忘れるとそれぞれ1時間かかる2つのこと

1. すべての内部呼び出しには accept-version: 4.0.0 が必要です。 これがないと上流は 404 を返します。これは間違ったパスのように見えますが、そうではありません。

2. 認証は同一オリジンのNext.jsプロキシに対するセッションクッキーであり、api.sumup.com へのベアラートークンではありません。

両方とも src/core/session/endpoints.ts にエンコードされており、すべてのパスに verified / unverified ステータスと最後に動作が確認された日付が記録されています。

知っておくべきデータの癖

• 金額は最小単位です。 value: 290 は CHF 2.90、cost_price.value: 144 は CHF 1.44 です。

• tax_rate はパーセント×1000です。 8100 は8.1%、2600 は2.6%を意味します。

• マージンは総額ではなく正味価格で計算されます。 SumUp自身の「Gewinn」と「Marge」は、総額2.90 / 正味2.68 / 原価1.44のアイテムに対してCHF 1.24と46.3%と表示されます。このツールはそれに一致します。

• SKUと在庫はアイテムリストに含まれていません。 アイテム検索には価格はありますがSKUや在庫はありません。在庫検索にはSKUと在庫はありますが価格はありません。catalog export はそれらを variant_id で結合します。

• 在庫はマイナスになります。 SumUpはカウントがゼロを下回ることを許容します。これは単に空の棚を超えて販売が行われたことを意味します。エラーではなくデータとして扱ってください。

• 行はアイテムごとではなくバリアントごとです。 2つのバリアントを持つアイテムは2行になるため、行数は常にアイテム数以上になります。

セットアップ

npm install

カタログアクセス（セッション）

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

ダッシュボードのアクセストークンの有効期間は約 15分 です。ダッシュボードを読み込むと、長期有効なリフレッシュクッキーが新しいものと交換されるため、SumUpがプロファイルのサインインを維持している限り、ヘッドレスリフレッシュは機能し続けます。クッキーは ~/.sumup-cli/session-cookie.txt にモード600で書き込まれます。

sumup auth status は残り秒数を正確に表示します。

ヘッドレスリフレッシュは、プロファイルがどのブラウザで実行されているかに依存します。実際のChromeまたはEdgeは通過しますが、Braveは通過しません。CloudflareがヘッドレスBraveで認証リダイレクトを保持するためです。そのため、auth capture はトークンが期限切れになるたびに --login と可視ウィンドウが必要です。いずれにせよ、サインインしたプロファイルは auth.sumup.com を経由してリフレッシュクッキーを交換するためにリダイレクトされるため、コードはナビゲーション直後にURLを読み取って誤ってログアウトと判断するのではなく、そのバウンスが落ち着くのを待ちます。

playwright-core は意図的に使用されています。ブラウザを同梱せず、150MBのダウンロードを引き出す代わりに、マシンに既にあるChromiumビルドを再利用します。見つからない場合は SUMUP_CHROMIUM_PATH をバイナリに指定してください。

公開APIアクセス（キー）

SumUpがデフォルトで表示するキーは 公開 キー (sup_pk_*) であり、ドキュメントでは使用しないように指示されています。/v0.1/me で401を返します。秘密 キーが必要です：

me.sumup.com → プロフィール → For Developers → Toolkit → API Keys → 作成

すぐにコピーしてください。SumUpは保存しません。次に：

sumup auth login --api-key sup_sk_xxxxx

使い方

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 は明細化された簿記エクスポートです。明細項目ごとに1行で、Datum, Transaktionsnummer, Zahlungsmethode, Beschreibung, Kategorie, Artikelnummer, Preis (brutto), Preis (netto), Steuer, Steuersatz が含まれます。列ヘッダーは --locale に従うため、英語の場合は --locale en-GB を渡してください。

ダウンロードセンターの10種類すべてのレポートが接続されています。出力タイプはレスポンスから検出されるため、PDF、レガシー .xls、zipはバイトとして書き込まれ、CSVにはExcel用のUTF-8 BOMが付加されます。-o を渡すか、ファイルは out/ の下に自動的に命名されます。

売上と支払いには意図的に2つのルートがあります。sales グループはダッシュボードセッションを使用し、現在はキーなしで動作します。transactions と payouts グループは文書化された公開APIを使用し、より安定しておりcronに適していますが、sup_sk_ 秘密キーが必要です。

CSV出力はセミコロン区切りでUTF-8 BOM付きのため、スイスのロケールのExcelでもウムラウトや絵文字がそのまま表示され、インポートダイアログは表示されません。

利益の計算方法

sumup profit は2つのレポートを組み合わせます。どちらも両方の側面を持っていないためです：

VATの減算は不要です。SumUpはすでに 正味 価格でGewinnを計算しています。

3つの落とし穴。すべてSumUp自身の数値と照合して発見されました：

1. 取引レポートはすべてのカード支払いを2回リストします。一度は Zahlung として、もう一度は Auszahlung として、同じ手数料が含まれます。盲目的に合計すると手数料が2倍になります。Zahlung 行のみがカウントされます。

2. そのレポートはカード支払いのみをカバーします。 現金は決して表示されないため、総収益はアイテムレポートから取得され、現金には手数料は適用されません。

3. 原価がないアイテムは空白のGewinnを報告します。 これらは純利益または純損失としてカウントされるのではなく、revenueWithoutCost として表示されます。

結果は営業貢献利益であり、最終的なNettogewinnではありません。家賃、人件費、およびAusgabenモジュールのすべての前の段階です。

商品の編集

CSVラウンドトリップを使用します。これはSumUp自身の一括編集メカニズムであり、リバースエンジニアリングされた書き込みエンドポイントは必要ありません：

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

次に、Artikelページの Importieren または sumup catalog import（後述）を使用してアップロードします。Item id (Do not change) または Variant id (Do not change) 列には決して触れないでください。これらはSumUpが行をレコードにマッチングする方法です。

入荷の記録

一般的なケースは自由形式の編集ではなく、仕入先請求書です。n個のカートンが到着し、在庫を増やし、他は変更しません。それは1つのコマンドです。

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

意図的に行う4つのこと：

• 数量セルのみが変更されます。 既存のアイテムは再入荷時に再価格設定されることはありません。仕入先の正味価格が変動しても、原価と販売価格は変更されずに引き継がれます。

• 在庫はライブで読み取られるため、入荷は先週のエクスポートではなく、現在のカタログの上に追加されます。--base <file> は、すでに新しいエクスポートを手元に持っている場合にそれを上書きします。

• 出力は部分的なファイルで、ヘッダーと変更された行のみです。SumUpは Item id でマッチングするため、他の680ほどのバリアントはトランザクションにまったく含まれず、古い列によって上書きされることはありません。

• 変更されていないバイトはそのまま残ります。 行は再シリアライズではなくスプライスされるため、SumUp独自の引用が維持されます。これには、末尾にスペースがあるアイテム名の引用も含まれ、プレーンなCSVライターでは維持されません。出力はLF、BOMなしで、エクスポーターが出力するものとまったく同じです。

安全に記録できないものは、推測されるのではなく報告されスキップされます。カタログにないSKU、複数の行に存在するSKU（実際に発生します：同じSKUが入力された2つの異なる商品）、または在庫追跡がオフのアイテムなどです。--dry-run は書き込みなしでテーブルを表示し、--set は数値を入荷ではなく結果の在庫として扱い、結果は書き込まれる前に validate を通過します。

アップロード

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

呼び出すインポートエンドポイントはまだないため、これはブラウザでダッシュボード自身のダイアログを操作します。ツールバーの Weitere Optionen、そのメニューの Import エントリ、その背後にあるファイル入力、そして SELECTORS.IMPORT.CONTINUE_BUTTON です。SumUpはこれらの data-selector 属性自体を提供しており、これらは翻訳やクラス名の変更後も存続するため、フローはボタンラベルではなくこれらによって駆動されます。すべての商品行にも "Aktionen" ボタンがあることに注意してください。そのテキストでマッチングすると、ツールバーではなく行メニューがヒットします。

知っておくべき3つのこと：

• 可視ウィンドウが必要です。プロファイルが実際のChromeまたはEdgeで実行されていない限り、CloudflareがヘッドレスBraveを認証バウンスで通過させないためです。--headless はそれを管理できるブラウザ用にあります。

• --yes がない場合はドライランにフォールバックします。 インポートはライブカタログを変更するため、沈黙は同意ではありません。ブラウザが起動する前にファイルが検証されます。

• ダイアログは成功時に何も表示しないため、コマンドは後でカタログを読み戻し、ファイルの内容と一致することを確認します。そのチェックが実際の確認です。--no-verify でオフにできます。

2026-08-18に、1行のファイルをインポートし、ライブカタログから変更を読み戻し、元の値を再度インポートすることでエンドツーエンドで検証済み。

直接のアイテムごとの書き込みAPIはまだ有効になっていません。読み取りエンドポイントは実際のトラフィックからマッピングされましたが、書き込みの形状はキャプチャされておらず、CLIとMCPツールの両方が、推測された PUT をライブカタログに発射するのではなく拒否します。

直接書き込みを有効にするには、トラフィックをキャプチャしながらダッシュボードで1つの商品を保存し、キャプチャに対して sumup discover を実行して src/core/session/endpoints.ts を埋めてください。書き込みはデフォルトではまだドライランで、--yes（CLI）または confirm: true（MCP）が必要です。

SumUpがAPIを変更したときの再マッピング

1. me.sumup.comにログインし、DevTools → Network → Preserve log にチェックを入れる

2. 関心のある画面をクリックして進む

3. リクエストリストを右クリック → Save all as HAR with content

sumup discover capture.har --catalog-only

トラフィックをメソッドとパステンプレートでグループ化し、IDを折りたたみ、クエリパラメータ、リクエストボディキー、レスポンス形状を報告します。HARにはライブセッショントークンが含まれます。.gitignore はすでに *.har を除外しています。

2026-08-17のマッピングからのサンプルペイロードは captures/ にあります（gitignore対象）。

MCPサーバー

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

17のツール：

sumup_catalog_stock は low: true と共に使うと、在庫補充の判断には sumup_sales_list と相性が良く、sumup_catalog_restock は結果として発生する注文をインポートファイルに変換します。

完全なAPIマップ

docs/api-map.md には、すべてのダッシュボードページを巡回して発見された全サーフェス（カタログ、売上、支払い、現金管理、顧客、メンバー、経費、オンラインストア、請求、支払いリンクの約60エンドポイントと、単位規則および既知のギャップ）が文書化されています。

注意

• Node.js 20以降が必要で、組み込みの fetch を使用します。

• 公式の @sumup/sdk は意図的に使用していません。まだ破壊的変更の対象とマークされており、内部半部分ではカスタムHTTPレイヤーが必要なため、両方の半部分が src/core/http.ts 内の再試行とレート制限バックオフ付きの1つのクライアントを共有しています。

• .env、.session-cookie.txt、*.har、captures/ をコミットしないでください。HARファイルとセッションCookieには、アカウントの有効なトークンが含まれています。

コントリビューション

問題やプルリクエストは歓迎します。特に、このツールがまだマッピングしていないエンドポイント、他のロケール、およびセレクターを壊すダッシュボードの変更についてです。SumUpが何かを移動した場合、新しいHARで sumup discover を実行するのがその内容を最も早く確認する方法であり、src/core/session/endpoints.ts が答えの配置場所です。

ライセンス

MITライセンスです。詳細は LICENSE を参照してください。