sumup-cli

영어 · 독일어

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 프록시에 대한 세션 쿠키이며, 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은 수량이 0 미만으로 떨어지는 것을 허용하며, 이는 빈 선반을 넘어 판매가 이루어졌음을 의미합니다. 오류가 아닌 데이터로 처리하십시오.

• 행은 아이템이 아닌 변형당입니다. 두 개의 변형이 있는 아이템은 두 행이 되므로, 행 수는 항상 아이템 수 이상입니다.

설정

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 → 프로필 → 개발자용 → 도구 키트 → 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를 전달하십시오.

10개의 다운로드 센터 보고서가 모두 연결되어 있습니다. 출력 유형은 응답에서 감지되므로, PDF, 레거시 .xls 및 zip은 바이트로 기록되고 CSV는 Excel용 UTF-8 BOM을 받습니다. -o를 전달하거나 파일이 out/ 아래에 자동으로 이름이 지정됩니다.

매출 및 정산에는 의도적으로 두 가지 경로가 있습니다. sales 그룹은 대시보드 세션을 사용하며 키 없이도 작동합니다. transactions 및 payouts 그룹은 문서화된 공개 API를 사용하며, 더 안정적이고 cron에 적합하지만 sup_sk_ 시크릿 키가 필요합니다.

CSV 출력은 세미콜론으로 구분되고 UTF-8 BOM이 포함되어 있어, 스위스 로케일의 Excel에서 움라우트와 이모지가 손상되지 않고 가져오기 대화상자 없이 열립니다.

수익 계산 방법

sumup profit은 두 보고서를 결합합니다. 어느 쪽도 양쪽을 모두 가지고 있지 않기 때문입니다:

VAT를 뺄 필요가 없습니다: 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 파일과 세션 쿠키에는 모두 계정의 실시간 토큰이 포함되어 있습니다.

기여

이슈와 풀 리퀘스트를 환영합니다. 특히 매핑되지 않은 엔드포인트, 다른 로케일, 선택기를 깨뜨리는 대시보드 변경을 환영합니다. SumUp이 무언가를 이동하면, 새 HAR에서 sumup discover를 실행하는 것이 무엇인지 알아내는 가장 빠른 방법이며, 답은 src/core/session/endpoints.ts에 속합니다.

라이선스

MIT, LICENSE를 참조하세요.