API REST · Base: /public

Documentation API Hôtela

Connectez votre site web à votre tableau de bord Hôtela. Vérifiez les disponibilités, créez des réservations et synchronisez les données de votre site vitrine — en temps réel, sans ressaisie manuelle.

Authentification Disponibilités Réservations Codes d'erreur

GET/v1/public/availabilityChambres disponibles sur une périodeavailability:read

GET/v1/public/roomsTypes de chambres avec disponibilitésrooms:read

POST/v1/public/reservationsCréer une réservation (HTTP 201)reservations:write

GET/v1/public/reservations/:idDétails d'une réservationreservations:read

Authentification

Tous les endpoints protégés requièrent deux en-têtes HTTP présents dans chaque requête. Ces identifiants sont générés dans votre tableau de bord sous Paramètres → Clés API.

Clé publique

x-api-key: YOUR_API_KEY

Identifie votre hôtel. Transmis avec chaque requête.

Secret

x-api-secret: YOUR_API_SECRET

Ne jamais exposer côté navigateur — serveur uniquement.

Sécurité : L'API secret ne doit jamais apparaître dans du code frontend, un dépôt public ou un bundle navigateur. Effectuez tous les appels API depuis votre serveur (backend, fonction serverless, etc.).

curl https://api.hotela.app/v1/public/rooms \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET"

En-tête absent ou invalide → 401 Unauthorized

Permission manquante → 403 Forbidden

URL de base & Permissions

Production

https://api.hotela.app

Tous les endpoints sous /v1/public/

Sandbox

https://sandbox.api.hotela.app

Tests uniquement. Aucune réservation réelle.

Chaque clé API est créée avec un jeu de permissions granulaires. Voir le tableau des permissions pour le détail.

GET/v1/public/availability availability:read

Retourne la liste des chambres physiques disponibles pour une période donnée, avec prix total calculé. Les chambres retournées ont le statut AVAILABLE ou CLEANING et aucune réservation CONFIRMED/PENDING en conflit.

Paramètres de requête

checkInstringrequis

Date d'arrivée au format YYYY-MM-DD. Ex: 2025-08-15

checkOutstringrequis

Date de départ (YYYY-MM-DD). Doit être strictement après checkIn.

curl "https://api.hotela.app/v1/public/availability?checkIn=2025-08-15&checkOut=2025-08-18" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET"

GET/v1/public/rooms rooms:read

Retourne les types de chambres (RoomType) de l'hôtel avec leurs équipements. Le champ rooms[] contient les chambres physiques au statut AVAILABLE — son length indique la disponibilité instantanée sans filtre de dates.

Pour connaître la disponibilité sur une période précise (ex: 15-18 août), utilisez GET /availability.GET /rooms convient pour afficher le catalogue sans contrainte de dates.

curl https://api.hotela.app/v1/public/rooms \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET"

POST/v1/public/reservations reservations:write

Crée une réservation. Vous fournissez un roomTypeId — Hôtela attribue automatiquement la première chambre physique disponible du type (ordre étage ASC, numéro ASC). Retourne HTTP 201 avec la réservation, la facture et le client.

Attribution auto

Pas besoin de connaître l'ID d'une chambre physique. Vous passez un roomTypeId, Hôtela fait le reste.

Upsert client

Si guestEmail correspond à un client existant, sa fiche est mise à jour. Sinon un nouveau client est créé.

Facture + notif

Une facture INV-XXXX est générée automatiquement. Votre équipe reçoit une notification push en temps réel.

Corps de la requête (JSON)

roomTypeIdstringrequis

ID du type de chambre (obtenu via GET /v1/public/rooms). Hôtela attribue la chambre physique disponible.

guestNamestringrequis

Nom complet du client.

guestEmailstringrequis

Email du client. Utilisé pour l'upsert du profil client dans le tableau de bord.

guestPhonestringrequis

Téléphone au format international. Ex: +225 07 00 00 00

checkInstringrequis

Date d'arrivée (YYYY-MM-DD).

checkOutstringrequis

Date de départ (YYYY-MM-DD). Strictement après checkIn.

specialRequestsstring

Demandes spéciales visibles par votre équipe. Optionnel.

La réservation est créée avec le statut PENDING et la source website. Le passage à CONFIRMED est effectué par votre équipe depuis le tableau de bord.

curl -X POST https://api.hotela.app/v1/public/reservations \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "roomTypeId": "clx2def...",
    "guestName": "Kouame Yao",
    "guestEmail": "kouame@example.com",
    "guestPhone": "+225 07 00 00 00",
    "checkIn": "2025-08-15",
    "checkOut": "2025-08-18",
    "specialRequests": "Chambre non-fumeur, étage élevé"
  }'

GET/v1/public/reservations/:id reservations:read

Récupère les informations essentielles d'une réservation à partir de son ID interne (retourné lors de la création).

Paramètre de chemin

:idstringrequis

ID interne de la réservation (champ reservation.id retourné par POST /reservations).

curl https://api.hotela.app/v1/public/reservations/clxres... \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET"

Codes d'erreur

Hôtela utilise les codes HTTP standard. Le corps de chaque réponse d'erreur suit le format NestJS natif.

{
  "statusCode": 400,
  "message": "Aucune chambre disponible pour le type \"Chambre Supérieure\" sur cette période",
  "error": "Bad Request"
}

400

Bad Request

Paramètres invalides ou manquants (ex: dates incohérentes, checkIn ≥ checkOut).

400

Aucune disponibilité

Aucune chambre du type demandé n'est libre sur la période.

401

Unauthorized

x-api-key ou x-api-secret manquant ou invalide.

403

Forbidden

La clé API ne possède pas la permission requise pour cet endpoint.

404

Not Found

Réservation ou type de chambre introuvable, ou site non publié.

500

Server Error

Erreur interne. Contactez le support si persistant.

Tableau des permissions

Chaque clé API est créée avec un sous-ensemble de permissions. Gérez-les dans Tableau de bord → Clés API.

Permission	Endpoint(s)	Description
`availability:read`	`GET /v1/public/availability`	Lire les disponibilités
`rooms:read`	`GET /v1/public/rooms`	Lire les types de chambres
`reservations:write`	`POST /v1/public/reservations`	Créer des réservations
`reservations:read`	`GET /v1/public/reservations/:id`	Lire les réservations

Prêt à connecter votre site ?

Générez votre clé API gratuitement avec l'essai 30 jours. Notre équipe vous accompagne dans l'intégration.