상품문의

상품 상세의 "상품 문의(Q&A)" 입니다. 고객이 상품에 대해 남긴 질문과 판매자 답변을 조회·작성·수정·삭제하고, 운영자가 답변을 등록합니다. 인증·오류 형식·페이지네이션 같은 공통 내용은 인증·오류·페이지네이션을 봅니다.

두 가지 호출 모드

모드 헤더 쓰는 곳
고객 모드 Bootpay-Role 없음 또는 user 쇼핑몰 서버가 상품 상세의 문의 탭을 대신 부른다. 목록·단건·작성·수정·삭제
운영자 모드 Bootpay-Role: supervisor 가맹점 관리 서버. 프로젝트 전체 목록(view=all)·단건·삭제·답변
  • 작성·수정은 고객 모드만, 답변은 운영자 모드만 받습니다. 그 밖의 역할(manager 등)은 401 API_ROLE_NOT_SUPPORT 입니다.
  • 고객 모드는 쇼핑몰의 상품문의 사용 설정이 꺼져 있으면 442 PRODUCT_QNA_DISABLED 입니다. 운영자 모드는 설정과 무관합니다.

회원 지정 (고객 모드)

쇼핑몰 서버가 자기 로그인 세션의 회원을 JWT 또는 user_id 로 넣습니다(인증 — 호출 구조).

  • Bootpay-User-JWT 헤더 또는 user_id(쿼리·본문) 중 하나를 보냅니다. 24자리 회원 ID 면 Bootpay 회원 ID, 그 밖의 값은 이 몰의 외부 회원 ID(ex_uid)로 찾습니다. user_ex_uid·user_external_uid·user_uid 도 같은 뜻이고, 로그인 아이디로 지정하려면 login_id 를 보냅니다.
  • 둘 다 보내면 JWT 가 우선이고, 서로 다른 회원이면 403 USER_NOT_MATCH 입니다. user_id 는 secretKey 인증(Basic·Bearer)일 때만 받습니다.
  • 회원을 보내지 않으면 비회원​​으로 처리합니다. 비회원도 목록·공개글은 볼 수 있고, 몰이 비회원 문의를 허용하면 guest_name·guest_password 로 작성합니다. 비회원 문의의 수정·삭제는 작성 때 넣은 guest_password 로 합니다.
  • 브라우저가 보낸 user_id·guest_password 를 검증 없이 넘기지 마세요. 로그인한 회원 본인인지 확인하는 책임은 쇼핑몰 서버에 있습니다.

비밀글

비밀글(is_secret: true)의 본문과 답변은 작성 회원 본인​​과 운영자 모드​​만 받습니다.

  • 목록: 그 밖의 사람에게는 카드만 나갑니다 — is_viewable: false, content·title·product_option_id·option_text 없음, 답변이 있으면 answer 가 {"answered": true} 만.
  • 단건: 그 밖의 사람이 열면 403 PRODUCT_QNA_SECRET_FORBIDDEN 입니다.
  • 비회원이 쓴 비밀글은 회원 식별이 없어 목록·단건으로는 운영자만 본문을 봅니다. 비회원 작성자는 작성·수정 응답으로 자기 글을 확인합니다.

문의 객체

목록의 list[], 단건·작성·수정·답변 응답이 같은 모양입니다. 값이 없는 필드는 응답에서 빠집니다​(null 로 나가지 않습니다) — 제목·옵션이 없으면 title·product_option_id·option_text 가 없고, 답변이 없으면 answer 가 없습니다.

필드 타입 설명
product_qna_id string 상품문의 ID
product_id string 상품 ID
product_option_id string 문의한 옵션 ID. 없거나 볼 수 없으면 생략
title string 제목. 없거나 볼 수 없으면 생략
option_text string 작성 때 저장한 옵션 표시 문구(예: 화이트 / M). 없거나 볼 수 없으면 생략
is_secret boolean 비밀글 여부
status integer 1 게시 중, 3 관리자 숨김(운영자 모드에서만 보임)
need_reply boolean 답변 대기 중이면 true. 답변이 등록되면 false
created_at string 작성 시각(ISO 8601)
updated_at string 마지막 수정 시각(ISO 8601)
author string 작성자 표시명. 회원은 닉네임(없으면 마스킹한 이름, 둘 다 없으면 회원), 비회원은 마스킹한 작성자명(예: 홍​**)
is_viewable boolean 이 요청자가 본문을 볼 수 있는지
answered boolean 판매자 답변이 있는지
content string 문의 본문. 볼 수 없으면 생략
answer object 답변. 없으면 생략. 볼 수 있으면 content·created_at·updated_at, 볼 수 없으면 {"answered": true}

