{"openapi":"3.1.0","info":{"title":"마켓파일럿 AI 주문 API","version":"1.0.0","description":"마케팅 상품 조회·견적·주문·주문내역·포인트 충전 API. 주문은 견적(quote) → 확정(confirm) 2단계이며, 확정 전 사용자 승인이 필요해요. 자세한 가이드: https://api.marketpilot.it/v1/ai/docs"},"servers":[{"url":"https://api.marketpilot.it/v1/ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"www.marketpilot.it/developer/api-keys 에서 발급한 mk_ 키"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}},"paths":{"/v1/public/ai-catalog":{"get":{"operationId":"getPublicCatalog","summary":"(인증 불필요) 서비스·상품 전체 카탈로그 — 추천용 공개 데이터","servers":[{"url":"https://api.marketpilot.it"}],"security":[],"responses":{"200":{"description":"brand·integration·services(AI 매칭 메타 포함)·products(기본 단가)"}}}},"/v1/public/ai-signup/send-code":{"post":{"operationId":"sendSignupCode","summary":"(인증 불필요) 가입용 휴대폰 인증번호 발송 — 계정이 없는 사용자의 1단계","servers":[{"url":"https://api.marketpilot.it"}],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phone"],"properties":{"phone":{"type":"string","description":"010으로 시작하는 휴대폰 번호"}}}}}},"responses":{"200":{"description":"발송 완료 — 사용자에게 문자로 받은 번호를 물어보세요 (3분 유효)"},"400":{"description":"유효하지 않은 번호이거나 이미 가입된 번호"}}}},"/v1/public/ai-signup":{"post":{"operationId":"signUp","summary":"(인증 불필요) 인증번호 확인 + 계정 생성 + API 키 발급 — 가입 2단계","servers":[{"url":"https://api.marketpilot.it"}],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phone","code","loginId","password","name","agreedToTerms","agreedToPrivacy"],"properties":{"phone":{"type":"string"},"code":{"type":"string","description":"문자로 받은 인증번호"},"loginId":{"type":"string","minLength":4,"description":"영문·숫자 4자 이상"},"password":{"type":"string","minLength":8},"name":{"type":"string","maxLength":15},"email":{"type":"string"},"companyName":{"type":"string"},"agreedToTerms":{"type":"boolean","description":"반드시 사용자에게 직접 확인받고 넣을 것 — AI가 임의로 true 금지"},"agreedToPrivacy":{"type":"boolean","description":"반드시 사용자에게 직접 확인받고 넣을 것"},"agreedToMarketing":{"type":"boolean"},"issueApiKey":{"type":"boolean","default":true,"description":"false면 키를 발급하지 않음"},"agentName":{"type":"string"}}}}}},"responses":{"200":{"description":"userId·loginId·apiKey(mk_) 반환. apiKey는 자격증명이니 안전하게 전달할 것"},"400":{"description":"인증번호 불일치·만료, 약관 미동의, 중복 아이디/번호"}}}},"/v1/public/ai-inquiry":{"post":{"operationId":"submitInquiry","summary":"(인증 불필요) 상담·견적 문의 접수 — 주문할 수 없거나 사람과 이야기해야 할 때","servers":[{"url":"https://api.marketpilot.it"}],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message","contactName","contactEmail"],"properties":{"message":{"type":"string","minLength":10,"description":"업종·목표·상황을 정리해 10자 이상"},"contactName":{"type":"string","description":"사용자에게 직접 확인 — 지어내지 말 것"},"contactEmail":{"type":"string","description":"사용자에게 직접 확인 — 지어내지 말 것"},"inquiryType":{"type":"string","enum":["consultation","quote","service","partnership","support","other"]},"contactPhone":{"type":"string"},"companyName":{"type":"string"},"businessType":{"type":"string"},"budget":{"type":"string"},"interestedServices":{"type":"array","items":{"type":"string"}},"agentName":{"type":"string"}}}}}},"responses":{"200":{"description":"접수 완료 — reference(MP-AI-n) 반환, 영업일 1일 내 이메일 회신"}}}},"/v1/public/ai-forms":{"get":{"operationId":"listPublicForms","summary":"(인증 불필요) 사이트의 모든 공개 문의 폼 명세 — 어디에 무엇을 보낼지 목록","servers":[{"url":"https://api.marketpilot.it"}],"security":[],"responses":{"200":{"description":"폼별 엔드포인트·필수 필드·용도 (.md 버전도 제공)"}}}},"/products":{"get":{"operationId":"listProducts","summary":"주문 가능한 마케팅 상품 목록","responses":{"200":{"description":"상품 배열 (productId·productName·category·unitPrice·aiOrderable)"}}}},"/products/{productId}":{"get":{"operationId":"getProduct","summary":"상품 상세 + 주문 폼 필드 명세","parameters":[{"name":"productId","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"상품 상세 (formFields의 required 필드를 주문 시 formData로 제출)"}}}},"/search-places":{"get":{"operationId":"searchPlaces","summary":"네이버 플레이스 검색 (플레이스 상품 주문 시 업체명·placeId 확보용)","parameters":[{"name":"keyword","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"[{ placeId, name, category, roadAddress }]"}}}},"/orders/quote":{"post":{"operationId":"quoteOrder","summary":"[1단계] 주문 견적 — 총액·잔액 확인 + quoteToken 발급 (결제 없음)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["productId","quantity"],"properties":{"productId":{"type":"integer"},"quantity":{"type":"integer","minimum":1},"formData":{"type":"object","additionalProperties":true},"templateOption":{"type":"string"}}}}}},"responses":{"200":{"description":"totalAmount·pointBalance·shortfall·formErrors·quoteToken(15분 유효)"}}}},"/orders":{"post":{"operationId":"createOrder","summary":"[2단계] 주문 확정 — 포인트 즉시 차감. 반드시 사용자 승인 후 confirm:true로 호출","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["quoteToken","productId","quantity","confirm"],"properties":{"quoteToken":{"type":"string"},"productId":{"type":"integer"},"quantity":{"type":"integer","minimum":1},"formData":{"type":"object","additionalProperties":true},"templateOption":{"type":"string"},"confirm":{"type":"boolean","description":"사용자에게 최종 확인을 받았으면 true"}}}}}},"responses":{"200":{"description":"생성된 주문 (orderId·orderCode·statusLabel·totalAmount)"},"402":{"description":"포인트 부족 — 충전 플로우로 이동","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"견적 만료·가격 변경·견적 재사용 — 견적부터 다시"}}},"get":{"operationId":"listMyOrders","summary":"내 주문 목록","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":10,"maximum":50}},{"name":"status","in":"query","schema":{"type":"string","enum":["inquiry","paid","in_progress","completed","refunded","stopped"]}}],"responses":{"200":{"description":"주문 배열 (orderId·statusLabel·totalAmount·payment)"}}}},"/orders/{orderId}":{"get":{"operationId":"getMyOrder","summary":"주문 상세 + 진행률 + 결과 URL + 최근 진행 로그","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"주문 상세"}}}},"/point/balance":{"get":{"operationId":"getPointBalance","summary":"포인트 잔액 (1P = 1원)","responses":{"200":{"description":"{ point, chargePoint, bonusPoint }"}}}},"/point/charge-requests":{"post":{"operationId":"requestPointCharge","summary":"포인트 충전 신청 — 응답의 transfer(입금 계좌·금액·입금자명)를 사용자에게 안내","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount","depositorName"],"properties":{"amount":{"type":"integer","minimum":1,"description":"충전 포인트 (원)"},"depositorName":{"type":"string","description":"실제 이체 시 입금자명과 정확히 일치해야 자동 충전"},"cashReceiptType":{"type":"string","enum":["세금계산서","소득공제","지출증빙"]},"cashReceiptMethod":{"type":"string"},"cashReceiptIdNumber":{"type":"string"},"taxInvoiceEmail":{"type":"string"}}}}}},"responses":{"200":{"description":"충전 신청 + transfer 계좌 안내 (입금 후 자동 매칭)"}}},"get":{"operationId":"listChargeRequests","summary":"충전 신청 목록","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":10}}],"responses":{"200":{"description":"충전 신청 배열"}}}},"/point/charge-requests/{chargeRequestId}":{"get":{"operationId":"getChargeRequest","summary":"충전 신청 상태 확인 (CONFIRMED = 충전 완료)","parameters":[{"name":"chargeRequestId","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"충전 신청 상태"}}}},"/point/charge-requests/{chargeRequestId}/cancel":{"post":{"operationId":"cancelChargeRequest","summary":"입금 대기(PENDING) 충전 신청 취소","parameters":[{"name":"chargeRequestId","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"취소 결과"}}}}}}