상품평

회원이 구매확정한 주문의 상품에 남기는 후기(상품평)를 조회·작성·수정·삭제하고, 운영자가 판매자 답글을 답니다. 모든 요청은 인증된 프로젝트(쇼핑몰)의 상품평만 다룹니다. 다른 프로젝트의 상품평 ID·삭제된 상품평·형식이 틀린 ID 는 모두 404 REVIEW_NOT_FOUND 입니다.

상품 상세 화면의 공개 후기 목록·별점 통계는 이 문서가 아니라 상품의 GET /v1/products/:id/reviews·GET /v1/products/:id/review_stats 를 씁니다.

인증·scope 는 인증, 오류 형식은 오류, page·limit 규칙은 페이지네이션을 봅니다.

역할

Bootpay-Role 헤더로 역할을 고릅니다. 이 API 는 user·supervisor 만 받고, 그 밖의 값은 401 API_ROLE_NOT_SUPPORT 입니다.

역할 할 수 있는 일
user (회원 모드) 회원 본인 후기 목록, 단건 조회, 작성·수정·삭제
supervisor (운영자 모드) 프로젝트 전체 목록, 숨긴 후기 단건 조회, 삭제, 판매자 답글
  • 회원 모드의 회원은 회원 JWT(Bootpay-User-JWT) 또는 user_id 로 정합니다. user_id 는 쇼핑몰 서버가 자기 로그인 세션의 회원 값을 넣습니다 — 인증 — 호출 구조. 둘 다 보내면 JWT 가 우선이고, 서로 다른 회원이면 403 USER_NOT_MATCH 입니다.
  • 운영자 모드는 회원을 받지 않습니다. 목록의 user_id 는 작성 회원 필터로만 씁니다.

작성·수정 정책

  • 구매확정된 본인 주문​​의 주문 상품​​에만 작성할 수 있습니다. 한 주문에 후기는 하나입니다(삭제한 후기가 있던 주문도 다시 쓸 수 없습니다).
  • 평점은 1~5 정수, 본문은 최대 5000자, 사진은 최대 5장입니다.
  • 수정은 작성자 본인이 작성 후 7일(edit_deadline_at) 안에만 할 수 있습니다. 관리자가 숨긴 후기는 수정·삭제할 수 없습니다.
  • 작성하면 쇼핑몰의 후기 적립금 설정에 따라 적립금이 지급되고(사진 후기 추가 적립 포함), 삭제하면 지급한 적립금을 회수합니다. 상품의 후기 수·평점 통계도 함께 바뀝니다.
  • 사진은 이미 업로드된 이미지 URL(http·https)로 보냅니다. 이 API 는 파일을 받지 않습니다.

응답 객체

단건·목록·작성·수정·답글 응답은 같은 상품평 객체입니다. 값이 없는 키는 빠집니다(답글이 없으면 reply 키가 없고, 옵션 없이 쓴 후기는 product_option_id 가 없습니다).

필드 타입 설명
product_review_id string 상품평 ID
product_id string 상품 ID
product_option_id string 작성 때 지정한 옵션 ID. 없으면 키가 빠집니다
user_id string 작성 회원 ID
author string 표시 이름. 닉네임, 없으면 가린 실명(김​**), 둘 다 없으면 구매자
rating integer 평점 1~5
content string 본문
is_photo_review boolean 사진 후기 여부
helpful_count integer 도움돼요 수
images object[] 전체 사진 {url, position} (position 은 0부터)
image_count integer 사진 수
reply object 판매자 답글 {reply_id, content, created_at, updated_at}. 없거나 삭제됐으면 키가 빠집니다
created_at, updated_at string 작성·수정 시각 (ISO 8601)
order_id string 후기를 쓴 주문 ID. 작성자 본인·운영자 응답에만
visibility string public(공개) 또는 hidden(관리자가 숨김). 작성자 본인·운영자 응답에만
editable boolean 작성자가 지금 수정할 수 있는지(공개 상태이고 7일 이내). 작성자 본인·운영자 응답에만
edit_deadline_at string 수정 마감 시각(작성 + 7일). 작성자 본인·운영자 응답에만

변경 이력

  • 2026-09-29 문서 최초 작성

GET /v1/reviews