작성자의 회원 ID·연락처, 비회원 비밀번호는 어떤 응답에도 나가지 않습니다.

GET /v1/product-qnas

한 상품의 문의 목록을 최신 작성순으로 돌려줍니다. 운영자 모드에서 view=all 을 주면 프로젝트 전체 문의(관리자 숨김 포함)를 봅니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:product_qna_list (운영자 모드는 supervisor:product_qna_list)
  • 회원: 선택 — JWT 또는 user_id. 보내면 그 회원이 쓴 비밀글의 본문이 보입니다 — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
query product_id string △ 상품 ID. view=public 이면 필수이고 이 몰의 공개 상품이어야 합니다. view=all 이면 선택 필터(이 몰 상품이면 공개 여부 무관)
query view string public public 게시 중 문의만, all 프로젝트 전체·관리자 숨김 포함(운영자 모드만)
query page integer 1 페이지 번호
query limit integer 20 페이지당 개수(최대 100)
query user_id string 회원 지정(위 "회원 지정" 참고)

응답

200 OK — 비회원이 조회한 예. 두 번째 항목은 다른 회원의 비밀글이라 본문이 가려졌습니다.

{
  "list": [
    {
      "product_qna_id": "6abb14c6fc77d2c7fd0a40d5",
      "product_id": "6abb14c6fc77d2c7fd0a40d8",
      "title": "사이즈",
      "is_secret": false,
      "status": 1,
      "need_reply": true,
      "created_at": "2026-09-29T10:30:46+09:00",
      "updated_at": "2026-09-29T10:30:46+09:00",
      "author": "김​*​수",
      "is_viewable": true,
      "answered": false,
      "content": "사이즈 문의합니다"
    },
    {
      "product_qna_id": "6abb14c6fc77d2c7fd0a40d4",
      "product_id": "6abb14c6fc77d2c7fd0a40d8",
      "is_secret": true,
      "status": 1,
      "need_reply": false,
      "created_at": "2026-09-29T10:30:46+09:00",
      "updated_at": "2026-09-29T10:30:46+09:00",
      "author": "문의왕",
      "is_viewable": false,
      "answered": true,
      "answer": {
        "answered": true
      }
    }
  ],
  "count": 2,
  "page": 1,
  "limit": 20
}json
필드 타입 설명
list array 문의 객체 배열(위 "문의 객체")
count integer 조건에 맞는 전체 건수
page integer 적용된 페이지
limit integer 적용된 페이지 크기

결과가 없으면 {"list": [], "count": 0, "page": 1, "limit": 20} 입니다.

오류

HTTP error_code 언제
400 PRODUCT_QNA_PRODUCT_REQUIRED view=public 인데 product_id 가 없음
400 INVALID_PARAMETER view 가 public·all 이 아님(payload.field=view)
401 API_SCOPE_INVALID 운영자 모드가 아닌데 view=all, 또는 키에 scope 없음
401 API_ROLE_NOT_SUPPORT Bootpay-Role 이 user·supervisor 가 아님
403 USER_NOT_MATCH JWT 와 user_id 가 서로 다른 회원
404 PRODUCT_NOT_FOUND 이 몰의 (공개) 상품이 아님 — 다른 몰 상품, 잘못된 ID 형식 포함
404 USER_NOT_FOUND user_id 가 이 몰의 회원이 아님
442 PRODUCT_QNA_DISABLED 고객 모드인데 상품문의 사용 설정이 꺼져 있음
442 MALL_INACTIVE view=public 인데 쇼핑몰이 비활성 상태

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-29 최초 작성

GET /v1/product-qnas/:id

문의 한 건을 돌려줍니다. 다른 사람의 비밀글은 403 입니다(위 "비밀글").

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:product_qna_detail (운영자 모드는 supervisor:product_qna_detail)
  • 회원: 선택 — JWT 또는 user_id. 자기 비밀글을 열 때 필요합니다 — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
path id string O 상품문의 ID
query user_id string 회원 지정

고객 모드는 게시 중인 문의만, 운영자 모드는 관리자 숨김 문의도 조회합니다.

