Datenformate & IntegrationData Formats & Integration

Welche Daten BEEP! erwartet (Input) und welche BEEP! zurückgibt (Output). Von POS über API bis Transaktions-Export.

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

Datenfluss-ÜbersichtData Flow Overview

POS / ERP

Korona, RPOS,
Excel, SAP

Produkte, Preise

→ API / Sync

BEEP! API

europe-west6
Firebase

Transaktionen

Webhooks / API →

Ihr System

Buchhaltung,
Analytics, BI

INPUT (HändlerMerchant → BEEP!)

Produktdaten (EAN, Name, Preis, MwSt.)Product data (EAN, name, price, VAT)
Angebotsdaten (Rabatt, Gültigkeit)Offer data (discount, validity)
Store-Stammdaten (Adresse, Logo)Store master data (address, logo)
Produktbilder (JPEG/PNG)Product images (JPEG/PNG)

OUTPUT (BEEP! → HändlerMerchant)

Transaktionsdaten (Checkout, Items)Transaction data (checkout, items)
Digitale Belege (PDF, JSON)Digital receipts (PDF, JSON)
Analytics (Scans, Umsatz, Klicks)Analytics (scans, revenue, clicks)
Webhook-Events (Echtzeit)Webhook events (real-time)

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 Händler-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
API: POST /bulkImportProducts	Batch-Import großer Kataloge	JSON Array	500 / Batch
Excel-Upload (Händler-App)	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": "4000000000001", // EAN-13 (13 Stellen) oder EAN-8 (8 Stellen) "name": "Bio-Vollmilch 3,5%", // max. 120 Zeichen "price": 1.49, // EUR Dezimal (kein Integer!), aktueller Verkaufspreis "oldPrice": 1.79, // EUR Dezimal, optional. Ursprungspreis (wird durchgestrichen angezeigt, z.B. im C&C-Picker) "vat": 7, // 7 (ermäßigt) oder 19 (normal) "storeId": "store_abc123", // Welcher Store? (Pflicht für registerProductToStore) // === OPTIONALE FELDER === "category": "Molkerei", // Für Katalog-Filterung "unit": "Liter", // Mengeneinheit "brand": "BioHof", // Marke "description": "Frische Bio-Vollmilch", // 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 "flags": { "requiresHumanVerification": false // true = Altersverifikation pflicht (z.B. Alkohol) }, // === SYSTEM-FELDER (von BEEP! gesetzt) === "createdAt": "2026-02-27T10:00:00.000Z", "updatedAt": "2026-02-27T10:00:00.000Z", "nameLower": "bio-vollmilch 3,5%", // Automatisch: Name lowercase, für Produkt-Suche/Autocomplete "brandLower": "biohof" // Automatisch: Marke lowercase, für Produkt-Suche/Autocomplete }

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 4000000000001,Bio-Vollmilch 3-5%,1.49,7,Molkerei,Liter,BioHof,Frische Bio-Vollmilch,true,false 4000000000002,Schwarzbier 0-5l,1.19,19,Getränke,Flasche,Klosterbrau,Fränkisches Schwarzbier,false,true 4000000000003,Butterbrezel,0.89,7,Backwaren,Stück,Backstube,Frisch gebackene Butterbrezel,false,true

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

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

// v1.2.0+. Breaking change: storeIds[] + products[] (kein storeId/discountPrice/originalPrice) { // === PFLICHTFELDER === "storeIds": ["store_abc123"], // 1 Store = LOCAL, 2-10 = MULTI_STORE usw. "title": "Bio-Vollmilch Sonderangebot", // max. 80 Zeichen "products": [ { "ean": "4000000000001", // Muss im Katalog existieren "discountPrice": 1.19, // EUR Dezimal, Aktionspreis "originalPrice": 1.49 // EUR Dezimal, Streichpreis } ], "validFrom": "2026-03-01T00:00:00.000Z", "validTo": "2026-03-07T23:59:59.000Z", // === REICHWEITE (auto-ermittelt aus storeIds.length) === // LOCAL: 1 Store | MULTI_STORE: 2-10 | CITY_WIDE: 11-30 | REGIONAL: 31-100 | NATIONAL: 100+ // === OPTIONALE FELDER === "description": "Nur solange Vorrat reicht", "imageUrl": "https://...", // Angebotsbild (überschreibt Produktbild) "quantity": 500, // Kontingent (optional) // === SYSTEM-FELDER (von BEEP! gesetzt) === "offerId": "off_xyz789", "groupId": "grp_uuid", // Gruppen-ID für Multi-Store Kopien "storeCount": 1, "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 bis 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 // === PRODUKTSICHERUNG (v1.7.0+, optional) === "securityTagMode": "manual", // "none" (default) | "manual" | "station" | "rfid" "securityTagHint": "Bitte nach Bezahlung die Produkte an der Kasse vorzeigen." // Freitext, optional }

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 "checkoutSessionId": "cs_live_...", // PSP 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": "Bio-Vollmilch 3,5%", "ean": "4000000000001", // wenn verfügbar "priceUnit": 149, // Cent (Einzelpreis) "quantity": 2, "vat": 7, "totalCent": 298 // priceUnit * quantity }, { "name": "Schwarzbier 0,5l", "ean": "4000000000002", "priceUnit": 119, "quantity": 1, "vat": 19, "totalCent": 119 } ], // === 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,...", // === PRODUKTSICHERUNG (v1.7.0+, nur wenn securityTagMode != "none") === "securityTagMode": "manual", // "manual" | "station" | "rfid" "securityTagStatus": "pending", // "pending" | "deactivated" "securityTagHint": "Bitte nach Bezahlung Produkte an der Kasse vorzeigen." // Custom Händler-Hinweis (optional) }

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 POST /fetchPurchase

✓ Für Buchhaltungs-Integration

PDF (Landing Page)

Rendern via receiptUrl aus der Transaktion

✓ TSE-konform, druckfähig

Analytics-ExportAnalytics Export

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 Alle gängigen PSPs (z.B. Adyen, Mollie, Payone, Unzer, SumUp) 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 importiert Produkte automatisch. Über die Developer API (syncPOS) kann derselbe Sync manuell für eigene Integrationen ausgelöst werden.The existing Korona sync imports products automatically. Via the Developer API (syncPOS) you can trigger the same sync manually for your own integrations.

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.