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 de la boutique, et le personnel, qui utilise celles du tableau de bord admin. 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 renseignent, traduite dans la langue de la requête, et vide sinon.

Le health check est la seule route hors de l'enveloppe. Il n'exige pas de jeton :

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

{"status":"ok"}

Il répond 503 avec {"status":"unavailable"} tant que la base de données est injoignable ou ne contient pas de tables : un répartiteur de charge peut donc s'en servir comme sonde de disponibilité.

Erreurs

Une requête échouée répond avec le statut HTTP correspondant et la même enveloppe, avec success: false, data: null et, pour la validation, les problèmes par champ :

{
  "success": false,
  "data": null,
  "message": "<the first field's problem>",
  "errors": {
    "email": ["<the problem with email>"]
  }
}

Les écritures réussies répondent 201 pour POST et 200 pour les autres méthodes.

Pagination et tri

Les listes acceptent page, à partir de 1, et page_count, la taille de page. Une page contient au plus 100 lignes : une taille plus grande est lue comme 100, une plus petite comme 1, et une taille absente ou illisible revient à la valeur par défaut de la liste. Une liste répond toujours sous la même forme :

{
  "success": true,
  "data": { "data": [ ], "page": 1, "limit": 15, "total": 35, "totalPages": 3 },
  "message": ""
}

• order=asc ou order=desc définit le sens de tri des produits, catégories, clients et commandes. Les catégories sont par défaut en ordre croissant, les autres des plus récentes aux plus anciennes.
• Les produits se trient aussi avec sort : created_at, updated_at, price, rating ou best_selling. Une valeur inconnue revient au tri par défaut, par date de mise à jour décroissante, les égalités départagées par id. order_by_featured=true place en premier les produits mis en avant et les meilleures ventes.
• La liste des produits filtre par search (nom dans l'une ou l'autre langue, ou SKU), category_id, is_active, is_featured, is_best_seller, min_price, max_price, tag et on_sale.

Langue

Envoyez la langue du lecteur dans l'en-tête Accept-Language : en ou ar tels que livrés. ar-SA compte comme de l'arabe, et toute langue que l'API ne possède pas reçoit une réponse en anglais. Il n'y a pas de paramètre de requête pour la langue.

• Les messages d'erreur et le message d'une écriture réussie sont traduits.
• Le texte enregistré dans les deux langues, comme les noms de produits et de catégories, revient sous la forme { "en": "...", "ar": "..." } et le client choisit l'une d'elles.

Authentification

Les clients et le personnel se connectent sur des endpoints différents, auprès de tables différentes, et reçoivent des jetons que seules leurs propres routes acceptent.

