본문으로 건너뛰기

Penta 백엔드 API 문서

개요​

Penta는 디즈니 아동 도서 서비스로, Django REST Framework 기반의 REST API를 제공한다.

  • 프레임워크: Django 4.2+ / Django REST Framework
  • 인증: JWT (Access Token 1일, Refresh Token 7일)
  • 다국어: django-parler (ko, en, ja/jp, es)
  • 데이터베이스: PostgreSQL (운영), SQLite (개발)

Base URL​

개발: http://localhost:8080/api
운영: https://api.pentadisney.com/api

지원 언어​

코드언어
ko한국어
en영어
ja (jp)일본어
es스페인어

언어 선택 우선순위: Accept-Language 헤더 > 사용자 프로필 app_language 설정 > 기본값(en)

1. 인증 (Authentication)​

JWT 인증 시스템​

  • Access Token: 유효기간 1일 (24시간)
  • Refresh Token: 유효기간 7일
  • 모든 인증 필요 API에 Authorization: Bearer <access_token> 헤더를 포함한다.

1.1 회원가입​

POST /api/users/register/

소셜 로그인 기반 회원가입. social_provider와 social_id로 사용자를 생성한다.

  • Auth: 불필요
  • Rate Limit: 9/hr (register)

1.2 소셜 로그인​

POST /api/users/social-auth/

소셜 로그인 인증. 지원 제공자: Google, Apple, Kakao, LINE, Facebook. 기존 계정이면 로그인, 없으면 자동 생성한다.

  • Auth: 불필요
  • Rate Limit: 15/min (login)
  • 응답: access, refresh 토큰 + 사용자 정보

1.3 토큰 갱신​

POST /api/users/token/refresh/

Refresh Token으로 새 Access Token과 Refresh Token을 발급받는다.

  • Auth: 불필요
  • 파라미터: refresh (string, 필수)

1.4 로그아웃​

POST /api/users/logout/

현재 토큰을 무효화한다.

  • Auth: 필요

1.5 관리자 Google 로그인​

POST /api/users/admin-google-login/

관리자 전용 Google OAuth 로그인.

  • Auth: 불필요

2. 사용자 (Users)​

2.1 프로필 조회/수정​

GET  /api/users/profile/
PATCH /api/users/profile/

현재 사용자의 프로필 정보를 조회하거나 수정한다.

  • Auth: 필요
  • 수정 가능 필드: nickname, language, country, birth_year, marketing_consent 등

2.2 프로필 요약​

GET /api/users/profile-summary/

사용자 프로필 + 읽기 통계 요약 정보.

  • Auth: 필요

2.3 설정​

GET  /api/users/settings/
PATCH /api/users/settings/

앱 설정 관리 (app_language, viewer_languages, push_notification_enabled, notification_marketing, notification_bookmark).

  • Auth: 필요

2.4 기기 관리​

POST /api/users/devices/register/
GET  /api/users/devices/

기기 등록 (FCM 토큰 포함) 및 등록된 기기 목록 조회.

  • Auth: 필요
  • 파라미터: device_id, device_type (ios/android), device_model, app_version, fcm_token

2.5 로그인 이력​

GET /api/users/login-history/

로그인 이력 조회.

  • Auth: 필요

2.6 계정 삭제​

POST /api/users/delete-account/

계정 탈퇴 (소프트 삭제). deletion_reason 포함 가능.

  • Auth: 필요

2.7 북마크​

GET    /api/users/bookmarks/
POST   /api/users/bookmarks/
DELETE /api/users/bookmarks/<book_id>/
GET    /api/users/bookmarks/status/<book_id>/

북마크 목록 조회, 추가, 삭제, 특정 도서 북마크 상태 확인.

  • Auth: 필요

2.8 읽기 이력​

GET /api/users/reading-history/

읽기 이력 조회 (에피소드 단위 진행률 포함).

  • Auth: 필요

2.9 녹음​

GET    /api/users/recordings/
DELETE /api/users/recordings/<pk>/

사용자 녹음 목록 조회 및 삭제.

  • Auth: 필요

2.10 도서 상태별 조회​

GET /api/users/recent-books/
GET /api/users/books-in-progress/
GET /api/users/completed-books/

최근 읽은 도서, 진행중 도서, 완독 도서를 각각 조회한다.

  • Auth: 필요

2.11 리뷰 요청​

GET  /api/users/review-eligibility/
POST /api/users/review-requested/

