Quickstart GuideQuickstart Guide

Dein erster BEEP! API-Call in unter 5 Minuten. Schritt 1 und 2 gelten fuer alle Pakete. In Schritt 3 waehlst du deinen Einstiegspunkt passend zu deinem Paket: DISCOVER, ASSIST, GO, GROW oder PRIME.

Your first BEEP! API call in under 5 minutes. Steps 1 and 2 apply to all packages. In Step 3 you choose your entry point matching your package: DISCOVER, ASSIST, GO, GROW or PRIME.

Alle Calls in diesem Guide nutzen die Sandbox. Dein Account wird automatisch imAll calls in this guide use the sandbox. Your account is automatically created in Test ModeTest Mode erstellt. Test-Keys beginnen mitcreated. Test keys start with bk_test_ und erzeugen niemals echte Transaktionen.and never generate real transactions.

Schritt 1: Developer Account & API-KeyStep 1: Developer Account & API Key

Erstelle deinen kostenlosen Developer-Account auf developer.beep-technologies.de/dashboard. Nach der Registrierung findest du deine Test-Keys im Dashboard:

Create your free developer account at developer.beep-technologies.de/dashboard. After signing up, find your Test Keys in the Dashboard:

Publishable Key

Secret Key

Der Secret Key (sk) ist nur serverseitig zu verwenden. Committe ihn nie in Git. Der Publishable Key (pk) kann im Client-Code genutzt werden.

The Secret Key (sk) is for server-side use only. Never commit it to Git. The Publishable Key (pk) can be used in client code.

Schritt 2: Sandbox-Store abrufenStep 2: Fetch Sandbox Store

In der Sandbox stehen 2 vorbereitete Test-Stores bereit. Hole dir die Store-ID die du in weiteren Calls benötigst:

The sandbox contains 2 pre-configured test stores. Fetch the store ID you need for subsequent calls:

curl

curl -G \ "https://europe-west6-beep-c6786.cloudfunctions.net/apiGateway/api/v1/fetchStores" \ -H "Authorization: Bearer ${BEEP_TEST_SK}"

200 OK

{ "data": [ { "id": "sandbox_store_001", "name": { "legal": "Sandbox Lebensmittel GmbH", "trading": "Sandbox Markt" }, "mode": "demo", "package": "grow", "address": { "street": "Unter den Linden 1", "city": "Berlin", "postalCode": "10117", "countryCode": "DE" } } ], "total": 2 }

Schritt 3: Ersten API-Call machenStep 3: Make your first API call

Wähle den Flow passend zu deinem BEEP!-Paket. Jeder Pfad zeigt den typischen Einstiegs-Call:

Choose the flow matching your BEEP! package. Each path shows the typical entry-level call:

Füge dein erstes Produkt via API in den Store-Katalog ein. Es erscheint sofort in der BEEP!-Nutzer-App als durchsuchbarer Katalogeintrag:

Insert your first product via API into the store catalogue. It immediately appears in the BEEP! user app as a searchable catalogue entry:

POST /insertProduct

curl -X POST \ "https://europe-west6-beep-c6786.cloudfunctions.net/apiGateway/api/v1/insertProduct" \ -H "Authorization: Bearer ${BEEP_TEST_SK}" \ -H "Content-Type: application/json" \ -d '{ "storeId": "sandbox_store_001", "ean": "4000000000001", "name": "Bio-Vollmilch 3,5%", "brand": "BioHof", "price": 1.49, "vat": 7, "category": "Molkerei", "unit": "Liter" }'

200 OK

{ "success": true, "productId": "sandbox_product_001", "storeId": "sandbox_store_001", "name": "Bio-Vollmilch 3,5%", "ean": "4000000000001", "price": 1.49, "createdAt": "2026-03-02T10:00:00.000Z" }

Das Produkt ist jetzt im Store-Katalog und in der BEEP!-App suchbar. Für Bulk-Imports nutze POST /bulkImportProducts (bis 500 Produkte pro Call) oder den Excel-Upload in der Händler-App.

