Référence de l'API

URL de base et format des réponses

Chaque route est servie sous le préfixe /api. En local, l'URL de base est http://localhost:8000/api. Sur un serveur, c'est l'adresse de votre API suivie de /api, la même valeur que les deux frontends lisent dans NEXT_PUBLIC_API_BASE_URL (Variables d'environnement).

L'API sert deux publics qui ne partagent jamais de jeton : les clients, qui utilisent les routes du site, et le personnel, qui utilise celles du tableau de bord. Les corps de requête sont en JSON, sauf pour les envois de fichiers. Chaque réponse arrive dans la même enveloppe :

{
  "success": true,
  "data": { },
  "message": ""
}

data contient le résultat. message est une courte phrase que certaines écritures remplissent, dans la langue de la requête, et qui est vide sinon. Les montants sont en dollars décimaux dans le JSON, par exemple 14.99, et chaque total est calculé par l'API : rien de ce qu'un client envoie au sujet d'un montant n'est pris pour argent comptant.

La vérification de santé ne demande aucun jeton :

curl http://localhost:8000/api/health

{"success":true,"data":{"status":"ok","database":"up"},"message":""}

Quand la base de données ne peut pas être lue, elle répond quand même 200, avec "status":"degraded" et "database":"down". La vérification de santé de l'image Docker lit ce champ.

Erreurs

Un échec garde l'enveloppe, avec success: false et le statut HTTP :

{
  "success": false,
  "data": null,
  "message": "errors.kitchen_closed",
  "errors": { "email": ["…"] },
  "code": "…"
}

• Les erreurs qu'un client voit sont des clés comme errors.kitchen_closed, errors.outside_area ou errors.rate_limited, que le site traduit lui-même. Les autres messages sont des phrases dans la langue de la requête.
• errors apparaît en cas d'échec de validation, avec les problèmes par champ.
• code porte une raison lisible par une machine quand il en existe une, comme changes avec une liste changes quand un prix a changé avant qu'une commande soit passée.
• Une route protégée sans jeton répond 401 ; un jeton sans la permission répond 403.

Listes et pagination

Les routes de liste acceptent page et limit (page_count est accepté à la place de limit). limit est plafonné à 100. Sauf si l'appelant trie, les lignes arrivent de la plus récemment modifiée à la plus ancienne, avec l'id pour départager, donc la pagination est stable.

{ "items": [ ], "total": 64, "page": 1, "limit": 12, "totalPages": 6 }

Les listes de plats et de commandes placent les lignes sous items. Les listes de catégories, d'avis, de clients, d'équipe, de rôles et de paramètres les placent sous data, avec les mêmes champs de pagination. Les listes lues dans un ordre défini, comme les sections de la page d'accueil et la file d'attente des cuisines, gardent cet ordre.

Langue

Envoyez Accept-Language: ar pour des messages en arabe ; toute autre valeur répond en anglais. Les éléments du menu portent les deux langues sous la forme { "en": "…", "ar": "…" } quel que soit l'en-tête, et le client en choisit une.

Connexion

1. 01

   Se connecter en tant que membre du personnel

   TerminalCopier

   curl -X POST http://localhost:8000/api/auth/login \
     -H "Content-Type: application/json" \
     -d '{"email":"owner@foodstudio.example","password":"FoodDemo2026!"}'

   data.access_token est le jeton du personnel, avec token_type Bearer, expires_in (7d par défaut, JWT_EXPIRATION) et le membre avec ses rôles. GET /api/auth/me renvoie le membre connecté avec ses permissions.
2. 02

   Appeler une route protégée

   TerminalCopier

   curl http://localhost:8000/api/orders -H "Authorization: Bearer YOUR_TOKEN"
3. 03

   Se connecter en tant que client

   POST /api/auth/customer/login avec le même corps répond { token, user } ; POST /api/auth/customer/register accepte first_name, last_name, email, password (8 caractères ou plus) et éventuellement phone, et répond de la même façon. Le client de démonstration est sam@foodstudio.example avec FoodDemo2026!.

• Un jeton client est refusé sur toutes les routes du personnel, et un jeton du personnel sur toutes les routes client.
• Un e-mail inconnu et un mauvais mot de passe répondent tous deux 401 avec le même message.
• Dix échecs de connexion depuis une même adresse en 15 minutes, par formulaire, répondent 429 jusqu'à ce que le plus ancien échec date de 15 minutes (RATE_LIMIT_LOGIN). Les connexions réussies ne sont pas comptées.
• Il n'y a pas de route de déconnexion : un client se déconnecte en oubliant son jeton.

Permissions

Les routes du personnel vérifient une permission, nommée <module>.<action>. Un membre détient toutes les permissions de tous ses rôles.

Le menu

