인증서 발급

인증서 발급 (POST)

인증서를 이메일 또는 문자 방식으로 일괄 발급합니다.

• Method: POST

• URL: /achievements/issue

• Request Body (JSON):

  필드	타입	필수	유효성검사	설명
  achievementFormId	number	Yes		사용될 인증서 폼의 고유 ID
  mode	string	Yes	값은 email 또는 phone만 허용됨	발급 방식
  users	user[]	Yes		발급 대상 사용자 목록 (아래 개별 사용자 오브젝트 참조)

user (object)

필드명	타입	필수	유효성검사	설명
name	string	Yes		사용자의 이름
email	string	Yes, (mode 가 "email" 일 경우)	유효한 이메일 형식이어야 함 (예: user@example.com)	사용자의 이메일 주소 (이메일 방식인 경우)
phoneNumber	string	Yes, (mode 가 "phone" 일 경우)	정규표현식: ^010\d8$ (010으로 시작하는 11자리 숫자만 허용)	사용자의 전화번호 (전화 방식인 경우)
admin_comment	string	No		관리자가 해당 사용자에 대해 남긴 코멘트
level	number	No		인증서 레벨
custom_attributes	Custom Attribute[]	No		인증서 커스텀 속성 배열 (아래 개별 객체 참조)

Custom Attribute (object)

필드명	타입	필수	유효성검사	설명
attribute_tag	string	Yes		속성 태그
attribute_value	string	Yes		속성 값

• Body 예시:

{
  "achievementFormId": 482,
  "mode": "email",
  "users": [
    {
      "name": "홍길동",
      "email": "hong@example.com",
      "admin_comment": "축하합니다!",
      "level": 5,
      "custom_attributes": [
        { "attribute_tag": "score", "attribute_value": "90" }
      ]
    }
  ]
}

---

Response

{
  "statusCode": 201,
  "message": "인증서가 발급되었습니다."
}

---

오류 코드

상태 코드	에러	메시지	상세 설명
400	Bad Request	잘못된 요청입니다.	허가되지 않은 값, 올바르지 않은 형식의 요청
400	Bad Request	email 또는 phoneNumber 중 하나는 반드시 포함되어야 합니다.	User Object에 이메일 또는 전화번호 중 하나는 필수
401	Unauthorized	Invalid token	인증 정보가 올바르지 않은 경우
404	Not Found	도메인이 domain인 클럽을 찾을 수 없습니다.	도메인 정보가 올바르지 않은 경우
404	Not Found	유효하지 않은 인증서 폼 ID입니다.	인증서 폼이 존재하지 않은 경우
500	Internal Server Error	인증서 발급 중 예기치 않은 오류가 발생했습니다.	서버 에러

---

Request Sample

Java

Unirest

String url = "https://${baseURL}/open-api/achievements/issue";

Map<String, String> customAttribute = new HashMap<>();
customAttribute.put("attribute_tag", "score");
customAttribute.put("attribute_value", "90");

Map<String, Object> user = new HashMap<>();
user.put("name", "홍길동");
user.put("email", "hong@example.com");
user.put("admin_comment", "축하합니다!");
user.put("level", 5);
user.put("custom_attributes", List.of(customAttribute));

Map<String, Object> requestBody = new HashMap<>();
requestBody.put("achievementFormId", 482);
requestBody.put("mode", "email");
requestBody.put("users", List.of(user));

ObjectMapper mapper = new ObjectMapper();
String jsonBody = mapper.writeValueAsString(requestBody);

HttpResponse<String> response = Unirest.post(url)
    .header("Content-Type", "application/json")
    .header("Accept", "application/json")
    .header("Authorization", apiKey)
    .body(jsonBody)
    .asString();

System.out.println("Status: " + response.getStatus());
System.out.println("Response: " + response.getBody());

OkHttp

OkHttpClient client = new OkHttpClient();
String url = "https://api.test.kolleges.net/open-api/achievements/issue";

JSONObject customAttribute = new JSONObject();
customAttribute.put("attribute_tag", "score");
customAttribute.put("attribute_value", "90");

JSONArray customAttributes = new JSONArray();
customAttributes.put(customAttribute);

JSONObject user = new JSONObject();
user.put("name", "홍길동");
user.put("email", "hong@example.com");
user.put("admin_comment", "축하합니다!");
user.put("level", 5);
user.put("custom_attributes", customAttributes);

JSONArray usersArray = new JSONArray();
usersArray.put(user);

JSONObject requestBody = new JSONObject();
requestBody.put("achievementFormId", 482);
requestBody.put("mode", "email");
requestBody.put("users", usersArray);

MediaType JSON = MediaType.get("application/json; charset=utf-8");
RequestBody body = RequestBody.create(requestBody.toString(), JSON);

