{
  "openapi": "3.0.3",
  "info": {
    "title": "BeautyConnect Cameroun Public API",
    "version": "1.0.0",
    "description": "API publique et programmable de BeautyConnect Cameroun pour la découverte de salons de coiffure, instituts de beauté, prise de rendez-vous en temps réel et catalogue de cosmétiques certifiés à Douala, Yaoundé et sur l'ensemble du Cameroun.",
    "contact": {
      "name": "Équipe Technique & Développeurs BeautyConnect",
      "email": "api@beautyconnect.cm",
      "url": "https://beautyconnectcm.vercel.app/contact"
    },
    "license": {
      "name": "Propriétaire",
      "url": "https://beautyconnectcm.vercel.app/terms"
    }
  },
  "servers": [
    {
      "url": "https://beautyconnectcm.vercel.app/api",
      "description": "Serveur API Principal (Vercel Proxy / Railway Production)"
    },
    {
      "url": "https://beautyconnectcm-production.up.railway.app/api",
      "description": "Serveur Backend Direct (Railway)"
    }
  ],
  "tags": [
    {
      "name": "Salons",
      "description": "Recherche et consultation des salons de coiffure, barbiers, instituts et spas"
    },
    {
      "name": "Boutique",
      "description": "Catalogue de produits cosmétiques et capillaires certifiés"
    },
    {
      "name": "Réservations",
      "description": "Vérification des disponibilités et création de rendez-vous"
    },
    {
      "name": "Santé & MCP",
      "description": "Points de terminaison d'intégrité, statut et protocole MCP"
    }
  ],
  "paths": {
    "/salons": {
      "get": {
        "tags": ["Salons"],
        "summary": "Lister et rechercher des salons de beauté",
        "description": "Renvoie la liste paginée des salons partenaires vérifiés avec filtres géographiques et catégoriels.",
        "operationId": "listSalons",
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "description": "Ville camerounaise (Douala, Yaoundé, Bafoussam, Kribi)",
            "required": false,
            "schema": {
              "type": "string",
              "example": "Douala"
            }
          },
          {
            "name": "category",
            "in": "query",
            "description": "Catégorie principale de service (coiffure, onglerie, barbier, spa, maquillage)",
            "required": false,
            "schema": {
              "type": "string",
              "example": "coiffure"
            }
          },
          {
            "name": "search",
            "in": "query",
            "description": "Mot-clé de recherche textuelle sur le nom ou la description",
            "required": false,
            "schema": {
              "type": "string",
              "example": "Akwa"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Nombre maximal d'éléments retournés",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 20,
              "minimum": 1,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Liste des salons récupérée avec succès",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "salons": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Salon"
                      }
                    },
                    "total": {
                      "type": "integer",
                      "example": 45
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/salons/{id}": {
      "get": {
        "tags": ["Salons"],
        "summary": "Obtenir les détails d'un salon",
        "description": "Renvoie les informations complètes d'un salon incluant son adresse, ses horaires et son catalogue de prestations.",
        "operationId": "getSalonById",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identifiant unique (UUID) ou slug du salon",
            "schema": {
              "type": "string",
              "example": "glamour-beauty-akwa"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Détails du salon",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SalonDetail"
                }
              }
            }
          },
          "404": {
            "description": "Salon introuvable"
          }
        }
      }
    },
    "/salons/{id}/availability": {
      "get": {
        "tags": ["Réservations"],
        "summary": "Consulter les créneaux horaires disponibles",
        "description": "Renvoie les créneaux disponibles pour une date donnée pour un salon et une prestation.",
        "operationId": "getSalonAvailability",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identifiant du salon",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "date",
            "in": "query",
            "required": true,
            "description": "Date au format YYYY-MM-DD",
            "schema": {
              "type": "string",
              "format": "date",
              "example": "2026-10-26"
            }
          },
          {
            "name": "service_id",
            "in": "query",
            "required": false,
            "description": "Identifiant du service demandé",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Liste des créneaux horaires libres",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "date": { "type": "string" },
                    "slots": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "example": "10:30"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/boutique/products": {
      "get": {
        "tags": ["Boutique"],
        "summary": "Catalogue des produits cosmétiques",
        "description": "Liste les cosmétiques certifiés disponibles à la commande avec paiement Mobile Money.",
        "operationId": "listBoutiqueProducts",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "description": "Catégorie de produit (capillaire, visage, corps, maquillage)",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "search",
            "in": "query",
            "description": "Recherche par nom ou marque",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Catalogue de produits",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "products": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Product"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/boutique/products/{id}": {
      "get": {
        "tags": ["Boutique"],
        "summary": "Obtenir les détails d'un produit cosmétique",
        "description": "Renvoie la description détaillée, la composition et le stock d'un cosmétique.",
        "operationId": "getProductById",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identifiant du produit",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Fiche produit complète",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Product"
                }
              }
            }
          }
        }
      }
    },
    "/bookings": {
      "post": {
        "tags": ["Réservations"],
        "summary": "Créer une demande de réservation",
        "description": "Enregistre une réservation de rendez-vous dans un salon avec confirmation et paiement escrow Mobile Money.",
        "operationId": "createBooking",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BookingRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Réservation créée avec succès",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BookingResponse"
                }
              }
            }
          }
        }
      }
    },
    "/bookings/{id}/status": {
      "get": {
        "tags": ["Réservations"],
        "summary": "Vérifier le statut d'une réservation",
        "description": "Consulte l'avancement et le statut de paiement d'une réservation.",
        "operationId": "getBookingStatus",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identifiant de la réservation",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Statut de la réservation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": { "type": "string" },
                    "status": { "type": "string", "enum": ["pending", "confirmed", "completed", "cancelled"] },
                    "payment_status": { "type": "string", "enum": ["unpaid", "escrowed", "released", "refunded"] }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "tags": ["Santé & MCP"],
        "summary": "Model Context Protocol (MCP) Streamable HTTP Endpoint",
        "description": "Point d'entrée du protocole MCP pour agents IA (Claude, ChatGPT, etc.) supportant initialize, tools/list et tools/call.",
        "operationId": "mcpRpcHandler",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "jsonrpc": { "type": "string", "example": "2.0" },
                  "method": { "type": "string", "example": "tools/list" },
                  "params": { "type": "object" },
                  "id": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Réponse JSON-RPC 2.0 MCP standard"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Salon": {
        "type": "object",
        "required": ["id", "name", "city", "address"],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "name": { "type": "string", "example": "Salon Élégance Douala" },
          "slug": { "type": "string", "example": "salon-elegance-douala" },
          "city": { "type": "string", "example": "Douala" },
          "neighborhood": { "type": "string", "example": "Akwa" },
          "address": { "type": "string", "example": "Rue Drouot, Akwa, Douala" },
          "rating": { "type": "number", "format": "float", "example": 4.8 },
          "review_count": { "type": "integer", "example": 34 },
          "categories": {
            "type": "array",
            "items": { "type": "string" },
            "example": ["coiffure", "onglerie"]
          },
          "is_verified": { "type": "boolean", "example": true }
        }
      },
      "SalonDetail": {
        "allOf": [
          { "$ref": "#/components/schemas/Salon" },
          {
            "type": "object",
            "properties": {
              "description": { "type": "string" },
              "phone": { "type": "string", "example": "+237655000000" },
              "services": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ServiceItem"
                }
              }
            }
          }
        ]
      },
      "ServiceItem": {
        "type": "object",
        "required": ["id", "name", "price_cfa", "duration_minutes"],
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string", "example": "Tresses Nattes Couchées" },
          "price_cfa": { "type": "integer", "example": 8000 },
          "currency": { "type": "string", "default": "XAF" },
          "duration_minutes": { "type": "integer", "example": 90 }
        }
      },
      "Product": {
        "type": "object",
        "required": ["id", "name", "price_cfa"],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "name": { "type": "string", "example": "Beurre de Karité Bio Brut 250g" },
          "brand": { "type": "string", "example": "Natur'Afrique" },
          "price_cfa": { "type": "integer", "example": 4500 },
          "currency": { "type": "string", "default": "XAF" },
          "in_stock": { "type": "boolean", "example": true }
        }
      },
      "BookingRequest": {
        "type": "object",
        "required": ["salon_id", "service_id", "booking_date", "client_name", "client_phone"],
        "properties": {
          "salon_id": { "type": "string" },
          "service_id": { "type": "string" },
          "booking_date": { "type": "string", "format": "date-time" },
          "client_name": { "type": "string", "example": "Marie Dupont" },
          "client_phone": { "type": "string", "example": "+237699112233" },
          "notes": { "type": "string" }
        }
      },
      "BookingResponse": {
        "type": "object",
        "properties": {
          "booking_id": { "type": "string", "format": "uuid" },
          "status": { "type": "string", "example": "confirmed" },
          "payment_link": { "type": "string" }
        }
      }
    }
  }
}