상품평 목록을 최신순으로 조회합니다. 삭제된 후기는 빠집니다.

  • 회원 모드: 그 회원이 쓴 후기(관리자가 숨긴 후기 포함, visibility 로 구분)
  • 운영자 모드: 프로젝트 전체 후기(숨긴 후기 포함)

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:product_review_list (회원 모드), supervisor:product_review_list (운영자 모드, Bootpay-Role: supervisor)
  • 회원: 회원 모드는 JWT 또는 user_id 필수 — 회원 JWT. 운영자 모드는 필요 없음

요청

위치 이름 타입 필수 기본값 설명
query page integer 1 페이지네이션 규칙
query limit integer 20 1~100
query product_id string 이 상품의 후기만. 형식이 틀린 ID 면 빈 목록
query view string all 은 운영자 모드에서만 받습니다(운영자 모드는 보내지 않아도 전체). 회원 모드에서 all 을 보내면 401 API_SCOPE_INVALID
query user_id string 회원 모드: 회원 지정(JWT 를 보내지 않을 때 필수). 운영자 모드: 작성 회원 필터. 24자리 회원 ID 면 Bootpay 회원 ID, 그 밖의 값은 외부 회원 ID(ex_uid)

응답

200 OK

{
  "list": [
    {
      "product_review_id": "6abb14aa1073500b84eb40ab",
      "product_id": "6abb14aa1073500b84eb40b0",
      "user_id": "6abb14aa1073500b84eb40ad",
      "author": "김​**",
      "rating": 5,
      "content": "좋아요",
      "is_photo_review": true,
      "helpful_count": 0,
      "images": [{ "url": "https://cdn.example.com/r1.jpg", "position": 0 }],
      "image_count": 1,
      "reply": {
        "reply_id": "6abb14aa1073500b84eb40b4",
        "content": "구매해 주셔서 감사합니다. 또 방문해 주세요.",
        "created_at": "2026-09-29T10:30:18+09:00",
        "updated_at": "2026-09-29T10:30:18+09:00"
      },
      "created_at": "2026-09-29T09:30:18+09:00",
      "updated_at": "2026-09-29T10:30:18+09:00",
      "order_id": "6abb14aa1073500b84eb40b2",
      "visibility": "public",
      "editable": true,
      "edit_deadline_at": "2026-10-06T09:30:18+09:00"
    }
  ],
  "count": 1,
  "page": 1,
  "limit": 20
}json
필드 타입 설명
list[] object 응답 객체. 목록은 항상 작성자 본인·운영자 기준이라 order_id·visibility·editable·edit_deadline_at 이 들어갑니다
count integer 조건에 맞는 전체 후기 수
page, limit integer 실제로 적용한 값

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

오류

HTTP error_code 언제
401 API_ROLE_NOT_SUPPORT Bootpay-Role 이 user·supervisor 가 아님
401 API_SCOPE_INVALID 회원 모드에서 view=all, 또는 키에 scope 없음
400 REQUIRED_PARAMETER_IS_MISSING (131) 회원 모드인데 JWT·user_id 가 모두 없음 (payload.field=user_id)
401 USER_SESSION_INVALID·USER_JWT_INVALID 회원 JWT 가 만료·무효
403 USER_NOT_MATCH (2302) JWT 의 회원과 user_id 가 다름
404 USER_NOT_FOUND (2300) user_id 가 이 몰의 회원이 아님(운영자 모드의 필터 포함)

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

변경 이력

  • 2026-09-29 최초 작성

GET /v1/reviews/:id

상품평 하나를 조회합니다.

  • 공개 후기: 이 프로젝트의 호출이면 회원 없이도 읽을 수 있습니다
  • 관리자가 숨긴 후기: 작성자 본인(회원 모드)과 운영자 모드만. 그 밖은 404
  • 삭제된 후기: 누구에게나 404

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:product_review_detail (회원 모드), supervisor:product_review_detail (운영자 모드)
  • 회원: 회원 모드에서 JWT 또는 user_id 선택 — 보내면 작성자 본인 여부를 판정해 본인 후기에 order_id·visibility·editable·edit_deadline_at 을 싣습니다. 운영자 모드는 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O 상품평 ID
query user_id string 회원 모드의 조회 회원(선택)

응답

200 OK — 응답 객체. 작성자 본인이 아닌 조회는 order_id·visibility·editable·edit_deadline_at 이 빠집니다.

