sumup-cli

English · Deutsch

CLI и MCP-сервер для SumUp: каталог, склад, продажи, выплаты и массовое редактирование товаров, включая то, что официальный API вообще не предоставляет.

Одно ядро на TypeScript, две тонкие обёртки над ним:

• src/cli/ — командная строка, для скриптов и cron

• src/mcp/ — MCP-сервер, для использования внутри Claude и других MCP-клиентов

Собрано и протестировано на живом швейцарском аккаунте киоска с примерно 650 позициями.

Не связано с SumUp. Половина того, что делает этот инструмент, основана на недокументированном внутреннем API за панелью мерчанта, который SumUp может изменить или сломать в любой момент без предупреждения. Он читает ваш собственный аккаунт с вашими учётными данными и с радостью отредактирует ваш живой каталог, если вы его попросите. Перед массовым редактированием сохраните экспорт. Лицензия MIT, без гарантий.

Две половины

У SumUp есть документированный публичный API и недокументированный внутренний, и нужные вам вещи находятся по обе стороны.

В публичном API нет ни одной конечной точки для товаров или инвентаря, поэтому часть с каталогом работает через сессию, вошедшую в панель управления.

Две вещи, каждая из которых стоит часа, если о них забыть

1. Каждый внутренний вызов требует accept-version: 4.0.0. Без него сервер возвращает 404, что выглядит как неправильный путь, но это не так.

2. Аутентификация — это куки сессии для прокси Next.js того же источника, а не токен-носитель для api.sumup.com.

Обе закодированы в src/core/session/endpoints.ts, где для каждого пути записан статус verified / unverified и дата последнего наблюдения работоспособности.

Особенности данных, которые стоит знать

• Деньги в младших единицах. value: 290 — это 2,90 швейцарских франка, cost_price.value: 144 — это 1,44 швейцарских франка.

• tax_rate — это процент, умноженный на 1000. 8100 означает 8,1 процента, 2600 — 2,6 процента.

• Маржа рассчитывается от чистой цены, а не от валовой. Собственные показатели SumUp "Gewinn" и "Marge" для товара с валовой ценой 2,90 / чистой ценой 2,68 / себестоимостью 1,44 составляют 1,24 швейцарских франка и 46,3 процента. Этот инструмент соответствует этому.

• Артикул и склад отсутствуют в списке товаров. Поиск товаров содержит цены, но не артикул или склад; поиск инвентаря содержит артикул и склад, но не цены. 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 минут. Загрузка панели управления обменивает долгоживущую куки обновления на новую, поэтому безголовое обновление продолжает работать, пока SumUp держит профиль авторизованным. Куки записывается в ~/.sumup-cli/session-cookie.txt с правами 600.

sumup auth status показывает, сколько секунд осталось.

Безголовое обновление зависит от того, в каком браузере работает профиль. Настоящий Chrome или Edge проходят; Brave — нет, потому что Cloudflare удерживает редирект аутентификации на безголовом Brave, поэтому там auth capture требует --login и видимого окна каждый раз, когда истекает срок действия токена. В любом случае, авторизованный профиль всё равно перенаправляется через auth.sumup.com, чтобы обменять свою куки обновления, поэтому код ждёт завершения этого перехода, а не читает URL сразу после навигации и ошибочно не делает вывод, что пользователь вышел из системы.

playwright-core используется намеренно: он не поставляет браузеры и повторно использует уже установленную на машине сборку Chromium вместо загрузки 150 МБ. Укажите SUMUP_CHROMIUM_PATH на бинарный файл, если он не найден.

Доступ к публичному API (ключ)

Ключ, который SumUp показывает по умолчанию, — это публичный ключ (sup_pk_*), и в их документации сказано не использовать его. Он возвращает 401 на /v0.1/me. Вам нужен секретный ключ:

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 для Excel. Передайте -o, иначе файл будет назван автоматически в каталоге out/.

Намеренно существуют два пути к продажам и выплатам. Группа sales использует сессию панели управления и работает сегодня вообще без ключа. Группы transactions и payouts используют документированный публичный API, который более стабилен и подходит для cron, но требует секретного ключа sup_sk_.

Вывод CSV разделён точкой с запятой с меткой порядка байтов UTF-8, поэтому Excel в швейцарской локали открывает его с умляутами и эмодзи без изменений и без диалога импорта.

Как рассчитывается прибыль

sumup profit объединяет два отчёта, потому что ни один из них не содержит обеих сторон:

НДС вычитать не нужно: SumUp уже рассчитывает Gewinn на основе чистой цены.

Три ловушки, все обнаружены при сверке с собственными цифрами SumUp:

1. Отчёт по транзакциям перечисляет каждый платёж картой дважды, один раз как Zahlung и один раз как Auszahlung, с той же комиссией. Суммирование вслепую удваивает комиссии. Учитываются только строки 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

Затем загрузите его либо с помощью Importieren на странице Artikel, либо с помощью 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

Четыре вещи, которые она делает намеренно:

• Меняется только ячейка Quantity. Товар, который уже существует, никогда не переоценивается при пополнении запасов, даже если чистая цена поставщика изменилась. Себестоимость и продажная цена переносятся без изменений.

• Склад считывается в реальном времени, поэтому поставка ложится поверх того, что каталог говорит сейчас, а не поверх экспорта из прошлой недели. --base <file> переопределяет это, если у вас уже есть свежий экспорт под рукой.

• Результат — это частичный файл, заголовок плюс только затронутые строки. SumUp сопоставляет по Item id, поэтому остальные 680 с лишним вариантов остаются вне транзакции полностью, и ничто не может быть испорчено устаревшей колонкой.

• Нетронутые байты остаются нетронутыми. Строки вставляются, а не пересериализуются, поэтому собственное цитирование SumUp сохраняется, включая названия товаров с пробелами в конце, которые оно цитирует и которые простой CSV-писатель не стал бы. Вывод — LF, без BOM, именно то, что выдаёт экспортёр.

Всё, что не может быть безопасно оформлено, сообщается и пропускается, а не угадывается: артикул, которого нет в каталоге, артикул, находящийся более чем в одной строке (что действительно случается: два разных товара с одинаковым артикулом), или товар с отключённым отслеживанием запасов. --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).

Пересопоставление API при изменении SumUp

1. Войдите в me.sumup.com, DevTools → Сеть → отметьте Сохранить журнал

2. Пройдите по экранам, которые вас интересуют

3. Щёлкните правой кнопкой мыши по списку запросов → Сохранить всё как HAR с содержимым

sumup discover capture.har --catalog-only

Он группирует трафик по методу и шаблону пути, сворачивая идентификаторы, и сообщает параметры запроса, ключи тела запроса и форму ответа. 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 20 или новее, используется встроенный fetch.

• Официальный @sumup/sdk намеренно не используется: он всё ещё помечен как подверженный критическим изменениям, а внутренняя половина всё равно требует собственного HTTP-слоя, поэтому обе половины используют один клиент в src/core/http.ts с повторными попытками и экспоненциальной задержкой при ограничении скорости.

• Никогда не коммитьте .env, .session-cookie.txt, *.har или captures/. Файл HAR и файл cookie сессии содержат действующий токен для вашей учётной записи.

Участие в разработке

Приветствуются вопросы и запросы на включение изменений, особенно для конечных точек, которые ещё не отображены, других локалей и изменений панели управления, нарушающих работу селектора. Если SumUp что-то перемещает, sumup discover на свежем HAR — самый быстрый способ узнать, что именно, а src/core/session/endpoints.ts — место, куда следует поместить ответ.

Лицензия

MIT, см. LICENSE.