개요

엑솔라 API 포함 사항:

• Pay Station API - 결제 UI 및 직접 결제 방식.
• IGS API - 인게임 스토어 모듈 작동 방식.
• Subscriptions API - 정기 결제 방식.
• Login API - 자체 인터페이스를 사용하여 사용자 인증 방식(통합 가이드 보기).

HTTP 인증 및 HTTP 동사(verb) 등 상용 HTTP 클라이언트가 이해할 수 있는 기본 HTTP 기능을 사용하며, 교차 원본(cross-origin) 리소스 공유를 지원하여 개발자가 클라이언트측 웹 애플리케이션에서 API 와 보안된 상호작용을 할 수 있도록 했습니다.

• https://api.xsolla.com - Pay Station API, Subscriptions API
• https://login.xsolla.com/api - Login API
• https://store.xsolla.com/api - IGS API

요청 및 응답

• HTTPS를 통해 전송해야 하며
• TLS 1.2 이상을 사용해야 하고
• 인증 매개변수를 포함해야 하며
• PUT과 POST 요청에 대해추가 헤더(Content-Type: application/json)를 포함해야 합니다.

Authorization: Basic <your_authorization_basic_key>
Content-Type: application/json

기본적으로 모든 요청은 본문에 있는 JSON으로 데이터를 제공하며 헤더에 Content-Type: application/json를 포함합니다.

API 변경사항

• 엑솔라는 새로운 API 자원을 추가할 수 있습니다.
• 엑솔라는 선택적 요청 매개변수를 추가할 수 있습니다.
• 엑솔라는 기존 API 응답에 대한 새로운 속성을 추가할 수 있습니다.
• 엑솔라는 나열된 값들의 묶음들로 이루어진 기존 매개변수에 새 값들을 추가할 수 있습니다.
• 엑솔라는 JSON에 새 webhook 타입들과 매개변수들을 추가할 수 있습니다.
• 엑솔라는 선택적 HTTP 요청 헤더를 추가할 수 있습니다.
• 엑솔라는 유효한 매개변수에 유효하지 않은 매개변수 값이 포함된 요청을 거부할 수 있습니다.
• 지나치게 관대한 파싱으로 인해 승인된 부적절한 형식의 요청들은 파싱로직이 올바르다면 거부될 수도 있습니다.
• 엑솔라는 언제든지 문서화되지 않은 기능을 추가, 변경 또는 제거할 수 있습니다.

버전 관리

인증

• 기본 액세스 인증 유형을 사용합니다. API에 전송된 이러한 요청에는 Authorization: Basic <your_authorization_basic_key< 헤더가 포함되어야 하며 여기에서, <your_authorization_basic_key>는 Base64 표준에 따라 부호화된 판매자 ID:API 키 쌍입니다. 이러한 매개 변수를 찾으려면 관리자 페이지로 이동하십시오:
  • 판매자 ID가 다음에 표시됩니다:
    • 회사 설정 > 회사 섹션.
    • 관리자 페이지의 브라우저 주소 표시줄에 있는 URL. URL 형식은 다음과 같습니다: https:​//publisher.xsolla.com/<merchant ID>/<Publisher Account section>. 생성한 경우에만 관리자 페이지에
  • API 키가 표시되며 이를 직접 보관해 두어야 합니다. 다음 섹션에서 새로운 키를 생성할 수 있습니다:
    • 회사 설정 > API 키
    • 프로젝트 설정 > API 키
• 사용자 JWT를 사용하여 인증. API에 전송된 이러한 요청에는 Authorization: Bearer <user_JWT> 헤더가 포함되어야 하며 여기에서, <user_JWT>는 사용자 토큰입니다.
• 서버 JWT를 사용하여 인증. 해당 API 메서드에는 X-SERVER-AUTHORIZATION: <server_JWT> 헤더가 포함되어야 하며 여기에서, <server_JWT>는 서버 토큰입니다.
• 인증 없음.

상호 작용 모델별 API 호출

• 클라이언트 측 API 호출 — 파트너 애플리케이션의 클라이언트 부분과 엑솔라 서버 간의 상호 작용을 위한 API 호출입니다. 클라이언트에서 사용자가 작업을 수행할 경우 이러한 API 호출 요청이 시작됩니다. 클라이언트 측 API 호출의 예: 아이템 목록 입수, 사용자 인증, 클라이언트에서 결제 토큰 획득.
• 서버 측 API 호출 - 파트너의 서버와 엑솔라 서버 간의 상호 작용을 위한 API 호출로, 다음 작업을 위한 것입니다:
  • 사용자 플로우 구현.
    클라이언트에서 사용자가 작업을 수행할 경우 파트너의 클라이언트 측 API 호출이 트리거되고, 엑솔라 서버 측 API 호출은 파트너의 서버에서 호출됩니다. 사용자 플로우 구현을 위한 서버 API 호출 예시: 서버에서 사용자 속성 업데이트, 서버에서 결제 토큰 획득.
  • 파트너의 관리 작업 또는 엑솔라 제품 설정.
    클라이언트에서 사용자가 작업을 수행할 경우 이러한 메서드 호출을 시작할 수 없습니다. 관리자 서버 API 호출의 예: 아이템 또는 프로모션 생성 및 편집.

