Datenformate & IntegrationData Formats & Integration

Verstehe, welche Daten BEEP! erwartet (Input) und welche Daten BEEP! zurückgibt (Output). Vom POS-System über die API bis zum Transaktions-Export.

Understand what data BEEP! expects (input) and what data BEEP! returns (output). From POS system via API through to transaction export.

Datenfluss-ÜbersichtData Flow Overview

🏪

POS / ERP

Korona, RPOS,
Excel, SAP

Produkte, Preise

→ API / Sync

⚡

BEEP! API

europe-west1
Firebase

Transaktionen

Webhooks / API →

📊

Ihr System

Buchhaltung,
Analytics, BI

INPUT (Händler → BEEP!)

📦 Produktdaten (EAN, Name, Preis, MwSt.)
🏷️ Angebotsdaten (Rabatt, Gültigkeit)
🏪 Store-Stammdaten (Adresse, Logo)
📸 Produktbilder (JPEG/PNG)

OUTPUT (BEEP! → Händler)

💳 Transaktionsdaten (Checkout, Items)
🧾 Digitale Belege (PDF, JSON)
📈 Analytics (Scans, Umsatz, Klicks)
🔔 Webhook-Events (Echtzeit)

Unterstützte POS-SystemeSupported POS Systems

✓ Nativ unterstützt

Korona POS

Vollständiger bidirektionaler Sync. Produkte, Preise und Kassenumsätze werden automatisch synchronisiert.

↑ Via CSV/API

Excel / CSV

Manuelle und automatisierte Imports via Excel-Upload in der Fermat-App oder via API.

⚙ Custom Webhook

Beliebige POS/ERP

Jedes System, das HTTP-Calls macht. BEEP! empfängt Produktupdates via POST /insertProduct.

Import-MethodenImport Methods

Methode	Use Case	Format	Limit
API: POST /insertProduct	Automatisierter POS-Sync, Echtzeit-Updates	JSON + multipart	1 Produkt / Call
Bulk API (planned)	Batch-Import großer Kataloge	JSON Array	500 / Batch
Excel-Upload (Fermat)	Manuelle Imports durch Store Manager	.xlsx	10.000 Zeilen
Korona POS Sync	Automatischer Nacht-Sync aus Korona	Korona API	Unbegrenzt

Produkt-DatenformatProduct Data Format

Produktdaten sind EAN-basiert. Jedes Produkt wird über seinen EAN-13 oder EAN-8 Barcode eindeutig identifiziert. Gleiches EAN in verschiedenen Stores = gleiches Produkt, unterschiedliche Preise.

Product data is EAN-based. Each product is uniquely identified by its EAN-13 or EAN-8 barcode. Same EAN in different stores = same product, different prices.

JSON: Produkt-Objekt

