1:1 문의

회원이 쇼핑몰에 남기는 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 가 우선이고, 서로 다른 회원이면 403 USER_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 최초 작성

함께 보기