Penta API 빠른 참조

모든 API 엔드포인트의 빠른 참조 테이블이다. Auth 열의 값은 다음과 같다:

X: 인증 불필요
O: 인증 필요 (Bearer Token)
Admin: 관리자 권한 필요

인증

Method	URL	Auth	설명
POST	`/api/users/register/`	X	회원가입
POST	`/api/users/social-auth/`	X	소셜 로그인 (Google/Apple/Kakao/LINE/Facebook)
POST	`/api/users/admin-google-login/`	X	관리자 Google 로그인
POST	`/api/users/token/refresh/`	X	JWT 토큰 갱신
POST	`/api/users/logout/`	O	로그아웃

사용자

Method	URL	Auth	설명
GET	`/api/users/profile/`	O	프로필 조회
PATCH	`/api/users/profile/`	O	프로필 수정
GET	`/api/users/profile-summary/`	O	프로필 + 읽기 통계 요약
GET	`/api/users/settings/`	O	설정 조회
PATCH	`/api/users/settings/`	O	설정 수정
POST	`/api/users/devices/register/`	O	기기 등록 (FCM 토큰)
GET	`/api/users/devices/`	O	등록된 기기 목록
GET	`/api/users/login-history/`	O	로그인 이력
POST	`/api/users/delete-account/`	O	계정 탈퇴
GET	`/api/users/bookmarks/`	O	북마크 목록
POST	`/api/users/bookmarks/`	O	북마크 추가
DELETE	`/api/users/bookmarks/<book_id>/`	O	북마크 삭제
GET	`/api/users/bookmarks/status/<book_id>/`	O	북마크 상태 확인
GET	`/api/users/reading-history/`	O	읽기 이력
GET	`/api/users/recordings/`	O	녹음 목록
DELETE	`/api/users/recordings/<pk>/`	O	녹음 삭제
GET	`/api/users/recent-books/`	O	최근 읽은 도서
GET	`/api/users/books-in-progress/`	O	진행중 도서
GET	`/api/users/completed-books/`	O	완독 도서
GET	`/api/users/review-eligibility/`	O	리뷰 요청 대상 여부
POST	`/api/users/review-requested/`	O	리뷰 요청 기록

도서

Method	URL	Auth	설명
GET	`/api/books/`	X	도서 목록
GET	`/api/books/all/`	X	전체 도서 데이터
GET	`/api/books/catalog/`	X	도서 카탈로그
GET	`/api/books/<pk>/`	X	도서 상세
GET	`/api/books/<book_id>/recommendations/`	X	도서 추천
GET	`/api/books/<book_id>/reading-progress/`	O	도서 읽기 진행률 조회
POST	`/api/books/<book_id>/reading-progress/`	O	도서 읽기 진행률 업데이트
GET	`/api/books/<book_id>/episodes/<pk>/`	O	에피소드 상세 (페이지 포함)
GET	`/api/books/<book_id>/episodes/<ep_id>/recordings/`	O	에피소드 녹음 목록
POST	`/api/books/<book_id>/episodes/<ep_id>/recordings/`	O	에피소드 녹음 업로드
GET	`/api/books/<book_id>/episodes/<ep_id>/reading-progress/`	O	에피소드 읽기 진행률
POST	`/api/books/<book_id>/episodes/<ep_id>/reading-progress/`	O	에피소드 읽기 진행률 업데이트
GET	`/api/books/search/`	X	도서 검색
GET	`/api/books/characters/`	X	캐릭터 목록
GET	`/api/books/characters/<pk>/`	X	캐릭터 상세
GET	`/api/books/illustrators/`	X	일러스트레이터 목록
GET	`/api/books/illustrators/<pk>/`	X	일러스트레이터 상세

홈

Method	URL	Auth	설명
GET	`/api/home/`	X	종합 홈 데이터
GET	`/api/home/filters/`	X	필터 옵션 목록
GET	`/api/home/characters/`	X	캐릭터 친구들
GET	`/api/home/rankings/`	X	실시간 랭킹 TOP 10
GET	`/api/home/banners/`	X	배너 목록
GET	`/api/home/curations/<curation_id>/`	X	큐레이션 상세

결제

Method	URL	Auth	설명
POST	`/api/payments/subscribe/`	O	구독 생성
GET	`/api/payments/subscription/`	O	구독 상태 조회
POST	`/api/payments/subscription/cancel/`	O	구독 취소
POST	`/api/payments/promo/apply/`	O	결제 시 프로모 코드 적용
GET	`/api/payments/subscription-offers/`	O	구독 오퍼 조회
GET	`/api/payments/history/`	O	결제 이력
GET	`/api/payments/subscription-history/`	O	구독 이력
POST	`/api/payments/verify/`	O	결제 검증 (Google/Apple)
POST	`/api/payments/refund-request/`	O	환불 요청
POST	`/api/payments/refund-process/`	Admin	환불 처리
POST	`/api/payments/google-play/manage/`	Admin	Google Play 관리
POST	`/api/payments/rtdn/pubsub/`	X	Google RTDN 웹훅
POST	`/api/payments/apple/notifications/`	X	Apple 웹훅

