상품 상세의 "상품 문의(Q&A)" 입니다. 고객이 상품에 대해 남긴 질문과 판매자 답변을 조회·작성·수정·삭제하고, 운영자가 답변을 등록합니다. 인증·오류 형식·페이지네이션 같은 공통 내용은 인증·오류·페이지네이션을 봅니다.
두 가지 호출 모드
| 모드 | 헤더 | 쓰는 곳 |
|---|---|---|
| 고객 모드 | Bootpay-Role 없음 또는 user |
쇼핑몰 서버가 상품 상세의 문의 탭을 대신 부른다. 목록·단건·작성·수정·삭제 |
| 운영자 모드 | Bootpay-Role: supervisor |
가맹점 관리 서버. 프로젝트 전체 목록(view=all)·단건·삭제·답변 |
- 작성·수정은 고객 모드만, 답변은 운영자 모드만 받습니다. 그 밖의 역할(
manager등)은 401API_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 최초 작성
