회원이 쇼핑몰에 남기는 1:1 문의와 판매자 답변입니다. 쇼핑몰 고객센터의 1:1 문의, 관리자 화면의 1:1 문의와 같은 데이터입니다. 1:1 문의는 항상 비밀글이라 작성한 회원과 운영자만 볼 수 있습니다.
두 가지 방식으로 부릅니다.
- 회원 요청(
Bootpay-Role헤더 없음 또는user): 쇼핑몰 서버가 로그인한 회원 대신 부릅니다. 회원은 회원 JWT(Bootpay-User-JWT) 또는user_id중 하나로 정하며, 그 회원이 쓴 문의만 보이고 다룰 수 있습니다. 쇼핑몰 설정에서 1:1 문의 사용(use_qna)이 켜져 있어야 합니다. - 운영자 요청(
Bootpay-Role: supervisor): 이 쇼핑몰의 모든 문의를 조회·삭제하고 답변합니다. 회원을 지정할 필요가 없고, 1:1 문의 사용 여부와 관계없이 동작합니다.
문의 작성·수정은 회원 요청만, 답변은 운영자 요청만 받습니다. 역할과 scope 는 인증을 봅니다.
회원 지정 규칙:
user_id는 쇼핑몰 서버가 자기 로그인 세션의 회원 ID 를 넣어 보냅니다(쿼리 또는 본문). 24자리 회원 ID 면 Bootpay 회원 ID, 그 밖의 값은 이 몰의 외부 회원 ID(ex_uid)로 찾습니다.user_ex_uid·user_external_uid·user_uid도 같은 뜻이고, 로그인 아이디로 지정하려면login_id를 보냅니다.user_id는 secretKey 인증(Basic·Bearer)일 때만 받습니다. 브라우저가 보낸 값을 그대로 넘기지 마세요 — 인증 — 호출 구조.- JWT 와
user_id를 둘 다 보내면 JWT 가 우선이고, 서로 다른 회원이면 403USER_NOT_MATCH입니다.
모든 요청은 인증한 프로젝트의 1:1 문의만 다룹니다. 다른 쇼핑몰의 문의, 공지사항·FAQ 글, 답변 글의 ID, 회원 요청에서 다른 회원의 문의 ID 는 모두 404 POST_NOT_FOUND 입니다(존재 여부를 알려주지 않습니다).
문의 객체
| 필드 | 타입 | 설명 |
|---|---|---|
| inquiry_id | string | 문의 ID |
| user_id | string | null | 작성한 회원의 Bootpay 회원 ID |
| title | string | null | 제목. 제목 없이 쓴 문의는 null |
| content | string | 문의 내용 |
| images | string[] | 첨부 이미지 URL. 없으면 [] |
| is_secret | boolean | 비밀글 여부. 1:1 문의는 항상 true |
| answered | boolean | 판매자 답변이 등록됐는지 |
| order_id | string | null | 연결한 주문 ID. 없으면 null |
| product | object | null | 연결한 상품. 작성할 때의 상품명·이미지를 저장해 두므로 이후 상품이 바뀌어도 그대로입니다. 없으면 null |
| product.product_id | string | 상품 ID |
| product.name | string | 작성 시점 상품명 |
| product.image | string | 작성 시점 대표 이미지 URL. 없으면 키가 빠집니다 |
| product.option_text | string | 작성할 때 보낸 옵션 문구. 없으면 키가 빠집니다 |
| answer | object | null | 판매자 답변. 답변 전이면 null. 단건 응답에만 있고 목록에는 이 키가 없습니다 |
| answer.content | string | 답변 내용 |
| answer.created_at | string | 답변 등록 시각 (ISO 8601) |
| answer.answered_by | string | 답변자 표시. 항상 "판매자" |
| created_at | string | 작성 시각 (ISO 8601, 예 2026-09-29T09:00:00+09:00) |
| updated_at | string | 마지막 수정 시각 (ISO 8601). 처음 답변이 등록될 때도 바뀝니다 |
product 안쪽을 뺀 필드는 값이 없어도 항상 들어 있습니다.
GET /v1/inquiries
1:1 문의 목록을 최근 작성 순으로 조회합니다. 회원 요청은 그 회원의 문의만, 운영자 요청은 이 쇼핑몰의 전체 문의입니다. 목록에는 답변 내용이 없습니다(answered 로 여부만 알 수 있습니다).
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:inquiry_list—Bootpay-Role: supervisor로 부르면supervisor:inquiry_list - 회원: 회원 요청이면 JWT 또는 user_id 필수 —
Bootpay-User-JWT헤더 또는user_id(쇼핑몰 서버 지정) — 회원 JWT. 운영자 요청은 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| query | user_id | string | 회원 요청이면 O | 회원 요청: 문의를 볼 회원(JWT 를 보내면 생략). 운영자 요청: 이 회원의 문의만 조회(선택) | |
| query | answered | boolean | true: 답변 완료만, false: 미답변만. 보내지 않으면 전체 |
||
| query | page | integer | 1 | 페이지 번호 — 페이지네이션 | |
| query | limit | integer | 20 | 페이지 크기(최대 100) |
잘못된 page·limit 는 오류 없이 기본값·상한으로 고쳐 조회하고, 응답의 page·limit 에 고친 값을 돌려줍니다.
응답
200 OK
{
"list": [
{
"inquiry_id": "66f9a1c0e1b2c3d4e5f60003",
"user_id": "66f9a1c0e1b2c3d4e5f60010",
"title": "배송 문의",
"content": "언제 출고되나요?",
"images": [],
"is_secret": true,
"answered": false,
"order_id": "66f9a1c0e1b2c3d4e5f60100",
"product": {
"product_id": "66f9a1c0e1b2c3d4e5f60101",
"name": "드립백 커피 10입",
"image": "https://example.com/drip.png",
"option_text": "10개입"
},
"created_at": "2026-09-29T09:00:00+09:00",
"updated_at": "2026-09-29T09:00:00+09:00"
}
],
"count": 1,
"page": 1,
"limit": 20
}json| 필드 | 타입 | 설명 |
|---|---|---|
| list | array | 문의 객체 배열(answer 키 없음) |
| count | integer | 조건에 맞는 전체 문의 수 |
| page | integer | 적용한 페이지 |
| limit | integer | 적용한 페이지 크기 |
1:1 문의 게시판이 아직 없으면 {"list": [], "count": 0, "page": 1, "limit": 20} 입니다.
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | REQUIRED_PARAMETER_IS_MISSING |
회원 요청인데 JWT·user_id 가 모두 없음 (payload.field: "user_id") |
| 400 | INVALID_PARAMETER |
answered 가 true·false 가 아님 (payload.field: "answered"), 또는 clientKey 만으로 인증한 요청에 user_id 를 보냄 (payload.reason: merchant_auth_required) |
| 401 | API_ROLE_NOT_SUPPORT |
Bootpay-Role 이 user·supervisor 가 아님 |
| 401 | USER_JWT_INVALID |
JWT 서명이 틀렸거나 만료됨 |
| 401 | USER_SESSION_INVALID |
JWT 세션이 끝남(로그아웃·탈퇴 등) |
| 403 | USER_NOT_MATCH |
JWT 와 user_id(또는 user_id 와 login_id)가 서로 다른 회원 |
| 404 | USER_NOT_FOUND |
user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원(운영자 요청의 필터 포함) |
| 442 | BOARD_FEATURE_DISABLED |
회원 요청인데 쇼핑몰의 1:1 문의 사용이 꺼져 있음 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-29 최초 작성
GET /v1/inquiries/:id
문의 하나를 판매자 답변과 함께 조회합니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:inquiry_detail—Bootpay-Role: supervisor로 부르면supervisor:inquiry_detail - 회원: 회원 요청이면 JWT 또는 user_id 필수 —
Bootpay-User-JWT헤더 또는user_id(쇼핑몰 서버 지정) — 회원 JWT. 운영자 요청은 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 문의 ID(inquiry_id) |
|
| query | user_id | string | 회원 요청이면 O | 문의를 쓴 회원(JWT 를 보내면 생략) |
응답
200 OK — 문의 객체(answer 포함).
{
"inquiry_id": "66f9a1c0e1b2c3d4e5f60003",
"user_id": "66f9a1c0e1b2c3d4e5f60010",
"title": "배송 문의",
"content": "언제 출고되나요?",
"images": [],
"is_secret": true,
"answered": true,
"order_id": null,
"product": null,
"answer": {
"content": "내일 출고 예정입니다.",
"created_at": "2026-09-29T10:30:00+09:00",
"answered_by": "판매자"
},
"created_at": "2026-09-29T09:00:00+09:00",
"updated_at": "2026-09-29T10:30:00+09:00"
}json오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | POST_NOT_FOUND |
없는 문의, 형식이 틀린 ID, 다른 쇼핑몰·다른 게시판(공지·FAQ)의 글, 답변 글, 회원 요청에서 다른 회원의 문의 |
| 400 | REQUIRED_PARAMETER_IS_MISSING |
회원 요청인데 JWT·user_id 가 모두 없음 (payload.field: "user_id") |
| 400 | INVALID_PARAMETER |
clientKey 만으로 인증한 요청에 user_id 를 보냄 (payload.reason: merchant_auth_required) |
| 401 | API_ROLE_NOT_SUPPORT |
Bootpay-Role 이 user·supervisor 가 아님 |
| 401 | USER_JWT_INVALID |
JWT 서명이 틀렸거나 만료됨 |
| 401 | USER_SESSION_INVALID |
JWT 세션이 끝남(로그아웃·탈퇴 등) |
| 403 | USER_NOT_MATCH |
JWT 와 user_id 가 서로 다른 회원 |
| 404 | USER_NOT_FOUND |
user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원 |
| 442 | BOARD_FEATURE_DISABLED |
회원 요청인데 쇼핑몰의 1:1 문의 사용이 꺼져 있음 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-29 최초 작성
POST /v1/inquiries
회원의 1:1 문의를 작성합니다. 비밀글·미답변 상태로 만들어지고, 관리자 화면의 미답변 문의에 바로 잡힙니다. 회원 요청만 받습니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:inquiry_create.Bootpay-Role: supervisor로는 부를 수 없습니다 - 회원: JWT 또는 user_id 필수 —
Bootpay-User-JWT헤더 또는user_id(쇼핑몰 서버 지정) — 회원 JWT
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| body | user_id | string | JWT 없으면 O | 문의를 쓰는 회원 | |
| body | content | string | O | 문의 내용. 공백만 있으면 안 됩니다 | |
| body | title | string | 제목. 앞뒤 공백은 지우고, 비어 있으면 null 로 저장합니다 |
||
| body | product_id | string | 관련 상품 ID. 이 쇼핑몰의 상품이어야 합니다(판매 중지 상품도 가능) | ||
| body | option | string | 관련 상품의 옵션 문구(예 "화이트 / L"). 100자까지 저장하고, product_id 가 없으면 무시합니다 |
||
| body | order_id | string | 관련 주문 ID. 문의를 쓰는 회원의 주문이어야 합니다 |
이미지 첨부는 받지 않습니다.
응답
200 OK — 만든 문의 객체(answer 는 null).
{
"inquiry_id": "66f9a1c0e1b2c3d4e5f60003",
"user_id": "66f9a1c0e1b2c3d4e5f60010",
"title": "배송 문의",
"content": "언제 출고되나요?",
"images": [],
"is_secret": true,
"answered": false,
"order_id": "66f9a1c0e1b2c3d4e5f60100",
"product": {
"product_id": "66f9a1c0e1b2c3d4e5f60101",
"name": "드립백 커피 10입",
"image": "https://example.com/drip.png",
"option_text": "10개입"
},
"answer": null,
"created_at": "2026-09-29T09:00:00+09:00",
"updated_at": "2026-09-29T09:00:00+09:00"
}json같은 요청을 다시 보내면 문의가 하나 더 만들어집니다. 재시도로 중복되지 않게 하려면 Idempotency-Key 를 보내세요 — 멱등 요청.
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | POST_CONTENT_REQUIRED |
content 가 없거나 공백뿐 |
| 404 | BOARD_NOT_FOUND |
이 쇼핑몰에 사용 중인 1:1 문의 게시판이 없음 |
| 404 | PRODUCT_NOT_FOUND |
product_id 가 이 쇼핑몰의 상품이 아님 |
| 404 | ORDER_NOT_FOUND |
order_id 가 이 회원의 주문이 아님 |
| 400 | REQUIRED_PARAMETER_IS_MISSING |
JWT·user_id 가 모두 없음 (payload.field: "user_id") |
| 400 | INVALID_PARAMETER |
clientKey 만으로 인증한 요청에 user_id 를 보냄 (payload.reason: merchant_auth_required) |
| 401 | API_ROLE_NOT_SUPPORT |
Bootpay-Role 이 user 가 아님(supervisor 포함) |
| 401 | USER_JWT_INVALID |
JWT 서명이 틀렸거나 만료됨 |
| 401 | USER_SESSION_INVALID |
JWT 세션이 끝남(로그아웃·탈퇴 등) |
| 403 | USER_NOT_MATCH |
JWT 와 user_id 가 서로 다른 회원 |
| 404 | USER_NOT_FOUND |
user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원 |
| 442 | BOARD_FEATURE_DISABLED |
쇼핑몰의 1:1 문의 사용이 꺼져 있음 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-29 최초 작성
PUT /v1/inquiries/:id
회원이 자기 문의의 제목·내용을 고칩니다. 보낸 필드만 바뀌고, 판매자 답변이 등록된 뒤에는 고칠 수 없습니다. 회원 요청만 받습니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:inquiry_update.Bootpay-Role: supervisor로는 부를 수 없습니다 - 회원: JWT 또는 user_id 필수 —
Bootpay-User-JWT헤더 또는user_id(쇼핑몰 서버 지정) — 회원 JWT
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 문의 ID(inquiry_id) |
|
| body | user_id | string | JWT 없으면 O | 문의를 쓴 회원 | |
| body | title | string | 새 제목. 빈 문자열이면 제목을 지웁니다(null) |
||
| body | content | string | 새 문의 내용. 보낸다면 공백만 있으면 안 됩니다 |
title·content 중 하나는 보내야 합니다. 관련 상품·주문은 바꿀 수 없습니다.
응답
200 OK — 고친 문의 객체(answer 포함 — 답변 전이라 null).
{
"inquiry_id": "66f9a1c0e1b2c3d4e5f60003",
"user_id": "66f9a1c0e1b2c3d4e5f60010",
"title": "배송 문의",
"content": "주소를 바꿀 수 있나요?",
"images": [],
"is_secret": true,
"answered": false,
"order_id": null,
"product": null,
"answer": null,
"created_at": "2026-09-29T09:00:00+09:00",
"updated_at": "2026-09-29T09:10:00+09:00"
}json오류
| HTTP | error_code | 언제 |
|---|---|---|
| 409 | INQUIRY_ALREADY_ANSWERED |
판매자 답변이 이미 등록된 문의(수정 요청과 거의 같은 때 답변이 등록된 경우 포함) |
| 400 | INVALID_PARAMETER |
title·content 를 하나도 보내지 않음 (payload.reason: nothing_to_update), 또는 clientKey 만으로 인증한 요청에 user_id 를 보냄 (payload.reason: merchant_auth_required) |
| 400 | POST_CONTENT_REQUIRED |
content 를 공백으로 보냄 |
| 404 | POST_NOT_FOUND |
없는 문의, 형식이 틀린 ID, 다른 쇼핑몰·다른 게시판의 글, 다른 회원의 문의 |
| 400 | REQUIRED_PARAMETER_IS_MISSING |
JWT·user_id 가 모두 없음 (payload.field: "user_id") |
| 401 | API_ROLE_NOT_SUPPORT |
Bootpay-Role 이 user 가 아님(supervisor 포함) |
| 401 | USER_JWT_INVALID |
JWT 서명이 틀렸거나 만료됨 |
| 401 | USER_SESSION_INVALID |
JWT 세션이 끝남(로그아웃·탈퇴 등) |
| 403 | USER_NOT_MATCH |
JWT 와 user_id 가 서로 다른 회원 |
| 404 | USER_NOT_FOUND |
user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원 |
| 442 | BOARD_FEATURE_DISABLED |
쇼핑몰의 1:1 문의 사용이 꺼져 있음 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-29 최초 작성
DELETE /v1/inquiries/:id
문의를 삭제합니다. 회원 요청은 자기 문의만, 운영자 요청은 이 쇼핑몰의 어떤 문의든 지울 수 있습니다. 답변이 등록된 문의도 지울 수 있고, 판매자 답변도 함께 지워집니다. 삭제는 되돌릴 수 없으며 이후 같은 ID 조회는 404 입니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:inquiry_delete—Bootpay-Role: supervisor로 부르면supervisor:inquiry_delete - 회원: 회원 요청이면 JWT 또는 user_id 필수 —
Bootpay-User-JWT헤더 또는user_id(쇼핑몰 서버 지정) — 회원 JWT. 운영자 요청은 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 문의 ID(inquiry_id) |
|
| query | user_id | string | 회원 요청이면 O | 문의를 쓴 회원(JWT 를 보내면 생략) |
응답
200 OK
{
"deleted": true,
"inquiry_id": "66f9a1c0e1b2c3d4e5f60003"
}json| 필드 | 타입 | 설명 |
|---|---|---|
| deleted | boolean | 항상 true |
| inquiry_id | string | 지운 문의 ID |
이미 지운 문의를 다시 지우면 404 POST_NOT_FOUND 입니다.
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | POST_NOT_FOUND |
없는(이미 지운) 문의, 형식이 틀린 ID, 다른 쇼핑몰·다른 게시판의 글, 답변 글, 회원 요청에서 다른 회원의 문의 |
| 400 | REQUIRED_PARAMETER_IS_MISSING |
회원 요청인데 JWT·user_id 가 모두 없음 (payload.field: "user_id") |
| 400 | INVALID_PARAMETER |
clientKey 만으로 인증한 요청에 user_id 를 보냄 (payload.reason: merchant_auth_required) |
| 401 | API_ROLE_NOT_SUPPORT |
Bootpay-Role 이 user·supervisor 가 아님 |
| 401 | USER_JWT_INVALID |
JWT 서명이 틀렸거나 만료됨 |
| 401 | USER_SESSION_INVALID |
JWT 세션이 끝남(로그아웃·탈퇴 등) |
| 403 | USER_NOT_MATCH |
JWT 와 user_id 가 서로 다른 회원 |
| 404 | USER_NOT_FOUND |
user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원 |
| 442 | BOARD_FEATURE_DISABLED |
회원 요청인데 쇼핑몰의 1:1 문의 사용이 꺼져 있음 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-29 최초 작성
PUT /v1/inquiries/:id/answer
문의에 판매자 답변을 등록합니다. 이미 답변이 있으면 새로 만들지 않고 내용을 바꿉니다(문의 하나에 답변 하나). 답변을 등록하면 answered 가 true 가 되고, 관리자 화면의 미답변 문의에서 빠지며, 회원은 더 이상 문의를 고칠 수 없습니다. 관리자 화면에서 등록한 답변과 같은 데이터라 어느 쪽에서든 수정할 수 있습니다. 운영자 요청만 받습니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
supervisor:inquiry_answer(Bootpay-Role헤더가 없거나supervisor일 때) - 회원: 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 문의 ID(inquiry_id) |
|
| body | content | string | O | 답변 내용. 공백만 있으면 안 됩니다 |
응답
200 OK — 답변이 반영된 문의 객체(answer 포함).
{
"inquiry_id": "66f9a1c0e1b2c3d4e5f60003",
"user_id": "66f9a1c0e1b2c3d4e5f60010",
"title": "배송 문의",
"content": "언제 출고되나요?",
"images": [],
"is_secret": true,
"answered": true,
"order_id": null,
"product": null,
"answer": {
"content": "내일 출고 예정입니다.",
"created_at": "2026-09-29T10:30:00+09:00",
"answered_by": "판매자"
},
"created_at": "2026-09-29T09:00:00+09:00",
"updated_at": "2026-09-29T10:30:00+09:00"
}json답변을 수정해도 answer.created_at 은 처음 등록한 시각 그대로입니다.
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | POST_CONTENT_REQUIRED |
content 가 없거나 공백뿐 |
| 404 | POST_NOT_FOUND |
없는 문의, 형식이 틀린 ID, 다른 쇼핑몰·다른 게시판의 글, 답변 글 |
| 401 | API_ROLE_NOT_SUPPORT |
Bootpay-Role 이 supervisor 가 아님(user 포함) |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-29 최초 작성
