`는 사용자 토큰입니다. 이 토큰은 사용자를 식별하고 개인화된 데이터에 대한 액세스를 제공합니다. 또는 [결제 UI를 여는 토큰](/ko/api/pay-station/token/create-token)을 사용할 수 있습니다.\n\n2. **Simplified mode without Authorization header.** 이 모드는 미인증 사용자만 사용하며, [게임 키 판매](/ko/doc/buy-button/how-to/set-up-authentication/#guides_buy_button_selling_items_not_authenticated_users)에만 적용할 수 있습니다. 토큰 대신 요청에 다음 헤더를 포함해야 합니다.\n - 요청 ID와 `x-unauthorized-id`\n - Base64로 인코딩된 사용자의 이메일 주소와 `x-user`\n\n## 유용한 링크\n\n- [상호작용 모델별 API 호출](https://developers.xsolla.com/ko/api/catalog/)\n- [엔드포인트 유형](https://developers.xsolla.com/ko/api/catalog/)\n- [오류 처리](https://developers.xsolla.com/ko/api/catalog/)\n- [API 키](https://developers.xsolla.com/ko/api/catalog/)\n\n# 핵심 엔티티 구조\n\n모든 유형의 아이템(가상 아이템, 번들, 인게임 재화, 키)은 유사한 데이터 구조를 사용합니다. 기본 구조를 이해하면 API 작업이 간소화되고 문서를 더 쉽게 탐색할 수 있습니다.\n\n참고
일부 호출에는 추가 입력란이 포함될 수 있지만 기본 구조는 변경되지 않습니다.
\n\n**식별**\n\n- `merchant_id`- [관리자 페이지](https://publisher.xsolla.com/)의 회사 ID\n- `project_id` - 관리자 페이지의 프로젝트 ID\n- `sku` - 프로젝트 내의 고유한 아이템 SKU\n\n**Store display**\n\n- `name` - 아이템 이름\n- `description` - 아이템 설명\n- `image_url` - 이미지 URL\n- `is_enabled` - 아이템 가용성\n- `is_show_in_store` - 카탈로그에 아이템이 표시되는지 여부\n\n카탈로그에서 아이템 가용성 관리에 대한 자세한 정보는 [문서](/ko/items-catalog/catalog-features/items-availability/)를 참조하세요.\n\n**Organization**\n\n- `type` - 아이템 유형, 예를 들어 가상 아이템(`virtual_item`) 또는 번들(`bundle`)\n- `groups` - 아이템이 속한 그룹\n- `order` - 카탈로그 내 디스플레이 순서\n\n**판매 조건**\n\n- `prices` - 실제 화폐 또는 인게임 재화로 된 가격\n- `limits` - 구매 한도\n- `periods` - 가용 기간\n- `regions` - 지역 제한\n\n**핵심 엔티티 구조 예시:**\n\n```json\n{\n \"attributes\": [],\n \"bundle_type\": \"virtual_currency_package\",\n \"content\": [\n {\n \"description\": {\n \"en\": \"Main in-game currency\"\n },\n \"image_url\": \"https://.../image.png\",\n \"name\": {\n \"en\": \"Crystals\",\n \"de\": \"Kristalle\"\n },\n \"quantity\": 500,\n \"sku\": \"com.xsolla.crystal_2\",\n \"type\": \"virtual_currency\"\n }\n ],\n \"description\": {\n \"en\": \"Crystals x500\"\n },\n \"groups\": [],\n \"image_url\": \"https://.../image.png\",\n \"is_enabled\": true,\n \"is_free\": false,\n \"is_show_in_store\": true,\n \"limits\": {\n \"per_item\": null,\n \"per_user\": null,\n \"recurrent_schedule\": null\n },\n \"long_description\": null,\n \"media_list\": [],\n \"name\": {\n \"en\": \"Medium crystal pack\"\n },\n \"order\": 1,\n \"periods\": [\n {\n \"date_from\": null,\n \"date_until\": \"2020-08-11T20:00:00+03:00\"\n }\n ],\n \"prices\": [\n {\n \"amount\": 20,\n \"country_iso\": \"US\",\n \"currency\": \"USD\",\n \"is_default\": true,\n \"is_enabled\": true\n }\n ],\n \"regions\": [],\n \"sku\": \"com.xsolla.crystal_pack_2\",\n \"type\": \"bundle\",\n \"vc_prices\": []\n}\n```\n\n# 기본 구매 흐름\n\n엑솔라 API를 사용하면 아이템 카탈로그 검색, 장바구니 관리, 주문 생성 및 상태 추적을 포함한 인게임 스토어 로직을 구현할 수 있습니다. 통합 시나리오에 따라 API 호출은 **Admin**와 **Catalog** 하위 섹션으로 구분되며, 서로 다른 [인증 방식](/ko/api/catalog/section/authentication)을 사용합니다.\n\n다음 예시는 아이템 생성부터 구매까지 스토어 설정 및 운영을 위한 기본 흐름을 보여줍니다.\n\n## 아이템 및 그룹 생성(관리자)\n\n가상 아이템, 번들, 인게임 재화와 같은 스토어의 아이템 카탈로그를 생성합니다.\n\n예시 API 호출:\n- [가상 아이템 생성](/ko/api/catalog/virtual-items-currency-admin/admin-create-virtual-item)\n- [번들 생성](/ko/api/catalog/bundles-admin/admin-create-bundle)\n- [인게임 재화 생성](/ko/api/catalog/virtual-items-currency-admin/admin-create-virtual-currency)\n\n## 프로모션, 체인 및 한도 설정(관리자)\n\n할인, 보너스, 일일 보상 또는 혜택 체인과 같은 사용자 획득 및 수익화 도구를 구성합니다.\n\n예시 API 호출:\n- [보너스 프로모션 생성](/ko/api/liveops/promotions-bonuses/create-bonus-promotion)\n- [일일 보상 생성](/ko/api/liveops/daily-chain-admin/admin-create-daily-chain)\n- [고유 카탈로그 혜택 프로모션 생성](/ko/api/liveops/promotions-unique-catalog-offers/admin-create-unique-catalog-offer)\n\n## 아이템 정보 가져오기(클라이언트)\n\n애플리케이션에서 아이템 디스플레이를 구성합니다.\n\n\n
알림\n 사용자 카탈로그를 구축하는 데 관리자 하위 섹션의 API 호출을 사용하지 마십시오. 이러한 API 호출에는
속도 제한이 있으며 사용자 트래픽을 위한 것이 아닙니다.\n
\n\nAPI 호출 예시:\n- [가상 아이템 목록 가져오기](/ko/api/catalog/virtual-items-currency-catalog/get-virtual-items)\n- [아이템 그룹 목록 가져오기](/ko/api/catalog/virtual-items-currency-catalog/get-item-groups)\n- [번들 목록 가져오기](/ko/api/catalog/bundles-catalog/get-bundle-list)\n- [판매 가능한 아이템 목록 가져오기](/ko/api/catalog/common-catalog/get-sellable-items)\n\n\n 참고
\n 기본적으로 카탈로그 API 호출은 요청 시점에 스토어에서 현재 사용 가능한 아이템을 반환합니다. 아직 사용 가능하지 않거나 더 이상 사용 가능하지 않은 아이템을 검색하려면 카탈로그 요청에 \"show_inactive_time_limited_items\": 1 매개 변수를 포함하십시오.\n
\n\n## 아이템 판매\n\n다음 방법을 사용하여 아이템을 판매할 수 있습니다:\n- 빠른 구매 - 하나의 SKU를 여러 번 판매합니다.\n- 장바구니 구매 - 사용자가 장바구니에 아이템을 추가하고, 제거하고, 수량을 업데이트합니다.\n\n아이템이 실제 돈 대신 인게임 재화로 구매된 경우, [인게임 재화로 구매한 특정 아이템으로 주문 생성](/ko/api/catalog/virtual-payment/create-order-with-item-for-virtual-currency) API 호출을 사용하십시오. 결제 UI는 필요하지 않으며, API 호출이 실행될 때 청구가 처리됩니다.\n\n무료 아이템 구매의 경우, [특정 무료 아이템으로 주문 생성](/ko/api/catalog/free-item/create-free-order-with-item) API 호출 또는 [무료 장바구니로 주문 생성](/ko/api/catalog/free-item/create-free-order) API 호출을 사용하십시오. 결제 UI는 필요하지 않으며, 주문은 즉시 done 상태로 설정됩니다.\n\n### 빠른 구매\n\n클라이언트 측 API 호출을 사용하여 [특정 아이템으로 주문 생성](/ko/api/catalog/payment-client-side/create-order-with-item)을 수행합니다. 호출은 결제 UI를 열기 위한 토큰을 반환합니다.\n\n\n 참고
\n 할인 정보는 결제 UI에서만 사용자에게 제공됩니다. 프로모션 코드는 지원되지 않습니다.\n
\n\n### 장바구니 구매\n\n장바구니 설정 및 구매는 클라이언트 또는 서버 측에서 수행할 수 있습니다.\n\n**클라이언트에서 장바구니 설정 및 구매**\n\n아이템 추가 및 제거 로직을 직접 구현하십시오. 장바구니 설정을 위한 API 호출 전에는 구매에 적용될 프로모션에 대한 정보를 알 수 없습니다. 이는 총 비용과 추가 보너스 아이템의 세부 사항을 알 수 없음을 의미합니다.\n\n다음 장바구니 로직을 구현하십시오:\n1. 플레이어가 장바구니를 채운 후, [아이템으로 장바구니 채우기](/ko/api/shop-builder/operation/cart-fill/) API 호출을 사용하십시오. 호출은 선택한 아이템에 대한 현재 정보를 반환합니다 (할인 전후 가격, 보너스 아이템).\n2. 사용자 작업에 따라 장바구니 내용을 업데이트하십시오:\n - 아이템을 추가하거나 아이템 수량을 변경하려면 [장바구니 ID로 장바구니 아이템 업데이트](/ko/api/shop-builder/operation/put-item-by-cart-id/) API 호출을 사용하십시오.\n - 아이템을 제거하려면 [장바구니 ID로 장바구니 아이템 삭제](/ko/api/shop-builder/operation/delete-item-by-cart-id/) API 호출을 사용하십시오.\n\n\n 참고
\n 현재 장바구니 상태를 얻으려면 현재 사용자의 장바구니 가져오기 API 호출을 사용하십시오.\n
\n\n3. [현재 장바구니의 모든 아이템으로 주문 생성](/ko/api/shop-builder/operation/create-order/) API 호출을 사용하십시오. 호출은 주문 ID와 결제 토큰을 반환합니다. 새로 생성된 주문은 기본적으로 new 상태로 설정됩니다.\n\n**서버에서 장바구니 설정 및 구매**\n\n이 설정 옵션은 장바구니 설정에 더 많은 시간이 걸릴 수 있습니다. 장바구니의 각 변경 사항은 API 호출을 동반해야 하기 때문입니다.\n\n다음 장바구니 로직을 구현하십시오:\n1. 플레이어가 장바구니를 채운 후, [아이템으로 장바구니 채우기](/ko/api/catalog/cart-server-side) API 호출을 사용하십시오. 호출은 선택한 아이템에 대한 현재 정보를 반환합니다(할인 전후 가격, 보너스 아이템).\n2. [현재 장바구니의 모든 아이템으로 주문 생성](/ko/api/shop-builder/operation/create-order/) API 호출을 사용하십시오. 호출은 주문 ID와 결제 토큰을 반환합니다. 새로 생성된 주문은 기본적으로 new 상태로 설정됩니다.\n\n## 결제 UI 열기\n\n반환된 토큰을 사용하여 새 창에서 결제 UI를 엽니다. 결제 UI를 여는 다른 방법은 [문서](/ko/payment-ui-and-flow/payment-ui/how-to-open-payment-ui/#open_payment_ui)에 설명되어 있습니다.\n\n| 작업 | 엔드포인트 |\n|:--------------------------------|:--------------------------------------------------------------------------|\n| 프로덕션 환경에서 열기. | https://secure.xsolla.com/paystation4/?token={token} |\n| 샌드박스 모드에서 열기. | https://sandbox-secure.xsolla.com/paystation4/?token={token} |\n\n\n
참고\n 개발 및 테스트 중에는 샌드박스 모드를 사용하세요. 테스트 구매는 실제 계정에 청구되지 않습니다.
테스트 은행 카드를 사용할 수 있습니다.\n\n 첫 번째 실제 결제가 이루어진 후에는 엄격한 샌드박스 결제 정책이 적용됩니다. 샌드박스 모드에서의 결제는 [관리자 페이지 > 회사 설정 > 사용자](https://publisher.xsolla.com/0/settings/users)에 지정된 사용자에게만 가능합니다.\n\n 실제 통화로 인게임 재화와 아이템을 구매하려면 엑솔라와의 라이선스 계약을 체결해야 합니다. 이를 위해 [관리자 페이지](https://publisher.xsolla.com/)에서 **Agreements & Taxes > Agreements**으로 이동하여 계약 양식을 작성하고 확인을 기다리세요. 계약 검토에는 최대 3영업일이 소요될 수 있습니다.\n