양식 생성

인증서 양식 생성 (POST)

인증서 양식을 생성합니다.

Method: POST
URL: /achievements/forms

Request Body (JSON)

필드	타입	필수	유효성검사	설명
name	string	Yes	-	인증서 폼의 이름
description	string	No	-	인증서 폼 설명
type	string (enum)	Yes	completion, activity, license, career, award, recommendation, membership, degree 중 하나	인증서 폼의 유형
tags	string[]	No	각 요소가 문자열이어야 함	스킬 태그 등, 인증서 폼에 적용할 태그 배열
prefix	string	No	알파벳만 포함, 최대 5자	인증서 폼 접두사 (예: 인증번호 접두사)
program_name	string	No	-	프로그램 이름
program_type	string	No	-	프로그램 종류
program_url	string	No	-	프로그램 URL
course_begin_at	string (ISO 8601 Date)	No	ISO8601 형식 (예: "2025-04-03T00:00:00.000Z")	코스 시작일
course_end_at	string (ISO 8601 Date)	No	ISO8601 형식	코스 종료일
achievementCertificateDesignId	number	No	정수여야 함	인증서 템플릿(디자인) ID
achievementBadgeDesignId	number	Yes	정수여야 함	뱃지 디자인 ID
requirements	Requirement[]	No	각 요소는 아래의 서브 스키마를 따름	인증서 폼에 대한 요구사항 배열 (예: 취득 조건 등)

Requirement (object)

필드	타입	필수	유효성검사	설명
type	string	No	-	요구사항의 유형
url	string	No	-	요구사항 관련 URL
description	string	No	-	요구사항의 상세 설명
order	number	No	정수, 최소 0	요구사항 순서(정렬 기준으로 사용)

Request Body 예시

{
  "name": "프로그래밍 기초 과정 수료증",
  "description": "프로그래밍 기초 과정을 성공적으로 수료한 학습자에게 발급되는 인증서입니다.",
  "type": "completion",
  "tags": ["programming", "basic", "python"],
  "prefix": "PROG",
  "program_name": "프로그래밍 기초 과정",
  "program_type": "온라인 강의",
  "program_url": "https://example.com/basic-programming",
  "course_begin_at": "2024-03-01T00:00:00.000Z",
  "course_end_at": "2024-06-30T23:59:59.999Z",
  "achievementCertificateDesignId": 1,
  "achievementBadgeDesignId": 1,
  "requirements": [
    {
      "type": "수료 조건",
      "description": "모든 과제 제출 완료",
      "order": 1
    },
    {
      "type": "수료 조건",
      "description": "최종 평가 70점 이상 획득",
      "order": 2
    }
  ]
}

Response

{
  "statusCode": 201,
  "message": "인증서 폼이 성공적으로 생성되었습니다.",
  "achievementFormId": 123
}

오류 코드

상태 코드	에러	메시지	상세 설명
400	Bad Request	잘못된 요청입니다.	요청 본문에 필수 필드 누락 또는 유효하지 않은 값 제출 시
400	Bad Request	Prefix는 알파벳만 포함해야 합니다.	prefix 필드에 알파벳 외 문자 포함 시
400	Bad Request	Prefix는 최대 5자까지만 허용됩니다.	prefix 필드가 5자를 초과할 경우
401	Unauthorized	Invalid token	인증 정보가 올바르지 않은 경우
404	Not Found	유효하지 않은 인증서 폼 ID입니다.	도메인 정보가 올바르지 않은 경우
404	Not Found	해당 증명서 디자인을 찾을 수 없습니다.	증명서 디자인이 존재하지 않은 경우
404	Not Found	해당 뱃지 디자인을 찾을 수 없습니다.	배지 디자인이 존재하지 않은 경우
500	Internal Server Error	인증서 발급 중 예기치 않은 오류가 발생했습니다.	서버 에러

Request Sample

Java
JavaScript
Python
Shell

Unirest
OkHttp

String url = "https://api.test.kolleges.net/open-api/achievements/forms";

Map<String, Object> requestBody = new HashMap<>();
requestBody.put("name", "OpenBadge 3.0 Certificate");
requestBody.put("description", "This certificate is for achievement");
requestBody.put("type", "completion");
requestBody.put("tags", List.of("skill1", "skill2"));
requestBody.put("prefix", "SB");
requestBody.put("program_name", "Program Name");
requestBody.put("program_type", "Online");
requestBody.put("program_url", "https://example.com/program");
requestBody.put("course_begin_at", "2025-04-03T00:00:00.000Z");
requestBody.put("course_end_at", "2025-05-03T00:00:00.000Z");
requestBody.put("achievementCertificateDesignId", 165);
requestBody.put("achievementBadgeDesignId", 83);

Map<String, Object> requirement = new HashMap<>();
requirement.put("type", "score");
requirement.put("url", "https://example.com/requirement-info");
requirement.put("description", "해당 과제 완료");
requirement.put("order", 1);

requestBody.put("requirements", List.of(requirement));

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());

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

JSONObject requirement = new JSONObject();
requirement.put("type", "score");
requirement.put("url", "https://example.com/requirement-info");
requirement.put("description", "해당 과제 완료");
requirement.put("order", 1);

JSONArray requirementsArray = new JSONArray();
requirementsArray.put(requirement);

JSONObject requestBody = new JSONObject();
requestBody.put("name", "OpenBadge 3.0 Certificate");
requestBody.put("description", "This certificate is for achievement");
requestBody.put("type", "completion");
requestBody.put("tags", new JSONArray().put("skill1").put("skill2"));
requestBody.put("prefix", "SB");
requestBody.put("program_name", "Program Name");
requestBody.put("program_type", "Online");
requestBody.put("program_url", "https://example.com/program");
requestBody.put("course_begin_at", "2025-04-03T00:00:00.000Z");
requestBody.put("course_end_at", "2025-05-03T00:00:00.000Z");
requestBody.put("achievementCertificateDesignId", 165);
requestBody.put("achievementBadgeDesignId", 83);
requestBody.put("requirements", requirementsArray);

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();
}

