sumup-cli

English · Deutsch

用于 SumUp 的 CLI 和 MCP 服务器：目录、库存、销售、结算和批量产品编辑，包括官方 API 完全未公开的内容。

一个 TypeScript 核心，两个薄包装：

• src/cli/ 命令行，用于脚本和 cron

• src/mcp/ MCP 服务器，用于在 Claude 和其他 MCP 客户端中使用

针对一个约 650 个品项的瑞士售货亭账户构建并测试。

与 SumUp 无关。 此工具的一半功能依赖于商户后台背后的未记录内部 API，SumUp 可随时更改或破坏它，恕不另行通知。它使用您自己的凭据读取您自己的账户，如果您要求，它也会愉快地编辑您的实时目录。在批量编辑任何内容之前，请保留一份导出。MIT 许可证，无担保。

两半部分

SumUp 有一个有文档记录的公共 API 和一个未记录的内部 API，您想要的东西存在于两侧。

公共 API 中没有任何产品或库存端点，这就是为什么目录部分依赖于登录的仪表板会话。

两件如果您忘记每件会花费一小时的事情

1. 每个内部调用都需要 accept-version: 4.0.0。 没有它，上游返回 404，这看起来像是路径错误，但并非如此。

2. 认证是同源 Next.js 代理的会话 Cookie，而不是 api.sumup.com 的 bearer token。

两者都编码在 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 允许计数低于零，这仅仅意味着销售超过了空货架。将其视为数据，而非错误。

• 行按变体，而非按商品。 一个有两个变体的商品变成两行，因此行数始终至少等于商品数。

设置

npm install

目录访问（会话）

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

仪表板的访问令牌大约持续 15 分钟。加载仪表板会将长期有效的刷新 Cookie 交换为新的 Cookie，因此只要 SumUp 保持配置文件登录，无头刷新就能继续工作。Cookie 写入到 ~/.sumup-cli/session-cookie.txt，权限为 600。

sumup auth status 精确打印剩余秒数。

无头刷新取决于配置文件运行的浏览器。真正的 Chrome 或 Edge 可以成功；Brave 不行，因为 Cloudflare 在无头 Brave 上阻止了认证重定向，因此在那里 auth capture 需要 --login 和一个可见窗口，每次令牌过期时都需要。无论哪种方式，登录的配置文件仍然通过 auth.sumup.com 重定向以交换其刷新 Cookie，因此代码等待该跳转稳定，而不是在导航后立即读取 URL 并错误地认为已注销。

有意使用 playwright-core：它不附带浏览器，而是重用机器上已有的 Chromium 构建，而不是下载 150 MB。如果未找到二进制文件，请将 SUMUP_CHROMIUM_PATH 指向一个二进制文件。

公共 API 访问（密钥）

SumUp 默认向您显示的密钥是 公共 密钥（sup_pk_*），他们的文档说不要使用它。它在 /v0.1/me 上返回 401。您需要一个 秘密 密钥：

me.sumup.com → 个人资料 → 面向开发者 → 工具包 → API 密钥 → 创建

立即复制它，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 是详细的簿记导出：每个订单项一行，包含 Datum, Transaktionsnummer, Zahlungsmethode, Beschreibung, Kategorie, Artikelnummer, Preis (brutto), Preis (netto), Steuer, Steuersatz。列标题遵循 --locale，因此传递 --locale en-GB 以获取英文。

所有十个下载中心报告都已连接。输出类型根据响应检测，因此 PDF、传统 .xls 和 zip 文件以字节写入，而 CSV 则获得 UTF-8 BOM 以便 Excel 使用。传递 -o 或文件自动命名在 out/ 下。

有意提供两条通向销售和结算的路径。sales 组使用仪表板会话，今天无需任何密钥即可工作。transactions 和 payouts 组使用有文档记录的公共 API，该 API 更稳定，适合 cron，但需要 sup_sk_ 秘密密钥。