• Les deux sont des JWT signés avec JWT_SECRET. Envoyez-les sous la forme Authorization: Bearer <token>.
• Un jeton dure JWT_EXPIRATION, 7d par défaut (Variables d'environnement). La connexion du personnel indique la même valeur dans expires_in.
• Il n'y a pas d'endpoint de rafraîchissement. Quand un jeton expire, la requête suivante répond 401 et le client se reconnecte.
• Un jeton client est refusé sur les routes admin et un jeton du personnel sur les routes clients, même si les deux utilisent le même secret.
• Une connexion échouée répond 401 avec un seul message, que l'e-mail n'ait pas de compte ou que le mot de passe soit faux.
• Les routes de connexion, d'inscription, de mot de passe et de suivi de commande acceptent 10 tentatives par minute depuis une même adresse, comptées par route. Au-delà, elles répondent 429 avec un en-tête Retry-After. Le compteur est conservé dans la mémoire de l'API : il repart donc de zéro à chaque redémarrage et est compté séparément par chaque instance. Derrière un proxy, voyez TRUST_PROXY (Dépannage).

1. 01

   Se connecter avec le Super Admin des données de démonstration

   TerminalCopier

   curl -X POST http://localhost:8000/api/auth/login \
     -H "Content-Type: application/json" \
     -d '{"email":"admin@example.com","password":"Admin@123"}'

   RéponseCopier

   {
     "success": true,
     "data": {
       "access_token": "eyJhbGciOiJIUzI1NiIs...",
       "token_type": "Bearer",
       "expires_in": "7d",
       "admin": {
         "id": 1,
         "email": "admin@example.com",
         "roles": [{ "id": 1, "name": "Super Admin", "guard_name": "web" }],
         "permissions": ["admins.view", "admins.create", "..."]
       }
     },
     "message": "..."
   }
2. 02

   Appeler une route protégée avec le jeton

   TerminalCopier

   curl "http://localhost:8000/api/orders?page=1&page_count=5" \
     -H "Authorization: Bearer <access_token>"

   Résultat attendu: Les cinq commandes les plus récentes, sous la forme d'une liste.
3. 03

   Se connecter avec un client de démonstration

   La boutique de démonstration contient aussi des clients, comme john.doe@example.com avec le mot de passe password123 :

   TerminalCopier

   curl -X POST http://localhost:8000/api/auth/customer/login \
     -H "Content-Type: application/json" \
     -d '{"email":"john.doe@example.com","password":"password123"}'

   Puis transmettez data.token de la même façon, par exemple à GET /api/orders/my.

Permissions

Chaque route admin vérifie d'abord le jeton, puis la permission qu'elle indique. Un administrateur détient toutes les permissions de tous ses rôles ; quand une route en indique plusieurs, une seule suffit. Dans les tableaux admin ci-dessous, un nom de permission dans la colonne Qui peut l'appeler désigne un administrateur dont les rôles l'accordent.

Les sections de la page d'accueil et le studio IA utilisent les permissions des produits. Les avis n'ont pas de permission propre : le tableau de bord les lit via les produits.

Relancer le seed crée ce qui manque et laisse les permissions des rôles existants telles que vous les avez définies.

Catalogue public

Aucun jeton n'est nécessaire. Les clients ne voient jamais que les produits actifs : sans jeton admin, un produit inactif ou supprimé n'existe pas.

Inscription et comptes clients

Un panier côté serveur est aussi disponible pour les clients connectés. La boutique livrée garde son panier dans le navigateur et ne l'appelle pas.

Commandes, paiement et suivi

Avec payment_method: "stripe" et Stripe configuré, la réponse contient un client_secret que la boutique confirme auprès de Stripe. La livraison est gratuite à partir d'un sous-total de 75 et coûte 9,99 en dessous ; la taxe est de 0. Un promo_code est enregistré sur la commande mais pas appliqué.

• Paiements

Connexion et comptes du personnel

Rôles

Clients

Les clients sont désignés par leur nom d'utilisateur. La liste filtre par search, email, phone, country_id, username, first_name, last_name, verified, from_date et to_date.

Produits et catégories

Les clés des sections sont style-pillars, editorial-split, new-drops, best-sellers, spotlight, lux-difference et editorial-slider.

Commandes

L'API accepte n'importe quel changement de statut ; le tableau de bord ne propose que l'étape suivante ou une annulation.

Paramètres

Il n'y a pas de route pour créer un paramètre : c'est le seed qui les crée. Rien dans le code livré ne lit leurs valeurs.

Envoi de médias

• Formulaire multipart : le fichier dans file, le dossier dans path (uploads par défaut), et éventuellement un préréglage de taille dans for.
• Jusqu'à 150 Mo. Les vidéos (MP4, WebM, MOV, M4V) sont enregistrées telles quelles et répondent { "original": url }.
• Les images sont réencodées en JPEG, à 1920 pixels de large au plus, plus la taille du préréglage, et répondent avec chaque URL, comme { "original": url, "250x250": url }.
• Sans les cinq variables R2_*, elle répond 503 : « File uploads are not set up yet. »

Notifications

• Les notifications en direct utilisent Socket.IO sur le namespace /notifications, à l'adresse de l'API sans /api. Envoyez le jeton du personnel dans auth.token du handshake ; les jetons clients sont déconnectés.
• Chaque nouvelle notification arrive en tant que notification:created. Les types sont order_created, pour chaque administrateur autorisé à voir les commandes, ainsi que studio_generation_completed et studio_generation_failed, pour l'administrateur qui a lancé la génération.
• Un second namespace, /auth, envoie permissions-updated quand les rôles ou les permissions d'un administrateur changent.
• Le socket n'accepte de connexions que depuis FRONTEND_URL.

Assistant IA

Studio IA

Cabine d'essayage

Routes du mode démo