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