{
  "product_review_id": "6abb14aa1073500b84eb40ab",
  "product_id": "6abb14aa1073500b84eb40b0",
  "user_id": "6abb14aa1073500b84eb40ad",
  "author": "김​**",
  "rating": 5,
  "content": "좋아요",
  "is_photo_review": true,
  "helpful_count": 0,
  "images": [{ "url": "https://cdn.example.com/r1.jpg", "position": 0 }],
  "image_count": 1,
  "created_at": "2026-09-29T09:30:18+09:00",
  "updated_at": "2026-09-29T09:30:18+09:00"
}json

오류

HTTP error_code 언제
404 REVIEW_NOT_FOUND (4040) 없는 ID·형식이 틀린 ID·다른 프로젝트 후기·삭제된 후기, 또는 숨긴 후기를 작성자·운영자가 아닌 호출이 조회
401 API_ROLE_NOT_SUPPORT Bootpay-Role 이 user·supervisor 가 아님
401 USER_SESSION_INVALID·USER_JWT_INVALID 보낸 회원 JWT 가 만료·무효
403 USER_NOT_MATCH (2302) JWT 의 회원과 user_id 가 다름
404 USER_NOT_FOUND (2300) user_id 가 이 몰의 회원이 아님

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

변경 이력

  • 2026-09-29 최초 작성

POST /v1/reviews

회원 본인의 구매확정 주문에 담긴 상품에 후기를 작성합니다. 적립금 지급·상품 통계 반영이 함께 일어납니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:product_review_create
  • 역할: user 만 (Bootpay-Role: supervisor 는 401 API_ROLE_NOT_SUPPORT)
  • 회원: JWT 또는 user_id 필수 — 회원 JWT

요청

Content-Type: application/json

위치 이름 타입 필수 기본값 설명
body user_id string 회원 지정(JWT 를 보내지 않을 때 필수)
body order_id string O 이 회원의 구매확정 주문 ID
body product_id string O 그 주문에 담긴 상품 ID
body product_option_id string 그 주문에 담긴 옵션 ID. 보내면 상품·옵션이 모두 맞아야 합니다
body rating integer O 1~5 정수
body content string O 본문, 최대 5000자
body images array 사진 URL 최대 5개. 문자열 URL 또는 {"url": "..."} 객체
{
  "user_id": "6abb14aa1073500b84eb40ad",
  "order_id": "6abb14aa1073500b84eb40b2",
  "product_id": "6abb14aa1073500b84eb40b0",
  "rating": 4,
  "content": "배송이 빠르고 품질이 좋아요",
  "images": ["https://cdn.example.com/r1.jpg"]
}json

응답

200 OK — 작성한 응답 객체 (작성자 본인 기준이라 order_id·visibility·editable·edit_deadline_at 포함)

{
  "product_review_id": "6abb14aa1073500b84eb40ab",
  "product_id": "6abb14aa1073500b84eb40b0",
  "user_id": "6abb14aa1073500b84eb40ad",
  "author": "김​**",
  "rating": 4,
  "content": "배송이 빠르고 품질이 좋아요",
  "is_photo_review": true,
  "helpful_count": 0,
  "images": [{ "url": "https://cdn.example.com/r1.jpg", "position": 0 }],
  "image_count": 1,
  "created_at": "2026-09-29T09:30:18+09:00",
  "updated_at": "2026-09-29T09:30:18+09:00",
  "order_id": "6abb14aa1073500b84eb40b2",
  "visibility": "public",
  "editable": true,
  "edit_deadline_at": "2026-10-06T09:30:18+09:00"
}json

오류