XMLHttpRequest
HTTP
Axios
Fetch

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;
const url = "https://api.test.kolleges.net/open-api/achievements/forms";
const data = {
  name: "OpenBadge 3.0 Certificate",
  description: "This certificate is for achievement",
  type: "completion",
  tags: ["skill1", "skill2"],
  prefix: "SB",
  program_name: "Program Name",
  program_type: "Online",
  program_url: "https://example.com/program",
  course_begin_at: "2025-04-03T00:00:00.000Z",
  course_end_at: "2025-05-03T00:00:00.000Z",
  achievementCertificateDesignId: 165,
  achievementBadgeDesignId: 83,
  requirements: [
    {
      type: "score",
      url: "https://example.com/requirement-info",
      description: "해당 과제 완료",
      order: 1,
    },
  ],
};

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));

const https = require("https");

const postData = JSON.stringify({
  name: "OpenBadge 3.0 Certificate",
  description: "This certificate is for achievement",
  type: "completion",
  tags: ["skill1", "skill2"],
  prefix: "SB",
  program_name: "Program Name",
  program_type: "Online",
  program_url: "https://example.com/program",
  course_begin_at: "2025-04-03T00:00:00.000Z",
  course_end_at: "2025-05-03T00:00:00.000Z",
  achievementCertificateDesignId: 165,
  achievementBadgeDesignId: 83,
  requirements: [
    {
      type: "score",
      url: "https://example.com/requirement-info",
      description: "해당 과제 완료",
      order: 1,
    },
  ],
});

const options = {
  method: "POST",
  hostname: "api.test.kolleges.net",
  path: "/open-api/achievements/forms",
  headers: {
    "Content-Type": "application/json",
    Accept: "application/json",
    Authorization: `Bearer ${process.env.API_KEY}`,
    "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();

const axios = require("axios");

const url = "https://api.test.kolleges.net/open-api/achievements/forms";

const body = {
  name: "OpenBadge 3.0 Certificate",
  description: "This certificate is for achievement",
  type: "completion",
  tags: ["skill1", "skill2"],
  prefix: "SB",
  program_name: "Program Name",
  program_type: "Online",
  program_url: "https://example.com/program",
  course_begin_at: "2025-04-03T00:00:00.000Z",
  course_end_at: "2025-05-03T00:00:00.000Z",
  achievementCertificateDesignId: 165,
  achievementBadgeDesignId: 83,
  requirements: [
    {
      type: "score",
      url: "https://example.com/requirement-info",
      description: "해당 과제 완료",
      order: 1,
    },
  ],
};

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

const fetch = require("node-fetch");

const url = "https://api.test.kolleges.net/open-api/achievements/forms";

const body = {
  name: "OpenBadge 3.0 Certificate",
  description: "This certificate is for achievement",
  type: "completion",
  tags: ["skill1", "skill2"],
  prefix: "SB",
  program_name: "Program Name",
  program_type: "Online",
  program_url: "https://example.com/program",
  course_begin_at: "2025-04-03T00:00:00.000Z",
  course_end_at: "2025-05-03T00:00:00.000Z",
  achievementCertificateDesignId: 165,
  achievementBadgeDesignId: 83,
  requirements: [
    {
      type: "score",
      url: "https://example.com/requirement-info",
      description: "해당 과제 완료",
      order: 1,
    },
  ],
};

fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Accept: "application/json",
    Authorization: `Bearer ${process.env.API_KEY}`,
  },
  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));

Requests

import requests
import json

url = "https://api.test.kolleges.net/open-api/achievements/forms"

payload = {
  "name": "OpenBadge 3.0 Certificate",
  "description": "This certificate is for achievement",
  "type": "completion",
  "tags": ["skill1", "skill2"],
  "prefix": "SB",
  "program_name": "Program Name",
  "program_type": "Online",
  "program_url": "https://example.com/program",
  "course_begin_at": "2025-04-03T00:00:00.000Z",
  "course_end_at": "2025-05-03T00:00:00.000Z",
  "achievementCertificateDesignId": 165,
  "achievementBadgeDesignId": 83,
  "requirements": [
    {
      "type": "score",
      "url": "https://example.com/requirement-info",
      "description": "해당 과제 완료",
      "order": 1
    }
  ]
}

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)

cURL

curl -X POST "https://api.test.kolleges.net/open-api/achievements/forms" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "name": "OpenBadge 3.0 Certificate",
    "description": "This certificate is for achievement",
    "type": "completion",
    "tags": ["skill1", "skill2"],
    "prefix": "SB",
    "program_name": "Program Name",
    "program_type": "Online",
    "program_url": "https://example.com/program",
    "course_begin_at": "2025-04-03T00:00:00.000Z",
    "course_end_at": "2025-05-03T00:00:00.000Z",
    "achievementCertificateDesignId": 165,
    "achievementBadgeDesignId": 83,
    "requirements": [
      { "type": "score", "url": "https://example.com/requirement-info", "description": "해당 과제 완료", "order": 1 }
    ]
  }'

인증서 양식 생성 (POST)​

Request Body (JSON)​

Requirement (object)​

Request Body 예시​

Response​

오류 코드​

Request Sample​

인증서 양식 생성 (POST)

Request Body (JSON)

Requirement (object)

Request Body 예시

Response

오류 코드

Request Sample