회원이 구매확정한 주문의 상품에 남기는 후기(상품평)를 조회·작성·수정·삭제하고, 운영자가 판매자 답글을 답니다. 모든 요청은 인증된 프로젝트(쇼핑몰)의 상품평만 다룹니다. 다른 프로젝트의 상품평 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 최초 작성