Request request = new Request.Builder()
        .url(url)
        .post(body)
        .addHeader("Content-Type", "application/json")
        .addHeader("Accept", "application/json")
        .addHeader("Authorization", apiKey)
        .build();

try (Response response = client.newCall(request).execute()) {
    System.out.println("Status: " + response.code());
    System.out.println("Response: " + response.body().string());
} catch (Exception e) {
    e.printStackTrace();
}

JavaScript

Axios

const axios = require("axios");
const url = "https://${baseURL}/open-api/achievements/issue";

const body = {
  achievementFormId: 482,
  mode: "email",
  users: [
    {
      name: "홍길동",
      email: "hong@example.com",
      admin_comment: "축하합니다!",
      level: 5,
      custom_attributes: [{ attribute_tag: "score", attribute_value: "90" }],
    },
  ],
};

axios
  .post(url, body, {
    headers: {
      "Content-Type": "application/json",
      Accept: "application/json",
      Authorization: `Bearer ${apiKey}`,
    },
  })
  .then((response) => {
    console.log("Status:", response.status);
    console.log("Response:", response.data);
  })
  .catch((error) => {
    console.error(
      "Error:",
      error.response ? error.response.data : error.message
    );
  });

XMLHttpRequest

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;
const url = "https://${baseURL}/open-api/achievements/issue";

const data = {
  achievementFormId: 482,
  mode: "email",
  users: [
    {
      name: "홍길동",
      email: "hong@example.com",
      admin_comment: "축하합니다!",
      level: 5,
      custom_attributes: [{ attribute_tag: "score", attribute_value: "90" }],
    },
  ],
};

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log("Status:", this.status);
    console.log("Response:", this.responseText);
  }
});

xhr.open("POST", url);
xhr.setRequestHeader("Content-Type", "application/json");
xhr.setRequestHeader("Accept", "application/json");
xhr.setRequestHeader("Authorization", "Bearer " + apiKey);

xhr.send(JSON.stringify(data));

Fetch

const fetch = require("node-fetch");
const url = "https://${baseURL}/open-api/achievements/issue";

const body = {
  achievementFormId: 482,
  mode: "email",
  users: [
    {
      name: "홍길동",
      email: "hong@example.com",
      admin_comment: "축하합니다!",
      level: 5,
      custom_attributes: [{ attribute_tag: "score", attribute_value: "90" }],
    },
  ],
};

fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Accept: "application/json",
    Authorization: `Bearer ${apiKey}`,
  },
  body: JSON.stringify(body),
})
  .then((response) => {
    console.log("Status:", response.status);
    return response.json();
  })
  .then((data) => {
    console.log("Response:", data);
  })
  .catch((error) => console.error("Error:", error));

HTTP

const https = require("https");

const postData = JSON.stringify({
  achievementFormId: 482,
  mode: "email",
  users: [
    {
      name: "홍길동",
      email: "hong@example.com",
      admin_comment: "축하합니다!",
      level: 5,
      custom_attributes: [{ attribute_tag: "score", attribute_value: "90" }],
    },
  ],
});

const options = {
  method: "POST",
  hostname: "api.test.kolleges.net",
  path: "/open-api/achievements/issue",
  headers: {
    "Content-Type": "application/json",
    Accept: "application/json",
    Authorization: `Bearer ${apiKey}`,
    "Content-Length": Buffer.byteLength(postData),
  },
};

const req = https.request(options, (res) => {
  const chunks = [];

  res.on("data", (chunk) => {
    chunks.push(chunk);
  });

  res.on("end", () => {
    const body = Buffer.concat(chunks).toString();
    console.log("Status:", res.statusCode);
    console.log("Response:", body);
  });
});

req.on("error", (error) => {
  console.error("Error:", error);
});

req.write(postData);
req.end();

Python

Requests

import requests
import json

url = "https://${baseURL}/open-api/achievements/issue"
payload = {
  "achievementFormId": 482,
  "mode": "email",
  "users": [
    {
      "name": "홍길동",
      "email": "hong@example.com",
      "admin_comment": "축하합니다!",
      "level": 5,
      "custom_attributes": [
        {"attribute_tag": "score", "attribute_value": "90"}
      ]
    }
  ]
}
headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Authorization": f"Bearer {api_key}"
}

response = requests.post(url, headers=headers, data=json.dumps(payload))

print("Status:", response.status_code)
try:
    print("Response:", response.json())
except Exception as e:
    print("Response:", response.text)

Shell

cURL

curl -X POST "https://${baseURL}/open-api/achievements/issue" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer $API_KEY" \
     -d '{
       "achievementFormId": 482,
       "mode": "email",
       "users": [
         {
           "name": "홍길동",
           "email": "hong@example.com",
           "admin_comment": "축하합니다!",
           "level": 5,
           "custom_attributes": [
             {"attribute_tag": "score", "attribute_value": "90"}
           ]
         }
       ]
     }'

---