Documentation développeur

Premiers pas

Créez un token API depuis votre tableau de bord, sous Tokens API et webhooks. Choisissez les read et/ou write et copiez le token — il n’est affiché qu’une seule fois.

Une vérification rapide que votre token fonctionne :

curl https://www.menubarcode.com/api/v1/restaurants \
  -H "Authorization: Bearer YOUR_TOKEN"

Authentification

Envoyez votre token en en-tête Bearer sur chaque requête :

Authorization: Bearer YOUR_TOKEN

Pour des tests rapides, vous pouvez aussi passer ?api_token=YOUR_TOKEN en paramètre de requête, mais l’en-tête est fortement recommandé pour que les tokens ne fuient jamais dans les logs.

Tokens à portée limitée

Au-delà du grossier read/write, un token peut être limité à des ressources précises avec des resource:action capacités. Ressources : restaurants, menu, orders, customers, analytics, drivers, webhooks; Actions read, write. Sélectionnez-les lors de la création du token dans le tableau de bord.

Règles de couverture : * accorde tout ; une portée :write accorde aussi ses :read; grossier read/write se comportent comme *:read / *:write. Une requête sans la portée requise renvoie 403. Anciens read/write les tokens ne sont pas affectés.

Les tokens sont hachés au repos (SHA-256) et peuvent avoir une expiration facultative. Révoquez n’importe quel token instantanément depuis le tableau de bord.

Limites de débit

L’API autorise 120 requêtes par minute par token. Le dépassement renvoie 429 Too Many Requests avec un en-tête Retry-After . Les en-têtes standard de limitation de débit sont inclus dans chaque réponse :

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118

Erreurs

Chaque erreur sur une route /api/v1 renvoie des codes de statut HTTP conventionnels et une seule enveloppe JSON — un message lisible message, un code machine stable code, et (à la validation) un détail par champ errors Carte

{ "message": "Invalid or expired token.", "code": "unauthenticated" }

{ "message": "The given data was invalid.",
  "code": "validation_failed",
  "errors": { "title": ["The title field is required."] } }

Pagination

Les endpoints de liste renvoient des enveloppes paginées façon Laravel. Utilisez le ?page= paramètre de requête pour parcourir les pages.

{
  "data": [ ... ],
  "current_page": 1,
  "last_page": 3,
  "per_page": 20,
  "total": 47
}

Lire restaurants et menu

Liste les restaurants détenus par le token, paginés (20 par page).

{
  "data": [
    { "id": 12, "title": "Nova Bistro", "slug": "nova-bistro",
      "url": "https://.../nova-bistro", "template": "linen",
      "created_at": "2026-06-01T10:22:00+00:00" }
  ],
  "current_page": 1, "last_page": 1, "total": 1
}

Un restaurant unique avec ses catégories de menu et son nombre d’articles.

Le menu actif complet, regroupé par catégorie.

[
  { "id": 3, "name": "Starters",
    "items": [
      { "id": 88, "name": "Bruschetta", "price": 6.50,
        "is_sold_out": false, "is_popular": true, "is_vegan": true,
        "is_halal": true, "calories": 210 }
    ]
  }
]

Gérer le menu Écrire

CRUD complet pour les catégories et les articles — tout ce dont une application marchande a besoin pour gérer le menu. Tous les points de terminaison en écriture requièrent un write token et sont limités à un restaurant que vous possédez. Les envois d'images ne sont pas pris en charge en JSON ; transmettez une URL déjà hébergée dans image.

curl -X POST https://www.menubarcode.com/api/v1/restaurants/12/menu/items \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "category_id": 3, "name": "Margherita", "price": 11.00,
    "description": "San Marzano, mozzarella, basil",
    "is_vegan": true, "is_halal": true, "calories": 850
  }'

Bascule rapide « 86 ». Envoyez {"is_sold_out": true}, ou omettez le corps pour inverser.

Commandes

Commandes du plus récent au plus ancien, paginées (30/page). Filtrez avec ?status=.

Détail complet de la commande avec lignes, extras, livreur et chronologie de livraison.

Créer une commande — c'est ainsi qu'un appli client soumet un panier (le backend du marchand détient le token). Chaque article est validé par rapport au menu en direct du restaurant ; les articles épuisés ou étrangers font rejeter toute la commande (422). Déclenche order.created et renvoie la commande complète, y compris son track_token.

