{"openapi":"3.1.0","info":{"title":"Agotels API","version":"1.0.0","description":"Infrastructure B2A (Business-to-Agent) pour l'hôtellerie de Kinshasa, RDC.\nDonnées en temps réel, booking transactionnel anti-overbooking, paiement Mobile Money.\nOpen routes require no authentication. Protected routes require x-api-key header.","contact":{"email":"api@agotels.com"}},"servers":[{"url":"https://api.agotels.com/api/v1","description":"Serveur de production Agotels API v1"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Obtenez votre clé via POST /v1/agents/register"}}},"paths":{"/health":{"get":{"summary":"Health check","operationId":"getHealth","tags":["meta"],"responses":{"200":{"description":"API healthy"}}}},"/hotels":{"get":{"summary":"Liste des hôtels actifs","operationId":"listHotels","tags":["hotels"],"parameters":[{"name":"commune","in":"query","schema":{"type":"string"}},{"name":"stars","in":"query","schema":{"type":"integer","minimum":1,"maximum":5}},{"name":"features","in":"query","schema":{"type":"string"}},{"name":"ai_ready_min","in":"query","schema":{"type":"integer"}},{"name":"limit","in":"query","schema":{"type":"integer","default":20}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Liste des hôtels"}}}},"/hotels/{id}":{"get":{"summary":"Détail d'un hôtel (slug ou UUID)","operationId":"getHotel","tags":["hotels"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Hôtel trouvé"},"404":{"description":"Introuvable"}}}},"/hotels/{id}/availability":{"get":{"summary":"Disponibilité en temps réel","operationId":"checkAvailability","tags":["availability"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"check_in","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"check_out","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"guests","in":"query","schema":{"type":"integer","default":2}}],"responses":{"200":{"description":"Disponibilités par type de chambre"}}}},"/availability/search":{"get":{"summary":"Disponibilité multi-hôtels","operationId":"searchAvailability","tags":["availability"],"parameters":[{"name":"commune","in":"query","schema":{"type":"string"}},{"name":"check_in","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"check_out","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"max_price","in":"query","schema":{"type":"number"}},{"name":"guests","in":"query","schema":{"type":"integer","default":2}}],"responses":{"200":{"description":"Hôtels disponibles"}}}},"/search":{"post":{"summary":"Recherche sémantique par langage naturel","operationId":"semanticSearch","tags":["search"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string","minLength":3,"description":"Ex: hôtel avec piscine à Gombe moins de 150$"},"check_in":{"type":"string","format":"date"},"check_out":{"type":"string","format":"date"},"limit":{"type":"integer","default":5,"maximum":20},"commune":{"type":"string"},"max_price":{"type":"number"}}}}}},"responses":{"200":{"description":"Résultats avec score de pertinence"}}}},"/agents/register":{"post":{"summary":"Obtenir une clé API instantanément","operationId":"registerAgent","tags":["agents"],"x-openai-isConsequential":false,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agent_name","contact_email"],"properties":{"agent_name":{"type":"string"},"contact_email":{"type":"string","format":"email"},"description":{"type":"string"},"plan":{"type":"string","enum":["sandbox","starter","growth"],"default":"starter"}}}}}},"responses":{"201":{"description":"Clé API générée — affichée une seule fois"}}}},"/bookings":{"post":{"summary":"Créer un hold de 10 minutes","operationId":"createBooking","tags":["bookings"],"x-openai-isConsequential":true,"security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["hotel_id","room_type_id","check_in","check_out","guest"],"properties":{"hotel_id":{"type":"string"},"room_type_id":{"type":"string"},"check_in":{"type":"string","format":"date"},"check_out":{"type":"string","format":"date"},"guest":{"type":"object","required":["name","phone"],"properties":{"name":{"type":"string"},"phone":{"type":"string","description":"Format international requis. Exemple: +243810000000"},"email":{"type":"string","format":"email"}}},"payment_method":{"type":"string","enum":["airtel_money","orange_money","vodacom","cash_usd"]},"webhook_url":{"type":"string","format":"uri"}}}}}},"responses":{"201":{"description":"Hold créé — valide 10 minutes"},"401":{"description":"Clé API manquante ou invalide"},"409":{"description":"Pas de disponibilité ou conflit concurrent"}}}},"/bookings/{id}":{"get":{"summary":"Statut d'une réservation","operationId":"getBooking","tags":["bookings"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Détail de la réservation"}}}},"/payments/initiate":{"post":{"summary":"Initier un paiement Mobile Money","operationId":"initiatePayment","tags":["payments"],"x-openai-isConsequential":true,"security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["booking_id","provider"],"properties":{"booking_id":{"type":"string"},"provider":{"type":"string","enum":["airtel_money","orange_money","vodacom","cash_usd"]},"phone":{"type":"string","description":"Numéro lié au compte Mobile Money au format international (+243...)"}}}}}},"responses":{"201":{"description":"Code USSD généré"}}}}}}