API 개요

본 문서는 (주)메이즈 Open API 개발 연동을 위한 안내 문서입니다.
실제로 (주)메이즈 Open API를 사용하기 위해서는 (주)메이즈 API 계정으로 로그인 후 서 API Client ID, Client Secret 을 신청, OpenAPI 연동까지 2단계의 절차가 있습니다.
Open API는 사전 승인등록된 게임사를 기준으로 사용이 가능합니다. 본 문서에는 게임사 제공 API의 내용이 기술되어 있습니다.


API 규격

호출 도메인 주소는 https://{도메인}/api/{제공API} 형식이며 주소는 도메인 표를 확인해주세요. Restful방식으로 호출이 가능하며 Method는 GET/POST 만 지원합니다.
통신 구간에 대한 암호화는 HTTPS 방식을 사용합니다. 통신 포맷은 JSON 규격으로 제공합니다.

구분 URL IP
테스트(Test) test-api.maze.games 106.249.36.18
라이브(Live) api.maze.games 117.52.84.85


제공 API

※ 주식회사 메이즈에서 제공하는 API 입니다.
구분 API 명 1일 허용량
회원 팬덤박스 회원 조회 제한 없음
결제 게임 결제정보 등록 제한 없음
게임 결제정보 취소처리 제한 없음


API 변경 이력

※ 이 문서의 내용은 언제든지 변경될 수 있습니다. 사용처에 통보 없이 변경될 수 있으니 고려하여 개발 진행하시길 권장합니다.
날짜 제목 변경 내용
2023.10.02 최초 작성 API 문서화
2023.10.18 API 추가 결제취소 API 추가
2024.03.07 API 문서 개편 API 문서 템플릿 변경
2024.05.21 API 문서 내용 수정 API 문서 잘못된 안내문구 수정, 테스트 전용 accountId 표시


사전 준비사항

API의 인증 단계는 아래와 같습니다.

  • Step 1. API 회원가입을 진행합니다.
  • Step 2. 로그인 후 내 정보 > API 발급 페이지로 이동, API 키 발급(생성)을 진행합니다.
  • Step 3. 발급된 API Client ID, Client Key로 인증 절차를 수행합니다.
보안상의 문제로 Client ID와 Client Key가 절대 노출되지 않도록 유의해 주시기 바랍니다. 만약 보안 키를 분실하거나 유출된 경우 문의하기 게시판 또는 연락 창구로 직접 문의해 주시기 바랍니다.


시작하기

HMAC 서명 생성 및 API 호출
HMAC은 해시 메시지 인증코드(Hash Message Authentication Code)의 준말로써 RFC2104 표준 암호화 프로토콜입니다. 메이즈 API는 HMAC기반으로 제작되었으며 모든 request header의 Authorization에 생성한 HMAC signature를 함께 보내주셔야 합니다. 아래는 HMAC signature 생성 및 API 호출 예시입니다.


1. OAuth 인증 URL
POST https://{API 도메인 주소}/oauth/token

2. 요청 Body
항목 필수여부 자료형 길이 설명
grant_type O string - 인증 방식
client_id O string 40 API Client ID
client_secret O string 40 API Client Key
scope O string - API 계정
username O string - API 사용자 계정
password O string - API 사용자 비밀번호

3. 응답 Body
항목 필수여부 자료형 길이 설명
token_type O string 6 토큰 타입
expires_in O integer 7 토큰 유효시간
access_token O string - 인증 토큰
refresh_token O string - 재인증 토큰

4. 요청 Body 예시
{
    "grant_type": "password",
    "client_id": "9b65123a-45fd-44d0-9be4-240d008e154b",
    "client_secret": "eN2tkqWIQGgsbeT2ZhjRbDPcdyWZF5l6vMWws2Qh",
    "scope": "*",
    "username": "test@maze.games",
    "password": "1234"
}
5. 응답 Body 예시

# 언어 별 인증 예제
                
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.HashMap;
import java.util.Map;