앱 리뷰 요청 대상 여부 확인 및 리뷰 요청 노출 기록.

  • Auth: 필요

3. 도서 (Books)​

3.1 도서 목록​

GET /api/books/

도서 목록 조회. 언어별 출판된 도서만 반환.

  • Auth: 불필요 (인증 시 북마크/진행률 포함)
  • 파라미터: lang, page, page_size, brand, series, character

3.2 전체 도서 데이터​

GET /api/books/all/

전체 도서 데이터를 한번에 반환 (캐싱 최적화).

  • Auth: 불필요

3.3 도서 카탈로그​

GET /api/books/catalog/

도서 카탈로그 조회 (필터, 정렬 지원).

  • Auth: 불필요

3.4 도서 상세​

GET /api/books/<pk>/

도서 상세 정보 (에피소드 목록, 캐릭터, 시리즈, 스티커 정보 포함).

  • Auth: 불필요 (인증 시 북마크/진행률 포함)

3.5 도서 추천​

GET /api/books/<book_id>/recommendations/

특정 도서 기반 추천 도서 목록.

  • Auth: 불필요

3.6 도서 읽기 진행률​

GET  /api/books/<book_id>/reading-progress/
POST /api/books/<book_id>/reading-progress/

도서의 읽기 진행률 조회 및 업데이트.

  • Auth: 필요

3.7 에피소드 상세​

GET /api/books/<book_id>/episodes/<pk>/

에피소드 상세 정보 (페이지 URL 목록 포함). 구독 필요 콘텐츠는 인증/구독 필수.

  • Auth: 필요 (프리미엄 콘텐츠)
  • Rate Limit: 300/min (book_content)

3.8 에피소드 녹음​

GET  /api/books/<book_id>/episodes/<episode_id>/recordings/
POST /api/books/<book_id>/episodes/<episode_id>/recordings/

에피소드별 녹음 목록 조회 및 녹음 업로드.

  • Auth: 필요

3.9 에피소드 읽기 진행률​

GET  /api/books/<book_id>/episodes/<episode_id>/reading-progress/
POST /api/books/<book_id>/episodes/<episode_id>/reading-progress/

에피소드별 읽기 진행률 조회 및 업데이트.

  • Auth: 필요

3.10 검색​

GET /api/books/search/

도서 검색. 제목, 저자, 시놉시스를 대상으로 검색한다.

  • Auth: 불필요
  • Rate Limit: 90/min (search)
  • 파라미터: q (검색어), lang

3.11 캐릭터​

GET /api/books/characters/
GET /api/books/characters/<pk>/

캐릭터 목록 및 상세 조회.

  • Auth: 불필요

3.12 일러스트레이터​

GET /api/books/illustrators/
GET /api/books/illustrators/<pk>/

일러스트레이터 목록 및 상세 조회.

  • Auth: 불필요

4. 홈 (Home)​

4.1 종합 홈 데이터​

GET /api/home/

홈 화면에 필요한 종합 데이터를 한번에 반환한다. 배너, 큐레이션, 랭킹, 캐릭터, 필터 등을 포함한다.

  • Auth: 불필요 (인증 시 개인화 데이터 포함)

4.2 필터​

GET /api/home/filters/

홈 화면 필터 옵션 목록 (tab, series, reading_level).

  • Auth: 불필요

4.3 캐릭터 친구들​

GET /api/home/characters/

홈 화면 캐릭터 목록.

  • Auth: 불필요

4.4 랭킹​

GET /api/home/rankings/

실시간 랭킹 TOP 10 (국가별).

  • Auth: 불필요
  • 파라미터: country (기본: 사용자 국가 또는 KR)

4.5 배너​

GET /api/home/banners/

활성 배너 목록 (시간 기반 필터링).

  • Auth: 불필요

4.6 큐레이션 상세​

GET /api/home/curations/<curation_id>/

특정 큐레이션의 도서 목록.

  • Auth: 불필요

5. 결제 (Payments)​

5.1 구독​

POST /api/payments/subscribe/

구독 생성 (Google Play / Apple App Store 결제 후 호출).

  • Auth: 필요

5.2 구독 조회​

GET /api/payments/subscription/

현재 구독 상태 조회.

  • Auth: 필요

5.3 구독 취소​

POST /api/payments/subscription/cancel/

구독 취소 (자동갱신 중지, 만료일까지 유효).

  • Auth: 필요

5.4 프로모 코드 적용 (결제)​

POST /api/payments/promo/apply/

