App entwickeln

Apps erweitern das Konto eines Restaurants durch beschränkten, widerrufbaren OAuth-Zugriff. Ihr Code läuft auf Ihren Servern; die Plattform hält die Registry, das Installationsledger und die Abrechnungsinfrastruktur. Diese Anleitung führt Sie von null bis zu einer installierten, abgerechneten App.

1. Registrieren Sie Ihre App

Erstellen Sie eine App im Partner-Dashboard: Name, Kategorie, die benötigten Scopes, eine optionale Webhook-URL und Ihr Abrechnungsmodell. Beim Absenden wird ein OAuth-Client (Client-ID + Secret) erzeugt und die App zur Überprüfung eingereicht. Sobald ein Admin sie genehmigt, erscheint sie im App Store und kann installiert werden.

2. Lassen Sie sich installieren

Ein Restaurantinhaber installiert Ihre App über deren App-Store-Detailseite und gewährt die von Ihnen angeforderten Scopes. Die Installation erstellt eine AppInstallation und belastet (bei kostenpflichtigen Apps) den ersten Zeitraum über sein Wallet.

3. Rufen Sie die API auf

Tauschen Sie ein OAuth-Token für das installierende Konto ein und rufen Sie dann die REST API damit auf. Melden Sie Nutzung, empfangen Sie Webhooks oder betten Sie eine Seite in ihr Dashboard ein — weiter unten behandelt.

OAuth & Tokens

Apps authentifizieren sich mit OAuth 2.0 (Laravel Passport). Ihre Client-Anmeldedaten stammen aus dem Partner-Dashboard. Verwenden Sie den Standard-Authorization-Code-Flow; das gewährte Token trägt die Scopes, die der Inhaber bei der Installation genehmigt hat.

# Exchange an authorization code for an access token
curl -X POST https://www.menubarcode.comoauth/token \
  -d grant_type=authorization_code \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d redirect_uri=YOUR_REDIRECT \
  -d code=AUTH_CODE

# Call the API with the returned bearer token
curl https://www.menubarcode.com/api/v1/restaurants \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Accept: application/json"

Tokens sind beschränkt: ein Aufruf, der orders:read benötigt, schlägt fehl, sofern der Inhaber es nicht gewährt hat. Fordern Sie den minimalen Satz an — Prüfer kontrollieren dies.

Session-Tokens

Für kurzlebige Server-zu-Embed-Aufrufe erzeugen Sie ein Session-Token aus einer aktiven Installation. Tokens verfallen nach 60 Sekunden.

GET https://www.menubarcode.comapps/{appId}/session-token
# → { "token": "…", "expires_in": 60 }

Eingebettete Apps

Wenn Ihre App eine embed_url, deklariert, hostet die Plattform sie in einem iframe im Dashboard des Inhabers unter /apps/{appId}/embed. Kombinieren Sie es mit einem Session-Token (oben), um die eingebettete Seite ohne vollständigen OAuth-Roundtrip zu authentifizieren.

Webhooks

Abonnieren Sie Events an der webhook_url. Zustellungen werden in eine Warteschlange gestellt, wiederholt und mit dem Standard Webhooks -Schema mithilfe des Signatur-Secrets Ihrer App signiert. Ihr Endpunkt muss eine öffentliche HTTPS-URL sein (keine privaten/Loopback-/Metadata-Hosts) und 2xx schnell zurückgeben.

# A delivery your endpoint receives
POST https://your-app.com/webhooks
webhook-id: msg_...
webhook-timestamp: 1710000000
webhook-signature: v1,BASE64_HMAC
Content-Type: application/json

{ "type": "order.paid", "data": { "order_id": 123, ... } }

Verifizieren Sie die Signatur gegen Ihr Secret, bevor Sie einem Payload vertrauen. Siehe die Event-Liste.

Nutzungsabrechnung

Nutzungsabgerechnete Apps messen den Verbrauch durch das Melden von Einheiten. Jede Meldung wird dem Wallet des Inhabers zu Ihrem Stückpreis belastet. Übergeben Sie eine eindeutige ref um eine Meldung idempotent zu machen (eine Wiederholung mit derselben Ref wird ignoriert).

curl -X POST https://www.menubarcode.com/api/app/usage \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -d quantity=1 \
  -d ref=unique-key-per-event

Der Endpunkt gibt zurück 403 wenn das Token nicht zu einer registrierten App gehört oder die App nicht für das Konto installiert ist.

Anleitungen

Wählen Sie einen Abrechnungstyp

• Kostenlos — keine Gebühr bei der Installation.
• Wiederkehrend — ein Festpreis, der jeden Abrechnungszeitraum (standardmäßig 30 Tage) vom Wallet des Inhabers abgebucht wird.
• Nutzungsbasiert — ein Stückpreis, der abgerechnet wird, während Sie die Nutzung melden.

Fordern Sie Scopes verantwortungsvoll an

Fordern Sie nur Scopes an, die Ihre App verwendet. Das Ändern von Scopes bei einem Live-Listing schickt die App zurück in die Überprüfung. Siehe die Scopes-Referenz.

Aufräumen bei Deinstallation

Wenn ein Inhaber deinstalliert, widerruft die Plattform die Tokens der App und löst ein app/uninstalled -Event aus. Stoppen Sie Hintergrundarbeiten und löschen Sie gespeicherte Daten für dieses Konto, wenn Sie es erhalten.

Scopes-Referenz

Aus der OAuth-Scope-Registry der Plattform übernommen.

Webhook-Events

Events, die Sie heute abonnieren können:

Listing- & Überprüfungsanforderungen

Bevor ein Admin Ihre App genehmigt, muss sie:

• Nur die Scopes anfordern, die sie verwendet, jeweils in der Beschreibung begründet.
• Einen funktionierenden Webhook-Endpunkt bereitstellen (öffentliches HTTPS), wenn sie Events abonniert.
• Korrekte Preise angeben — die Preistabelle auf Ihrer Detailseite wird daraus generiert.
• Einen klaren Slogan, eine Beschreibung, eine Kategorie und mindestens einen Screenshot enthalten.
• Die Deinstallation sauber abwickeln (Zugriff widerrufen, Abrechnung stoppen, Kontodaten löschen).

Metadaten-Änderungen (Slogan, Beschreibung, Screenshots, Links) werden sofort live geschaltet; Preis- oder Scope-Änderungen stellen die Überprüfung erneut in die Warteschlange.