The product is now in the store catalogue and searchable in the BEEP! app. For bulk imports use POST /bulkImportProducts (up to 500 products per call) or the Excel upload in the Merchant App.

Erstelle ein digitales Angebot und rolle es für einen oder mehrere Stores gleichzeitig aus. Kunden sehen es in der BEEP!-Nutzer-App in der Nähe der jeweiligen Filiale:

Create a digital offer and roll it out to one or more stores simultaneously. Customers see it in the BEEP! user app near the relevant branch:

POST /createOffer

curl -X POST \ "https://europe-west6-beep-c6786.cloudfunctions.net/apiGateway/api/v1/createOffer" \ -H "Authorization: Bearer ${BEEP_TEST_SK}" \ -H "Content-Type: application/json" \ -d '{ "storeIds": ["sandbox_store_001", "sandbox_store_002"], "title": "Frische Woche", "description": "Bio-Produkte bis zu 30% reduziert", "validFrom": "2026-03-03T00:00:00.000Z", "validUntil": "2026-03-09T23:59:59.000Z", "products": [ { "ean": "4000000000001", "name": "Bio-Vollmilch 3,5%", "originalPrice": 1.49, "discountPrice": 0.99 } ] }'

200 OK

{ "success": true, "offerId": "offer_abc123", "groupId": "grp_x1y2z3", "offerIds": ["offer_abc123", "offer_def456"], "storeCount": 2 }

groupId verknüpft alle Filial-Kopien des Angebots. Updates und Deletes via updateOffer/deleteOffer propagieren automatisch zu allen Filialen. Details in der Angebote-API-Dokumentation.

groupId links all branch copies of the offer. Updates and deletes via updateOffer/deleteOffer propagate automatically to all branches. Details in the Offers API documentation.

GO enthält Loyalty: Ab GO kannst du ein Treueprogramm (Stamps oder Points) aktivieren. Kunden sammeln Punkte per QR-Code, GPS Check-in und Click & Collect. Weiter mit dem Loyalty Quickstart.

GO includes Loyalty: Starting with GO you can activate a loyalty program (Stamps or Points). Customers earn points via QR code, GPS check-in and Click & Collect. Continue with the Loyalty Quickstart.

Das Check-in startet eine Scan & Go Session. In der BEEP!-Nutzer-App scannt der Kunde den Store-QR-Code. Per API kannst du das manuell triggern:

Check-in starts a Scan & Go session. In the BEEP! user app the customer scans the store QR code. Via the API you can trigger this manually:

POST /checkIn

curl -X POST \ "https://europe-west6-beep-c6786.cloudfunctions.net/apiGateway/api/v1/checkIn" \ -H "Authorization: Bearer ${BEEP_TEST_SK}" \ -H "Content-Type: application/json" \ -d '{ "storeId": "sandbox_store_001", "userId": "usr_test_consumer_42" }'

200 OK

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

Nachdem der Kunde seine Produkte gescannt hat, startet er den Checkout. Übergib die Session-ID und die Items-Liste:

After the customer has scanned their products, they start checkout. Pass the session ID and items list:

POST /startCheckout

curl -X POST \ "https://europe-west6-beep-c6786.cloudfunctions.net/apiGateway/api/v1/startCheckout" \ -H "Authorization: Bearer ${BEEP_TEST_SK}" \ -H "Content-Type: application/json" \ -d '{ "userId": "usr_test_consumer_42", "storeId": "sandbox_store_001", "sessionId": "sess_k7aB3xQm9wPz", "currency": "EUR", "items": [ { "name": "Bio-Vollmilch 3,5%", "priceUnit": 149, "quantity": 2, "vat": 7 }, { "name": "Schwarzbier 0,5l", "priceUnit": 119, "quantity": 1, "vat": 19 } ] }'

Hinweis: Das Zielkonto des Zahlungsdienstleisters wird nicht im Request übergeben. Es wird aus der Store-Konfiguration gelesen, die du zuvor über configurePSP gesetzt hast.

Note: The payment provider destination account is not passed in the request. It is read from the store configuration you set earlier via configurePSP.

