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 lisent les deux frontends dans NEXT_PUBLIC_API_BASE_URL (Variables d'environnement). Les photos sont servies en dehors du préfixe, sur /media/….

Les routes du site sont publiques ; celles du tableau de bord demandent le jeton bearer d'un admin, et la plupart aussi une permission. Les corps de requête sont en JSON, sauf pour les fichiers téléversés. 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, dans la langue de la requête, et vide sinon. Les prix sont des nombres décimaux dans la devise du bien.

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": { "email": ["…"] }
}

• message est une phrase dans la langue de la requête.
• errors apparaît lors d'un échec de validation, avec les problèmes par champ, indexés par le chemin envoyé par le client (comme title.en). Un champ inconnu dans un corps est refusé.
• Une route protégée sans jeton, ou avec un jeton expiré, répond 401 ; un jeton sans la permission répond 403.
• Une requête au-delà d'une limite répond 429.

Listes et pagination

{ "data": [ ], "page": 1, "limit": 12, "total": 15, "totalPages": 2 }

• Les biens, les demandes et les visites sont paginés avec page et page_size : 12 par page par défaut sur le site (24 au maximum), 10 dans le tableau de bord (50 au maximum). Les listes du tableau de bord renvoient aussi leurs nombres par statut.
• Les admins, les rôles et les paramètres sont paginés avec page et page_count.
• Sauf si la route a son propre ordre, les lignes arrivent de la plus récemment mise à jour à la plus ancienne, avec l'identifiant comme départage, si bien que la pagination est stable.
• Les filtres de biens du site sont validés : une valeur inconnue est refusée avec 400 plutôt qu'ignorée, tandis qu'une clé que l'API ne lit pas est ignorée, si bien qu'un lien partagé avec des paramètres en trop fonctionne quand même.

Langue

Envoyez Accept-Language: ar pour des messages en arabe ; toute autre valeur répond en anglais. Les biens et les quartiers 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 qu'admin

   TerminalCopier

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

   data.access_token est le jeton, avec token_type valant Bearer et l'admin avec ses rôles et ses permissions. Le jeton dure JWT_EXPIRATION, 7d par défaut, et expires_in rapporte cette valeur telle qu'elle est écrite. GET /api/auth/me renvoie l'admin connecté avec ses rôles et ses permissions.
2. 02

   Appeler une route protégée

   TerminalCopier

   curl http://localhost:8000/api/leads -H "Authorization: Bearer YOUR_TOKEN"

• Un e-mail inconnu et un mauvais mot de passe répondent tous deux 401 avec le même message.
• Dix connexions échouées depuis une même adresse en 15 minutes répondent 429 jusqu'à ce que le plus ancien échec ait 15 minutes (RATE_LIMIT_LOGIN). Les connexions réussies ne sont pas comptées.
• Il n'y a ni inscription ni route de déconnexion : les comptes viennent du seed ou de la gestion des admins, et un client se déconnecte en oubliant son jeton.

Permissions

Les routes du tableau de bord vérifient une permission nommée <area>.<action>. Un admin détient toutes les permissions de tous ses rôles, et une route qui en nomme plusieurs accepte n'importe laquelle. Les 31 permissions et les deux rôles du seed sont listés dans Admins, rôles et permissions.

Les biens sur le site

Les quartiers et les paramètres de l'agence

Le formulaire de contact et les demandes de visite

• Un client_token répété renvoie le reçu du premier envoi au lieu d'en stocker un second.
• Un champ company rempli est traité comme un robot : la réponse paraît identique, et rien n'est stocké.
• Une visite doit commencer au moins une heure à l'avance, à l'heure Asia/Dubai ; plus tôt, la réponse est 400 avec preferred_time_too_soon sur preferred_at.
• Chaque adresse peut envoyer cinq de chaque en dix minutes ; le suivant répond 429.

Gérer les biens

Demandes et visites

Quartiers et paramètres

Admins et rôles

Notifications et fichiers téléversés

Un fichier téléversé n'a pas de permission propre : ce que devient le fichier est vérifié par la route qui l'enregistre. Les notifications sont conservées 30 jours.

Limites par adresse

Une requête au-delà d'une limite répond 429. Les compteurs vivent dans la mémoire de l'API : un redémarrage les efface. 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 de mise en scène

Serveur MCP

Mises à jour en direct via WebSocket

Route du mode démo