curl -X POST https://www.menubarcode.com/api/v1/restaurants/12/orders \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "delivery",
    "customer_name": "A. Idriss",
    "phone": "+15551234567",
    "address": "9 Cedar Road",
    "tip_amount": 3.00,
    "note": "Ring the bell",
    "source": "customer_app",
    "items": [
      { "item_id": 88, "quantity": 2, "variation": 5, "extras": [12], "note": "no onion" },
      { "item_id": 91, "quantity": 1 }
    ]
  }'

Commande type est l'un de on-table, takeaway, delivery. pour on-table transmettez table_number; pour delivery transmettez address.

Idempotence. Envoyez un Idempotency-Key en-tête (ou un corps client_uuid) sur tout appel de création de commande. Réessayer avec la même clé renvoie la commande d'origine et ne crée jamais de doublon — sûr en cas de réponses perdues et de rejeu hors ligne. Les clés sont limitées à chaque restaurant.

Mettre à jour le statut en cuisine (new|preparing|ready|delivered|completed|cancelled). Déclenche order.status_changed.

API vitrine (token par restaurant)

Une API distincte, orientée public, authentifiée par un token vitrine par restaurant envoyé en tant que X-Storefront-Token (et non le token Bearer du propriétaire). Générez-les depuis votre tableau de bord ; chaque token ne peut jamais atteindre que son propre restaurant. La portée de lecture est menu:read; passer des commandes nécessite le order:write Portée

Menu complet du restaurant du token (variantes, extras, groupes, galerie).

Infos de base sur le restaurant du token.

Soumettre un panier pour le compte d'un client. Prix calculé côté serveur et non payé (le client paie à l'arrivée) ; takeaway ou on-table uniquement. Chaque article est validé par rapport au menu en direct — les articles épuisés ou étrangers font rejeter toute la commande (422). Limites : 40 articles/commande, 30 qté/ligne. Facultatif coupon_code applique une remise propriétaire côté serveur. Déclenche order.created et renvoie track_token + continue_url.

curl -X POST https://www.menubarcode.com/api/v1/storefront/orders \
  -H "X-Storefront-Token: YOUR_STOREFRONT_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "takeaway",
    "customer_name": "A. Idriss",
    "phone": "+15551234567",
    "coupon_code": "WELCOME10",
    "items": [
      { "item_id": 88, "quantity": 2, "variation": 5, "extras": [12] },
      { "item_id": 91, "quantity": 1 }
    ]
  }'

Analyses et clients

Récapitulatif des ventes sur une plage de dates (?from=YYYY-MM-DD&to=YYYY-MM-DD, 30 derniers jours par défaut) : nombre de commandes par statut/type, chiffre d'affaires brut et encaissé, valeur moyenne de commande et articles les plus vendus.

{
  "range": { "from": "2026-06-02", "to": "2026-07-02" },
  "orders": { "total": 214, "paid": 198, "by_status": {...}, "by_type": {...} },
  "revenue": { "gross": 8420.50, "paid": 7990.00, "avg_order_value": 39.35 },
  "top_items": [ { "item_id": 88, "name": "Margherita", "quantity": 143 } ]
}

La liste des clients du restaurant (CRM), paginée. Filtrez avec ?search=.

Gérer les livreurs Écrire

Les livreurs vous appartiennent et (facultativement) à un restaurant. Créer ou renouveler un livreur renvoie un token de livreur brut exactement une fois — transmettez-le à l'application du livreur ; il s'authentifie avec (voir ci-dessous).

curl -X POST https://www.menubarcode.com/api/v1/drivers \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Alex","phone":"+15550001111","restaurant_id":12}'

# → { "id": 7, "name": "Alex", ..., "token": "RAW_DRIVER_TOKEN_SHOWN_ONCE" }

Invalide l'ancien token et en renvoie un nouveau.

Attribuer et suivre une livraison

Commandes en livraison, filtrables par ?delivery_status= et ?driver_id=.

Attribuer un livreur {"driver_id": 7}. Définit delivery_status=assigned et déclenche order.driver_assigned.

Forcer l'étape de livraison : pending | assigned | picked_up | out_for_delivery | delivered | failed.

API appli livreur

L'application du livreur s'authentifie avec un Jeton de livreur (et non un token propriétaire) généré ci-dessus. Chemin de base https://www.menubarcode.com/api/v1/driver. Chaque réponse est limitée à ce seul livreur.

Authorization: Bearer RAW_DRIVER_TOKEN

Le profil du livreur authentifié.

Commandes attribuées à ce livreur. Ajoutez ?active=1 pour masquer livrées/échouées.

