시작하기

개요

엑솔라 API 포함 사항:

엑솔라 API는 REST를 기반으로 구성되어 있습니다. 예측 가능한 리소스 중심의 URL과 함께 API 오류를 HTTP 응답 코드로 표시하도록 구성된 API입니다. 오류를 포함한 API의 모든 응답에서 JSON이 반환됩니다.

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

엑솔라 API는 다음 Endpoint 경로를 사용합니다.
  • https://api.xsolla.com — 페이 스테이션 API, 관리자 페이지 API, 정기 결제 API
  • https://login.xsolla.com/api — 로그인 API
  • https://store.xsolla.com/api — 인게임 스토어 및 직접 판매 API
대부분의 Endpoint 경로에는 merchant_id 매개변수가 포함되어 있습니다. 이는 애플리케이션이 사용자를 대신하여 작업 중임을 나타냅니다.

요청 및 응답

엑솔라 API에 대한 요청은
  • HTTPS를 통해 전송해야 하며
  • TLS 1.2 이상을 사용해야 하고
  • 인증 매개변수를 포함해야 하며
  • PUT과 POST 요청에 대해추가 헤더(Content-Type: application/json)를 포함해야 합니다.
Copy
Full screen
Small screen
    Authorization: Basic <your_authorization_basic_key>
    Content-Type: application/json
    

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

    API 변경사항

    엑솔라는 API로 기능을 변경할 수 있습니다.
    • 엑솔라는 새로운 API 자원을 추가할 수 있습니다.
    • 엑솔라는 선택적 요청 매개변수를 추가할 수 있습니다.
    • 엑솔라는 기존 API 응답에 대한 새로운 속성을 추가할 수 있습니다.
    • 엑솔라는 나열된 값들의 묶음들로 이루어진 기존 매개변수에 새 값들을 추가할 수 있습니다.
    • 엑솔라는 JSON에 새 webhook 타입들과 매개변수들을 추가할 수 있습니다.
    • 엑솔라는 선택적 HTTP 요청 헤더를 추가할 수 있습니다.
    • 엑솔라는 유효한 매개변수에 유효하지 않은 매개변수 값이 포함된 요청을 거부할 수 있습니다.
    • 지나치게 관대한 파싱으로 인해 승인된 부적절한 형식의 요청들은 파싱로직이 올바르다면 거부될 수도 있습니다.
    • 엑솔라는 언제든지 문서화되지 않은 기능을 추가, 변경 또는 제거할 수 있습니다.
    당신의 고객은 이러한 변경사항과 관계없이 계속 운영할 수 있어야만 합니다. 예를 들어, 클라이언트가 알아채지 못한 새로운 JSON 매개변수로 인해 제대로 동작하는 능력이 방해받지는 않습니다.

    버전 관리

    모든 엑솔라 API 방식은 버전 관리를 지원합니다. 현재 버전과 호환되지 않는 변경 사항이 있을 때마다 새 버전을 발행합니다. 이러한 버전은 “v1”/“v2” 등으로 식별하며 URL에 “/merchant"와 같은 식별자가 붙습니다. API를 처음으로 사용하는 경우 최신 버전을 사용하도록 합니다. 버전을 생략하는 경우, 기본값으로 첫 번째 버전을 사용합니다.
    알림
    동일한 버전을 사용하는 경우에만 API 무결성이 보장됩니다.

    인증

    엑솔라 API는 기본 액세스 인증을 사용합니다. 모든 API 요청에는 Authorization: Basic <your_authorization_basic_key> 헤더가 있어야 합니다. 여기에서 <your_authorization_basic_key>는 Base64 표준으로 인코딩된 판매자 ID:API 키 쌍입니다. 이러한 매개변수를 찾으려면 관리자 페이지으로 이동합니다.
    • 판매자 ID 표시 위치:
      • 프로젝트 설정 > 웹훅 섹션
      • 회사 설정 > 회사 섹션
      • 관리자 페이지 페이지의 브라우저 주소 표시줄에 있는 URL. 이 URL의 형식: `https://publisher.xsolla.com/​판매자 ID/관리자 페이지 섹션`
    • API 키는 생성할 때 한 번만 관리자 페이지에 표시되며 따로 저장하고 관리해야 합니다. 다음 섹션에서 새 키를 생성할 수 있습니다.
      • 회사 설정 > API 키
      • 프로젝트 설정 > API 키
    주의

    API 키 작업에 대한 자세한 정보는 API 참조를 확인하세요.

    주요 권장 사항:

    • 본인의 공간에 생성된 API 키를 저장합니다.. 생성된 API 키는 관리자 페이지에서 한 번만 볼 수 있습니다.
    • API 키를 비밀로 유지해야 합니다. 이러한 API 키는 개인 계정과 관리자 페이지의 프로젝트에 대한 액세스를 제공합니다.
    • API 키는 서버에 저장해야 하며 바이너리나 프론트엔드에는 저장해선 안 됩니다.

    엔드포인트 유형

    Endpoint 형식이란 처리할 데이터 형식과 해당 데이터에서 수행하는 작업을 나타냅니다. 가장 일반적인 작업은 다음과 같습니다.
    동작HTTP 방식설명
    CreatePOST해당 형식의 엔터티를 생성하고 유지합니다.
    ListGET입력한 쿼리 파라미터와 일치하는 모든 엔터티에 대한 요약 정보가 리턴됩니다. 특정 엔터티에 대한 전체 정보를 얻으려면 먼저 List endpoint를 통해 엔터티 ID를 가져온 다음 해당 Retrieve endpoint에 ID를 입력합니다.
    RetrieveGET입력한 식별자와 일치하는 단일 엔터티에 대한 전체 정보를 제공합니다.
    ReplacePUT입력한 식별자와 일치하는 기존 엔터티의 모든 필드를 수정합니다.
    UpdatePATCH입력한 식별자와 일치하는 기존 엔터티의 모든 필드를 수정합니다.
    DeleteDELETE입력한 식별자와 일치하는 기존 엔터티를 삭제합니다.

    데이터 형식

    모든 날짜는 ISO 8601 형식의 문자열로 표현합니다. UTC(예: 2013-01-15T00:00:00Z) 또는 UTC에 시차를 가감한(UTC보다 8시간 늦을 경우의 예: 2013-01-15T00:00:00-08:00) 날짜 문자열을 입력하여 시간대를 표시할 수 있습니다. 시차를 가감한 날짜를 입력할 때는 정확한 서머 타임을 고려하도록 하십시오.

    페이징

    List endpoint 리스트는 리턴한 결과에 페이지를 매길 수도 있습니다. 이 말은 전체 결과를 단일 응답으로 리턴하지않고, 다음 결과와 연결된 응답 헤더와 함께 일부 결과만 리턴 할수있다는 뜻입니다. 이를 위해 offset 및 limit 매개 변수가 사용됩니다.

    오류 처리

    지원 HTTP 오류 목록:
    • 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 응답 코드를 사용하여 API 요청의 성공 또는 실패를 표시합니다. 일반적으로 2xx 코드는 성공을 뜻하고, 4xx 코드는 입력한 정보로 인한 오류(예: 필수 매개 변수 누락, 인증 실패 등)를 나타내며, 5xx 코드는 엑솔라 서버와 관련된 오류를 나타냅니다. 하지만 모든 오류를 HTTP응답 코드에 명확히 대응시킬 수 있는 것은 아닙니다. 올바른 요청인 경우에도 성공적으로 완료되지 않으면 422 오류가 반환됩니다. 모든 API 오류 응답은 json 개체에 다음 필드를 제공합니다.
    이름유형설명
    http_status_codeintegerHTTP 코드
    messagestring판독 가능한 메시지로서 오류를 설명합니다. 이 메시지는 항상 영문입니다. 특정 오류에 대한 설명은 나중에 변경될 수도 있습니다.
    extended_messagestring오류에 대한 확장된 설명입니다.
    request_idstring문제 해결에 도움이 될 수 있는 고유한 ID입니다.
    Copy
    Full screen
    Small screen
    {
        "http_status_code": 500,
        "message": "Internal Server Error",
        "extended_message": null,
        "request_id": "6445b85"
    }
    

    속도 제한

    일반 정보

    엑솔라 시스템의 과부하를 방지하고 인입되는 트래픽 버스트로부터 시스템을 보호하기 위해 엑솔라는 지정된 기간 동안 엑솔라 API가 수신하는 요청 수를 제한합니다. 제한 설정을 초과하면 엑솔라 API는 429 상태 코드와 함께 HTTP 응답을 반환합니다. 제한 설정은 메소드, 프로젝트 및 기타 요인에 따라 다릅니다. 제한 설정은 엑솔라 시스템의 안정적이고 중단 없는 작동을 위해 정기적으로 업데이트됩니다. 경우에 따라 사전 요청 시 지정된 제한 설정을 조정할 수 있습니다. 고객 성공 매니저에게 문의하거나 csm@xsolla.com으로 이메일을 보내 요청을 제출할 수 있습니다.

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

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

    속도 제한 처리

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

    API 키

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

    알림
    회사의 모든 프로젝트에서 유효한 API 키는 개별 프로젝트 페이지에 표시되지 않습니다.
    주의

    다음 역할 중 하나를 수행하는 경우 API 키로 작업(목록 보기, 생성, 삭제)할 수 있습니다.

    • 개발자
    • 소유자

    프로젝트 소유자만 회사 설정 > 사용자 섹션의 관리자 페이지에서 역할을 변경할 수 있습니다.

    API 키 생성

    API 키 생성 방법:
    1. 관리자 페이지을 엽니다.
    2. 회사 설정 > API 키 또는 프로젝트 설정 > API 키 섹션으로 이동합니다.
    3. API 키 생성을 클릭합니다.
    4. 다음 필드를 완성합니다.
      • 키 이름. 키 목록에 표시되는 항목입니다. 키 이름을 설정하면 키를 쉽게 식별할 수 있습니다.
      • 키 유형 - 영구 혹은 임시.
      • 만료 날짜 - 임시 키에만 사용 가능. 만료 날짜가 지나면 키가 더 이상 유효하지 않으며 새 키를 생성해야 합니다.
      • 프로젝트. 여기에서 키가 유효합니다(프로젝트 페이지에서 API 키를 생성할 때 필드가 표시되지 않음). 기본적으로 모든 프로젝트가 선택됩니다.
    5. 생성을 클릭합니다.
    6. 열리는 창에서 API 키 복사를 클릭하고 생성된 API 키를 자체적으로 저장합니다.
    알림
    프로젝트 페이지에서 API 키를 생성하면 키가 이 특정 프로젝트에서만 유효합니다.
    주의
    주요 권장 사항:
    • 본인의 공간에 생성된 API 키를 저장합니다.. 생성된 API 키는 관리자 페이지에서 한 번만 볼 수 있습니다.
    • API 키를 비밀로 유지해야 합니다. 이러한 API 키는 개인 계정과 관리자 페이지의 프로젝트에 대한 액세스를 제공합니다.
    • API 키는 서버에 저장해야 하며 바이너리나 프론트엔드에는 저장해선 안 됩니다.

    API 키 삭제

    API 키 삭제 방법:
    1. 관리자 페이지을 엽니다.
    2. 회사 설정 > API 키 또는 프로젝트 설정 > API 키 섹션으로 이동합니다.
    3. API 키 행에서 휴지통 아이콘을 클릭하고 작업을 확인합니다.
    API 키 삭제 중지:
    • 이 API 키가 사용된 프로젝트에서 결제 대금 받기
    • 이 API 키를 사용한 API 메소드 호출
    방지 방법:
    1. 새 API 키를 생성합니다.
    2. 새 API 키를 사용하도록 애플리케이션을 변경합니다.
    3. 초기 API 키를 삭제합니다.

    웹훅

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

    이 기사가 도움이 되었나요?
    감사합니다!
    개선해야 할 점이 있을까요? 메시지
    유감입니다
    이 기사가 도움이 안 된 이유를 설명해 주세요. 메시지
    의견을 보내 주셔서 감사드립니다!
    메시지를 검토한 후 사용자 경험 향상에 사용하겠습니다.
    이 페이지 평가
    이 페이지 평가
    개선해야 할 점이 있을까요?

    답하기 원하지 않습니다

    의견을 보내 주셔서 감사드립니다!
    마지막 업데이트: 2024년 1월 24일

    오자 또는 기타 텍스트 오류를 찾으셨나요? 텍스트를 선택하고 컨트롤+엔터를 누르세요.