sumup-cli

Inglés · Deutsch

CLI y servidor MCP para SumUp: catálogo, stock, ventas, pagos y ediciones masivas de productos, incluyendo las cosas que la API oficial no expone en absoluto.

Un núcleo TypeScript, dos envoltorios ligeros sobre él:

• src/cli/ línea de comandos, para scripts y cron

• src/mcp/ servidor MCP, para usar dentro de Claude y otros clientes MCP

Construido y probado contra una cuenta de quiosco suiza real de aproximadamente 650 artículos.

No afiliado con SumUp. La mitad de lo que esta herramienta hace se basa en la API interna no documentada detrás del panel de comerciante, la cual SumUp puede cambiar o romper en cualquier momento sin previo aviso. Lee tu propia cuenta con tus propias credenciales, y editará felizmente tu catálogo en vivo si se lo pides. Mantén una exportación antes de editar algo masivamente. Licencia MIT, sin garantía.

Las dos mitades

SumUp tiene una API pública documentada y una interna no documentada, y las cosas que quieres viven en ambos lados.

No hay ningún endpoint de producto o inventario en la API pública, por lo que la mitad del catálogo se basa en una sesión de panel iniciada.

Dos cosas que cuestan una hora cada una si las olvidas

1. Cada llamada interna necesita accept-version: 4.0.0. Sin ella, el upstream devuelve 404, que parece una ruta incorrecta pero no lo es.

2. La autenticación es la cookie de sesión contra el proxy Next.js del mismo origen, no un token bearer para api.sumup.com.

Ambas están codificadas en src/core/session/endpoints.ts, donde cada ruta registra un estado verified / unverified y la fecha en que se observó funcionando por última vez.

Particularidades de los datos que vale la pena conocer

• El dinero está en unidades menores. value: 290 son CHF 2.90, cost_price.value: 144 son CHF 1.44.

• tax_rate es porcentaje por 1000. 8100 significa 8.1 por ciento, 2600 significa 2.6 por ciento.

• El margen se calcula sobre el precio neto, no sobre el bruto. La propia "Gewinn" y "Marge" de SumUp para un artículo de 2.90 bruto / 2.68 neto / 1.44 costo leen CHF 1.24 y 46.3 por ciento. Esta herramienta coincide con eso.

• SKU y stock no están en la lista de artículos. La búsqueda de artículos tiene precios pero no SKU ni stock; la búsqueda de inventario tiene SKU y stock pero no precios. catalog export los une en variant_id.

• El stock se vuelve negativo. SumUp permite que un recuento caiga por debajo de cero, lo que simplemente significa que se registraron ventas más allá de un estante vacío. Trátalo como datos, no como un error.

• Las filas son por variante, no por artículo. Un artículo con dos variantes se convierte en dos filas, por lo que el número de filas siempre es al menos el número de artículos.

Configuración

npm install

Acceso al catálogo (sesión)

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

El token de acceso del panel dura aproximadamente 15 minutos. Cargar el panel intercambia la cookie de actualización de larga duración por una nueva, por lo que la actualización sin cabeza sigue funcionando mientras SumUp mantenga la sesión iniciada. La cookie se escribe en ~/.sumup-cli/session-cookie.txt con modo 600.

sumup auth status imprime exactamente cuántos segundos quedan.

La actualización sin cabeza depende del navegador en el que se ejecute el perfil. Un Chrome o Edge real pasa; Brave no, porque Cloudflare retiene la redirección de autenticación en un Brave sin cabeza, por lo que allí auth capture necesita --login y una ventana visible cada vez que el token caduca. De cualquier manera, un perfil con sesión iniciada sigue siendo redirigido a través de auth.sumup.com para intercambiar su cookie de actualización, por lo que el código espera a que ese rebote se estabilice en lugar de leer la URL inmediatamente después de la navegación y concluir erróneamente que ha cerrado sesión.

playwright-core se usa deliberadamente: no incluye navegadores y reutiliza una compilación de Chromium ya en la máquina en lugar de descargar 150 MB. Apunta SUMUP_CHROMIUM_PATH a un binario si no se encuentra ninguno.

Acceso a la API pública (clave)

La clave que SumUp te muestra por defecto es una clave pública (sup_pk_*) y su documentación dice que no la uses. Devuelve 401 en /v0.1/me. Necesitas una clave secreta:

me.sumup.com → profile → For Developers → Toolkit → API Keys → Create

Cópiala inmediatamente, SumUp no la almacena. Luego:

sumup auth login --api-key sup_sk_xxxxx

Uso

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 es la exportación de contabilidad detallada: una fila por línea de artículo con Datum, Transaktionsnummer, Zahlungsmethode, Beschreibung, Kategorie, Artikelnummer, Preis (brutto), Preis (netto), Steuer, Steuersatz. Los encabezados de columna siguen --locale, así que pasa --locale en-GB para inglés.

Los diez informes del Centro de descargas están conectados. El tipo de salida se detecta a partir de la respuesta, por lo que los PDF, los .xls heredados y los zip se escriben como bytes, mientras que los CSV obtienen una marca BOM UTF-8 para Excel. Pasa -o o un archivo se nombra automáticamente bajo out/.

Hay deliberadamente dos rutas para ventas y pagos. El grupo sales usa la sesión del panel y funciona hoy sin ninguna clave. Los grupos transactions y payouts usan la API pública documentada, que es más estable y adecuada para cron, pero necesita una clave secreta sup_sk_.

La salida CSV está separada por punto y coma con una marca BOM UTF-8, por lo que Excel en una configuración regional suiza lo abre con diéresis y emoji intactos y sin diálogo de importación.

Cómo se calcula la ganancia

sumup profit combina dos informes, porque ninguno tiene ambos lados:

El IVA no necesita resta: SumUp ya calcula Gewinn sobre el precio neto.

Tres trampas, todas encontradas al conciliar con las propias cifras de SumUp:

1. El informe de transacciones lista cada pago con tarjeta dos veces, una como Zahlung y otra como Auszahlung, con la misma comisión. Sumar ciegamente duplica las comisiones. Solo cuentan las filas Zahlung.

2. Ese informe cubre solo pagos con tarjeta. El efectivo nunca aparece en él, por lo que los ingresos totales provienen del informe de artículos y no se aplica ninguna comisión al efectivo.

3. Los artículos sin precio de costo reportan un Gewinn en blanco. Se muestran como revenueWithoutCost en lugar de contarse como ganancia o pérdida pura.

El resultado es una contribución operativa, no un Nettogewinn final: es antes de alquiler, salarios y cualquier cosa en el módulo Ausgaben.

Edición de productos

Usa el ciclo de ida y vuelta CSV. Es el propio mecanismo de edición masiva de SumUp, por lo que no necesita un endpoint de escritura con ingeniería inversa:

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

Luego súbelo, ya sea con Importieren en la página de Artikel o con sumup catalog import (abajo). Nunca toques las columnas Item id (Do not change) o Variant id (Do not change); así es como SumUp empareja las filas con los registros.

Registro de una entrega

El caso común no es una edición libre, sino una factura de proveedor: llegaron n cajas, aumenta el stock, no cambies nada más. Eso es un solo comando.

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

Cuatro cosas que hace a propósito:

• Solo se mueve la celda Quantity. Un artículo que ya existe nunca se re-precifica en un reabastecimiento, incluso cuando el precio neto del proveedor ha cambiado. El costo y el precio de venta se trasladan sin cambios.

• El stock se lee en vivo, por lo que la entrega se aplica sobre lo que dice el catálogo ahora en lugar de sobre una exportación de la semana pasada. --base <file> anula eso cuando ya tienes una exportación reciente a mano.

• La salida es un archivo parcial, encabezado más solo las filas tocadas. SumUp empareja por Item id, por lo que las otras 680 variantes quedan fuera de la transacción y nada puede ser sobrescrito por una columna desactualizada.

• Los bytes no tocados permanecen intactos. Las filas se empalman, no se re-serializan, por lo que las comillas propias de SumUp sobreviven, incluidos los nombres de artículo con espacios finales que cita y que un escritor CSV simple no haría. La salida es LF, sin BOM, exactamente lo que emite el exportador.

Cualquier cosa que no pueda registrar de forma segura se informa y se omite en lugar de adivinarse: un SKU que no está en el catálogo, un SKU que aparece en más de una fila (lo que realmente sucede: dos productos diferentes escritos con el mismo SKU), o un artículo con seguimiento de inventario desactivado. --dry-run muestra la tabla sin escribir, --set trata los números como el stock resultante en lugar de como una entrega, y el resultado se pasa por validate antes de escribirse.

