쇼핑몰 고객센터의 자주 묻는 질문(FAQ)을 조회하고, 가맹점 서버에서 FAQ 를 작성·수정·삭제합니다. 관리자 화면의 자주 묻는 질문과 같은 데이터입니다. 질문은 title, 답변은 content 입니다.
조회는 두 가지 방식으로 부를 수 있습니다.
- 고객 조회(
Bootpay-Role헤더 없음 또는user): 쇼핑몰 설정에서 FAQ 사용(use_faq)이 켜져 있어야 하고, 공개(is_display=true) FAQ 만 보입니다. 쇼핑몰 화면을 그릴 때 씁니다. - 운영자 조회(
Bootpay-Role: supervisor): FAQ 사용 여부와 관계없이 조회되고, 비공개 FAQ 도 볼 수 있습니다. 관리 화면·동기화에 씁니다.
작성·수정·삭제는 운영자 권한(supervisor scope)만 할 수 있고, FAQ 사용 여부와 관계없이 동작합니다. 역할과 scope 는 인증을 봅니다.
모든 요청은 인증한 프로젝트의 FAQ 만 다룹니다. 다른 쇼핑몰의 FAQ, 공지사항·1:1 문의의 ID 를 넣으면 404 POST_NOT_FOUND 입니다. 공지사항은 공지사항을 봅니다.
FAQ 객체
| 필드 | 타입 | 설명 |
|---|---|---|
| faq_id | string | FAQ ID |
| title | string | 질문 |
| content | string | null | 답변(HTML 일 수 있음). 비밀글로 저장된 예전 글은 고객 조회에서 null |
| images | string[] | 이미지 URL 목록. 없으면 [] |
| is_display | boolean | 공개 여부. 고객 조회에는 true 인 FAQ 만 나옵니다 |
| read_count | integer | 조회 수. 이 API 로 조회해도 늘어나지 않습니다 |
| created_at | string | 작성 시각 (ISO 8601, 예 2026-09-29T09:00:00+09:00) |
| updated_at | string | 마지막 수정 시각 (ISO 8601) |
필드는 값이 없어도 항상 들어 있습니다. FAQ 에는 공지사항의 상단 고정(is_notice)·작성자(author)가 없습니다.
GET /v1/faqs
FAQ 목록을 조회합니다. 최근 작성 순입니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:faq_list—Bootpay-Role: supervisor로 부르면supervisor:faq_list - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| query | page | integer | 1 | 페이지 번호 — 페이지네이션 | |
| query | limit | integer | 20 | 페이지 크기(최대 100) | |
| query | keyword | string | 질문·답변 부분 일치 검색(대소문자 무시) | ||
| query | view | string | public |
public: 공개 FAQ 만. all: 비공개 FAQ 포함 — Bootpay-Role: supervisor 일 때만 |
잘못된 page·limit 는 오류 없이 기본값·상한으로 고쳐 조회하고, 응답의 page·limit 에 고친 값을 돌려줍니다.
응답
200 OK
{
"list": [
{
"faq_id": "66f9a1c0e1b2c3d4e5f60002",
"title": "배송비는 얼마인가요?",
"content": "<p>상품·지역별 배송비를 주문서에서 확인하세요.</p>",
"images": [],
"is_display": true,
"read_count": 15,
"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 | FAQ 객체 배열 |
| count | integer | 조건에 맞는 전체 FAQ 수 |
| page | integer | 적용한 페이지 |
| limit | integer | 적용한 페이지 크기 |
FAQ 게시판이 아직 없으면 {"list": [], "count": 0, "page": 1, "limit": 20} 입니다.
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | INVALID_PARAMETER |
view 가 public·all 이 아님 (payload.field: "view") |
| 401 | API_SCOPE_INVALID |
view=all 을 운영자 조회(Bootpay-Role: supervisor)가 아닌 요청으로 보냄 |
| 401 | API_ROLE_NOT_SUPPORT |
Bootpay-Role 이 user·supervisor 가 아님 |
| 442 | BOARD_FEATURE_DISABLED |
고객 조회인데 쇼핑몰의 FAQ 사용이 꺼져 있음 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-29 최초 작성
GET /v1/faqs/:id
FAQ 하나를 조회합니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:faq_detail—Bootpay-Role: supervisor로 부르면supervisor:faq_detail - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | FAQ ID |
비공개 FAQ 는 운영자 조회(Bootpay-Role: supervisor)에서만 보입니다. 고객 조회에서는 없는 FAQ 와 같이 404 입니다.
응답
200 OK — FAQ 객체.
{
"faq_id": "66f9a1c0e1b2c3d4e5f60002",
"title": "배송비는 얼마인가요?",
"content": "<p>상품·지역별 배송비를 주문서에서 확인하세요.</p>",
"images": [],
"is_display": true,
"read_count": 15,
"created_at": "2026-09-29T09:00:00+09:00",
"updated_at": "2026-09-29T09:00:00+09:00"
}json오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | POST_NOT_FOUND |
없는 ID, ID 형식 오류, 다른 쇼핑몰의 FAQ, FAQ 가 아닌 글(공지사항·1:1 문의), 고객 조회에서 비공개 FAQ |
| 401 | API_ROLE_NOT_SUPPORT |
Bootpay-Role 이 user·supervisor 가 아님 |
| 442 | BOARD_FEATURE_DISABLED |
고객 조회인데 쇼핑몰의 FAQ 사용이 꺼져 있음 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-29 최초 작성
POST /v1/faqs
FAQ 를 작성합니다. FAQ 게시판이 아직 없으면 기본 게시판을 만든 뒤 작성합니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
supervisor:faq_create.Bootpay-Role헤더는 생략하거나supervisor여야 합니다 - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| body | title | string | O | 질문. 앞뒤 공백은 지웁니다 | |
| body | content | string | O | 답변(HTML 가능) | |
| body | images | string[] | [] |
이미지 URL 목록. 빈 문자열은 뺍니다 | |
| body | is_display | boolean | true | 공개 여부 |
참/거짓 값은 true/false(또는 문자열 "true"/"false")만 받습니다. 다른 값은 400 입니다. is_notice 는 받지 않습니다(보내도 무시).
{
"title": "배송비는 얼마인가요?",
"content": "<p>상품·지역별 배송비를 주문서에서 확인하세요.</p>"
}json응답
200 OK — 작성한 FAQ 객체.
{
"faq_id": "66f9a1c0e1b2c3d4e5f60002",
"title": "배송비는 얼마인가요?",
"content": "<p>상품·지역별 배송비를 주문서에서 확인하세요.</p>",
"images": [],
"is_display": true,
"read_count": 0,
"created_at": "2026-09-29T09:00:00+09:00",
"updated_at": "2026-09-29T09:00:00+09:00"
}json오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | INVALID_PARAMETER |
title·content 누락 또는 빈 값(payload: {"field": "title", "reason": "required"}), 형식 오류(reason: "invalid" — 문자열이 아닌 질문·답변, 문자열 배열이 아닌 images, 참/거짓이 아닌 is_display) |
| 401 | API_ROLE_NOT_SUPPORT |
Bootpay-Role 이 supervisor 가 아님 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-29 최초 작성
PUT /v1/faqs/:id
FAQ 를 수정합니다. 보낸 필드만 바꾸고, 보내지 않은 필드는 그대로 둡니다. PATCH 도 같습니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
supervisor:faq_update.Bootpay-Role헤더는 생략하거나supervisor여야 합니다 - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | FAQ ID. 비공개 FAQ 도 수정할 수 있습니다 | |
| body | title | string | 질문. 보낸다면 빈 값이면 안 됩니다 | ||
| body | content | string | 답변. 보낸다면 빈 값이면 안 됩니다 | ||
| body | images | string[] | 이미지 URL 목록 전체를 바꿉니다. [] 를 보내면 모두 지웁니다 |
||
| body | is_display | boolean | 공개 여부. false 로 바꾸면 고객 조회에서 사라집니다 |
{
"content": "<p>배송비는 주문서에서 지역별로 계산됩니다.</p>"
}json응답
200 OK — 수정한 뒤의 FAQ 객체.
{
"faq_id": "66f9a1c0e1b2c3d4e5f60002",
"title": "배송비는 얼마인가요?",
"content": "<p>배송비는 주문서에서 지역별로 계산됩니다.</p>",
"images": [],
"is_display": true,
"read_count": 15,
"created_at": "2026-09-29T09:00:00+09:00",
"updated_at": "2026-09-30T10:00:00+09:00"
}json오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | INVALID_PARAMETER |
보낸 title·content 가 빈 값(reason: "required"), 형식 오류(reason: "invalid") — payload.field 에 필드 이름 |
| 404 | POST_NOT_FOUND |
없는 ID, ID 형식 오류, 다른 쇼핑몰의 FAQ, FAQ 가 아닌 글(공지사항·1:1 문의) |
| 401 | API_ROLE_NOT_SUPPORT |
Bootpay-Role 이 supervisor 가 아님 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-29 최초 작성
DELETE /v1/faqs/:id
FAQ 를 삭제합니다. 관리자 화면의 삭제와 같이 FAQ 를 완전히 지우며 되돌릴 수 없습니다. 삭제한 뒤 같은 ID 로 조회·삭제하면 404 입니다. 잠시 내리려면 PUT /v1/faqs/:id 로 is_display: false 를 보내세요.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
supervisor:faq_delete.Bootpay-Role헤더는 생략하거나supervisor여야 합니다 - 회원 JWT(
Bootpay-User-JWT): 필요 없음
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | FAQ ID |
응답
200 OK
{
"deleted": true,
"faq_id": "66f9a1c0e1b2c3d4e5f60002"
}json| 필드 | 타입 | 설명 |
|---|---|---|
| deleted | boolean | 항상 true |
| faq_id | string | 삭제한 FAQ ID |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | POST_NOT_FOUND |
없는 ID(이미 삭제한 FAQ 포함), ID 형식 오류, 다른 쇼핑몰의 FAQ, FAQ 가 아닌 글(공지사항·1:1 문의) |
| 401 | API_ROLE_NOT_SUPPORT |
Bootpay-Role 이 supervisor 가 아님 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-29 최초 작성
