daiso 1.0.0

package/openapi.json

@@ -0,0 +1,1938 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "다이소 MCP API",
+    "description": "다이소 제품 검색, 매장 찾기, 재고 확인을 위한 API입니다.\n\n## 주요 기능\n- 🔍 **제품 검색**: 키워드로 다이소 제품 검색\n- 🏪 **매장 찾기**: 지역/키워드로 매장 검색\n- 📦 **재고 확인**: 온라인 및 오프라인 매장 재고 조회\n- 🎬 **메가박스 지점/영화 조회**: 주변 지점, 상영 목록, 잔여 좌석 조회\n- 🎥 **CGV 지점/영화 조회**: 극장 목록, 영화 목록, 시간표 조회\n\n## 사용 팁\n1. 한글 검색어는 URL 인코딩이 자동 처리됩니다\n2. 재고 확인 시 먼저 제품 검색으로 제품 ID를 확인하세요\n3. 위치 기반 재고 조회 시 lat, lng 파라미터를 활용하세요",
+    "version": "1.0.0",
+    "contact": {
+      "name": "GitHub Repository",
+      "url": "https://github.com/hmmhmmhm/daiso-mcp"
+    }
+  },
+  "servers": [
+    {
+      "url": "https://mcp.aka.page",
+      "description": "Production Server"
+    }
+  ],
+  "paths": {
+    "/api/daiso/products": {
+      "get": {
+        "operationId": "searchProducts",
+        "summary": "제품 검색",
+        "description": "키워드로 다이소 제품을 검색합니다. 수납박스, 펜, 정리함 등 다양한 키워드로 검색할 수 있습니다.",
+        "parameters": [
+          {
+            "name": "q",
+            "in": "query",
+            "required": true,
+            "description": "검색 키워드 (예: 수납박스, 펜, 정리함)",
+            "schema": {
+              "type": "string"
+            },
+            "example": "수납박스"
+          },
+          {
+            "name": "page",
+            "in": "query",
+            "required": false,
+            "description": "페이지 번호",
+            "schema": {
+              "type": "integer",
+              "default": 1,
+              "minimum": 1
+            }
+          },
+          {
+            "name": "pageSize",
+            "in": "query",
+            "required": false,
+            "description": "페이지당 결과 수",
+            "schema": {
+              "type": "integer",
+              "default": 30,
+              "minimum": 1,
+              "maximum": 100
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "검색 성공",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProductSearchResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "잘못된 요청 (검색어 누락)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/daiso/products/{productId}": {
+      "get": {
+        "operationId": "getProduct",
+        "summary": "제품 상세 정보",
+        "description": "제품 ID로 상세 정보를 조회합니다.",
+        "parameters": [
+          {
+            "name": "productId",
+            "in": "path",
+            "required": true,
+            "description": "제품 ID (제품 검색 결과의 id 값)",
+            "schema": {
+              "type": "string"
+            },
+            "example": "1234567890"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "조회 성공",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProductDetailResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "제품을 찾을 수 없음",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/daiso/stores": {
+      "get": {
+        "operationId": "findStores",
+        "summary": "매장 찾기",
+        "description": "키워드 또는 지역으로 다이소 매장을 검색합니다. keyword 또는 sido 중 하나는 필수입니다.",
+        "parameters": [
+          {
+            "name": "keyword",
+            "in": "query",
+            "required": false,
+            "description": "매장명 또는 주소 키워드 (예: 강남, 홍대, 안산)",
+            "schema": {
+              "type": "string"
+            },
+            "example": "강남"
+          },
+          {
+            "name": "sido",
+            "in": "query",
+            "required": false,
+            "description": "시/도 (예: 서울, 경기, 부산)",
+            "schema": {
+              "type": "string"
+            },
+            "example": "서울"
+          },
+          {
+            "name": "gugun",
+            "in": "query",
+            "required": false,
+            "description": "구/군 (예: 강남구, 마포구)",
+            "schema": {
+              "type": "string"
+            },
+            "example": "강남구"
+          },
+          {
+            "name": "dong",
+            "in": "query",
+            "required": false,
+            "description": "동 (예: 역삼동, 합정동)",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "required": false,
+            "description": "최대 결과 수",
+            "schema": {
+              "type": "integer",
+              "default": 50,
+              "minimum": 1,
+              "maximum": 100
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "검색 성공",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/StoreSearchResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "잘못된 요청 (필수 파라미터 누락)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/daiso/inventory": {
+      "get": {
+        "operationId": "checkInventory",
+        "summary": "재고 확인",
+        "description": "특정 제품의 온라인 재고와 매장별 재고를 확인합니다. 위치 정보를 제공하면 가까운 매장 순으로 정렬됩니다.",
+        "parameters": [
+          {
+            "name": "productId",
+            "in": "query",
+            "required": true,
+            "description": "제품 ID (제품 검색 결과의 id 값)",
+            "schema": {
+              "type": "string"
+            },
+            "example": "1234567890"
+          },
+          {
+            "name": "lat",
+            "in": "query",
+            "required": false,
+            "description": "위도 (기본값: 서울 시청 37.5665)",
+            "schema": {
+              "type": "number",
+              "format": "float",
+              "default": 37.5665
+            },
+            "example": 37.4979
+          },
+          {
+            "name": "lng",
+            "in": "query",
+            "required": false,
+            "description": "경도 (기본값: 서울 시청 126.978)",
+            "schema": {
+              "type": "number",
+              "format": "float",
+              "default": 126.978
+            },
+            "example": 127.0276
+          },
+          {
+            "name": "keyword",
+            "in": "query",
+            "required": false,
+            "description": "매장 검색어 (예: 안산, 강남)",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "page",
+            "in": "query",
+            "required": false,
+            "description": "페이지 번호",
+            "schema": {
+              "type": "integer",
+              "default": 1,
+              "minimum": 1
+            }
+          },
+          {
+            "name": "pageSize",
+            "in": "query",
+            "required": false,
+            "description": "페이지당 결과 수",
+            "schema": {
+              "type": "integer",
+              "default": 30,
+              "minimum": 1,
+              "maximum": 100
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "조회 성공",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/InventoryResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "잘못된 요청 (제품 ID 누락)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/oliveyoung/stores": {
+      "get": {
+        "operationId": "oliveyoungFindStores",
+        "summary": "올리브영 매장 검색",
+        "description": "위치(위도/경도)와 키워드로 올리브영 매장을 검색합니다.",
+        "parameters": [
+          {
+            "name": "keyword",
+            "in": "query",
+            "required": false,
+            "description": "매장명 또는 지역 키워드 (예: 명동, 강남)",
+            "schema": {
+              "type": "string"
+            },
+            "example": "명동"
+          },
+          {
+            "name": "lat",
+            "in": "query",
+            "required": false,
+            "description": "위도 (기본값: 서울 시청 37.5665)",
+            "schema": {
+              "type": "number",
+              "format": "float",
+              "default": 37.5665
+            }
+          },
+          {
+            "name": "lng",
+            "in": "query",
+            "required": false,
+            "description": "경도 (기본값: 서울 시청 126.978)",
+            "schema": {
+              "type": "number",
+              "format": "float",
+              "default": 126.978
+            }
+          },
+          {
+            "name": "pageIdx",
+            "in": "query",
+            "required": false,
+            "description": "매장 검색 페이지 번호",
+            "schema": {
+              "type": "integer",
+              "default": 1,
+              "minimum": 1
+            }
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "required": false,
+            "description": "최대 결과 수",
+            "schema": {
+              "type": "integer",
+              "default": 20,
+              "minimum": 1,
+              "maximum": 100
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "검색 성공",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/OliveyoungStoreSearchResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "올리브영 API 호출 실패",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/oliveyoung/inventory": {
+      "get": {
+        "operationId": "oliveyoungCheckInventory",
+        "summary": "올리브영 재고 확인",
+        "description": "상품 키워드로 올리브영 재고를 검색하고 주변 매장 정보를 함께 조회합니다.",
+        "parameters": [
+          {
+            "name": "keyword",
+            "in": "query",
+            "required": true,
+            "description": "재고를 확인할 상품 키워드",
+            "schema": {
+              "type": "string"
+            },
+            "example": "선크림"
+          },
+          {
+            "name": "lat",
+            "in": "query",
+            "required": false,
+            "description": "위도 (기본값: 서울 시청 37.5665)",
+            "schema": {
+              "type": "number",
+              "format": "float",
+              "default": 37.5665
+            }
+          },
+          {
+            "name": "lng",
+            "in": "query",
+            "required": false,
+            "description": "경도 (기본값: 서울 시청 126.978)",
+            "schema": {
+              "type": "number",
+              "format": "float",
+              "default": 126.978
+            }
+          },
+          {
+            "name": "storeKeyword",
+            "in": "query",
+            "required": false,
+            "description": "주변 매장 필터 키워드",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "page",
+            "in": "query",
+            "required": false,
+            "description": "상품 검색 페이지 번호",
+            "schema": {
+              "type": "integer",
+              "default": 1,
+              "minimum": 1
+            }
+          },
+          {
+            "name": "size",
+            "in": "query",
+            "required": false,
+            "description": "페이지당 결과 수",
+            "schema": {
+              "type": "integer",
+              "default": 20,
+              "minimum": 1,
+              "maximum": 100
+            }
+          },
+          {
+            "name": "sort",
+            "in": "query",
+            "required": false,
+            "description": "정렬 코드",
+            "schema": {
+              "type": "string",
+              "default": "01"
+            }
+          },
+          {
+            "name": "includeSoldOut",
+            "in": "query",
+            "required": false,
+            "description": "품절 포함 여부 (true/false)",
+            "schema": {
+              "type": "boolean",
+              "default": false
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "조회 성공",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/OliveyoungInventoryResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "잘못된 요청 (검색어 누락)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "올리브영 API 호출 실패",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/megabox/theaters": {
+      "get": {
+        "operationId": "megaboxFindNearbyTheaters",
+        "summary": "메가박스 주변 지점 조회",
+        "description": "좌표 기준으로 메가박스 지점을 거리순으로 조회합니다.",
+        "parameters": [
+          {
+            "name": "lat",
+            "in": "query",
+            "required": false,
+            "description": "위도 (기본값: 서울 시청 37.5665)",
+            "schema": {
+              "type": "number",
+              "format": "float",
+              "default": 37.5665
+            }
+          },
+          {
+            "name": "lng",
+            "in": "query",
+            "required": false,
+            "description": "경도 (기본값: 서울 시청 126.978)",
+            "schema": {
+              "type": "number",
+              "format": "float",
+              "default": 126.978
+            }
+          },
+          {
+            "name": "playDate",
+            "in": "query",
+            "required": false,
+            "description": "조회 날짜 (YYYYMMDD)",
+            "schema": {
+              "type": "string",
+              "example": "20260304"
+            }
+          },
+          {
+            "name": "areaCode",
+            "in": "query",
+            "required": false,
+            "description": "지역 코드 (기본값: 11, 서울)",
+            "schema": {
+              "type": "string",
+              "default": "11"
+            }
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "required": false,
+            "description": "최대 결과 수",
+            "schema": {
+              "type": "integer",
+              "default": 10,
+              "minimum": 1,
+              "maximum": 100
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "조회 성공",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/MegaboxTheaterSearchResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "메가박스 API 호출 실패",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/megabox/movies": {
+      "get": {
+        "operationId": "megaboxListNowShowing",
+        "summary": "메가박스 영화/회차 목록 조회",
+        "description": "날짜, 지점, 영화 조건으로 메가박스 영화 및 상영 회차를 조회합니다.",
+        "parameters": [
+          {
+            "name": "playDate",
+            "in": "query",
+            "required": false,
+            "description": "조회 날짜 (YYYYMMDD)",
+            "schema": {
+              "type": "string",
+              "example": "20260304"
+            }
+          },
+          {
+            "name": "theaterId",
+            "in": "query",
+            "required": false,
+            "description": "지점 ID (예: 1372)",
+            "schema": {
+              "type": "string",
+              "example": "1372"
+            }
+          },
+          {
+            "name": "movieId",
+            "in": "query",
+            "required": false,
+            "description": "영화 ID (예: 25104500)",
+            "schema": {
+              "type": "string",
+              "example": "25104500"
+            }
+          },
+          {
+            "name": "areaCode",
+            "in": "query",
+            "required": false,
+            "description": "지역 코드 (기본값: 11, 서울)",
+            "schema": {
+              "type": "string",
+              "default": "11"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "조회 성공",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/MegaboxMovieListResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "메가박스 API 호출 실패",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/megabox/seats": {
+      "get": {
+        "operationId": "megaboxGetRemainingSeats",
+        "summary": "메가박스 잔여 좌석 조회",
+        "description": "영화/지점/날짜 조건으로 회차별 잔여 좌석 수를 조회합니다.",
+        "parameters": [
+          {
+            "name": "playDate",
+            "in": "query",
+            "required": false,
+            "description": "조회 날짜 (YYYYMMDD)",
+            "schema": {
+              "type": "string",
+              "example": "20260304"
+            }
+          },
+          {
+            "name": "theaterId",
+            "in": "query",
+            "required": false,
+            "description": "지점 ID",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "movieId",
+            "in": "query",
+            "required": false,
+            "description": "영화 ID",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "areaCode",
+            "in": "query",
+            "required": false,
+            "description": "지역 코드 (기본값: 11, 서울)",
+            "schema": {
+              "type": "string",
+              "default": "11"
+            }
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "required": false,
+            "description": "최대 결과 수",
+            "schema": {
+              "type": "integer",
+              "default": 50,
+              "minimum": 1,
+              "maximum": 200
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "조회 성공",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/MegaboxSeatListResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "메가박스 API 호출 실패",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/cgv/theaters": {
+      "get": {
+        "operationId": "cgvFindTheaters",
+        "summary": "CGV 극장 목록 조회",
+        "description": "날짜/지역 코드 조건으로 CGV 극장 목록을 조회합니다.",
+        "parameters": [
+          {
+            "name": "playDate",
+            "in": "query",
+            "required": false,
+            "description": "조회 날짜 (YYYYMMDD)",
+            "schema": {
+              "type": "string",
+              "example": "20260304"
+            }
+          },
+          {
+            "name": "regionCode",
+            "in": "query",
+            "required": false,
+            "description": "지역 코드 (예: 01 서울)",
+            "schema": {
+              "type": "string",
+              "example": "01"
+            }
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "required": false,
+            "description": "최대 결과 수",
+            "schema": {
+              "type": "integer",
+              "default": 30,
+              "minimum": 1,
+              "maximum": 100
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "조회 성공",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CgvTheaterSearchResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "CGV API 호출 실패",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/cgv/movies": {
+      "get": {
+        "operationId": "cgvSearchMovies",
+        "summary": "CGV 영화 목록 조회",
+        "description": "날짜/극장 조건으로 CGV 영화 목록을 조회합니다.",
+        "parameters": [
+          {
+            "name": "playDate",
+            "in": "query",
+            "required": false,
+            "description": "조회 날짜 (YYYYMMDD)",
+            "schema": {
+              "type": "string",
+              "example": "20260304"
+            }
+          },
+          {
+            "name": "theaterCode",
+            "in": "query",
+            "required": false,
+            "description": "극장 코드 (예: 0056)",
+            "schema": {
+              "type": "string",
+              "example": "0056"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "조회 성공",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CgvMovieSearchResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "CGV API 호출 실패",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/cgv/timetable": {
+      "get": {
+        "operationId": "cgvGetTimetable",
+        "summary": "CGV 시간표 조회",
+        "description": "날짜/극장/영화 조건으로 CGV 상영 시간표를 조회합니다.",
+        "parameters": [
+          {
+            "name": "playDate",
+            "in": "query",
+            "required": false,
+            "description": "조회 날짜 (YYYYMMDD)",
+            "schema": {
+              "type": "string",
+              "example": "20260304"
+            }
+          },
+          {
+            "name": "theaterCode",
+            "in": "query",
+            "required": false,
+            "description": "극장 코드",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "movieCode",
+            "in": "query",
+            "required": false,
+            "description": "영화 코드",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "required": false,
+            "description": "최대 결과 수",
+            "schema": {
+              "type": "integer",
+              "default": 50,
+              "minimum": 1,
+              "maximum": 200
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "조회 성공",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CgvTimetableResponse"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "CGV API 호출 실패",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "Product": {
+        "type": "object",
+        "description": "제품 정보",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "제품 ID",
+            "example": "1234567890"
+          },
+          "name": {
+            "type": "string",
+            "description": "제품명",
+            "example": "PP 수납박스 대형"
+          },
+          "price": {
+            "type": "integer",
+            "description": "가격 (원)",
+            "example": 5000
+          },
+          "imageUrl": {
+            "type": "string",
+            "description": "제품 이미지 URL",
+            "example": "https://img.daisomall.co.kr/..."
+          },
+          "soldOut": {
+            "type": "boolean",
+            "description": "품절 여부",
+            "example": false
+          },
+          "isNew": {
+            "type": "boolean",
+            "description": "신상품 여부",
+            "example": false
+          },
+          "pickupAvailable": {
+            "type": "boolean",
+            "description": "매장 픽업 가능 여부",
+            "example": true
+          }
+        }
+      },
+      "ProductDetail": {
+        "type": "object",
+        "description": "제품 상세 정보",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "제품 ID"
+          },
+          "name": {
+            "type": "string",
+            "description": "제품명"
+          },
+          "price": {
+            "type": "integer",
+            "description": "가격 (원)"
+          },
+          "currency": {
+            "type": "string",
+            "description": "통화",
+            "example": "KRW"
+          },
+          "imageUrl": {
+            "type": "string",
+            "description": "제품 이미지 URL"
+          },
+          "brand": {
+            "type": "string",
+            "description": "브랜드명"
+          },
+          "soldOut": {
+            "type": "boolean",
+            "description": "품절 여부"
+          },
+          "isNew": {
+            "type": "boolean",
+            "description": "신상품 여부"
+          }
+        }
+      },
+      "Store": {
+        "type": "object",
+        "description": "매장 정보",
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "매장명",
+            "example": "다이소 강남역점"
+          },
+          "phone": {
+            "type": "string",
+            "description": "전화번호",
+            "example": "02-1234-5678"
+          },
+          "address": {
+            "type": "string",
+            "description": "주소",
+            "example": "서울특별시 강남구 강남대로 123"
+          },
+          "lat": {
+            "type": "number",
+            "format": "float",
+            "description": "위도",
+            "example": 37.4979
+          },
+          "lng": {
+            "type": "number",
+            "format": "float",
+            "description": "경도",
+            "example": 127.0276
+          },
+          "openTime": {
+            "type": "string",
+            "description": "영업 시작 시간",
+            "example": "10:00"
+          },
+          "closeTime": {
+            "type": "string",
+            "description": "영업 종료 시간",
+            "example": "22:00"
+          },
+          "options": {
+            "type": "object",
+            "description": "매장 옵션",
+            "properties": {
+              "parking": {
+                "type": "boolean",
+                "description": "주차 가능 여부"
+              },
+              "pickup": {
+                "type": "boolean",
+                "description": "픽업 가능 여부"
+              },
+              "taxFree": {
+                "type": "boolean",
+                "description": "면세 가능 여부"
+              }
+            }
+          }
+        }
+      },
+      "StoreInventory": {
+        "type": "object",
+        "description": "매장 재고 정보",
+        "properties": {
+          "storeCode": {
+            "type": "string",
+            "description": "매장 코드",
+            "example": "ST001"
+          },
+          "storeName": {
+            "type": "string",
+            "description": "매장명",
+            "example": "다이소 강남역점"
+          },
+          "address": {
+            "type": "string",
+            "description": "주소"
+          },
+          "distance": {
+            "type": "string",
+            "description": "거리",
+            "example": "0.5km"
+          },
+          "quantity": {
+            "type": "integer",
+            "description": "재고 수량",
+            "example": 12
+          },
+          "options": {
+            "type": "object",
+            "properties": {
+              "parking": {
+                "type": "boolean"
+              },
+              "pickup": {
+                "type": "boolean"
+              }
+            }
+          }
+        }
+      },
+      "ProductSearchResponse": {
+        "type": "object",
+        "properties": {
+          "success": {
+            "type": "boolean",
+            "example": true
+          },
+          "data": {
+            "type": "object",
+            "properties": {
+              "products": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/components/schemas/Product"
+                }
+              }
+            }
+          },
+          "meta": {
+            "type": "object",
+            "properties": {
+              "total": {
+                "type": "integer",
+                "description": "전체 결과 수"
+              },
+              "page": {
+                "type": "integer",
+                "description": "현재 페이지"
+              },
+              "pageSize": {
+                "type": "integer",
+                "description": "페이지당 결과 수"
+              }
+            }
+          }
+        }
+      },
+      "ProductDetailResponse": {
+        "type": "object",
+        "properties": {
+          "success": {
+            "type": "boolean",
+            "example": true
+          },
+          "data": {
+            "$ref": "#/components/schemas/ProductDetail"
+          }
+        }
+      },
+      "StoreSearchResponse": {
+        "type": "object",
+        "properties": {
+          "success": {
+            "type": "boolean",
+            "example": true
+          },
+          "data": {
+            "type": "object",
+            "properties": {
+              "stores": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/components/schemas/Store"
+                }
+              }
+            }
+          },
+          "meta": {
+            "type": "object",
+            "properties": {
+              "total": {
+                "type": "integer",
+                "description": "전체 결과 수"
+              }
+            }
+          }
+        }
+      },
+      "InventoryResponse": {
+        "type": "object",
+        "properties": {
+          "success": {
+            "type": "boolean",
+            "example": true
+          },
+          "data": {
+            "type": "object",
+            "properties": {
+              "productId": {
+                "type": "string",
+                "description": "제품 ID"
+              },
+              "location": {
+                "type": "object",
+                "properties": {
+                  "latitude": {
+                    "type": "number",
+                    "format": "float"
+                  },
+                  "longitude": {
+                    "type": "number",
+                    "format": "float"
+                  }
+                }
+              },
+              "onlineStock": {
+                "type": "integer",
+                "description": "온라인 재고 수량",
+                "example": 150
+              },
+              "storeInventory": {
+                "type": "object",
+                "properties": {
+                  "totalStores": {
+                    "type": "integer",
+                    "description": "전체 매장 수"
+                  },
+                  "inStockCount": {
+                    "type": "integer",
+                    "description": "재고 있는 매장 수"
+                  },
+                  "stores": {
+                    "type": "array",
+                    "items": {
+                      "$ref": "#/components/schemas/StoreInventory"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "meta": {
+            "type": "object",
+            "properties": {
+              "total": {
+                "type": "integer"
+              },
+              "page": {
+                "type": "integer"
+              },
+              "pageSize": {
+                "type": "integer"
+              }
+            }
+          }
+        }
+      },
+      "OliveyoungStore": {
+        "type": "object",
+        "description": "올리브영 매장 정보",
+        "properties": {
+          "storeCode": {
+            "type": "string",
+            "example": "D176"
+          },
+          "storeName": {
+            "type": "string",
+            "example": "올리브영 명동 타운"
+          },
+          "address": {
+            "type": "string",
+            "example": "서울특별시 중구 명동길 53"
+          },
+          "latitude": {
+            "type": "number",
+            "format": "float",
+            "example": 37.56409158
+          },
+          "longitude": {
+            "type": "number",
+            "format": "float",
+            "example": 126.9851771
+          },
+          "pickupYn": {
+            "type": "boolean",
+            "example": false
+          },
+          "o2oRemainQuantity": {
+            "type": "integer",
+            "example": 0
+          }
+        }
+      },
+      "OliveyoungProduct": {
+        "type": "object",
+        "description": "올리브영 상품 재고 정보",
+        "properties": {
+          "goodsNumber": {
+            "type": "string",
+            "example": "A000000200614"
+          },
+          "goodsName": {
+            "type": "string",
+            "example": "달바 퍼플 톤업 선크림 듀오 기획"
+          },
+          "priceToPay": {
+            "type": "integer",
+            "example": 32130
+          },
+          "originalPrice": {
+            "type": "integer",
+            "example": 51000
+          },
+          "discountRate": {
+            "type": "integer",
+            "example": 37
+          },
+          "o2oStockFlag": {
+            "type": "boolean",
+            "example": true
+          },
+          "o2oRemainQuantity": {
+            "type": "integer",
+            "example": 0
+          }
+        }
+      },
+      "OliveyoungStoreSearchResponse": {
+        "type": "object",
+        "properties": {
+          "success": {
+            "type": "boolean",
+            "example": true
+          },
+          "data": {
+            "type": "object",
+            "properties": {
+              "stores": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/components/schemas/OliveyoungStore"
+                }
+              }
+            }
+          },
+          "meta": {
+            "type": "object",
+            "properties": {
+              "total": {
+                "type": "integer"
+              },
+              "page": {
+                "type": "integer"
+              },
+              "pageSize": {
+                "type": "integer"
+              }
+            }
+          }
+        }
+      },
+      "OliveyoungInventoryResponse": {
+        "type": "object",
+        "properties": {
+          "success": {
+            "type": "boolean",
+            "example": true
+          },
+          "data": {
+            "type": "object",
+            "properties": {
+              "keyword": {
+                "type": "string",
+                "example": "선크림"
+              },
+              "location": {
+                "type": "object",
+                "properties": {
+                  "latitude": {
+                    "type": "number",
+                    "format": "float"
+                  },
+                  "longitude": {
+                    "type": "number",
+                    "format": "float"
+                  }
+                }
+              },
+              "nearbyStores": {
+                "type": "object",
+                "properties": {
+                  "totalCount": {
+                    "type": "integer"
+                  },
+                  "stores": {
+                    "type": "array",
+                    "items": {
+                      "$ref": "#/components/schemas/OliveyoungStore"
+                    }
+                  }
+                }
+              },
+              "inventory": {
+                "type": "object",
+                "properties": {
+                  "totalCount": {
+                    "type": "integer"
+                  },
+                  "nextPage": {
+                    "type": "boolean"
+                  },
+                  "products": {
+                    "type": "array",
+                    "items": {
+                      "$ref": "#/components/schemas/OliveyoungProduct"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "meta": {
+            "type": "object",
+            "properties": {
+              "total": {
+                "type": "integer"
+              },
+              "page": {
+                "type": "integer"
+              },
+              "pageSize": {
+                "type": "integer"
+              }
+            }
+          }
+        }
+      },
+      "MegaboxTheater": {
+        "type": "object",
+        "properties": {
+          "theaterId": {
+            "type": "string",
+            "example": "1372"
+          },
+          "theaterName": {
+            "type": "string",
+            "example": "강남"
+          },
+          "address": {
+            "type": "string",
+            "example": "서울특별시 강남구 강남대로 438"
+          },
+          "latitude": {
+            "type": "number",
+            "format": "float",
+            "example": 37.4982
+          },
+          "longitude": {
+            "type": "number",
+            "format": "float",
+            "example": 127.0264
+          },
+          "distanceKm": {
+            "type": "number",
+            "format": "float",
+            "example": 0.5
+          }
+        }
+      },
+      "MegaboxShowtime": {
+        "type": "object",
+        "properties": {
+          "scheduleId": {
+            "type": "string",
+            "example": "2603041372011"
+          },
+          "movieId": {
+            "type": "string",
+            "example": "25104500"
+          },
+          "movieName": {
+            "type": "string",
+            "example": "미키 17"
+          },
+          "theaterId": {
+            "type": "string",
+            "example": "1372"
+          },
+          "theaterName": {
+            "type": "string",
+            "example": "강남"
+          },
+          "playDate": {
+            "type": "string",
+            "example": "20260304"
+          },
+          "startTime": {
+            "type": "string",
+            "example": "09:30"
+          },
+          "endTime": {
+            "type": "string",
+            "example": "11:20"
+          },
+          "totalSeats": {
+            "type": "integer",
+            "example": 120
+          },
+          "remainingSeats": {
+            "type": "integer",
+            "example": 42
+          }
+        }
+      },
+      "MegaboxTheaterSearchResponse": {
+        "type": "object",
+        "properties": {
+          "success": {
+            "type": "boolean",
+            "example": true
+          },
+          "data": {
+            "type": "object",
+            "properties": {
+              "location": {
+                "type": "object",
+                "properties": {
+                  "latitude": {
+                    "type": "number",
+                    "format": "float"
+                  },
+                  "longitude": {
+                    "type": "number",
+                    "format": "float"
+                  }
+                }
+              },
+              "playDate": {
+                "type": "string"
+              },
+              "areaCode": {
+                "type": "string"
+              },
+              "theaters": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/components/schemas/MegaboxTheater"
+                }
+              }
+            }
+          },
+          "meta": {
+            "type": "object",
+            "properties": {
+              "total": {
+                "type": "integer"
+              },
+              "pageSize": {
+                "type": "integer"
+              }
+            }
+          }
+        }
+      },
+      "MegaboxMovieListResponse": {
+        "type": "object",
+        "properties": {
+          "success": {
+            "type": "boolean",
+            "example": true
+          },
+          "data": {
+            "type": "object",
+            "properties": {
+              "playDate": {
+                "type": "string"
+              },
+              "filters": {
+                "type": "object",
+                "properties": {
+                  "theaterId": {
+                    "type": "string",
+                    "nullable": true
+                  },
+                  "movieId": {
+                    "type": "string",
+                    "nullable": true
+                  },
+                  "areaCode": {
+                    "type": "string"
+                  }
+                }
+              },
+              "theaters": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "theaterId": {
+                      "type": "string"
+                    },
+                    "theaterName": {
+                      "type": "string"
+                    }
+                  }
+                }
+              },
+              "movies": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "movieId": {
+                      "type": "string"
+                    },
+                    "movieName": {
+                      "type": "string"
+                    },
+                    "movieStatus": {
+                      "type": "string"
+                    }
+                  }
+                }
+              },
+              "showtimes": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/components/schemas/MegaboxShowtime"
+                }
+              }
+            }
+          },
+          "meta": {
+            "type": "object",
+            "properties": {
+              "total": {
+                "type": "integer"
+              }
+            }
+          }
+        }
+      },
+      "MegaboxSeatListResponse": {
+        "type": "object",
+        "properties": {
+          "success": {
+            "type": "boolean",
+            "example": true
+          },
+          "data": {
+            "type": "object",
+            "properties": {
+              "playDate": {
+                "type": "string"
+              },
+              "filters": {
+                "type": "object",
+                "properties": {
+                  "theaterId": {
+                    "type": "string",
+                    "nullable": true
+                  },
+                  "movieId": {
+                    "type": "string",
+                    "nullable": true
+                  },
+                  "areaCode": {
+                    "type": "string"
+                  }
+                }
+              },
+              "seats": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/components/schemas/MegaboxShowtime"
+                }
+              }
+            }
+          },
+          "meta": {
+            "type": "object",
+            "properties": {
+              "total": {
+                "type": "integer"
+              },
+              "pageSize": {
+                "type": "integer"
+              }
+            }
+          }
+        }
+      },
+      "CgvTheater": {
+        "type": "object",
+        "properties": {
+          "theaterCode": {
+            "type": "string",
+            "example": "0056"
+          },
+          "theaterName": {
+            "type": "string",
+            "example": "CGV강남"
+          },
+          "regionCode": {
+            "type": "string",
+            "example": "01"
+          }
+        }
+      },
+      "CgvMovie": {
+        "type": "object",
+        "properties": {
+          "movieCode": {
+            "type": "string",
+            "example": "200001"
+          },
+          "movieName": {
+            "type": "string",
+            "example": "테스트 영화"
+          },
+          "rating": {
+            "type": "string",
+            "example": "12"
+          }
+        }
+      },
+      "CgvTimetable": {
+        "type": "object",
+        "properties": {
+          "scheduleId": {
+            "type": "string",
+            "example": "SCH1"
+          },
+          "movieCode": {
+            "type": "string",
+            "example": "200001"
+          },
+          "movieName": {
+            "type": "string",
+            "example": "테스트 영화"
+          },
+          "theaterCode": {
+            "type": "string",
+            "example": "0056"
+          },
+          "theaterName": {
+            "type": "string",
+            "example": "CGV강남"
+          },
+          "playDate": {
+            "type": "string",
+            "example": "20260304"
+          },
+          "startTime": {
+            "type": "string",
+            "example": "09:30"
+          },
+          "endTime": {
+            "type": "string",
+            "example": "11:20"
+          },
+          "totalSeats": {
+            "type": "integer",
+            "example": 150
+          },
+          "remainingSeats": {
+            "type": "integer",
+            "example": 42
+          }
+        }
+      },
+      "CgvTheaterSearchResponse": {
+        "type": "object",
+        "properties": {
+          "success": {
+            "type": "boolean",
+            "example": true
+          },
+          "data": {
+            "type": "object",
+            "properties": {
+              "playDate": {
+                "type": "string"
+              },
+              "filters": {
+                "type": "object",
+                "properties": {
+                  "regionCode": {
+                    "type": "string",
+                    "nullable": true
+                  }
+                }
+              },
+              "theaters": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/components/schemas/CgvTheater"
+                }
+              }
+            }
+          },
+          "meta": {
+            "type": "object",
+            "properties": {
+              "total": {
+                "type": "integer"
+              },
+              "pageSize": {
+                "type": "integer"
+              }
+            }
+          }
+        }
+      },
+      "CgvMovieSearchResponse": {
+        "type": "object",
+        "properties": {
+          "success": {
+            "type": "boolean",
+            "example": true
+          },
+          "data": {
+            "type": "object",
+            "properties": {
+              "playDate": {
+                "type": "string"
+              },
+              "filters": {
+                "type": "object",
+                "properties": {
+                  "theaterCode": {
+                    "type": "string",
+                    "nullable": true
+                  }
+                }
+              },
+              "movies": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/components/schemas/CgvMovie"
+                }
+              }
+            }
+          },
+          "meta": {
+            "type": "object",
+            "properties": {
+              "total": {
+                "type": "integer"
+              }
+            }
+          }
+        }
+      },
+      "CgvTimetableResponse": {
+        "type": "object",
+        "properties": {
+          "success": {
+            "type": "boolean",
+            "example": true
+          },
+          "data": {
+            "type": "object",
+            "properties": {
+              "playDate": {
+                "type": "string"
+              },
+              "filters": {
+                "type": "object",
+                "properties": {
+                  "theaterCode": {
+                    "type": "string",
+                    "nullable": true
+                  },
+                  "movieCode": {
+                    "type": "string",
+                    "nullable": true
+                  }
+                }
+              },
+              "timetable": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/components/schemas/CgvTimetable"
+                }
+              }
+            }
+          },
+          "meta": {
+            "type": "object",
+            "properties": {
+              "total": {
+                "type": "integer"
+              },
+              "pageSize": {
+                "type": "integer"
+              }
+            }
+          }
+        }
+      },
+      "ErrorResponse": {
+        "type": "object",
+        "properties": {
+          "success": {
+            "type": "boolean",
+            "example": false
+          },
+          "error": {
+            "type": "object",
+            "properties": {
+              "code": {
+                "type": "string",
+                "description": "에러 코드",
+                "example": "MISSING_QUERY"
+              },
+              "message": {
+                "type": "string",
+                "description": "에러 메시지",
+                "example": "검색어(q)를 입력해주세요."
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}