• 속도 제한:
  • 서버 측 API 호출에 대한 속도 제한은 클라이언트 측 API 호출보다 더 엄격합니다.
  • 관리자 서버 측 API 호출에 대한 속도 제한은 사용자 플로우 구현 API 호출보다 더 엄격합니다.
• 응답으로 관련 없는 정보 수신. 예를 들어, 카탈로그를 구축하기 위해 목록을 입수하는 클라이언트 측 API 호출 외에 관리자 아이템 목록을 입수하는 서버 측 API 호출을 사용하는 경우입니다.
• 사용자에 의한 무단 데이터 변경. 예를 들어, 서버 측 API 호출 대신 클라이언트 측 API 호출을 사용하여 속성을 업데이트하는 경우입니다.
• 결제 인터페이결제 인터페이스에서의 국가 및 통화 잘못 결정.

인증 체계에 따라 API 호출이 클라이언트 측인지 서버 측인지 확인할 수 있습니다:

• 클라이언트 측 — 인증을 제외하거나 Authorization header: Bearer <user_JWT> 헤더를 포함한 상태로 호출됩니다. 여기에서 <user_JWT>는 사용자 토큰입니다.
• 사용자 플로우 구현을 위한 서버 측 API 호출은
  • X-SERVER-AUTHORIZATION: <server_JWT>헤더를 포함한 상태로 호출됩니다. 여기에서 <server_JWT>는 서버 토큰입니다.
  • Authorization: Basic <your_authorization_basic_key>로 호출됩니다. 여기에서 <your_authorization_basic_key> — project_id:api_key 쌍은 Base64 표준에 따라 부호화됩니다.
• 관리 작업을 위한 서버 측 API 호출은 Authorization: Basic <your_authorization_basic_key> 헤더를 포함한 상태로 호출됩니다. 여기에서, <your_authorization_basic_key> — project_id:api_key 쌍은 Base64 표준에 따라 부호화됩니다.

서버 측 인증을 사용한 서버 측 API 호출의 예:

클라이언트 측 인증을 사용한 클라이언트 측 API 호출의 예:

요구 사항에 따라 사용자 플로우를 구현할 때 통합을 설정하는 방법을 서버 측 또는 클라이언트 측 API 호출로 선택할 수 있습니다. 사용자 플로우를 구현하는 데 서버 관리 API 호출을 사용해서는 안 됩니다.

클라이언트 측 API 호출을 사용한 사용자 플로우 구현의 예:

1. 사용자가 클라이언트에서 장바구니를 채우고, 상품을 구매하는 등의 작업을 수행합니다.
2. 게임 클라이언트는 엑솔라 서버에 데이터와 함께 요청을 전송합니다.
3. 엑솔라 서버가 게임 클라이언트에 응답을 보냅니다.
4. 게임 클라이언트는 사용자에게 결과를 표시합니다.

이 플로우에서 사용자 JWT를 통한 인증이 사용됩니다.

서버 측 API 호출을 사용하여 사용자 플로우를 구현하는 예:

1. 사용자가 클라이언트에서 장바구니를 채우고, 상품을 구매하는 등의 작업을 수행합니다.
2. 게임 클라이언트가 게임 서버에 요청을 보냅니다.
3. 필요한 경우 파트너는 게임 서버에서 추가 데이터 처리를 구현합니다.
4. 게임 서버가 엑솔라 서버로 요청을 보냅니다.
5. 엑솔라 서버가 게임 서버로 응답을 보냅니다.
6. 게임 서버는 데이터를 처리하고 게임 클라이언트에 응답을 보냅니다.
7. 게임 클라이언트는 사용자에게 결과를 표시합니다.

이 플로우에서 기본 액세스 인증 또는 서버 토큰이 사용됩니다.

서버 측 관리자 API 호출을 사용할 경우 상호 작용 플로우:

1. 파트너는 애플리케이션의 클라이언트 또는 서버에서 엑솔라 서버로 요청을 보냅니다.
2. 엑솔라 서버는 요청 처리 결과가 포함된 응답을 반환합니다.

엔드포인트 유형

데이터 형식

페이징

오류 처리