public class OAuthClient {
    public static void main(String[] args) {
        HttpClient client = HttpClient.newHttpClient();
        Map data = new HashMap<>();
        data.put("grant_type", "password");
        data.put("client_id", "YOUR_CLIENT_ID");
        data.put("client_secret", "YOUR_CLIENT_SECRET");
        data.put("username", "USER_EMAIL");
        data.put("password", "USER_PASSWORD");
        data.put("scope", "");

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://{API 도메인 주소}/oauth/token"))
                .headers("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(data.toString()))
                .build();

        try {
            HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
            System.out.println(response.body());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
            
                
import requests

data = {
    'grant_type': 'password',
    'client_id': 'YOUR_CLIENT_ID',
    'client_secret': 'YOUR_CLIENT_SECRET',
    'username': 'USER_EMAIL',
    'password': 'USER_PASSWORD',
    'scope': ''
}

response = requests.post('https://{API 도메인 주소}/oauth/token', json=data)
print(response.text)
            
                
$data = [
    'grant_type' => 'password',
    'client_id' => 'YOUR_CLIENT_ID',
    'client_secret' => 'YOUR_CLIENT_SECRET',
    'username' => 'USER_EMAIL',
    'password' => 'USER_PASSWORD',
    'scope' => ''
];

$ch = curl_init('https://{API 도메인 주소}/oauth/token');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));

$response = curl_exec($ch);
curl_close($ch);

echo $response;
            
                
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Threading.Tasks;

class OAuthClient
{
    static async Task Main(string[] args)
    {
        using (var client = new HttpClient())
        {
            var data = new Dictionary
            {
                {"grant_type", "password"},
                {"client_id", "YOUR_CLIENT_ID"},
                {"client_secret", "YOUR_CLIENT_SECRET"},
                {"username", "USER_EMAIL"},
                {"password", "USER_PASSWORD"},
                {"scope", ""}
            };

            var response = await client.PostAsync("https://{API 도메인 주소}/oauth/token", new FormUrlEncodedContent(data));
            var responseString = await response.Content.ReadAsStringAsync();

            Console.WriteLine(responseString);
        }
    }
}
            
                
const axios = require('axios');

const data = {
    grant_type: 'password',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    username: 'USER_EMAIL',
    password: 'USER_PASSWORD',
    scope: ''
};

axios.post('https://{API 도메인 주소}/oauth/token', data)
    .then((response) => {
        console.log(response.data);
    })
    .catch((error) => {
        console.error(error);
    });
            


Header의 구성

인증을 정상적으로 마친 후 접속하면 access_token을 발급 받습니다.
access_token을 사용해서 인증을 진행해 주시면 됩니다. 요청 Header의 구성은 다음과 같습니다.
"Authorization": "Bearer 인증키"
"Content-Type": "application/json"
"Accept": "application/json"

※ access_token의 유효기간은 최대 15일입니다.

회원 조회

팬덤박스 회원의 사용자 ID 또는 후원코드로 사용자를 조회합니다.

1. URL
GET https://{API 도메인 주소}/api/search/user

2. 요청 Body
항목 필수여부 자료형 길이 설명
accountId O string 15 팬덤박스 구글 ID 또는 후원코드(테스트 ID: maze)

3. 응답 Body
항목 필수여부 자료형 길이 설명
success O integer 1 요청 성공 여부
code O integer 3 결과 코드
message O string 50 결과 메시지
exists O boolean - 사용자 존재 여부
accountId O string 15 조회된 사용자 ID 또는 후원코드

4. 요청 Body 예시
{
    "accountId": "test"
}

5. 응답 Body 예시
{
    "success": 1,
    "code": 200,
    "message": "ok",
    "exists": true,
    "accountId": "test"
}


결제 등록

팬덤박스에 플랫폼 결제 정보 제공합니다.

1. URL
POST https://{API 도메인 주소}/api/purchase/invoice

2. 요청 Body
항목 필수여부 자료형 길이 설명
accountId O string 15 팬덤박스 구글 ID 또는 후원코드 (테스트 ID: maze)
orderId O string 255 주문번호
marketplace O integer 1 결제 플랫폼(1:구글, 2:애플, 3: MS, 4:갤럭시, 5:원스토어, 6:기타)
gameCode O string 6 메이즈 게임코드 (테스트 게임코드 : Bs9zev)
orderPrice O integer 10 결제 금액

3. 응답 Body
항목 필수여부 자료형 길이 설명
success O integer 1 요청 성공 여부
code O integer 3 결과 코드
message O string 50 결과 메시지

4. 요청 Body 예시
{
    "accountId": "test",
    "orderId": " GPA.1234-1234-1234-12345",
    "marketplace": 1,
    "gameCode": "Bs9zev",
    "orderPrice": 10000
}

5. 응답 Body 예시
{
    "success": 1,
    "code": 200,
    "message": "ok"
}


결제 취소

팬덤박스에 제공한 결제 정보를 취소 처리합니다.(취소한 결제 정보는 재사용이 불가능합니다.)

1. URL
GET https://{API 도메인 주소}/api/purchase/invoice/return

2. 요청 Body
항목 필수여부 자료형 길이 설명
orderId O string 50 주문번호

3. 응답 Body
항목 필수여부 자료형 길이 설명
success O integer 1 요청 성공 여부
code O integer 3 결과 코드
message O string 50 결과 메시지

4. 요청 Body 예시
{
    "orderId": "GPA.1234-1234-1234-12345"
}

5. 응답 Body 예시
{
    "success": 1,
    "code": 200,
    "message": "ok"
}


응답코드

(주)메이즈 API 서비스에서 사용되는 결과코드에 대한 안내입니다.

응답코드 메세지
101 `accountId`를 입력해주세요.
102 `accountId`형식이 옳지않습니다.
201 `orderId`를 입력해주세요.
202 `orderId`형식이 옳지않습니다.
203 `orderId`는 최대 255자 이하이어야 합니다.
204 `orderId`는 존재하지 않습니다.
301 `marketplace`를 입력해주세요.
302 `marketplace`형식이 옳지않습니다.
303 `marketplace`는 허용되지 않는 값입니다.
401 `gameCode`를 입력해주세요.
402 `gameCode`형식이 옳지않습니다.
501 `orderPrice`를 입력해주세요.
502 `orderPrice`형식이 옳지않습니다.
503 `orderPrice`는 0원 이상이어야 합니다.

에러코드

에러코드 메세지
1 구글 ID 또는 후원코드를 확인할 수 없습니다.
2 가입 정보가 없는 게임 입니다.
3 반환 가능한 적립금이 없습니다.
4 이미 취소 처리된 주문입니다.
5 피후원자 정보를 찾을 수 없습니다.
6 차단된 회원입니다.
처리 중...