Un plat porte name, description et ingredients dans les deux langues, price, sa category, images, option_groups avec leurs choices et le price_delta de chaque choix, allergens, dietary_tags, preparation_minutes, et les interrupteurs is_active (publié), is_available (commandable maintenant), is_featured et is_best_seller.

Les cuisines et la vérification du code postal

{ "postcode": "10001", "mode": "delivery", "kitchen_code": "central" }

Elle répond { result, kitchen, alternatives }, où result vaut match, outside_area ou closed. Le retrait sur place n'est pas limité par le code postal. L'ouverture d'une cuisine suit le réglage de l'horloge de service.

Prix, codes promo et panier

{
  "lines": [
    { "product_id": 9, "quantity": 1, "options": [{ "group": "size", "choice": "double" }], "instructions": "no onions" },
    { "offer_id": 1, "quantity": 1, "offer_choices": { "main": 9, "side": 5, "drink": 3 } }
  ],
  "kitchen_code": "central",
  "fulfillment": "delivery",
  "address": { "street": "12 Main St", "city": "Demo City", "postcode": "10001" },
  "promo_code": "TASTE10"
}

• Une ligne indique un product_id ou un offer_id, avec une quantity de 1 à 10 et des instructions de 200 caractères au plus.
• Le devis indique le sous-total, les remises, les frais, le total, les points que rapporterait la commande, si la livraison peut avoir lieu (address_incomplete, outside_area, closed, below_minimum) et une liste changes pour chaque ligne dont le prix a changé ou qui ne peut pas être commandée.
• Un code promo retire son pourcentage du sous-total du menu, jamais des frais de livraison. redeem_points: true applique une utilisation de points pour un client connecté qui en a assez.

Passer et suivre une commande

• POST /api/orders accepte les lines du devis, kitchen_code, fulfillment et address, plus phone, payment_method (stripe, paypal ou demo, comme les liste GET /api/payments/methods), terms_accepted: true et, pour un invité, name et email. Optionnels : promo_code, redeem_points, delivery_instructions, locale, accept_changes, ainsi que return_url_ok et return_url_cancel, qui doivent se trouver sur une adresse de CORS_ORIGIN.
• Elle répond 201 avec { order, payment, tracking }. payment.kind vaut redirect, avec la page du prestataire dans payment.url, ou none pour le paiement de démonstration, que POST /api/payments/checkout-session règle ensuite. tracking est un jeton signé, valable trois heures, pour GET /api/orders/track/status.
• Le même Idempotency-Key envoyé par la même personne renvoie la commande enregistrée au lieu d'en créer une deuxième.
• Un prix qui a changé, ou un plat devenu indisponible, répond 422 avec code: "changes" jusqu'à ce que le client envoie la clé du changement dans accept_changes.
• Le suivi invité répond le même 404 pour un numéro inconnu, un mauvais e-mail et des paramètres manquants.

Le statut d'une commande passe par pending, confirmed, preparing, ready, puis out_for_delivery et delivered pour une livraison, ou directement delivered pour un retrait. Elle peut être cancelled avec un motif avant de quitter la cuisine, et ne devient refunded que lorsque le prestataire de paiement signale un remboursement.

Paiements

• Configurer les paiements

Adresses, plats enregistrés, fidélité, avis et contact

Personnel : menu, catégories, menus combinés et page d'accueil

Personnel : commandes et vue d'ensemble

• Un passage que l'enchaînement des statuts n'autorise pas répond 409 errors.transition_not_allowed ; un passage que ce compte ne peut pas faire, 403 errors.transition_forbidden ; la confirmation d'une commande impayée, 409 errors.payment_required.
• Un compte cuisine ne voit que les commandes de sa propre cuisine, sans les prix, et toute autre commande répond 404.

Personnel : clients, équipe et rôles

Personnel : paramètres, cuisines, codes promo, envois de fichiers et notifications

• Les paramètres sur lesquels tourne le restaurant sont delivery_fee, pickup_fee, delivery_minimum, rewards_points_per_dollar, rewards_redeem_points, rewards_redeem_value et service_clock (real ou demo-fixed), à côté de site_name, site_tagline, support_email et support_phone.
• Une image envoyée est stockée en JPEG en plusieurs tailles, et la réponse associe chaque version à son adresse. Les fichiers vont dans le bucket quand les variables R2_* sont définies, et sinon dans /media/uploads/… sur l'API.
• Chaque route de notifications répond avec le flux complet : un client remplace donc ce qu'il a par la réponse.

Limites par adresse

Une requête au-delà d'une limite répond 429 avec errors.rate_limited. Les compteurs sont gardés dans la mémoire de l'API, donc un redémarrage les remet à zéro. Derrière un reverse proxy, définissez TRUST_PROXY pour que chaque visiteur soit compté sur sa propre adresse.

L'assistant IA et ses conversations

Studio IA

Serveur MCP

Mises à jour en direct via WebSocket

Routes du mode démo