응답

200 OK — 문의 객체. 이 요청으로는 항상 본문을 볼 수 있으므로 is_viewable 은 true 입니다.

{
  "product_qna_id": "6abb14c6fc77d2c7fd0a40e2",
  "product_id": "6abb14c6fc77d2c7fd0a40d8",
  "product_option_id": "6abb14c6fc77d2c7fd0a40e0",
  "title": "사이즈 문의",
  "option_text": "화이트 / M",
  "is_secret": true,
  "status": 1,
  "need_reply": true,
  "created_at": "2026-09-29T10:30:46+09:00",
  "updated_at": "2026-09-29T10:30:46+09:00",
  "author": "문의왕",
  "is_viewable": true,
  "answered": false,
  "content": "옵션 변경 가능한가요?"
}json

필드는 위 "문의 객체"를 봅니다.

오류

HTTP error_code 언제
401 API_ROLE_NOT_SUPPORT Bootpay-Role 이 user·supervisor 가 아님
403 PRODUCT_QNA_SECRET_FORBIDDEN 다른 사람(비회원 요청 포함)의 비밀글
403 USER_NOT_MATCH JWT 와 user_id 가 서로 다른 회원
404 PRODUCT_QNA_NOT_FOUND 이 몰에 없는 문의 — 다른 몰 문의, 삭제된 문의, 잘못된 ID 형식, (고객 모드) 관리자 숨김 문의
404 USER_NOT_FOUND user_id 가 이 몰의 회원이 아님
442 PRODUCT_QNA_DISABLED 고객 모드인데 상품문의 사용 설정이 꺼져 있음

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-29 최초 작성

POST /v1/product-qnas

상품에 문의를 작성합니다. 회원을 지정하면 회원 문의, 지정하지 않으면 비회원 문의입니다. 비회원 문의는 몰 설정이 비회원 작성을 허용할 때만 됩니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:product_qna_create
  • 고객 모드만(Bootpay-Role 없음 또는 user)
  • 회원: 몰이 회원 전용이면 JWT 또는 user_id 필수, 비회원 허용이면 선택 — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
body product_id string O 이 몰의 공개 상품 ID
body content string O 문의 내용(최대 2000자)
body title string 제목(앞뒤 공백 제거)
body product_option_id string 문의할 옵션 ID. 이 상품의 옵션이어야 합니다
body option_text string 화면에 보여줄 옵션 문구(100자까지 저장)
body is_secret boolean false 비밀글 여부. true/false(또는 문자열 "true"/"false")만 받습니다
body guest_name string △ 비회원 작성자명. 비회원 작성 시 필수
body guest_password string △ 비회원 비밀번호. 비회원 작성 시 필수. 수정·삭제에 씁니다
body user_id string 회원 지정. 회원 문의면 guest_* 는 무시됩니다
{
  "product_id": "6abb14c6fc77d2c7fd0a40d8",
  "product_option_id": "6abb14c6fc77d2c7fd0a40e0",
  "title": "사이즈 문의",
  "content": "옵션 변경 가능한가요?",
  "option_text": "화이트 / M",
  "is_secret": true,
  "user_id": "member-1024"
}json

응답

200 OK — 작성한 문의 객체. 작성자 기준이라 비밀글도 본문이 들어 있습니다.

{
  "product_qna_id": "6abb14c6fc77d2c7fd0a40e2",
  "product_id": "6abb14c6fc77d2c7fd0a40d8",
  "product_option_id": "6abb14c6fc77d2c7fd0a40e0",
  "title": "사이즈 문의",
  "option_text": "화이트 / M",
  "is_secret": true,
  "status": 1,
  "need_reply": true,
  "created_at": "2026-09-29T10:30:46+09:00",
  "updated_at": "2026-09-29T10:30:46+09:00",
  "author": "문의왕",
  "is_viewable": true,
  "answered": false,
  "content": "옵션 변경 가능한가요?"
}json

필드는 위 "문의 객체"를 봅니다.

오류

