공지사항

쇼핑몰 고객센터의 공지사항을 조회하고, 가맹점 서버에서 공지를 작성·수정·삭제합니다. 관리자 화면의 공지사항과 같은 데이터입니다.

조회는 두 가지 방식으로 부를 수 있습니다.

  • 고객 조회​(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 최초 작성

함께 보기