결제 시 프로모 코드 적용.

  • Auth: 필요

5.5 구독 오퍼​

GET /api/payments/subscription-offers/

사용 가능한 구독 오퍼 (프로모 코드 기반 할인 포함).

  • Auth: 필요

5.6 결제 이력​

GET /api/payments/history/
GET /api/payments/subscription-history/

결제 거래 이력 및 구독 이력 조회.

  • Auth: 필요

5.7 결제 검증​

POST /api/payments/verify/

Google Play / Apple App Store 영수증 검증 및 구독 활성화.

  • Auth: 필요
  • Rate Limit: 30/min (payment_verify)

5.8 환불​

POST /api/payments/refund-request/
POST /api/payments/refund-process/

환불 요청 및 환불 처리 (관리자).

  • Auth: 필요

5.9 Google Play 관리​

POST /api/payments/google-play/manage/

Google Play 구독 관리 (Acknowledge, Refund, Revoke).

  • Auth: 필요 (관리자)

5.10 웹훅​

POST /api/payments/rtdn/pubsub/

Google Play 실시간 개발자 알림 (RTDN) 수신 엔드포인트. Google Pub/Sub에서 호출한다.

  • Auth: 불필요 (Google Pub/Sub 인증)
POST /api/payments/apple/notifications/

Apple Server Notifications V2 웹훅 수신 엔드포인트.

  • Auth: 불필요 (Apple JWS 서명 검증)

6. 프로모코드 (Promo Codes)​

6.1 프로모 코드 적용​

POST /api/promocodes/apply/
GET  /api/promocodes/applied/
POST /api/promocodes/applied/clear/

프로모 코드 임시 적용 (IAP 결제 전), 적용된 프로모 조회, 적용 해제.

  • Auth: 필요

6.2 래퍼럴 코드​

POST /api/promocodes/referral/create/
GET  /api/promocodes/referral/my-stats/
GET  /api/promocodes/referral/my-benefits/
GET  /api/promocodes/referral/rewards/

래퍼럴 코드 생성, 내 추천 통계 조회, 내 래퍼럴 혜택 조회, 리워드 내역 조회.

  • Auth: 필요

6.3 친구 초대 링크​

GET /api/promocodes/invite/<code>/
GET /api/promocodes/invite/<code>/info/

래퍼럴 웹 리다이렉트 (앱 딥링크) 및 초대 링크 정보 조회.

  • Auth: 불필요

별도 웹 URL도 제공:

  • GET /invite/<code>/ - 웹 초대 링크

6.4 파트너 분석​

GET /api/promocodes/analytics/<partner_code>/

파트너 프로모션 분석 데이터 (관리자 전용).

  • Auth: 필요 (관리자)

별도 파트너 리다이렉트 URL:

  • GET /r/<code>/ - 파트너 프로모션 짧은 링크

7. 스티커 (Stickers)​

7.1 내 스티커 목록​

GET /api/stickers/

사용자가 수집한 스티커 목록.

  • Auth: 필요

7.2 스티커 통계​

GET /api/stickers/stats/

스티커 수집 통계 (총 수집수, 일/주/월간 통계).

  • Auth: 필요

7.3 인기 스티커​

GET /api/stickers/popular/

인기 스티커 목록 (기간별, 국가별).

  • Auth: 필요

7.4 미보유 스티커​

GET /api/stickers/missing/

사용자가 아직 보유하지 않은 스티커 목록.

  • Auth: 필요

7.5 공개 예정 스티커​

GET /api/stickers/upcoming/

공개 예정 스티커 목록.

  • Auth: 필요

7.6 스티커 위시리스트​

GET    /api/stickers/wishlist/
POST   /api/stickers/wishlist/
DELETE /api/stickers/wishlist/<sticker_id>/

스티커 위시리스트(찜) 조회, 추가, 삭제.

  • Auth: 필요

7.7 스티커 획득​

POST /api/stickers/earn/<episode_id>/

에피소드 완독 시 스티커 획득.

  • Auth: 필요

8. 이벤트/뉴스 (Events & News)​

8.1 이벤트 목록​

GET /api/events-news/

이벤트 및 뉴스 목록. type 파라미터로 event/news 구분 가능.

  • Auth: 불필요
  • 파라미터: type (event/news), lang

8.2 이벤트 상세​

GET /api/events-news/<pk>/

이벤트/뉴스 상세 정보.

  • Auth: 불필요

8.3 이벤트 참여​

