API ReferenceAPI Reference

Alle BEEP! Cloud Functions, Endpunkte, Parameter, Request/Response-Schemas. Alle Functions laufen in europe-west1.

All BEEP! Cloud Functions, endpoints, parameters, request/response schemas. All functions run in europe-west1.

Base URLBase URL

https://europe-west1-beep-c6786.cloudfunctions.net

AuthentifizierungAuthentication

Alle API-Calls erfordern einen Bearer Token im Authorization-Header. Nutze den Secret Key für serverseitige Calls.

All API calls require a Bearer token in the Authorization header. Use the Secret Key for server-side calls.

Header

Authorization: Bearer bk_test_sk_YOUR_KEY X-Beep-Store-Id: YOUR_STORE_ID # optional, für Store-spezifische Calls

Fehler-CodesError Codes

HTTP Code	FunctionsError	Beschreibung
400	`invalid-argument`	Fehlende oder ungültige Parameter
401	`unauthenticated`	Kein gültiger API-Key
403	`permission-denied`	Paket-Feature nicht freigeschaltet
404	`not-found`	Ressource nicht gefunden
409	`already-exists`	Ressource existiert bereits
500	`internal`	Interner Fehler

Error Response

{ "error": { "code": "invalid-argument", "message": "Missing required field: storeId", "status": 400 } }

Pagination

Listen-Endpunkte unterstützen cursor-basierte Pagination via limit und cursor. Der cursor ist das Dokument-ID des letzten Elements der vorherigen Seite.

List endpoints support cursor-based pagination via limit and cursor. The cursor is the document ID of the last item on the previous page.

Query Parameters (Liste)

GET /fetchPurchaseHistory?userId=usr_42&limit=20&cursor=purchase_abc123

GET /fetchStores

DISCOVER: kostenlos

Gibt alle Stores zurück, auf die der API-Key Zugriff hat. Im Sandbox-Modus werden 3 Test-Stores zurückgegeben.

Returns all stores the API key has access to. In sandbox mode 3 test stores are returned.

GET /fetchStores Liste aller zugänglichen Stores

Query Parameters

Parameter	Typ	Beschreibung
cityoptional	string	Filter nach Stadt
limitoptional	integer	Max. Ergebnisse (default: 50)

Response

200 OK

{ "data": [ { "id": "store_abc123", "name": { "legal": "Mustermann GmbH", "trading": "Frische Ecke Mitte" }, "address": { "street": "Hauptstraße 12", "city": "Berlin", "postalCode": "10115", "countryCode": "DE" }, "phone": "+49 30 12345678", "coordinates": { "latitude": 52.5200, "longitude": 13.4050 }, "mode": "live", "package": "grow", "hasScanAndGo": true, "hasOffers": true, "rating": 4, "receiptCount": 1247 } ], "total": 1 }

GET /fetchStore

DISCOVER: kostenlos

Gibt einen einzelnen Store zurück, inkl. Produktkatalog. Der API-Key darf nur den eigenen Store abrufen.

Returns a single store including the product catalog. The API key may only fetch its own store.

GET /fetchStore Einzelnen Store abrufen

Query Parameters

Parameter	Typ	Beschreibung
storeIdrequired	string	ID des Stores

Response

Gibt das Store-Objekt zurück (wie in fetchStores), ergänzt um ein products[]-Array mit allen Produkten des Stores.

Returns the store object (as in fetchStores), augmented with a products[] array containing all products of the store.

POST /insertStore

DISCOVER: kostenlos

Registriert einen neuen Store. Im Produktionsmodus wird eine Admin-Prüfung ausgelöst. Nutze alternativ submitStoreRegistration für die vollständige Registrierung mit Manager-Daten.

Registers a new store. In production mode an admin review is triggered. Alternatively use submitStoreRegistration for full registration with manager data.

POST /insertStore Neuen Store anlegen

Request Body

Parameter	Typ	Beschreibung
namerequired	object	`{ legal, trading }`
addressrequired	object	`{ street, city, postalCode, countryCode }`
phonerequired	string	Telefonnummer im E.164-Format

POST /checkIn

GROW

Startet eine neue Scan & Go Session für einen Kunden. Gibt eine sessionId zurück, die für den anschließenden Checkout benötigt wird.

Starts a new Scan & Go session for a customer. Returns a sessionId required for the subsequent checkout.

POST /checkIn Scan & Go Session starten

Request Body

Parameter	Typ	Beschreibung
storeIdrequired	string	ID des Stores
userIdrequired	string	Firebase Auth UID des Kunden

Response

200 OK

{ "success": true, "sessionId": "sess_k7aB3xQm9wPz", "storeId": "store_abc123", "userId": "usr_42", "checkedInAt": "2026-02-27T09:41:22.000Z", "message": "Check-in successful" }

POST /startCheckout

GROW

Initiiert den Stripe-Checkout für eine Scan & Go Session. Gibt eine Stripe-Checkout-URL zurück, zu der die BEEP-App weiterleitet.

