Créer une app

Les applications étendent le compte d'un restaurant via un accès OAuth cadré et révocable. Votre code s'exécute sur vos serveurs ; la plateforme gère le registre, le journal des installations et l'infrastructure de facturation. Ce guide vous accompagne de zéro jusqu'à une application installée et facturée à l'usage.

1. Enregistrez votre application

Créez une application dans le tableau de bord partenaire: nom, catégorie, les scopes dont vous avez besoin, une URL de webhook facultative et votre modèle de facturation. La soumission génère un client OAuth (client id + secret) et place l'application en révision. Une fois approuvée par un administrateur, elle apparaît dans l'App Store et peut être installée.

2. Faites-vous installer

Un propriétaire de restaurant installe votre application depuis sa page de détail dans l'App Store, en accordant les scopes que vous avez demandés. L'installation crée un AppInstallation et (pour les applications payantes) facture la première période via son portefeuille.

3. Appelez l'API

Échangez un token OAuth pour le compte qui installe, puis appelez l' API REST avec. Reportez l'usage, recevez des webhooks ou intégrez une page dans leur tableau de bord — détaillé ci-dessous.

OAuth et tokens

Les applications s'authentifient avec OAuth 2.0 (Laravel Passport). Vos identifiants client proviennent du tableau de bord partenaire. Utilisez le flux d'authorization code standard ; le token accordé porte les scopes que le propriétaire a approuvés à l'installation.

# 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"

Les tokens sont cadrés : un appel nécessitant orders:read échoue à moins que le propriétaire ne l'ait accordé. Demandez le minimum nécessaire — les évaluateurs le vérifient.

Tokens de session

Pour les appels serveur-vers-intégration de courte durée, générez un token de session à partir d'une installation active. Les tokens expirent après 60 secondes.

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

Applications intégrées

Si votre application déclare une embed_url, la plateforme l'héberge dans une iframe au sein du tableau de bord du propriétaire à /apps/{appId}/embed. Associez-la à un token de session (ci-dessus) pour authentifier la page intégrée sans un cycle OAuth complet.

Webhooks

Abonnez-vous aux événements sur votre webhook_url. Les livraisons sont mises en file, réessayées et signées avec le schéma Standard Webhooks à l'aide du secret de signature de votre application. Votre endpoint doit être une URL HTTPS publique (pas d'hôtes privés/loopback/metadata) et renvoyer 2xx rapidement.

# 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, ... } }

Vérifiez la signature avec votre secret avant de faire confiance à une charge utile. Consultez la liste des événements.

Facturation à l'usage

Les applications facturées à l'usage mesurent la consommation en reportant des unités. Chaque report est facturé au portefeuille du propriétaire à votre prix unitaire. Transmettez un ref unique pour rendre un report idempotent (un doublon avec le même ref est ignoré).

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

L'endpoint renvoie 403 si le token n'appartient pas à une application enregistrée ou si l'application n'est pas installée pour le compte.

Guides pratiques

Choisissez un type de facturation

• Gratuit — aucun frais à l'installation.
• Récurrent — un prix fixe facturé à chaque période de facturation (30 jours par défaut) depuis le portefeuille du propriétaire.
• À l’usage — un prix unitaire facturé au fur et à mesure que vous reportez l'usage.

Demandez les scopes de façon responsable

Ne demandez que les scopes utilisés par votre application. Modifier les scopes d'une publication en ligne renvoie l'application en révision. Consultez la référence des scopes.

Nettoyez à la désinstallation

Lorsqu'un propriétaire désinstalle, la plateforme révoque les tokens de l'application et déclenche un app/uninstalled événement. Arrêtez les traitements en arrière-plan et supprimez les données stockées pour ce compte dès sa réception.

référence des scopes

Reflété depuis le registre des scopes OAuth de la plateforme.

Événements de webhook

Événements auxquels vous pouvez vous abonner aujourd'hui :

Conditions de publication et de révision

Avant qu'un administrateur n'approuve votre application, elle doit :

• Ne demander que les scopes qu'elle utilise, chacun justifié dans la description.
• Fournir un endpoint de webhook fonctionnel (HTTPS public) si elle s'abonne à des événements.
• Déclarer une tarification exacte — le tableau des prix de votre page de détail en est généré.
• Inclure une accroche claire, une description, une catégorie et au moins une capture d'écran.
• Gérer proprement la désinstallation (révoquer l'accès, arrêter la facturation, supprimer les données du compte).

Les modifications de métadonnées (accroche, description, captures, liens) sont publiées immédiatement ; les changements de prix ou de scope replacent l'application en révision.