HTTP error_code 언제
400 PRODUCT_QNA_PRODUCT_REQUIRED product_id 가 없음
400 PRODUCT_QNA_CONTENT_REQUIRED content 가 없거나 공백
400 PRODUCT_QNA_CONTENT_TOO_LONG content 가 2000자 초과
400 PRODUCT_QNA_GUEST_INFO_REQUIRED 비회원 작성인데 guest_name·guest_password 중 하나가 없음
400 INVALID_PARAMETER 문자열이 아닌 title·content·option_text, 또는 true/false 가 아닌 is_secret (payload.field·reason=invalid)
401 PRODUCT_QNA_LOGIN_REQUIRED 회원 전용 몰인데 회원을 지정하지 않음
401 API_ROLE_NOT_SUPPORT Bootpay-Role 이 user 가 아님
403 USER_NOT_MATCH JWT 와 user_id 가 서로 다른 회원
404 PRODUCT_NOT_FOUND 이 몰의 공개 상품이 아님
404 PRODUCT_OPTION_NOT_FOUND product_option_id 가 이 상품의 옵션이 아님(payload 에 product_id·product_option_id)
404 USER_NOT_FOUND user_id 가 이 몰의 회원이 아님
442 PRODUCT_QNA_DISABLED 상품문의 사용 설정이 꺼져 있음
442 MALL_INACTIVE 쇼핑몰이 비활성 상태

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-29 최초 작성

PUT /v1/product-qnas/:id

자기가 쓴 문의를 고칩니다. 보낸 필드만 바뀌고, 답변이 등록된 문의는 고칠 수 없습니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:product_qna_update
  • 고객 모드만(Bootpay-Role 없음 또는 user)
  • 회원 문의: 작성 회원을 JWT 또는 user_id 로 지정 — 회원 JWT
  • 비회원 문의: 회원을 지정하지 않고 guest_password 를 보냅니다

요청

위치 이름 타입 필수 기본값 설명
path id string O 상품문의 ID
body title string 새 제목. 빈 문자열이면 제목을 지웁니다
body content string 새 본문(최대 2000자)
body is_secret boolean 비밀글 여부(true/false)
body guest_password string △ 비회원 문의면 필수
body user_id string 회원 문의면 작성 회원 지정

상품·옵션·작성자·비회원 비밀번호는 바꿀 수 없습니다. 아무 필드도 보내지 않으면 저장하지 않고 현재 문의를 돌려줍니다.

{
  "content": "M 사이즈로 변경 가능한가요?",
  "guest_password": "pw-1234"
}json

응답

200 OK — 수정한 문의 객체(작성자 기준이라 본문 포함).

{
  "product_qna_id": "6abb14c6fc77d2c7fd0a40e2",
  "product_id": "6abb14c6fc77d2c7fd0a40d8",
  "is_secret": true,
  "status": 1,
  "need_reply": true,
  "created_at": "2026-09-29T10:30:46+09:00",
  "updated_at": "2026-09-29T10:41:02+09:00",
  "author": "이​**",
  "is_viewable": true,
  "answered": false,
  "content": "M 사이즈로 변경 가능한가요?"
}json

필드는 위 "문의 객체"를 봅니다.

오류

HTTP error_code 언제
400 PRODUCT_QNA_CONTENT_REQUIRED content 를 보냈는데 비어 있음
400 PRODUCT_QNA_CONTENT_TOO_LONG content 가 2000자 초과
400 REQUIRED_PARAMETER_IS_MISSING 비회원 문의인데 guest_password 가 없음(payload.field=guest_password)
400 INVALID_PARAMETER 문자열이 아닌 title·content, 또는 true/false 가 아닌 is_secret
401 API_ROLE_NOT_SUPPORT Bootpay-Role 이 user 가 아님
403 PRODUCT_QNA_UNAUTHORIZED 작성자가 아님 — 다른 회원의 문의, 회원 없이 회원 문의를 요청, 회원으로 비회원 문의를 요청
403 PRODUCT_QNA_GUEST_PASSWORD_INVALID 비회원 비밀번호가 틀림
403 USER_NOT_MATCH JWT 와 user_id 가 서로 다른 회원
404 PRODUCT_QNA_NOT_FOUND 이 몰에 없는(다른 몰·삭제·숨김·잘못된 ID 형식) 문의
404 USER_NOT_FOUND user_id 가 이 몰의 회원이 아님
409 PRODUCT_QNA_ALREADY_ANSWERED 답변이 등록된 문의
442 PRODUCT_QNA_DISABLED 상품문의 사용 설정이 꺼져 있음

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-29 최초 작성

DELETE /v1/product-qnas/:id