Initiates the Stripe checkout for a Scan & Go session. Returns a Stripe checkout URL to which the BEEP app redirects.

POST /startCheckout Stripe Checkout initiieren

Request Body

Parameter	Typ	Beschreibung
userIdrequired	string	Firebase Auth UID des Kunden
storeIdrequired	string	ID des Stores
sessionIdrequired	string	Session-ID aus /checkIn
currencyrequired	string	ISO 4217, z.B. `EUR`
destinationrequired	string	PSP-Account-ID des Händlers (konfiguriert via `configurePSP`)
itemsrequired	array	Gekaufte Produkte (siehe unten)

Item-Objekt

Feld	Typ	Beschreibung
namerequired	string	Produktname (für Beleg)
priceUnitrequired	integer	Preis in Cent (z.B. 129 = 1,29 €)
quantityrequired	integer	Anzahl
vatrequired	integer	`7` oder `19` (MwSt.-Satz in %)

📌

Preise immer in Cent. MwSt. immer 7 (ermäßigt, z.B. Lebensmittel) oder 19 (normal). TSE-Konformität wird serverseitig sichergestellt.

Response

200 OK

{ "success": true, "transactionId": "txn_mP4kR9nX", "sessionId": "sess_k7aB3xQm9wPz", "stripeSessionId": "cs_test_a1B2c3D4", "checkoutUrl": "https://checkout.stripe.com/pay/cs_...", "total": 437, "currency": "EUR", "status": "PENDING_PAYMENT", "createdAt": "2026-02-27T09:41:55.000Z" }

Purchase Status Flow

CREATED → PENDING_PAYMENT → SUCCESS → CANCELLED

GET /fetchPurchase

GROW

GET /fetchPurchase?id={purchaseId} Einzelne Transaktion abrufen

Query Parameters

Parameter	Typ	Beschreibung
idrequired	string	Firestore-Dokument-ID der Transaktion

GET /fetchPurchaseHistory

GROW

GET /fetchPurchaseHistory?userId={uid} Transaktionshistorie eines Kunden

Parameter	Typ	Beschreibung
userIdrequired	string	Firebase Auth UID des Kunden
limitoptional	integer	Max. Ergebnisse (default: 50)

GET /fetchProducts

DISCOVER: kostenlos

Gibt alle Produkte im Katalog des Stores zurück, der dem API-Key zugeordnet ist.

Returns all products in the catalog of the store assigned to the API key.

GET /fetchProducts Alle Produkte des Stores

Query Parameters

Parameter	Typ	Beschreibung
categoryoptional	string	Filter nach Kategorie
limitoptional	integer	Max. Ergebnisse (default: 100)

GET /fetchProduct

DISCOVER: kostenlos

Gibt ein einzelnes Produkt zurück, per id (Firestore-ID) oder barcode (EAN).

Returns a single product by id (Firestore ID) or barcode (EAN).

GET /fetchProduct Einzelnes Produkt abrufen

Query Parameters

Parameter	Typ	Beschreibung
idone of	string	Firestore-Dokument-ID des Produkts
barcodeone of	string	EAN-13 oder EAN-8 Barcode

ℹ️

Entweder id oder barcode muss angegeben werden. Das Produkt muss dem Store des API-Keys gehören.

POST /insertProduct

DISCOVER

Fügt ein neues Produkt in den Store-Katalog ein. Vollständiges Datenformat-Guide: Datenformate →

Inserts a new product into the store catalog. Full data format guide: Data Formats →

POST /insertProduct Produkt in Katalog einfügen

Request Body (multipart/form-data)

Feld	Typ	Beschreibung
storeIdrequired	string	Store, in den das Produkt gehört
eanrequired	string	EAN-13 oder EAN-8 Barcode
namerequired	string	Produktname (max. 120 Zeichen)
pricerequired	number	Verkaufspreis in EUR (Dezimal)
vatrequired	integer	`7` oder `19`
categoryoptional	string	Kategorie (z.B. "Getränke")
unitoptional	string	Einheit (z.B. "Flasche", "kg")
imageoptional	file	Produktbild (JPEG/PNG, max. 5MB)

POST /registerProductToStore

DISCOVER: kostenlos

Verknüpft ein bestehendes Produkt mit dem Store des API-Keys. Das Produkt muss bereits über insertProduct angelegt worden sein.

Links an existing product to the store of the API key. The product must already have been created via insertProduct.

POST /registerProductToStore Produkt einem Store zuordnen

Request Body

Parameter	Typ	Beschreibung
productIdrequired	string	Firestore-ID des Produkts

POST /markPurchaseCancelled

GROW

Markiert eine Transaktion als storniert. Nur Transaktionen mit Status PENDING_PAYMENT oder SUCCESS können storniert werden. Bei bereits bezahlten Transaktionen wird ein Refund über den konfigurierten PSP ausgelöst.

Marks a transaction as cancelled. Only transactions with status PENDING_PAYMENT or SUCCESS can be cancelled. For already-paid transactions a refund is triggered via the configured PSP.

POST /markPurchaseCancelled Transaktion stornieren