HTTP error_code 언제
400 REQUIRED_PARAMETER_IS_MISSING (131) order_id·product_id 누락 또는 회원 미지정 (payload.field 에 이름)
404 ORDER_NOT_FOUND (3700) 없는 주문·형식이 틀린 ID·다른 프로젝트 주문
403 REVIEW_UNAUTHORIZED (4044) 다른 회원의 주문
400 REVIEW_PRODUCT_NOT_IN_ORDER (4067) 그 주문에 담긴 상품(·옵션)이 아님
400 REVIEW_PURCHASE_NOT_CONFIRMED (4043) 구매확정 전 주문
400 REVIEW_ALREADY_EXISTS (4041) 이 주문에 이미 후기가 있음(삭제한 후기 포함)
400 INVALID_PARAMETER rating·content 누락, 또는 images 에 http(s) URL 이 아닌 값 (payload.field=images)
400 REVIEW_RATING_INVALID (4050) rating 이 1~5 정수가 아님(4.5·"abc" 포함)
400 REVIEW_CONTENT_TOO_LONG (4054) 본문 5000자 초과
400 REVIEW_IMAGE_LIMIT_EXCEEDED (4047) 사진 5장 초과
401 API_ROLE_NOT_SUPPORT Bootpay-Role 이 user 가 아님
401 USER_SESSION_INVALID·USER_JWT_INVALID 회원 JWT 가 만료·무효
403 USER_NOT_MATCH (2302) JWT 의 회원과 user_id 가 다름
404 USER_NOT_FOUND (2300) user_id 가 이 몰의 회원이 아님

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

변경 이력

  • 2026-09-29 최초 작성

PUT /v1/reviews/:id

작성자 본인이 작성 후 7일 안에 후기를 수정합니다. 보낸 값만 바뀝니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:product_review_update
  • 역할: user 만
  • 회원: JWT 또는 user_id 필수 — 회원 JWT

요청

Content-Type: application/json

위치 이름 타입 필수 기본값 설명
path id string O 상품평 ID
body user_id string 회원 지정(JWT 를 보내지 않을 때 필수)
body rating integer 1~5 정수. 보내지 않으면 그대로
body content string 최대 5000자. 보내지 않거나 빈 문자열이면 그대로
body images array 사진 URL 최대 5개. 키를 보내면 통째로 교체​​하고, []·null 이면 사진을 모두 지웁니다. 키를 보내지 않으면 그대로
{
  "user_id": "6abb14aa1073500b84eb40ad",
  "rating": 3
}json

응답

200 OK — 수정한 응답 객체 (작성자 본인 기준)

{
  "product_review_id": "6abb14aa1073500b84eb40ab",
  "product_id": "6abb14aa1073500b84eb40b0",
  "user_id": "6abb14aa1073500b84eb40ad",
  "author": "김​**",
  "rating": 3,
  "content": "좋아요",
  "is_photo_review": true,
  "helpful_count": 0,
  "images": [{ "url": "https://cdn.example.com/r1.jpg", "position": 0 }],
  "image_count": 1,
  "created_at": "2026-09-29T09:30:18+09:00",
  "updated_at": "2026-09-29T11:02:40+09:00",
  "order_id": "6abb14aa1073500b84eb40b2",
  "visibility": "public",
  "editable": true,
  "edit_deadline_at": "2026-10-06T09:30:18+09:00"
}json

오류

HTTP error_code 언제
404 REVIEW_NOT_FOUND (4040) 없는 ID·형식이 틀린 ID·다른 프로젝트 후기·삭제된 후기
403 REVIEW_UNAUTHORIZED (4044) 다른 회원의 후기
400 REVIEW_NOT_EDITABLE (4042) 관리자가 숨긴 후기
400 REVIEW_EDIT_TIME_EXPIRED (4046) 작성 후 7일이 지남
400 REVIEW_RATING_INVALID (4050) rating 이 1~5 정수가 아님
400 REVIEW_CONTENT_TOO_LONG (4054) 본문 5000자 초과
400 REVIEW_IMAGE_LIMIT_EXCEEDED (4047) 사진 5장 초과
400 INVALID_PARAMETER images 에 http(s) URL 이 아닌 값 (payload.field=images)
400 REQUIRED_PARAMETER_IS_MISSING (131) 회원 미지정
401 API_ROLE_NOT_SUPPORT Bootpay-Role 이 user 가 아님
401 USER_SESSION_INVALID·USER_JWT_INVALID 회원 JWT 가 만료·무효
403 USER_NOT_MATCH (2302) JWT 의 회원과 user_id 가 다름
404 USER_NOT_FOUND (2300) user_id 가 이 몰의 회원이 아님

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

변경 이력

  • 2026-09-29 최초 작성

DELETE /v1/reviews/:id