문의를 삭제합니다. 고객 모드는 작성자 본인(회원 또는 비회원 비밀번호), 운영자 모드는 이 몰의 어떤 문의든 지울 수 있습니다. 답변이 있는 문의도 지울 수 있고, 지운 문의는 목록·단건·답변 대기 집계에서 빠집니다. 같은 ID 로 다시 조회하거나 지우면 404 입니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:product_qna_delete (운영자 모드는 supervisor:product_qna_delete)
  • 고객 모드: 회원 문의는 작성 회원을 JWT 또는 user_id 로 지정, 비회원 문의는 guest_password — 회원 JWT
  • 운영자 모드: 회원 지정 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O 상품문의 ID
query/body guest_password string △ 고객 모드에서 비회원 문의를 지울 때 필수
query/body user_id string 고객 모드에서 회원 문의를 지울 때 작성 회원 지정

응답

200 OK

{
  "deleted": true,
  "product_qna_id": "6abb14c6fc77d2c7fd0a40e2"
}json
필드 타입 설명
deleted boolean 항상 true
product_qna_id string 삭제한 상품문의 ID

오류

HTTP error_code 언제
400 REQUIRED_PARAMETER_IS_MISSING (고객 모드) 비회원 문의인데 guest_password 가 없음
401 API_ROLE_NOT_SUPPORT Bootpay-Role 이 user·supervisor 가 아님
403 PRODUCT_QNA_UNAUTHORIZED (고객 모드) 작성자가 아님
403 PRODUCT_QNA_GUEST_PASSWORD_INVALID (고객 모드) 비회원 비밀번호가 틀림
403 USER_NOT_MATCH JWT 와 user_id 가 서로 다른 회원
404 PRODUCT_QNA_NOT_FOUND 이 몰에 없는 문의 — 다른 몰 문의, 이미 삭제한 문의, 잘못된 ID 형식, (고객 모드) 관리자 숨김 문의
404 USER_NOT_FOUND user_id 가 이 몰의 회원이 아님
442 PRODUCT_QNA_DISABLED 고객 모드인데 상품문의 사용 설정이 꺼져 있음

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-29 최초 작성

PUT /v1/product-qnas/:id/answer

판매자 답변을 등록하거나 고칩니다(upsert). 답변이 없으면 새로 등록하고, 있으면 내용을 바꿉니다. 등록되면 need_reply 가 false 가 되어 답변 대기 집계에서 빠집니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: supervisor:product_qna_answer
  • 운영자 모드 전용 — Bootpay-Role: supervisor(생략하면 supervisor 로 봅니다). user 등 다른 역할은 401
  • 회원 JWT: 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O 상품문의 ID
body content string O 답변 내용
{
  "content": "확인했습니다."
}json

게시 중인 문의에만 답변합니다(관리자 숨김·삭제 문의는 404).

응답

200 OK — 답변이 반영된 문의 객체(운영자 기준이라 비밀글도 본문·답변 포함).

{
  "product_qna_id": "6abb14c6fc77d2c7fd0a40d5",
  "product_id": "6abb14c6fc77d2c7fd0a40d8",
  "title": "사이즈",
  "is_secret": false,
  "status": 1,
  "need_reply": false,
  "created_at": "2026-09-29T10:30:46+09:00",
  "updated_at": "2026-09-29T10:30:46+09:00",
  "author": "김​*​수",
  "is_viewable": true,
  "answered": true,
  "content": "사이즈 문의합니다",
  "answer": {
    "content": "확인했습니다.",
    "created_at": "2026-09-29T10:30:46+09:00",
    "updated_at": "2026-09-29T10:30:46+09:00"
  }
}json
필드 타입 설명
answer.content string 답변 내용
answer.created_at string 답변 등록 시각(ISO 8601)
answer.updated_at string 답변 마지막 수정 시각(ISO 8601)

나머지 필드는 위 "문의 객체"를 봅니다.

오류

HTTP error_code 언제
400 PRODUCT_QNA_CONTENT_REQUIRED content 가 없거나 공백
400 INVALID_PARAMETER content 가 문자열이 아님
401 API_ROLE_NOT_SUPPORT Bootpay-Role 이 supervisor 가 아님
401 API_SCOPE_INVALID 키에 supervisor:product_qna_answer scope 없음
404 PRODUCT_QNA_NOT_FOUND 이 몰에 없는(다른 몰·삭제·숨김·잘못된 ID 형식) 문의

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-29 최초 작성

함께 보기