# 런모아 API 문서 전체 요약 이 파일은 AI 도구가 런모아 API 문서를 쉽게 읽도록 만든 한국어 요약입니다. 기준 도메인은 `https://developers.runmoa.com`입니다. ## API 표면 런모아 API 문서는 두 표면으로 나뉩니다. 1. 스토어프론트 API - Base URL: `https://{site_host}/api/storefront/v1` - 헤더: `X-Runmoa-Site-Key: moa_pub_xxxxxxxxx` - 사용자 API 추가 헤더: `Authorization: Bearer USER_LOGIN_TOKEN` - 사용 위치: 브라우저, Cloudflare Pages, 정적 HTML/React 앱 - 기능: 사이트 정보, 상품/콘텐츠/카테고리/태그 조회, 로그인, 장바구니, 주문, 결제 초기화, 마이페이지, 게시판 2. 서버용 비공개 API - Base URL: `https://{site_host}/api/public/v1` - 헤더: `Authorization: Bearer {SERVER_PRIVATE_API_KEY}` - 사용 위치: 판매자 서버, 서버리스 함수, 직접 curl - 기능: 상품/콘텐츠 생성과 수정, 카테고리 조회, 태그 연결 - 브라우저에 노출하면 안 됨 ## 빠른 시작 정적 프론트엔드는 `API_BASE = https://your-site.runmoa.com/api/storefront/v1`와 `STOREFRONT_KEY = moa_pub_xxxxxxxxx`를 준비한다. 사이트 정보는 `GET /site`로 조회한다. 상품 목록은 `GET /products`, 콘텐츠 목록은 `GET /contents`로 조회한다. 모든 요청에는 `X-Runmoa-Site-Key`와 `Accept: application/json`을 보낸다. Schoolmoa 로그인은 `GET /auth/schoolmoa-client`로 `scid`를 가져온 뒤 `https://www.runmoa.com/login/?redirect_uri=...&client_id=...&lg=kr`로 이동한다. Callback 페이지는 받은 `code`를 `POST /auth/schoolmoa/callback`으로 보내고 응답의 `token`을 저장한다. 로그인 후 `GET /me`, `GET /cart`, `POST /orders` 같은 사용자 API는 `Authorization: Bearer USER_LOGIN_TOKEN`을 함께 보낸다. 결제는 `POST /payments/initialize`로 시작한다. 외부 정적 프론트엔드는 PG별 내부 결제 경로를 직접 호출하지 않는다. ## 스토어프론트 API 엔드포인트 사이트/페이지: - `GET /site`: 사이트 기본 정보 - `GET /site-meta/{key}`: 사이트 메타 값 - `GET /pages/home`: 홈 페이지 데이터 - `GET /pages`: 페이지 목록 - `GET /pages/{slug}`: 페이지 상세 - `GET /menus`: 메뉴 목록 - `GET /popups`: 활성 팝업 로그인: - `GET /auth/schoolmoa-client`: Schoolmoa client id 조회 - `POST /auth/schoolmoa/callback`: Schoolmoa callback 처리, 사용자 token 반환 - `POST /auth/logout`: 로그아웃. 사용자 토큰 필수 상품/콘텐츠 조회: - `GET /product-categories`: 상품에서 사용 중인 카테고리 조회 - `GET /product-categories/search`: 상품 카테고리 검색. query: `query`, `lang` - `GET /product-tags`: 노출 상품에서 사용 중인 태그 조회. query: `item_ids` - `GET /products`: 상품 목록. query: `page`, `limit`, `search`, `category_id`, `category_ids`, `tag_id`, `tag_ids` - `GET /products/{productId}`: 상품 상세 - `GET /content-categories`: 콘텐츠에서 사용 중인 카테고리 조회 - `GET /content-categories/search`: 콘텐츠 카테고리 검색. query: `query`, `lang` - `GET /content-tags`: 노출 콘텐츠에서 사용 중인 태그 조회. query: `item_ids` - `GET /contents`: 콘텐츠 목록. query: `page`, `limit`, `search`, `content_type`, `category_id`, `category_ids`, `tag_id`, `tag_ids` - `GET /contents/{contentId}`: 콘텐츠 상세 - `GET /contents/{contentId}/summary`: 콘텐츠 요약 - `GET /contents/{contentId}/description`: 콘텐츠 설명 - `POST /contents/bulk`: 여러 콘텐츠 조회 - `POST /contents/cart-preview`: 장바구니용 콘텐츠 미리보기 - `GET /membership/status`: 사이트 멤버십 활성 상태 - `GET /reviews/contents/{contentId}`: 콘텐츠 리뷰 목록 - `GET /reviews/pinned/{type}/{itemId}`: 고정 리뷰 - `GET /reviews/recent`: 최근 리뷰 사용자 기준 상품/콘텐츠: - `GET /contents/{contentId}/visibility`: 내 콘텐츠 접근 여부 - `GET /products/{productId}/visibility`: 내 상품 접근 여부 - `GET /me/contents`: 내 기준 콘텐츠 목록 - `GET /me/products`: 내 기준 상품 목록 - `GET /me/contents/{contentId}`: 내 기준 콘텐츠 상세 - `GET /me/products/{productId}`: 내 기준 상품 상세 - `GET /me/products/{productId}/summary`: 내 기준 상품 요약 - `GET /me/products/{productId}/description`: 내 기준 상품 설명 - `POST /me/owned-contents/check`: 보유 콘텐츠 확인 장바구니: - `GET /guest-cart`, `POST /guest-cart`, `PUT /guest-cart/quantity`, `DELETE /guest-cart/{itemId}`, `DELETE /guest-cart` - `GET /cart`, `POST /cart`, `PUT /cart/quantity`, `DELETE /cart/{itemId}`, `DELETE /cart` - `POST /cart/merge-guest`: 게스트 장바구니를 로그인 장바구니로 병합 주문/결제: - `GET /checkout/metadata`: 결제 화면 메타데이터 - `POST /orders`: 주문 생성 - `DELETE /orders/{orderId}`: 주문 삭제 - `GET /orders/check`: 주문 상태 확인 - `GET /orders/paid-products`: 결제된 상품 조회 - `POST /orders/validate-pcc-number`: 개인통관고유부호 검증 - `POST /payments/initialize`: 결제 초기화 마이페이지: - `GET /me`, `POST /me/timezone`, `GET /me/access-context`, `GET /me/plan-change-url` - `POST /me/meta`, `GET /me/meta/{metaKey}`, `PUT /me/meta/{userId}` - `POST /me/point-cash`, `GET /me/favorites`, `DELETE /me` - `GET /me/shipping-addresses`, `POST /me/shipping-addresses`, `POST /me/shipping-addresses/update`, `POST /me/shipping-addresses/set-main`, `DELETE /me/shipping-addresses` - `GET /me/orders`, `GET /me/orders/{orderId}`, `GET /me/orders/{orderId}/details`, `GET /me/orders/{orderId}/tracking`, `GET /me/orders/{orderId}/virtual-account` - `GET /me/content-counts/{type}`, `GET /me/contents/{type}/{status}`, `GET /me/content-items/{contentId}`, `GET /me/content-items/{contentId}/progress` - `POST /me/content-items/hold/start`, `POST /me/content-items/hold/stop` - `GET /me/curriculums/{status}`, `POST /me/curriculums/digital-download-info`, `POST /me/curriculums/digital-download-url` - `GET /billing/cards/has-cards`, `GET /billing/cards`, `POST /billing/cards`, `DELETE /billing/cards/{cardId}`, `PATCH /billing/cards/{cardId}/set-default` - `POST /membership/change-request`, `POST /membership/subscription-payment`, `GET /membership/me`, `POST /membership/expire-request`, `GET /membership/me/name`, `GET /membership/contents/{contentId}/access` 쿠폰: - `GET /coupons/claimable` - `GET /coupons/my` - `POST /coupons/{campaign}/claim` - `POST /coupons/validate` 게시판: - `GET /boards`, `GET /boards/{boardId}` - `GET /posts`, `GET /posts/product-info`, `GET /posts/{postId}`, `GET /posts/{postId}/attachments/{fileId}`, `GET /posts/{postId}/comments` - `POST /posts`, `GET /posts/{postId}/edit`, `PUT /posts/{postId}`, `DELETE /posts/{postId}` - `POST /comments`, `PUT /comments/{commentId}`, `DELETE /comments/{commentId}` - `POST /posts/images`, `POST /posts/attachments`, `DELETE /posts/attachments/{fileId}` ## 서버용 비공개 API 엔드포인트 서버용 비공개 API는 브라우저에서 호출하지 않는다. 상품: - `GET /api/public/v1/products`: 상품 목록. query: `page`, `limit`, `status`, `category_id`, `category_ids`, `tag_id`, `tag_ids`, `search` - `GET /api/public/v1/products/{productId}`: 상품 상세. query: `language` - `POST /api/public/v1/products`: 상품 생성. 필수: `title`, `category_id`, `featured_image` - `PUT /api/public/v1/products/{productId}`: 상품 수정. 전달한 필드만 업데이트 상품 생성/수정 주요 필드: - `title`, `description_html`, `category_id`, `status`, `base_price`, `sale_price`, `is_on_sale`, `is_free` - `requires_shipping`, `is_shipping_free`, `shipping_price`, `is_over_50000_free`, `is_extra_shipping_fee`, `is_purchase_agency` - `tax_type`, `options`, `variants`, `images`, `connected_membership_ids`, `related_product_ids`, `tag_ids` 콘텐츠: - `GET /api/public/v1/contents`: 콘텐츠 목록. query: `language`, `page`, `limit`, `status`, `content_type`, `category_id`, `category_ids`, `tag_id`, `tag_ids`, `search` - `GET /api/public/v1/contents/{contentId}`: 콘텐츠 상세. query: `language` - `POST /api/public/v1/contents`: 콘텐츠 생성 - `PUT /api/public/v1/contents/{contentId}`: 콘텐츠 수정. 전달한 필드만 업데이트 콘텐츠 생성 필수 필드: - `content_type`: `vod`, `live`, `offline`, `digital_content` - `title` - `description_html` - `category_ids` - `featured_image` - `tag_ids` 선택. 현재 콘텐츠당 1개까지 선택 가능 콘텐츠 수정 주의: - `content_type` 변경은 지원하지 않는다. - 대상 콘텐츠의 현재 유형 기준으로 검증한다. - `featured_image`, `images`, `category_ids`, `tag_ids`, `connected_membership_ids`, `options`를 보내면 해당 구조가 교체 또는 동기화된다. - VOD에서 `chapters`를 보내면 챕터/아이템 구조가 동기화된다. 카테고리: - `GET /api/public/v1/product-categories`: 상품 카테고리 전체 조회. query: `lang` - `GET /api/public/v1/product-categories/search`: 상품 카테고리 검색. query: `query`, `lang` - `GET /api/public/v1/content-categories`: 콘텐츠 카테고리 전체 조회. query: `lang` - `GET /api/public/v1/content-categories/search`: 콘텐츠 카테고리 검색. query: `query`, `lang` - 같은 카테고리 조회/검색 경로는 `/api/storefront/v1`에서도 `X-Runmoa-Site-Key`로 사용할 수 있다. 태그: - `GET /api/storefront/v1/product-tags`: 노출 상품에서 사용 중인 상품 태그 조회 - `GET /api/storefront/v1/content-tags`: 노출 콘텐츠에서 사용 중인 콘텐츠 태그 조회 - 상품/콘텐츠 생성과 수정에서 `tag_ids`를 보내면 태그 연결이 동기화된다. 현재 항목당 1개까지 선택 가능하다. ## 보안 규칙 - `moa_pub_...` 스토어프론트 키는 브라우저에 둘 수 있지만 관리자 작업에는 사용할 수 없다. - 서버용 비공개 API 키는 브라우저에 넣지 않는다. - 정적 프론트엔드에서 상품/콘텐츠 생성 또는 수정이 필요하면 판매자 서버나 서버리스 함수가 서버용 키를 보관하고 런모아 API를 대신 호출한다. - 외부 문서에서는 내부 라우트명, deprecated 로그인 경로, PG별 내부 결제 경로를 기본 예시로 노출하지 않는다. ## 배포 문서 프레임워크는 Starlight이다. Cloudflare Pages 설정은 root directory `storefront-api-docs`, build command `npm ci && npm run build`, output directory `dist`이다. 권장 도메인은 `developers.runmoa.com`이다.