Faire avancer la livraison : {"delivery_status":"out_for_delivery"} puis "delivered" ou "picked_up" / "failed", facultatif note). Déclenche les mêmes webhooks que le point de terminaison propriétaire.

Envoyer la position en direct : {"lat":25.2048,"lng":55.2708}. Affichée dans la vue de suivi du client pendant la livraison.

Comptes clients

A application client autonome authentifie ses propres utilisateurs avec un token par client (façon Sanctum : plusieurs appareils, révocables individuellement). Aucun token propriétaire n'est impliqué. Les clients sont limités à chaque restaurant, donc l'authentification se trouve sous /restaurants/{id}/customer/…. Parcourez d'abord le menu avec le point de terminaison public :

Menu actif groupé par catégorie (articles épuisés omis). Sans authentification.

Inscription / connexion

curl -X POST https://www.menubarcode.com/api/v1/restaurants/12/customer/login \
  -H "Content-Type: application/json" \
  -d '{"email":"sam@example.com","password":"secret123","device":"iPhone 15"}'

# → { "token": "RAW_CUSTOMER_TOKEN", "customer": { "id": 42, "name": "Sam", ... } }

Sans mot de passe (OTP par SMS)

Demandez un code pour un numéro de téléphone, puis vérifiez-le. La vérification trouve ou crée le client et renvoie un token. Les points de terminaison d'authentification sont limités en débit (connexion/inscription 10/min, demande OTP 6/min).

API appli client

Authentifiez-vous avec le token client. Chemin de base https://www.menubarcode.com/api/v1/customer. Tout est limité au client authentifié — le corps de la commande ne peut jamais usurper l'id d'un autre client.

Authorization: Bearer RAW_CUSTOMER_TOKEN

Lecture / mise à jour du profil (nom, e-mail, téléphone, anniversaire, consentements).

Passer une commande en tant que ce client (même structure d'article que le point de terminaison de création marchand ; l'identité est tirée du token). Renvoie la commande avec son track_token.

L'historique de commandes propre au client, paginé.

Adresses de livraison enregistrées (la première devient celle par défaut ; prend en charge lat/lng).

Révoque le token utilisé pour la requête (cet appareil uniquement).

Suivi de commande Public

Sans authentification — l'accès est protégé par le track_token impossible à deviner de la commande (renvoyé à la création de la commande). Cela alimente un appli client écran de suivi en direct.

{
  "id": 5501, "status": "preparing", "delivery_status": "out_for_delivery",
  "is_paid": true, "total": 42.00,
  "timeline": { "preparing_at": "...", "out_for_delivery_at": "..." },
  "items": [ { "name": "Margherita", "quantity": 2 } ],
  "driver": { "name": "Alex", "lat": 25.2, "lng": 55.27, "location_updated_at": "..." }
}

Le bloc livreur (avec coordonnées en direct) n'apparaît qu'une fois la commande récupérée / en cours de livraison.

Connexion du personnel

A app du personnel (POS / KDS / serveur) authentifie chaque membre du personnel avec un token par employé. Deux voies reflètent le tableau de bord : e-mail + mot de passe, ou un PIN numérique rapide pour les tablettes de cuisine partagées. Le personnel est limité à chaque restaurant.

curl -X POST https://www.menubarcode.com/api/v1/restaurants/12/staff/pin \
  -H "Content-Type: application/json" -d '{"pin":"4321","device":"Kitchen iPad"}'

# → { "token": "RAW_STAFF_TOKEN",
#     "staff": { "id": 3, "role": "kitchen", "permissions": ["kds"] } }

La réponse liste les Autorisations — un sous-ensemble de orders, menu_edit, coupons, analytics, kds, customers effectives du membre du personnel, dérivées de son rôle (gérant / caissier / cuisine / serveur) plus toute exception par employé. Les points de terminaison sont soumis aux permissions (403 sinon).

API appli personnel

Authentifiez-vous avec le token du personnel. Chemin de base https://www.menubarcode.com/api/v1/staff. Toutes les actions sont limitées au restaurant du membre du personnel.

Authorization: Bearer RAW_STAFF_TOKEN

Profil avec rôle et liste des permissions.

Lister les commandes et mettre à jour le statut en cuisine. Nécessite la orders autorisation.

Tickets de cuisine en direct groupés par commande, filtrés sur le poste du membre du personnel (ou ?station_id=). N'affiche que les articles encore queued|preparing|ready.

