본문으로 건너뛰기

Penta API Quick Reference Guide

Authentication Flow​

1. Register New User​

POST /api/users/register/
{
  "email": "user@example.com",
  "password": "SecurePass123!",
  "password_confirm": "SecurePass123!",
  "nickname": "User123",
  "birthdate": "2010-01-01",
  "country": "KR",
  "language": "ko"
}

2. Login​

POST /api/users/login/
{
  "email": "user@example.com",
  "password": "SecurePass123!"
}
# Returns: { "access": "...", "refresh": "..." }

3. Refresh Token​

POST /api/users/token/refresh/
{
  "refresh": "your_refresh_token"
}
# Returns: { "access": "...", "refresh": "..." }

4. Use Access Token​

Authorization: Bearer your_access_token

Quick Endpoint Reference​

User Management​

MethodEndpointDescriptionAuth
POST/api/users/register/Register new userNo
POST/api/users/login/User loginNo
POST/api/users/token/refresh/Refresh JWT tokenNo
GET/api/users/profile/Get user profileYes
PATCH/api/users/profile/Update profileYes
POST/api/users/devices/Register deviceYes

Books & Reading​

MethodEndpointDescriptionAuth
GET/api/books/List all booksNo
GET/api/books/{id}/Get book details with episodes, stickers, and all metadataNo
GET/api/books/{book_id}/episodes/{id}/Get episode content with pagesYes*
POST/api/books/reading-progress/Update reading progressYes
GET/api/books/reading-history/Get reading historyYes
GET/api/books/bookmarks/List bookmarksYes
POST/api/books/bookmarks/Add bookmarkYes
DELETE/api/books/bookmarks/{book_id}/Remove bookmarkYes

*Authentication required for premium episodes only

Categories & Tags​

MethodEndpointDescriptionAuth
GET/api/books/categories/List categoriesNo
GET/api/books/tags/List tagsNo
GET/api/series/List seriesNo

Home & Discovery​

MethodEndpointDescriptionAuth
GET/api/home/Get homepage dataYes
GET/api/rankings/Get book rankingsYes
GET/api/search/Global searchYes

Events​

MethodEndpointDescriptionAuth
GET/api/events-news/List active eventsNo
GET/api/events-news/{id}/Event detailsNo
POST/api/events-news/participate/Join eventYes

Stickers​

MethodEndpointDescriptionAuth
GET/api/stickers/User's sticker collectionYes
GET/api/stickers/stats/Sticker collection statsYes
GET/api/stickers/popular/Popular stickersYes
GET/api/stickers/missing/Missing stickersYes
GET/api/stickers/upcoming/Upcoming stickersYes
POST/api/stickers/earn/{episode_id}/Earn stickerYes

Notifications​

MethodEndpointDescriptionAuth
GET/api/notifications/List notificationsYes
PATCH/api/notifications/{id}/read/Mark as readYes

Payments​

MethodEndpointDescriptionAuth
GET/api/subscriptions/plans/List plansNo
POST/api/subscriptions/Create subscriptionYes
GET/api/payments/history/Payment historyYes
POST/api/promo-codes/apply/Apply promo codeYes

Statistics​

MethodEndpointDescriptionAuth
GET/api/stats/reading/User reading statsYes
GET/api/books/{id}/stats/Book statisticsYes

System​

MethodEndpointDescriptionAuth
GET/api/health/System health checkNo

Common Query Parameters​

Language Selection​

?lang=ko  # Korean (default)
?lang=en  # English
?lang=ja  # Japanese
?lang=es  # Spanish

Pagination​

?page=1&page_size=20

Filtering​

?category=1
?series=2
?tag=adventure
?is_free=true
?status=active

Sorting​

?ordering=created_at    # Ascending
?ordering=-created_at   # Descending
?ordering=popularity
?ordering=rating

Common Use Cases​

1. New User Onboarding​

# Step 1: Register
POST /api/users/register/

# Step 2: Login
POST /api/users/login/

# Step 3: Get categories
GET /api/books/categories/?lang=ko

# Step 4: Browse books
GET /api/books/?category=1&lang=ko

# Step 5: Start reading
GET /api/episodes/1/?lang=ko

2. Reading a Book​

# Step 1: Get book details (includes sticker_urls array)
GET /api/books/1/?lang=ko

# Step 2: Bookmark it
POST /api/bookmarks/
{ "book": 1 }

# Step 3: Read episode
GET /api/episodes/1/?lang=ko

# Step 4: Track progress
POST /api/reading-history/
{
  "episode": 1,
  "progress": 50,
  "reading_time": 300
}

# Step 5: Complete & earn sticker
POST /api/stickers/earn/
{
  "episode": 1,
  "reading_time": 600
}

3. Subscription Flow​

# Step 1: Check plans
GET /api/subscriptions/plans/  # Not implemented yet

# Step 2: Apply promo code
POST /api/promo-codes/apply/
{ "code": "NEWYEAR2025" }

# Step 3: Subscribe
POST /api/subscriptions/
{
  "plan": 1,
  "payment_method": "card",
  "promo_code": "NEWYEAR2025"
}

4. Homepage Experience​

# Step 1: Load homepage
GET /api/home/?lang=ko

# Step 2: Check rankings
GET /api/rankings/?period=daily

# Step 3: Check events
GET /api/events-news/?status=active

# Step 4: Check notifications
GET /api/notifications/

5. Search & Discovery​

# Global search
GET /api/search/?q=모험&lang=ko

# Category browsing
GET /api/books/?category=1&ordering=-created_at

# Tag filtering
GET /api/books/?tag=adventure&is_free=true

# Series collection
GET /api/books/?series=1&ordering=episode_number

Error Handling Quick Reference​

Common Error Responses​

// 401 Unauthorized
{
  "error": {
    "code": "AUTHENTICATION_FAILED",
    "message": "인증에 실패했습니다"
  }
}

// 400 Bad Request
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "입력값이 올바르지 않습니다",
    "details": {
      "email": ["이미 사용중인 이메일입니다"]
    }
  }
}

// 403 Forbidden
{
  "error": {
    "code": "SUBSCRIPTION_REQUIRED",
    "message": "구독이 필요한 콘텐츠입니다"
  }
}

Testing Credentials​

Test Users​

  • Regular: testuser@example.com / testpassword123
  • Admin: admin@example.com / admin123

Test Payment Cards​

  • Success: 4242-4242-4242-4242
  • Decline: 4000-0000-0000-0002

Development Tools​

Rate Limits​

  • Anonymous: 100 req/hour
  • Authenticated: 1000 req/hour
  • Premium: 5000 req/hour

Quick Tips​

  1. Always include language parameter for consistent responses
  2. Use pagination for list endpoints to improve performance
  3. Handle token refresh proactively before expiration
  4. Cache category/tag lists as they change infrequently
  5. Batch API calls when possible to reduce requests
  6. Monitor rate limit headers to avoid service disruption

Response Headers​

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1673784000
Content-Language: ko

Need Help?​