{"openapi":"3.1.0","info":{"title":"API LOKO","version":"1.0.0","description":"Catalogue des prestataires touristiques du Cameroun et demandes de réservation pour les centrales partenaires. Permissions : prestataires:read, reservations:read, reservations:write."},"servers":[{"url":"https://loko-trip.com/api/v1"}],"security":[{"bearerAuth":[]}],"paths":{"/ping":{"get":{"summary":"Vérifier la clé","responses":{"200":{"description":"OK"},"401":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/prestataires":{"get":{"summary":"Lister les prestataires approuvés","x-required-scope":"prestataires:read","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"categorie","in":"query","schema":{"type":"string","enum":["hebergement","restauration","guide","activite","transport"]}},{"name":"region","in":"query","schema":{"type":"string"}},{"name":"ville","in":"query","schema":{"type":"string"}},{"name":"q","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Liste paginée"},"400":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/prestataires/{id}":{"get":{"summary":"Détail d'un prestataire","x-required-scope":"prestataires:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Prestataire"},"400":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reservations":{"get":{"summary":"Lister vos réservations","x-required-scope":"reservations:read","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"statut","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Liste paginée"},"400":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Créer une demande de réservation (idempotent via external_ref)","x-required-scope":"reservations:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReservationInput"}}}},"responses":{"200":{"description":"Déjà existante (external_ref rejoué)"},"201":{"description":"Créée"},"400":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reservations/{id}":{"get":{"summary":"Détail d'une réservation","x-required-scope":"reservations:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Réservation"},"400":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Erreur","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{"reservation.status_changed":{"post":{"summary":"Changement de statut d'une réservation créée via l'API","description":"Signature : en-tête LOKO-Signature = t=<timestamp>,v1=<hex(HMAC-SHA256(secret, \"<timestamp>.<corps brut>\"))>. Répondre 2xx sous 8 s ; 6 tentatives (1 min, 5 min, 30 min, 2 h, 12 h).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Événement accepté"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"lk_live_…"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"}}}}},"WebhookEvent":{"type":"object","properties":{"id":{"type":"string","example":"evt_9f2c…"},"type":{"type":"string","enum":["reservation.status_changed","webhook.test"]},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"previous_status":{"type":"string"},"reservation":{"type":"object"}}}}},"ReservationInput":{"type":"object","required":["prestataire_id","date_debut","nb_personnes","montant","client"],"properties":{"prestataire_id":{"type":"string","format":"uuid"},"date_debut":{"type":"string","format":"date"},"date_fin":{"type":"string","format":"date"},"nb_personnes":{"type":"integer","minimum":1,"maximum":500},"montant":{"type":"integer","minimum":0,"description":"FCFA (XAF)"},"external_ref":{"type":"string","maxLength":100},"message":{"type":"string","maxLength":1000},"client":{"type":"object","required":["nom","email"],"properties":{"nom":{"type":"string"},"email":{"type":"string","format":"email"},"telephone":{"type":"string"}}}}}}}}