• 200, 201, 204 — 오류 없음
• 400 Bad Request — 보통 필수 매개 변수가 누락되었음을 나타냅니다. 자세한내용은 응답 본문을 참조합니다.
• 401 Unauthorized — 제공된 유효한 API 키가 없습니다.
• 402 Request Failed — 유효한 매개 변수이지만 요청이 실패했습니다.
• 403 Forbidden — 권한이 없습니다. 자세한내용은 응답 본문을 참조합니다.
• 404 Not Found — 요청한 항목이 존재하지 않습니다.
• 409, 422 — 잘못된 요청 매개 변수입니다.
• 412 Precondition Failed — 프로젝트가 아직 활성화되지 않았습니다(토큰 생성 방식에서 사용).
• 415 Unsupported Media Type — HTTP 헤더에 Content-Type: application/json이 없습니다.
• 500, 502, 503, 504 Server Errors — 문제가 발생했습니다.

{
    "http_status_code": 500,
    "message": "Internal Server Error",
    "extended_message": null,
    "request_id": "6445b85"
}

속도 제한

일반 정보

속도 제한 초과의 일반적인 원인

• 다음과 같은 경우 파트너 측의 트래픽이 갑자기 증가할 수 있습니다:
  • 시즌 판매
  • 비공개 및 공개 테스트 시작
• 파트너 측에 대한 DDoS 공격으로 인한 급격한 트래픽 증가.
• 잘못 구성한 통합입니다. 예시는 다음과 같습니다:
  • 카탈로그 하위 섹션 메소드 대신 자주 사용하지 않는 관리자 하위 섹션 메소드 사용
  • 주문 가져오기 메소드를 자주 호출하여 주문 상태와 이에 해당하는 아이템 목록을 가져옵니다. 예시: 요청 사이의 권장 지연 시간이 3초인 경우 초당 1회
• 지정된 기간 동안 과도한 수의 요청을 보냅니다. 예시: 아이템 카탈로그를 표시하기 위해 가상 아이템 목록 가져오기 메소드를 초당 200회 이상 호출합니다.

속도 제한 처리

• 429 상태 코드를 추적하고 재시도 메커니즘을 생성합니다. 연속 재시도 대신 재시도 사이에 고정 혹은 지수 백오프를 사용하는 재시도 패턴을 사용할 수 있습니다.
• 필요한 데이터만 가져오도록 코드를 최적화합니다. 애플리케이션에 필요한 요청만 하고 불필요한 API 호출은 피해야 합니다. IGS API를 사용하는 경우 WebSocket API를 사용하여 호출 수를 줄일 수 있습니다.
• 애플리케이션에서 자주 사용하는 캐시 데이터입니다. 자체적으로 정적 데이터를 유지하고 외부 API에 대한 요청 수를 줄일 수 있습니다.
• API를 손상시킬 수 있는 DDoS 공격을 방지합니다.
• 원활한 배포를 위해 요청 속도를 조정합니다. 429 오류가 주기적으로 발생하는 경우 요청 속도를 제한하고 보다 균등하게 배포할 수 있도록 코드에 프로세스를 포함하는 것을 고려해 보세요.

API 키

API 키는 사용자 데이터 암호화 및 API 요청 인증에 사용되는 고유 키입니다. 관리자 페이지에서 회사의 모든 프로젝트와 개별 프로젝트용 API 키를 생성할 수 있습니다.

API 키 생성

1. 관리자 페이지을 엽니다.
2. 회사 설정 > API 키 또는 프로젝트 설정 > API 키 섹션으로 이동합니다.
3. API 키 생성을 클릭합니다.
4. 다음 필드를 완성합니다.
   • 키 이름. 키 목록에 표시되는 항목입니다. 키 이름을 설정하면 키를 쉽게 식별할 수 있습니다.
   • 키 유형 - 영구 혹은 임시.
   • 만료 날짜 - 임시 키에만 사용 가능. 만료 날짜가 지나면 키가 더 이상 유효하지 않으며 새 키를 생성해야 합니다.
   • 프로젝트. 여기에서 키가 유효합니다(프로젝트 페이지에서 API 키를 생성할 때 필드가 표시되지 않음). 기본적으로 모든 프로젝트가 선택됩니다.
5. 생성을 클릭합니다.
6. 열리는 창에서 API 키 복사를 클릭하고 생성된 API 키를 자체적으로 저장합니다.

API 키 삭제

1. 관리자 페이지을 엽니다.
2. 회사 설정 > API 키 또는 프로젝트 설정 > API 키 섹션으로 이동합니다.
3. API 키 행에서 휴지통 아이콘을 클릭하고 작업을 확인합니다.

• 이 API 키가 사용된 프로젝트에서 결제 대금 받기
• 이 API 키를 사용한 API 메소드 호출

1. 새 API 키를 생성합니다.
2. 새 API 키를 사용하도록 애플리케이션을 변경합니다.
3. 초기 API 키를 삭제합니다.

웹훅

웹훅을 통해 엑솔라 측에서 구성된 이벤트에 대해 즉각적인 알림을 받을 수 있습니다. 웹훅 처리를 설정해 애플리케이션을 자동화할 수 있습니다. 문서를 참조해 사용할 수 있는 웹훅 목록과 작동 방법에 대한 자세한 설명을 확인할 수 있습니다.