priceUnit ist immer in Cent (Integer). vat ist 7 oder 19 (%). In der Sandbox werden keine echten Zahlungen ausgelöst.

priceUnit is always in cents (integer). vat is 7 or 19 (%). In the sandbox no real payments are triggered.

200 OK

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

PRIME gibt dir Zugriff auf alle Endpunkte. Hier ein typischer Analytics-Export mit Monatsumsatz, Top-Produkten und Belegdaten:

PRIME gives you access to all endpoints. Here is a typical analytics export with monthly revenue, top products and receipt data:

Fiskalisierung: Das Feld tse ist im Datenmodell vorhanden, wird derzeit aber nicht von einer zertifizierten Technischen Sicherheitseinrichtung befüllt. In der Sandbox liefert es feste Platzhalterwerte. Die Anbindung einer TSE ist geplant. Verwende dieses Feld nicht als Nachweis gegenüber dem Finanzamt.

Fiscalisation: The tse field exists in the data model but is currently not populated by a certified Technical Security Device. In the sandbox it returns fixed placeholder values. A TSE integration is planned. Do not use this field as evidence towards tax authorities.

POST /exportSalesData

curl -X POST \ "https://europe-west6-beep-c6786.cloudfunctions.net/apiGateway/api/v1/exportSalesData" \ -H "Authorization: Bearer ${BEEP_TEST_SK}" \ -H "Content-Type: application/json" \ -d '{"from": "2026-02-01", "to": "2026-02-28"}'

200 OK

{ "success": true, "data": { "period": { "from": "2026-02-01", "to": "2026-02-28" }, "summary": { "totalRevenue": 1847.93, "totalTransactions": 312, "topProducts": [{ "name": "Bio-Vollmilch", "sold": 89 }] } }, "_sandbox": true }

PRIME umfasst alle Endpunkte aus DISCOVER, ASSIST, GO und GROW plus Analytics-Export (exportSalesData, exportReceiptData). Rate Limit: 2.000 Req/Min. Analytics-API-Dokumentation

PRIME includes all endpoints from DISCOVER, ASSIST, GO and GROW plus analytics export (exportSalesData, exportReceiptData). Rate limit: 2,000 req/min. Analytics API documentation

Schritt 4: Webhook empfangenStep 4: Receive webhook

BEEP! sendet Events an deinen konfigurierten Webhook-Endpoint, z.B. checkout.completed nach einer Zahlung oder offer.published wenn ein Angebot live geht. So verifizierst du die Signatur:

BEEP! sends events to your configured webhook endpoint, e.g. checkout.completed after a payment or offer.published when an offer goes live. Here is how to verify the signature:

Node.js / Express

Nächste SchritteNext steps

Erkunde die API-Dokumentation für dein Paket:

Explore the API documentation for your package:

DISCOVER

API-ReferenzAPI Reference

Stores, Produkte, Katalog, DMsStores, products, catalogue, DMs

ASSIST

Zonen & QR-ChatZones & QR Chat

QR-Code-Zonen, In-Store-Chat (Haendler-App)QR code zones, in-store chat (Merchant App)

Angebote APIOffers API

Multi-Store-Angebote, groupId, cloneOfferMulti-store offers, groupId, cloneOffer

Click & Collect

Bestellungen erstellen & Status-UpdatesCreate orders & status updates

GROW

Scan & Go API

Check-in, Checkout, BelegdatenCheck-in, checkout, receipt data

GROW

POS/ERP/PSP-Sync

Kassensystem, ERP & Zahlungsanbieter anbindenConnect POS, ERP & payment providers

PRIME

Analytics & ExportAnalytics & Export

Erweiterte Analysen, Exports, Premium SupportAdvanced analytics, exports, premium support

GO+

Loyalty

Treueprogramme, Earning Methods, WalletLoyalty programs, earning methods, wallet

ALLE PAKETEALL PACKAGES

Webhooks

Alle Events, Payloads und Signatur-VerifikationAll events, payloads and signature verification