Faire avancer (queued → preparing → ready → served) ou reculer d'un statut KDS. Le statut de la commande parente se resynchronise automatiquement.

Modifier le menu depuis la salle (gérants). Mêmes charges utiles que les points de terminaison de menu marchand, limitées au restaurant du membre du personnel.

Récapitulatif des ventes pour le restaurant du membre du personnel (même structure que le point de terminaison d'analytique marchand ; ?from=&to=).

Révoque le token de cet appareil.

Webhooks — configuration

Enregistrez les points de terminaison depuis le tableau de bord sous Tokens API et webhooks. Choisissez les événements que reçoit chaque point de terminaison. À l'enregistrement, vous obtenez un Secret de signature; utilisez le Test bouton pour envoyer un ping. Suspendez un point de terminaison pour arrêter la remise sans perdre son secret.

Votre point de terminaison doit répondre avec un 2xx statut rapidement (dans les 10 s). Tout autre statut — ou un dépassement de délai — est traité comme un échec et réessayé.

Les points de terminaison peuvent aussi être gérés par programmation (pour les REST-Hooks Zapier/Make) avec un webhooks:write token :

GET    /api/v1/webhook-endpoints            # list your endpoints
POST   /api/v1/webhook-endpoints            # {"url":"https://…","events":["order.created"]} → 201 {id, secret, …}
DELETE /api/v1/webhook-endpoints/{id}       # unsubscribe → 204

Le secret est renvoyé uniquement à la création — conservez-le pour vérifier la signature. url doit être un point de terminaison HTTPS public (protégé contre le SSRF) ; events doit provenir de la liste ci-dessous (ou *).

Événements de webhook

Une remise a échoué pendant que votre point de terminaison était hors service ? Utilisez Redistribuer sur toute ligne du journal des remises récentes du tableau de bord pour la remettre en file avec un nouveau webhook-id.

Charge utile du webhook

Chaque remise est un POST avec cette enveloppe JSON et ces en-têtes :

POST /your-endpoint HTTP/1.1
Content-Type: application/json
webhook-id: msg_a1b2c3d4e5f6g7h8i9j0k1l2
webhook-timestamp: 1751472240
webhook-signature: v1,K5f...base64...==
X-Webhook-Event: order.created          (legacy)
X-Webhook-Signature: 9a3f...hex...      (legacy, HMAC of body only)

{
  "id": "msg_a1b2c3d4e5f6g7h8i9j0k1l2",
  "event": "order.created",
  "created_at": "2026-07-02T18:04:00+00:00",
  "data": { "order_id": 5501, "total": "42.00" }
}

Le id est unique par remise. Comme les nouvelles tentatives réutilisent le même id, utilisez-le pour rendre votre gestionnaire idempotent.

Vérifier la signature

Le webhook-signature en-tête est un HMAC-SHA256, encodé en base64, calculé sur {id}.{timestamp}.{body} à l'aide du secret de signature de votre point de terminaison. Lier l'id et l'horodatage à la signature est ce qui rend une requête capturée sûre contre le rejeu. Rejetez toute requête dont le webhook-timestamp a plus de ~5 minutes.

PHP

$secret  = 'whsec_from_dashboard';
$id      = $_SERVER['HTTP_WEBHOOK_ID'];
$ts      = $_SERVER['HTTP_WEBHOOK_TIMESTAMP'];
$body    = file_get_contents('php://input');
$sent    = explode(',', $_SERVER['HTTP_WEBHOOK_SIGNATURE'])[1] ?? '';

if (abs(time() - (int) $ts) > 300) { http_response_code(400); exit; }

$expected = base64_encode(hash_hmac('sha256', "$id.$ts.$body", $secret, true));
if (!hash_equals($expected, $sent)) { http_response_code(401); exit; }

// verified — process $body
http_response_code(200);

Node.js

const crypto = require('crypto');

function verify(req, secret) {
  const id  = req.headers['webhook-id'];
  const ts  = req.headers['webhook-timestamp'];
  const sig = (req.headers['webhook-signature'] || '').split(',')[1];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${id}.${ts}.${req.rawBody}`)
    .digest('base64');

  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig || ''));
}

Nouvelles tentatives et journal des remises

La remise est asynchrone et réessayée en cas d'échec avec un délai exponentiel plus une variation aléatoire : environ 1m → 5m → 15m → 1h (jusqu'à 5 tentatives au total). Chaque tentative — réussie ou échouée — est enregistrée dans le journal des remises de votre tableau de bord avec son statut HTTP, son numéro de tentative et un extrait de réponse.

Serveurs MCP

Cinq serveurs Model Context Protocol connectent les agents IA (ChatGPT, Claude, Cursor) à la plateforme — choisissez celui qui correspond à votre public. Tous parlent JSON-RPC 2.0 sur HTTP et négocient les versions de protocole 2024-11-05 / 2025-03-26 / 2025-06-18.

Démarrage rapide : aller à Admin, Catalog, Customer, ou Dev. Le serveur vitrine partage le schéma de connexion Admin avec un X-Storefront-Token en-tête au lieu d'un token Bearer.

Serveur MCP (Admin)

Un client IA compatible MCP (Claude, ChatGPT, Cursor) peut piloter votre restaurant en langage naturel à l'aide des mêmes tokens API. Pointez-le vers :

Authentifiez-vous avec Authorization: Bearer YOUR_TOKEN. Chaque outil déclare la capacité granulaire dont il a besoin (resource:action); un ancien read token couvre chaque :read outil et write couvre tout. Tous les appels sont limités à vos restaurants et à débit limité. Les outils pour lesquels vous n'avez pas la capacité sont masqués dans tools/list.

Connecter (Claude Code)

claude mcp add --transport http platform-admin https://www.menubarcode.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

Lister les outils

curl -X POST https://www.menubarcode.com/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Appeler un outil (p. ex. ajouter un article au menu)

curl -X POST https://www.menubarcode.com/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"add_menu_item",
                 "arguments":{"restaurant_id":12,"name":"Latte","price":4.5}}}'

Outils

MCP Catalogue (découvrir des restaurants)

Un serveur MCP public en lecture seule qui permet aux agents IA de découvrir des restaurants et des plats sur toute la plateforme, puis de créer un deep link vers une boutique précise pour commander. Sans authentification, à débit limité.

Connecter (Claude Code)

claude mcp add --transport http platform-catalog https://www.menubarcode.com/mcp/catalog

Seules les boutiques actives et répertoriées publiquement apparaissent ; les propriétaires peuvent se désinscrire dans les paramètres de leur boutique. Aucune coordonnée du propriétaire n'est jamais renvoyée. Pour passer une commande, utilisez le MCP vitrine de la boutique avec un token d'agent par boutique.

MCP Compte client

Permet à l'assistant IA d'un client de lire, suivre et recommander ses propres commandes. Authentifié par un token par client issu de la connexion OTP existante ; l'identité du client provient uniquement du token — un numéro de téléphone ou un id client n'est jamais accepté comme argument.

Obtenir un token (flux OTP)

# 1) request a one-time code (sent to the customer's phone)
curl -X POST https://www.menubarcode.com/api/v1/restaurants/12/customer/otp/request \
  -H "Content-Type: application/json" -d '{"phone":"+15551234567"}'

# 2) verify the code → returns a customer bearer token
curl -X POST https://www.menubarcode.com/api/v1/restaurants/12/customer/otp/verify \
  -H "Content-Type: application/json" -d '{"phone":"+15551234567","code":"123456"}'

Connecter (Claude Code)

claude mcp add --transport http my-orders https://www.menubarcode.com/mcp/customer \
  --header "Authorization: Bearer CUSTOMER_TOKEN"

curl -X POST https://www.menubarcode.com/mcp/customer \
  -H "Authorization: Bearer CUSTOMER_TOKEN" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"my_orders","arguments":{"limit":5}}}'

Connectez votre éditeur IA

Vous créez un thème ou une intégration avec Claude Code, Cursor ou VS Code ? Pointez-le vers le Serveur Dev MCP public — votre outil IA obtient la doc de la plateforme en direct, la liste blanche Liquid générée et la validation de thème côté serveur. Aucun token nécessaire.

Claude Code

claude mcp add --transport http platform-dev https://www.menubarcode.com/mcp/dev

Cursor — .cursor/mcp.json

{ "mcpServers": { "platform-dev": { "url": "https://www.menubarcode.com/mcp/dev" } } }

VS Code — .vscode/mcp.json

{ "servers": { "platform-dev": { "type": "http", "url": "https://www.menubarcode.com/mcp/dev" } } }

Outils learn_platform (commencez ici), search_docs / fetch_full_doc, get_liquid_reference, get_section_schema, validate_theme, list_webhook_events. Flux de travail d'agent recommandé : apprendre → créer → valider → livrer.

Journal des modifications

Retour à Menubarcode