POST /api/events-news/participate/

이벤트 참여 기록.

  • Auth: 필요
  • 파라미터: event_id

9. 알림 (Notifications)​

9.1 알림 목록​

GET /api/notifications/

사용자 알림 목록 (유저소식 + 팬타소식).

  • Auth: 필요

9.2 읽음 처리​

POST /api/notifications/mark-read/
POST /api/notifications/mark-all-read/

특정 알림 읽음 처리 및 전체 읽음 처리.

  • Auth: 필요

9.3 미읽음 수​

GET /api/notifications/unread-count/

미읽음 알림 개수 조회.

  • Auth: 필요

9.4 레드닷​

GET /api/notifications/red-dot/

알림 레드닷 표시 여부 (새 알림이 있는지 빠르게 확인).

  • Auth: 필요

10. 지원 (Support)​

10.1 FAQ​

GET /api/support/faq/
GET /api/support/faq/<pk>/

FAQ 목록 및 상세 조회. 카테고리별 필터링 가능 (account, payment, content, technical, other).

  • Auth: 불필요

10.2 1:1 문의​

GET  /api/support/inquiries/
POST /api/support/inquiries/
GET  /api/support/inquiries/<pk>/

문의 목록 조회, 문의 등록, 문의 상세 조회.

  • Auth: 필요
  • 파라미터 (등록 시): type (bug/payment/content/account/suggestion/other), subject, message

10.3 공지사항​

GET /api/support/announcements/
GET /api/support/announcements/<pk>/

공지사항 목록 및 상세 조회.

  • Auth: 불필요

11. 블로그 (Blog)​

11.1 포스트​

GET /api/blog/posts/
GET /api/blog/posts/<pk>/

블로그 포스트 목록 및 상세 조회. slug 기반 조회도 지원한다. 상세 조회 시 조회수가 자동 증가한다 (IP 기반 1시간 쿨다운).

  • Auth: 불필요

11.2 카테고리​

GET /api/blog/categories/
GET /api/blog/categories/<pk>/

블로그 카테고리 목록 및 상세 조회.

  • Auth: 불필요

11.3 태그​

GET /api/blog/tags/
GET /api/blog/tags/<pk>/

블로그 태그 목록 및 상세 조회.

  • Auth: 불필요

12. 업로드 및 CloudFront​

12.1 파일 업로드​

POST /api/upload/presigned-url/
POST /api/upload/confirm/

S3 Presigned URL 발급 (클라이언트에서 직접 S3 업로드) 및 업로드 완료 확인.

  • Auth: 필요

12.2 CloudFront​

CloudFront 쿠키는 자동으로 관리된다. 별도 엔드포인트 없이 CDN 콘텐츠를 포함하는 API 응답에 쿠키가 자동으로 포함된다.

CDN 콘텐츠를 포함하는 API:

  • /api/home/ (배너, 캐릭터, 도서 표지)
  • /api/books/ (도서 표지)
  • /api/books/{id}/ (도서 상세)
  • /api/books/{id}/episodes/{id}/ (에피소드 페이지)
  • /api/stickers/ (스티커 이미지)
  • /api/events-news/ (이벤트 이미지)
  • /api/users/recent-books/, /api/users/books-in-progress/ (도서 표지)

Rate Limiting​

대상제한설명
anon300/hr비인증 사용자
user3000/hr인증 사용자
login15/min로그인 시도
register9/hr회원가입
payment_verify30/min결제 검증
search90/min검색
book_content300/min도서 콘텐츠 접근
admin1500/hr관리자
sensitive90/min민감 작업

에러 응답 형식​

HTTP 상태 코드​

코드설명
200성공
201생성 성공
204성공 (응답 본문 없음)
400잘못된 요청
401인증 필요
403권한 없음 (구독 필요 포함)
404리소스 없음
429요청 한도 초과
500서버 오류

페이지네이션​

표준 DRF 페이지네이션 형식:

{
  "count": 100,
  "next": "https://api.pentadisney.com/api/books/?page=2",
  "previous": null,
  "results": [...]
}
  • page: 페이지 번호 (기본: 1)
  • page_size: 페이지당 항목 수 (기본: 20, 최대: 100)

기타 엔드포인트​

MethodURL설명
GET/health/ALB 헬스체크
GET/api/app/앱 설정 (최소 버전 등)
GET/.well-known/apple-app-site-associationApple Universal Links 설정
GET/privacy-policy/개인정보처리방침