프로모코드

Method	URL	Auth	설명
POST	`/api/promocodes/apply/`	O	프로모 코드 임시 적용
GET	`/api/promocodes/applied/`	O	적용된 프로모 조회
POST	`/api/promocodes/applied/clear/`	O	적용 해제
POST	`/api/promocodes/referral/create/`	O	래퍼럴 코드 생성
GET	`/api/promocodes/referral/my-stats/`	O	내 추천 통계
GET	`/api/promocodes/referral/my-benefits/`	O	내 래퍼럴 혜택
GET	`/api/promocodes/referral/rewards/`	O	리워드 내역
GET	`/api/promocodes/invite/<code>/`	X	초대 링크 리다이렉트
GET	`/api/promocodes/invite/<code>/info/`	X	초대 링크 정보
GET	`/api/promocodes/analytics/<partner_code>/`	Admin	파트너 분석

스티커

Method	URL	Auth	설명
GET	`/api/stickers/`	O	내 스티커 목록
GET	`/api/stickers/stats/`	O	스티커 통계
GET	`/api/stickers/popular/`	O	인기 스티커
GET	`/api/stickers/missing/`	O	미보유 스티커
GET	`/api/stickers/upcoming/`	O	공개 예정 스티커
GET	`/api/stickers/wishlist/`	O	위시리스트 조회
POST	`/api/stickers/wishlist/`	O	위시리스트 추가
DELETE	`/api/stickers/wishlist/<sticker_id>/`	O	위시리스트 삭제
POST	`/api/stickers/earn/<episode_id>/`	O	스티커 획득

이벤트/뉴스

Method	URL	Auth	설명
GET	`/api/events-news/`	X	이벤트/뉴스 목록
GET	`/api/events-news/<pk>/`	X	이벤트/뉴스 상세
POST	`/api/events-news/participate/`	O	이벤트 참여

알림

Method	URL	Auth	설명
GET	`/api/notifications/`	O	알림 목록
POST	`/api/notifications/mark-read/`	O	알림 읽음 처리
POST	`/api/notifications/mark-all-read/`	O	전체 읽음 처리
GET	`/api/notifications/unread-count/`	O	미읽음 수
GET	`/api/notifications/red-dot/`	O	레드닷 상태

지원

Method	URL	Auth	설명
GET	`/api/support/faq/`	X	FAQ 목록
GET	`/api/support/faq/<pk>/`	X	FAQ 상세
GET	`/api/support/inquiries/`	O	문의 목록
POST	`/api/support/inquiries/`	O	문의 등록
GET	`/api/support/inquiries/<pk>/`	O	문의 상세
GET	`/api/support/announcements/`	X	공지사항 목록
GET	`/api/support/announcements/<pk>/`	X	공지사항 상세

블로그

Method	URL	Auth	설명
GET	`/api/blog/posts/`	X	포스트 목록
GET	`/api/blog/posts/<pk>/`	X	포스트 상세
GET	`/api/blog/categories/`	X	카테고리 목록
GET	`/api/blog/categories/<pk>/`	X	카테고리 상세
GET	`/api/blog/tags/`	X	태그 목록
GET	`/api/blog/tags/<pk>/`	X	태그 상세

업로드/시스템

Method	URL	Auth	설명
POST	`/api/upload/presigned-url/`	O	S3 Presigned URL 발급
POST	`/api/upload/confirm/`	O	업로드 완료 확인
GET	`/health/`	X	헬스체크

Rate Limiting 요약

대상	제한
비인증 (anon)	300/hr
인증 (user)	3000/hr
로그인 (login)	15/min
회원가입 (register)	9/hr
결제 검증 (payment_verify)	30/min
검색 (search)	90/min
도서 콘텐츠 (book_content)	300/min
관리자 (admin)	1500/hr
민감 작업 (sensitive)	90/min

인증​

사용자​

도서​

홈​

결제​

프로모코드​

스티커​

이벤트/뉴스​

알림​

지원​

블로그​

업로드/시스템​

Rate Limiting 요약​

인증

사용자

도서

홈

결제

프로모코드

스티커

이벤트/뉴스

알림

지원

블로그

업로드/시스템

Rate Limiting 요약