후기를 삭제합니다. 지급한 적립금을 회수하고 상품 통계에서 뺍니다. 삭제한 후기는 이후 조회·삭제에서 404 입니다.

  • 회원 모드: 작성자 본인의 공개 후기만
  • 운영자 모드: 숨긴 후기를 포함해 이 프로젝트의 후기. reason 으로 삭제 사유를 남깁니다

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:product_review_delete (회원 모드), supervisor:product_review_delete (운영자 모드)
  • 회원: 회원 모드는 JWT 또는 user_id 필수 — 회원 JWT. 운영자 모드는 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O 상품평 ID
query user_id string 회원 모드의 회원 지정(JWT 를 보내지 않을 때 필수)
query reason string 관리자 삭제 운영자 모드의 삭제 사유

응답

200 OK

{
  "deleted": true,
  "product_review_id": "6abb14aa1073500b84eb40ab"
}json
필드 타입 설명
deleted boolean 항상 true
product_review_id string 삭제한 상품평 ID

오류

HTTP error_code 언제
404 REVIEW_NOT_FOUND (4040) 없는 ID·형식이 틀린 ID·다른 프로젝트 후기·이미 삭제된 후기
403 REVIEW_UNAUTHORIZED (4044) 회원 모드에서 다른 회원의 후기, 또는 관리자가 숨긴 후기
400 REQUIRED_PARAMETER_IS_MISSING (131) 회원 모드인데 회원 미지정
401 API_ROLE_NOT_SUPPORT Bootpay-Role 이 user·supervisor 가 아님
401 USER_SESSION_INVALID·USER_JWT_INVALID 회원 JWT 가 만료·무효
403 USER_NOT_MATCH (2302) JWT 의 회원과 user_id 가 다름
404 USER_NOT_FOUND (2300) user_id 가 이 몰의 회원이 아님

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

변경 이력

  • 2026-09-29 최초 작성

PUT /v1/reviews/:id/reply

판매자 답글을 등록하거나 수정합니다. 답글이 있으면 내용을 바꾸고(같은 reply_id), 없거나 삭제됐으면 새로 답니다. 관리자가 숨긴 후기에도 달 수 있습니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: supervisor:product_review_reply
  • 역할: supervisor 만. Bootpay-Role 헤더를 생략하면 supervisor 로 봅니다(user 를 보내면 401 API_ROLE_NOT_SUPPORT)
  • 회원: 필요 없음

요청

Content-Type: application/json

위치 이름 타입 필수 기본값 설명
path id string O 상품평 ID
body content string O 답글 내용, 10자 이상
{
  "content": "구매해 주셔서 감사합니다. 또 방문해 주세요."
}json

응답

200 OK — 답글이 반영된 응답 객체 (운영자 기준이라 order_id·visibility·editable·edit_deadline_at 포함)

{
  "product_review_id": "6abb14aa1073500b84eb40ab",
  "product_id": "6abb14aa1073500b84eb40b0",
  "user_id": "6abb14aa1073500b84eb40ad",
  "author": "김​**",
  "rating": 5,
  "content": "좋아요",
  "is_photo_review": true,
  "helpful_count": 0,
  "images": [{ "url": "https://cdn.example.com/r1.jpg", "position": 0 }],
  "image_count": 1,
  "reply": {
    "reply_id": "6abb14aa1073500b84eb40b4",
    "content": "구매해 주셔서 감사합니다. 또 방문해 주세요.",
    "created_at": "2026-09-29T10:30:18+09:00",
    "updated_at": "2026-09-29T10:30:18+09:00"
  },
  "created_at": "2026-09-29T09:30:18+09:00",
  "updated_at": "2026-09-29T10:30:18+09:00",
  "order_id": "6abb14aa1073500b84eb40b2",
  "visibility": "public",
  "editable": true,
  "edit_deadline_at": "2026-10-06T09:30:18+09:00"
}json

오류

HTTP error_code 언제
404 REVIEW_NOT_FOUND (4040) 없는 ID·형식이 틀린 ID·다른 프로젝트 후기·삭제된 후기
400 REVIEW_REPLY_CONTENT_REQUIRED (4063) content 누락·빈 값
400 REVIEW_REPLY_CONTENT_TOO_SHORT (4064) content 10자 미만
401 API_ROLE_NOT_SUPPORT Bootpay-Role 이 supervisor 가 아님

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

변경 이력

  • 2026-09-29 최초 작성

함께 보기