Request Body

Parameter	Typ	Beschreibung
purchaseIdrequired	string	Firestore-ID der Transaktion
reasonoptional	string	Stornierungsgrund (für interne Dokumentation)

POST /generateCodes

GROW

Generiert QR-Codes für einen Store, z.B. für Tisch-Aufsteller, Eingangsbereich oder Marketing-Material. Gibt Base64-kodierte PNG-Bilder zurück.

Generates QR codes for a store, e.g. for table stands, entrance area or marketing material. Returns Base64-encoded PNG images.

POST /generateCodes Store QR-Codes generieren

Request Body

Parameter	Typ	Beschreibung
storeIdrequired	string	ID des Stores
typeoptional	string	`checkin` (default), `payment`, `profile`
sizeoptional	integer	Bildgröße in px (default: 512)

POST /generateReceiptQR

GROW

Generiert einen QR-Code, der zu einem digitalen Beleg führt. Der QR-Code enthält einen Token, über den der Beleg öffentlich (ohne Auth) aufrufbar ist.

Generates a QR code that leads to a digital receipt. The QR code contains a token through which the receipt can be accessed publicly (without auth).

POST /generateReceiptQR Beleg-QR generieren

Request Body

Parameter	Typ	Beschreibung
purchaseIdrequired	string	Firestore-ID der Transaktion

Response

200 OK

{ "success": true, "receiptUrl": "https://beep-c6786.web.app/receipt/...", "qrCode": "data:image/png;base64,...", "token": "rct_a1B2c3D4e5F6" }

GET /getReceiptFromToken

GROW

Holt den vollständigen Beleg über einen öffentlichen Token. Dieser Endpoint erfordert keine Authentifizierung: der Token selbst ist das Zugriffsrecht.

Fetches the complete receipt via a public token. This endpoint requires no authentication: the token itself is the access credential.

GET /getReceiptFromToken?token={token} Beleg via Token abrufen

Query Parameters

Parameter	Typ	Beschreibung
tokenrequired	string	Receipt-Token (aus `generateReceiptQR`)

Gibt die vollständigen Belegdaten zurück inkl. Items, MwSt.-Aufschlüsselung und TSE-Signatur. Siehe Beleg-Datenformat.

POST /submitStoreRegistrationRequest

ℹ️

Store-Registrierungsanfragen werden von einem BEEP! Admin manuell geprüft und genehmigt. Neue Stores starten automatisch mit dem DISCOVER-Paket (kostenlos).

POST /submitStoreRegistrationRequest Neue Store-Registrierung beantragen

Request Body

JSON

{ "storeData": { "name": { "legal": "Mustermann Getränkemarkt GmbH", "trading": "Getränke Mustermann" }, "address": { "street": "Hauptstraße 12", "city": "Berlin", "postalCode": "10115", "countryCode": "DE" }, "phone": "+49 30 12345678" }, "managerData": { "firstName": "Max", "lastName": "Mustermann", "email": "max@mustermann.de", "phone": "+49 171 9876543" } }

Response

200 OK

{ "success": true, "registrationId": "reg_7c3f8e1a-...", "message": "Registration request submitted. Awaiting admin approval." }

POST /approveStoreRegistration

⚠️

Nur Master Admin. Dieser Endpoint erfordert Master-Admin-Berechtigung und kann nicht mit regulären API-Keys aufgerufen werden. Händler erhalten eine E-Mail-Benachrichtigung nach Freigabe.

POST /approveStoreRegistration Registrierung genehmigen (Admin)

Request Body

Parameter	Typ	Beschreibung
registrationIdrequired	string	ID aus `submitStoreRegistration`
packageoptional	string	Start-Paket (default: `discover`)

Angebote (GO-Paket)

GO (ab 17,99 €/Mo

Angebote werden direkt in Firestore verwaltet. Dies ermöglicht Echtzeit-Updates ohne API-Latenz. Angebote sind in stores/{storeId}/offers abgelegt.

Offers are managed directly in Firestore. This enables real-time updates without API latency. Offers are stored under stores/{storeId}/offers.

Firestore: Offer Schema

Collection: stores/{storeId}/offers

{ "offerId": "off_abc123", "storeId": "store_xyz", "title": "Bionade zum Sparpreis", "productEan": "4104420044052", "originalPrice": 1.29, // EUR Dezimal "discountPrice": 0.99, // EUR Dezimal "discountPercent": 23, // auto-berechnet "validFrom": "2026-03-01T00:00:00.000Z", "validUntil": "2026-03-07T23:59:59.000Z", "scope": "LOCAL", // scope: "LOCAL" | "MULTI_STORE" | "CITY_WIDE" | "REGIONAL" | "NATIONAL" "status": "ACTIVE", // status: "DRAFT" | "ACTIVE" | "EXPIRED" | "ARCHIVED" "imageUrl": "https://storage.googleapis.com/beep-c6786.appspot.com/...", "createdAt": "2026-02-27T10:00:00.000Z", "updatedAt": "2026-02-27T10:00:00.000Z" }