{ // === PFLICHTFELDER === "ean": "4104420044052", // EAN-13 (13 Stellen) oder EAN-8 (8 Stellen) "name": "Bionade Holunder 0,5L", // max. 120 Zeichen "price": 1.29, // EUR Dezimal (kein Integer!) "vat": 7, // 7 (ermäßigt) oder 19 (normal) "storeId": "store_abc123", // Welcher Store? (Pflicht für registerProductToStore) // === OPTIONALE FELDER === "category": "Getränke", // Für Katalog-Filterung "unit": "Flasche", // Mengeneinheit "brand": "Bionade", // Marke "description": "Bio-Limo...", // Kurzbeschreibung (max. 300 Zeichen) "imageUrl": "https://...", // Bereits hochgeladen (via uploadImageToProduct) "weight": "0.5kg", // Gewicht / Volumen als String "isOrganic": true, // Bio-Label "isVegan": true, // Vegan-Label "allergens": [], // Allergene-Liste // === SYSTEM-FELDER (von BEEP! gesetzt) === "createdAt": "2026-02-27T10:00:00.000Z", "updatedAt": "2026-02-27T10:00:00.000Z", "syncedFromKorona": false, // true wenn vom Korona-Sync "koronaProductId": null // Korona-interne ID wenn via Sync }

MwSt.-Sätze

Wert	Gilt für	Beispiele
7	Ermäßigter Steuersatz	Lebensmittel, Getränke (außer Alkohol), Bücher
19	Normaler Steuersatz	Alkohol, Tabak, Non-Food, Elektronik

Excel / CSV ImportExcel / CSV Import

Für manuelle Bulk-Imports akzeptiert BEEP! eine Excel-Datei (.xlsx) mit folgendem Schema. Lade die Vorlage herunter und befülle sie mit deinen Produktdaten:

For manual bulk imports BEEP! accepts an Excel file (.xlsx) with the following schema. Download the template and fill it with your product data:

CSV: Spalten (Headerzeile)

ean,name,price,vat,category,unit,brand,description,is_organic,is_vegan 4104420044052,Bionade Holunder 0-5L,1.29,7,Getränke,Flasche,Bionade,Bio-Limonade,true,true 4000521009985,Lay's Classic 175g,1.79,19,Snacks,Packung,Lay's,,false,false 4031700399215,Zott Monte Riegel,0.99,7,Süßwaren,Stück,Zott,,false,false

⚠️

Wichtige Regeln für den CSV-Import:

EAN muss exakt 8 oder 13 Stellen haben (ohne führende Nullen)
Preis als Dezimalzahl mit Punkt (nicht Komma): 1.29 nicht 1,29
vat muss genau 7 oder 19 sein
Keine Sonderzeichen in der EAN-Spalte
Enkoding: UTF-8

Angebots-DatenformatOffer Data Format

GO (ab 17,99 €/Mo

Angebote referenzieren immer ein Produkt über seine EAN. Das Produkt muss bereits im Store-Katalog vorhanden sein.

Offers always reference a product by its EAN. The product must already exist in the store catalog.

JSON: Angebots-Objekt

{ // === PFLICHTFELDER === "storeId": "store_abc123", "productEan": "4104420044052", // Muss im Katalog existieren "title": "Bionade zum Sparpreis", // max. 80 Zeichen "discountPrice": 0.99, // EUR Dezimal, neuer Aktionspreis "originalPrice": 1.29, // EUR Dezimal, durchgestrichener Preis "validFrom": "2026-03-01T00:00:00.000Z", "validUntil": "2026-03-07T23:59:59.000Z", // === REICHWEITE === "scope": "LOCAL", // "LOCAL" → 1 Store, 1 Woche: 14,99 € // "MULTI_STORE" → 2–10 Stores, 1 Woche: 49 € // "CITY_WIDE" → 11–30 Stores, 1 Woche: 149 € // "REGIONAL" → 31–100 Stores,1 Woche: 399 € // "NATIONAL" → 100+ Stores, 1 Woche: 800 € // === OPTIONALE FELDER === "description": "Nur solange Vorrat reicht", "imageUrl": "https://...", // Angebotsbild (überschreibt Produktbild) "storeIds": ["store_abc", "store_def"], // Nur bei MULTI_STORE+ "quantity": 500, // Kontingent (optionale Begrenzung) // === SYSTEM-FELDER (von BEEP! gesetzt) === "offerId": "off_xyz789", "discountPercent": 23, // auto-berechnet: (1 - 0.99/1.29) * 100 "status": "ACTIVE", // "DRAFT" | "ACTIVE" | "EXPIRED" | "ARCHIVED" "clickCount": 0, "favoritedCount": 0, "createdAt": "2026-02-27T10:00:00.000Z" }

Store-StammdatenStore Master Data

JSON: Store-Objekt (vollständig)

{ "id": "store_abc123", "name": { "legal": "Mustermann GmbH", // Handelsregister-Name "trading": "Frische Ecke Mitte" // Anzeigename in der BEEP!-App }, "address": { "street": "Hauptstraße 12", "city": "Berlin", "postalCode": "10115", "countryCode": "DE" // ISO 3166-1 alpha-2 }, "coordinates": { "latitude": 52.5200, "longitude": 13.4050 }, "phone": "+49 30 12345678", // E.164 Format "email": "info@frische-ecke.de", "website": "https://frische-ecke.de", "media": { "logo": "https://storage.googleapis.com/...", // min. 200x200px "cover": "https://storage.googleapis.com/..." // 1200x400px empfohlen }, "social": { "instagram": "@frischeecke", "facebook": "frischeecke.berlin", "tiktok": "@frischeecke" }, "mode": "live", // "demo" | "live" "package": "grow", // "discover" | "assist" | "go" | "grow" | "prime" "hasScanAndGo": true, "hasOffers": true, "rating": 4, // 0–5 "openingHours": { // optional "monday": "08:00–20:00", "tuesday": "08:00–20:00", // ... }, "pspAccountId": "acct_1ABC...", // PSP-Account des Händlers (für Scan & Go Payments) "receiptCount": 1247 // Auto-incrementiert vom System }

Transaktions-DatenformatTransaction Data Format

GROW

Jede abgeschlossene Scan & Go Transaktion wird in der Firestore Collection purchase gespeichert und über Webhooks an dein System gesendet.

Every completed Scan & Go transaction is stored in the Firestore collection purchase and sent to your system via webhooks.

JSON: Transaktions-Objekt (purchase)

{ // === IDENTIFIKATION === "id": "txn_mP4kR9nX", // Firestore-Dokument-ID "sessionId": "sess_k7aB3xQm9wPz", // Scan & Go Session "userId": "usr_42", // Firebase Auth UID des Käufers "stripeSessionId": "cs_live_...", // Stripe Checkout Session // === STORE === "storeData": { "id": "store_abc123", "name": "Frische Ecke Mitte", "mode": "live", "address": { "street": "Hauptstraße 12", /* ... */ }, "logo": "https://storage.googleapis.com/..." }, // === ITEMS LISTE === "items": [ { "name": "Bionade Holunder 0,5L", "ean": "4104420044052", // wenn verfügbar "priceUnit": 129, // Cent (Einzelpreis) "quantity": 2, "vat": 7, "totalCent": 258 // priceUnit * quantity }, { "name": "Lay's Classic 175g", "ean": "4000521009985", "priceUnit": 179, "quantity": 1, "vat": 19, "totalCent": 179 } ], // === ZUSAMMENFASSUNG === "currency": "EUR", "subtotalCent": 437, // Summe aller items "vatBreakdown": { "7": { "net": 241, "tax": 17 }, // Cent "19": { "net": 150, "tax": 29 } }, "totalVatCent": 46, "totalCent": 437, // Brutto (Brutto = subtotal hier) // === STATUS & ZEITSTEMPEL === "status": "SUCCESS", // "CREATED" | "PENDING_PAYMENT" | "SUCCESS" | "UNLOADED" | "CANCELLED" "createdAt": 1740645682000, // Unix Timestamp ms "completedAt": 1740645720000, // === BELEG === "receiptUrl": "https://beep-c6786.web.app/receipt/...", "receiptQrCode": "data:image/png;base64,..." }

Beleg-FormatReceipt Format

Belege werden von BEEP! generiert und sind in zwei Formaten verfügbar:

Receipts are generated by BEEP! and available in two formats:

JSON (via API)

Strukturierte Daten über GET /fetchPurchase?id=...

✓ Für Buchhaltungs-Integration

PDF (Landing Page)

Rendern via receiptUrl aus der Transaktion

✓ TSE-konform, druckfähig

Analytics-ExportAnalytics Export

GO / GROW

Analytics-Daten können über die Firestore-Collections direkt abgerufen werden (für eigene BI-Tools) oder als aggregierte Report-JSONs via API:

Analytics data can be fetched directly from Firestore collections (for custom BI tools) or as aggregated report JSONs via API:

JSON: Analytics Report (Tages-Aggregat)

{ "storeId": "store_abc123", "date": "2026-02-27", "period": "daily", // "daily" | "weekly" | "monthly" // === SCAN & GO METRIKEN === "scanAndGo": { "sessions": 47, // Check-ins "completedCheckouts": 41, // Erfolgreiche Checkouts "abandonedRate": 12.7, // % "revenueCent": 189453, // €1.894,53 in Cent "avgBasketCent": 4621, // €46,21 Durchschnittsbon "itemsScanned": 284 }, // === ANGEBOTS-METRIKEN (GO-Paket) === "offers": { "activeOffers": 8, "totalClicks": 342, "totalFavorites": 89, "conversionRate": 26.0 // % der Kunden mit Angebot im Warenkorb }, // === STORE METRIKEN === "store": { "profileViews": 156, "newFollowers": 12, "totalFollowers": 847, "dmReceived": 7 } }

POS/ERP/PSP-Sync (generisch)

GROW

Der bidirektionale Sync läuft über die generischen API-Endpoints syncPOS, pushToPOS, syncERP, pushToERP, configurePSP, processPayment und refundPayment. BEEP! ist nicht an ein bestimmtes Kassensystem, ERP oder Zahlungsanbieter gebunden, der Händler nutzt sein eigenes System.

Bidirectional sync runs via the generic API endpoints syncPOS, pushToPOS, syncERP, pushToERP, configurePSP, processPayment and refundPayment. BEEP! is not tied to a specific POS system, ERP or payment provider; the merchant uses their own system.

Unterstützte Systeme (Beispiele)

POS-Systeme Korona, Vectron, Casio, Lightspeed, SumUp POS, Zettle ERP-Systeme SAP Business One, lexoffice, sevDesk, Xentral, weclapp PSP / Zahlungsanbieter Stripe, Adyen, Mollie, Payone, Unzer, SumUp Payments Generisches Feld-Mapping (POS → BEEP!) pos.article_number → ean pos.article_name → name pos.sell_price → price (EUR) pos.tax_rate → vat (7 oder 19) pos.category → category pos.unit → unit pos.image_url → imageUrl pos.external_id → externalProductId pos.receipt_number → receiptCount pos.revenue → scanAndGo.revenueCent

Korona POS: Integration

GROW

Korona ist das am häufigsten angebundene Kassensystem bei BEEP!. Die Synchronisation läuft über die syncPOS API mit system: "korona".

Korona is the most commonly connected POS system at BEEP!. Synchronization runs via the syncPOS API with system: "korona".

Korona → BEEP! Feld-Mapping

# Korona Cloud API → BEEP! Produkt korona.product.number → ean (EAN-13 Barcode) korona.product.name → name (Produktname) korona.product.price → price (EUR Dezimal) korona.product.taxRate → vat (7 oder 19) korona.commodity_group → category (Warengruppe) korona.product.sector → tags[] (Abteilung) korona.product.image → imageUrl (Produktbild URL) # Korona Kassendaten → BEEP! Transaktion korona.receipt.number → receiptNumber (Belegnummer) korona.receipt.total → totalCent (Cent-Konvertierung) korona.receipt.items[] → items[] (1:1 Mapping) korona.receipt.timestamp → createdAt (Unix Timestamp)

📋

Der bestehende Korona-Sync (Curie/ + syncKoronaStore.js) importiert Produkte automatisch. Über die Developer API kann derselbe Sync manuell für eigene Integrationen ausgelöst werden.

Custom POS: Eigene Integration

GROW

Für Kassensysteme, die nicht direkt unterstützt werden, nutze die generische POS-API. Du definierst das Feld-Mapping selbst und synchronisierst Produkte über bulkImportProducts oder syncPOS.

For POS systems not directly supported, use the generic POS API. You define the field mapping yourself and sync products via bulkImportProducts or syncPOS.

Integrations-Ablauf (Custom POS)

Schritt 1: POS-System konfigurieren POST /api/v1/syncPOS system: "custom" credentials: { apiUrl, apiKey, ... } Schritt 2: Produkte importieren (Bulk) POST /api/v1/bulkImportProducts products: [ { barcode: "4000000000001", name: "Produkt A", price: 1.99, vat: 7 }, { barcode: "4000000000002", name: "Produkt B", price: 2.49, vat: 19 }, ... (max. 500 pro Call) ] Schritt 3: Verkaufsdaten exportieren POST /api/v1/exportSalesData from: "2026-02-01", to: "2026-02-27" Schritt 4: An POS zurückschieben POST /api/v1/pushToPOS system: "custom" dataType: "transactions" records: [ ... ]

✅

Tipp: Nutze checkout.completed Webhooks, um Transaktionen in Echtzeit an dein POS zu pushen, ohne Polling.