Subirlo

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

Todavía no hay un endpoint de importación al que llamar, por lo que esto impulsa el propio diálogo del panel en un navegador: Weitere Optionen en la barra de herramientas, la entrada Import en ese menú, la entrada de archivo detrás de él, luego SELECTORS.IMPORT.CONTINUE_BUTTON. SumUp envía esos atributos data-selector por sí mismo, que sobreviven a la traducción y al cambio de nombres de clase, por lo que el flujo se guía por ellos en lugar de por las etiquetas de los botones. Ten en cuenta que cada fila de producto también tiene un botón "Aktionen"; coincidir con ese texto golpea un menú de fila en lugar de la barra de herramientas.

Tres cosas que vale la pena saber:

• Necesita una ventana visible a menos que el perfil se ejecute en un Chrome o Edge real, ya que Cloudflare no dejará pasar un Brave sin cabeza a través del rebote de autenticación. --headless está ahí para los navegadores que lo logran.

• Sin --yes se degrada a una simulación. Una importación muta un catálogo en vivo, por lo que el silencio no es consentimiento. El archivo se valida antes de que siquiera se inicie el navegador.

• El diálogo no dice nada al tener éxito, por lo que el comando lee el catálogo de nuevo después y verifica que ahora dice lo que decía el archivo. Esa verificación es la confirmación real; --no-verify la desactiva.

Verificado de extremo a extremo el 2026-08-18 importando un archivo de una fila, leyendo el cambio de nuevo desde el catálogo en vivo e importando el valor original nuevamente.

La API de escritura directa por artículo todavía no está habilitada. Los endpoints de lectura se mapearon a partir del tráfico real, pero la forma de escritura nunca se capturó, y tanto la CLI como la herramienta MCP se niegan en lugar de lanzar un PUT adivinado a un catálogo en vivo.

Para habilitar escrituras directas, guarda un producto en el panel mientras capturas tráfico, luego ejecuta sumup discover en la captura y completa src/core/session/endpoints.ts. Las escrituras aún se simularían por defecto, necesitando --yes (CLI) o confirm: true (MCP).

Re-mapeo de la API cuando SumUp la cambia

1. Inicia sesión en me.sumup.com, DevTools → Network → marca Preserve log

2. Haz clic en las pantallas que te interesen

3. Haz clic derecho en la lista de solicitudes → Save all as HAR with content

sumup discover capture.har --catalog-only

Agrupa el tráfico por método y plantilla de ruta, colapsando ids, e informa parámetros de consulta, claves del cuerpo de la solicitud y forma de la respuesta. Un HAR contiene un token de sesión en vivo; .gitignore ya excluye *.har.

Las cargas de muestra del mapeo del 2026-08-17 están en captures/ (gitignored).

Servidor MCP

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

17 herramientas:

sumup_catalog_stock con low: true combina bien con sumup_sales_list para decisiones de reposición, y sumup_catalog_restock convierte el pedido resultante en un archivo de importación una vez que llega.

Mapa completo de la API

docs/api-map.md documenta toda la superficie descubierta recorriendo cada página del panel: aproximadamente 60 endpoints entre catálogo, ventas, pagos, gestión de efectivo, clientes, miembros, gastos, tienda en línea, facturación y enlaces de pago, además de las convenciones de unidades y las lagunas conocidas.

Notas

• Node 20 o superior, usa fetch integrado.

• El @sumup/sdk oficial no se usa deliberadamente: todavía está marcado como sujeto a cambios que rompen la compatibilidad, y la mitad interna necesita una capa HTTP personalizada de todos modos, por lo que ambas mitades comparten un cliente en src/core/http.ts con reintentos y retroceso por límite de tasa.

• Nunca hagas commit de .env, .session-cookie.txt, *.har ni captures/. Tanto un archivo HAR como una cookie de sesión contienen un token activo para tu cuenta.

Contribuciones

Las issues y las pull requests son bienvenidas, especialmente para endpoints que esta herramienta no ha mapeado, otras configuraciones regionales y cambios en el panel que rompan algún selector. Si SumUp mueve algo, sumup discover sobre un HAR nuevo es la forma más rápida de averiguar qué, y src/core/session/endpoints.ts es el lugar donde corresponde la respuesta.

Licencia

MIT, consulta LICENSE.