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 photographies sont servies hors 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 en dollars américains entiers, et les dates sont des jours calendaires de la société écrits YYYY-MM-DD.

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. message est une phrase dans la langue de la requête, code la clé non traduite qui la sous-tend, et un refus qui nomme quelque chose ajoute dans details les valeurs derrière sa phrase :

{
  "success": false,
  "data": null,
  "message": "Booking B0021 already holds some of these nights.",
  "code": "dates_taken",
  "details": { "held_by": "booking", "reference": "B0021" }
}

Un corps que le pipe de validation refuse porte code: "validation_failed" et errors, indexé par le nom complet de chaque champ :

{
  "success": false,
  "data": null,
  "message": "guest_email must be an email",
  "errors": { "guest_email": ["guest_email must be an email"] },
  "code": "validation_failed"
}

• Raisonnez sur code, jamais sur la phrase, qui change avec la langue. Les refus de réservation et de disponibilité portent des codes comme dates_taken, min_nights, capacity, cancellation_window_passed, awaiting_payment et payment_method_unavailable, et une limite rate_limited.
• errors apparaît lors d'un échec de validation, avec les problèmes sous le nom du champ tel que la requête l'a écrit (check_in, guest_email). 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.
• Des nuits déjà retenues répondent 409, une étape de réservation depuis le mauvais statut 422, et une requête au-delà d'une limite 429.

Listes et pagination

{ "data": [ ], "page": 1, "page_size": 6, "total": 12, "total_pages": 2 }

• Les séjours, réservations, demandes et avis se paginent avec page et page_size : 6 séjours par page sur le site (24 au plus), 20 dans le tableau de bord (50 au plus), 10 réservations et 20 demandes (50 au plus chacune), 8 avis. Les listes du tableau de bord renvoient aussi counts par statut.
• Les admins, rôles et paramètres se paginent avec page et page_count (les paramètres acceptent aussi page_size), 10 par défaut et 100 au plus, et répondent { data, page, limit, total, totalPages }.
• Les filtres de séjours 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 plus fonctionne toujours.

Langue

Envoyez Accept-Language: ar pour des messages en arabe ; toute autre valeur répond en anglais. Les séjours, destinations et questions de la page d'accueil 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@hollina.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/bookings/manage -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.
• Les voyageurs n'ont pas de comptes. Les routes de réservation d'un voyageur acceptent l'access_token de la réservation en ?token=, ou l'e-mail utilisé pour la faire en ?email= ; une paire erronée répond 404.

Permissions

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

Les séjours sur le site

Destinations, questions et paramètres de la société

Réservations

• Un client_token répété renvoie le reçu de la première réservation au lieu d'en faire une seconde, et un champ company rempli est traité comme un robot : la réponse est la même, et rien n'est stocké.
• Un payment_method que GET /api/payments/methods ne liste pas (PayPal avec seulement Stripe configuré, la carte avec seulement PayPal, le paiement à l'arrivée avec son paramètre désactivé) répond 422 avec payment_method_unavailable, avant que quoi que ce soit soit écrit.
• Les nuits sont vérifiées quand la réservation est écrite : des nuits retenues répondent 409 avec dates_taken, et le minimum d'un séjour, sa capacité ou une arrivée dans le passé 422 avec la raison.
• Un moyen hébergé répond pending avec une redirect_url vers Stripe ou PayPal ; la réservation n'est confirmée que par le webhook du processeur ou la capture PayPal.

Questions à l'hôte

• Un client_token répété renvoie le premier envoi au lieu d'en stocker un second, et un champ company rempli est traité comme un robot.
• Chaque adresse peut envoyer cinq réservations, cinq questions et cinq avis en dix minutes ; le suivant répond 429.

Gérer les séjours

Le calendrier et les dates bloquées

Réservations, demandes et avis

Destinations, questions 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

Serveur MCP

Mises à jour en direct via WebSocket

Routes du mode démo