CSV 输出以分号分隔，带有 UTF-8 BOM，因此瑞士语言环境的 Excel 打开时变音符号和表情符号完好无损，无需导入对话框。

利润如何计算

sumup profit 结合了两个报告，因为两者都没有同时包含两方面：

增值税无需扣除：SumUp 已经在 净价 上计算了 Gewinn。

三个陷阱，所有都是通过与 SumUp 自己的数字核对发现的：

1. 交易报告将每笔卡支付列出两次，一次作为 Zahlung，一次作为 Auszahlung，携带相同的费用。盲目求和会使费用翻倍。只有 Zahlung 行才算数。

2. 该报告仅涵盖卡支付。 现金从未出现在其中，因此总收入来自商品报告，现金不适用任何费用。

3. 没有成本价的商品报告空白 Gewinn。 它们作为 revenueWithoutCost 显示，而不是被计为纯利润或纯亏损。

结果是运营贡献，不是 最终的净利润：它是在租金、工资和 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 箱，增加库存，其他不变。这是一个命令。

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

它有意做四件事：

• 只有数量单元格移动。 已经存在的商品在补货时永远不会重新定价，即使供应商的净价发生了变化。成本和售价保持不变。

• 库存是实时读取的，因此交货落在目录现在说的数量之上，而不是基于上周的导出。--base <file> 覆盖此行为，当您手头已有最新导出时。

• 输出是部分文件，标题加上仅受影响的行的内容。SumUp 通过 Item id 匹配，因此其他 680 多个变体完全不受事务影响，不会被过时的列覆盖。

• 未触及的字节保持不变。 行被拼接，而不是重新序列化，因此 SumUp 自己的引用得以保留，包括它引用的尾随空格商品名称，而普通的 CSV 编写器不会保留。输出是 LF，无 BOM，正是导出器发出的内容。

任何无法安全记录的内容都会被报告并跳过，而不是猜测：不在目录中的 SKU、位于多行上的 SKU（这确实会发生：两个不同的产品输入了相同的 SKU），或者关闭了库存跟踪的商品。 --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”按钮；在该文本上匹配会击中行菜单而不是工具栏。

三件值得知道的事情：

• 它需要一个可见窗口，除非配置文件运行在真正的 Chrome 或 Edge 上，因为 Cloudflare 不会让无头 Brave 通过认证跳转。--headless 适用于那些能处理它的浏览器。

• 没有 --yes 它退化为仅做验证。 导入会修改实时目录，因此静默不等于同意。文件在浏览器启动之前就被验证了。

• 对话框成功时什么也不说，因此命令事后重新读取目录，并检查它现在是否与文件说的内容一致。该检查是实际的确认；--no-verify 将其关闭。

已于 2026-08-18 端到端验证，方法是导入一个单行文件，从实时目录读取更改，然后再次导入原始值。

直接的逐项写入 API 仍然 未 启用。读取端点是从真实流量映射的，但写入形状从未被捕获，CLI 和 MCP 工具都拒绝，而不是向实时目录发出猜测的 PUT。

要启用直接写入，在仪表板中保存一个产品的同时捕获流量，然后对捕获运行 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/ 中（已 gitignored）。

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 20 或更高版本，使用内置 fetch。

• 刻意未使用官方 @sumup/sdk：该库仍标记为可能有破坏性变更，且内部部分需要自定义 HTTP 层，因此两个部分共用一个位于 src/core/http.ts 中的客户端，具备重试和限速退避功能。

• 切勿提交 .env、.session-cookie.txt、*.har 或 captures/。HAR 文件和会话 Cookie 均包含您账户的实时令牌。

贡献

欢迎提交问题和拉取请求，尤其适用于：本工具尚未映射的端点、其他语言区域，以及仪表盘变更导致选择器失效的情况。如果 SumUp 移动了某些内容，在全新的 HAR 文件上运行 sumup discover 是快速查明变化的最佳方式，而 src/core/session/endpoints.ts 则是记录答案的位置。

许可证

MIT，参见 LICENSE。