Sign In

🥭 그라운드 API 통합 사용 가이드

그라운드의 API의 통합 사용 가이드를 정리한 문서입니다. 그라운드는 포인트 부여 API와 학생 정보 조회 API를 각각 제공합니다.

목차

7.

개요

그라운드 API를 사용하면 외부 애플리케이션에서 학생 관리 시스템과 연동할 수 있습니다. 포인트 부여, 학생 정보 조회 등 다양한 기능을 제공합니다.

지원하는 기능

포인트 부여 API: 학생에게 포인트 지급/차감
학생 정보 조회 API: 포인트, 레벨, 드래곤, 아이템 등 조회

제공 API

1. 포인트 부여 API

외부 애플리케이션에서 학생들에게 포인트를 부여하거나 차감할 수 있습니다.
주요 기능:
학생에게 리워드 포인트 부여
학생에게 페널티 포인트 차감
포인트 부여 시 텃밭 보너스 적용 옵션
커스텀 메타데이터 저장
엔드포인트:
POST /api/v1/classes/{classId}/students/{studentCode}/points
필요 권한: awardPoints

2. 학생 정보 조회 API

학생의 상세 정보를 조회할 수 있습니다.
조회 가능한 정보:
포인트 및 레벨 정보 (50점 단위, 최대 레벨 50)
레벨 명칭 (식물 이름: 아몬드, 아티초크, 바질 등)
드래곤 정보 (이름, 단계, 레벨, 경험치, 먹이, 하트스톤)
보유 마켓 상품 (일반 마켓 + 공동구매 + 케이브)
텃밭 아이템 (배치 아이템, 인벤토리, 하트베리)
엔드포인트:
GET /api/v1/classes/{classId}/students/{studentCode}
필요 권한: readStudents

빠른 시작

1단계: API 키 발급

1.
그라운드에 교사 계정으로 로그인
2.
우측 상단 프로필 → 내 정보 클릭
3.
API 키 관리 탭 선택
4.
새 API 키 생성 버튼 클릭
5.
다음 정보 입력:
API 키 이름: 애플리케이션 이름
만료 기간: 선택 (무제한 권장)
권한 설정 체크하기:
awardPoints: 포인트 부여 API 사용 시 필수
readStudents: 학생 정보 조회 API 사용 시 필수
호출 제한: 기본값 사용 (분당 60회, 일일 500회)
⚠️ 중요: API 키는 생성 시 한 번만 표시됩니다!

2단계: 클래스 ID 확인

1.
그라운드 → 클래스 관리
2.
클래스 카드에서 ID 필드 확인
3.
예시: NP0hetJ3wyQKFtRnFeftmPiy8Dl2_2

3단계: API 호출

현재 그라운드에서는 포인트 부여 / 학생 정보 조회가 가능한 2개의 독립 API를 제공합니다.

포인트 부여 예시 (cURL)

curl -X POST \ "https://growndcard.com/api/v1/classes/YOUR_CLASS_ID/students/2/points" \ -H "Content-Type: application/json" \ -H "X-API-Key: YOUR_API_KEY" \ -d '{ "type": "reward", "points": 10, "description": "퀴즈 정답" }'

학생 정보 조회 예시 (cURL)

curl -X GET \ "https://growndcard.com/api/v1/classes/YOUR_CLASS_ID/students/2" \ -H "X-API-Key: YOUR_API_KEY"

상세 가이드

각 API의 상세한 사용 방법은 아래 가이드를 참고하세요.

📘 포인트 부여 API

학생에게 포인트를 부여하거나 차감하는 방법을 안내합니다.
내용:
요청/응답 형식 상세
필드별 설명
에러 처리 방법
다양한 언어별 코드 예제 (JavaScript, Python, TypeScript, PHP)

📗 학생 정보 조회 API

학생의 포인트, 레벨, 드래곤, 아이템 등을 조회하는 방법을 안내합니다.
내용:
조회 가능한 정보 상세
응답 데이터 구조 설명
에러 처리 방법
다양한 언어별 코드 예제 (JavaScript, Python, TypeScript, PHP)

공통 사항

기본 정보

Base URL: https://growndcard.com (권장)
대체 URL: https://asia-northeast3-heartmap-ko.cloudfunctions.net/externalApi
리전: asia-northeast3
프로토콜: HTTPS
인증 방식: API Key (Header)
💡 권장: 커스텀 도메인(growndcard.com)을 사용하면 더 간결하고 관리하기 쉽습니다.

인증 방식

모든 API 요청에는 X-API-Key 헤더가 필요합니다.
X-API-Key: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

API 키 제한사항

교사 계정당 최대 3개 API 키 생성 가능
분당 최대: 60회 호출
일일 최대: 500회 호출
API 키는 생성 시 한 번만 표시

보안 권장사항

1.
⚠️ API 키를 절대 공개 저장소에 커밋하지 마세요
2.
✅ 환경 변수(.env)에 저장하세요
3.
✅ 프론트엔드에 노출하지 말고 백엔드에서만 사용하세요
4.
✅ 정기적으로 API 키를 재발급하세요

간단한 예제

포인트 부여와 학생 정보 조회를 함께 사용하는 예제입니다.

JavaScript (Node.js)

const fetch = require('node-fetch'); const API_KEY = 'sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p4'; const BASE_URL = 'https://growndcard.com'; const CLASS_ID = 'NP0hetJ3wyQKFtRnFeftmPiy8Dl4_2'; // 포인트 부여 async function awardPoints(studentCode, points, description) { const response = await fetch( `${BASE_URL}/api/v1/classes/${CLASS_ID}/students/${studentCode}/points`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-API-Key': API_KEY }, body: JSON.stringify({ type: 'reward', points, description, source: 'MyApp' }) } ); return await response.json(); } // 학생 정보 조회 async function getStudentInfo(studentCode) { const response = await fetch( `${BASE_URL}/api/v1/classes/${CLASS_ID}/students/${studentCode}`, { method: 'GET', headers: { 'X-API-Key': API_KEY } } ); return await response.json(); } // 사용 예시 async function main() { try { // 1. 포인트 부여 const awardResult = await awardPoints(2, 10, '퀴즈 정답'); console.log('포인트 부여 성공:', awardResult.data.totalPoints); // 2. 학생 정보 조회 const student = await getStudentInfo(2); console.log('학생:', student.data.studentName); console.log('총 포인트:', student.data.points.totalPoints); console.log('레벨:', student.data.points.currentLevel); if (student.data.dragon) { console.log('드래곤:', student.data.dragon.name); console.log('드래곤 레벨:', student.data.dragon.absoluteLevel); } } catch (error) { console.error('에러:', error); } } main();

Python

import requests API_KEY = 'sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p4' BASE_URL = 'https://growndcard.com' CLASS_ID = 'NP0hetJ3wyQKFtRnFeftmPiy8Dl4_2' def award_points(student_code, points, description): """포인트 부여""" url = f'{BASE_URL}/api/v1/classes/{CLASS_ID}/students/{student_code}/points' response = requests.post( url, headers={ 'Content-Type': 'application/json', 'X-API-Key': API_KEY }, json={ 'type': 'reward', 'points': points, 'description': description, 'source': 'MyApp' } ) return response.json() def get_student_info(student_code): """학생 정보 조회""" url = f'{BASE_URL}/api/v1/classes/{CLASS_ID}/students/{student_code}' response = requests.get( url, headers={'X-API-Key': API_KEY} ) return response.json() # 사용 예시 if __name__ == '__main__': # 1. 포인트 부여 award_result = award_points(2, 10, '퀴즈 정답') print(f"포인트 부여 성공: {award_result['data']['totalPoints']}") # 2. 학생 정보 조회 student = get_student_info(2) print(f"학생: {student['data']['studentName']}") print(f"총 포인트: {student['data']['points']['totalPoints']}") print(f"레벨: {student['data']['points']['currentLevel']}") if student['data']['dragon']: print(f"드래곤: {student['data']['dragon'].get('name', '이름 없음')}") print(f"드래곤 레벨: {student['data']['dragon']['absoluteLevel']}")

FAQ

Q1. classId는 어디서 확인하나요?

A: 그라운드 → 클래스 관리 → 각 클래스 카드의 "ID" 필드에서 확인할 수 있습니다.

Q2. 학생 번호(studentCode)는 무엇인가요?

A: 학생의 출석번호입니다. 그라운드의 학생 목록에서 확인할 수 있습니다.

Q3. API 키를 분실했어요!

A: API 키는 재조회가 불가능합니다. 기존 키를 삭제하고 새로운 키를 발급받으세요.

Q4. 두 가지 권한을 모두 사용하고 싶어요

A: API 키 생성 시 awardPointsreadStudents 권한을 모두 체크하면 됩니다.

Q5. 일일 호출 제한을 늘릴 수 있나요?

A: 현재는 최대 500회로 고정되어 있습니다. 더 많은 호출이 필요한 경우 문의 게시판으로 연락주세요.

Q6. 여러 학생의 정보를 한 번에 조회할 수 있나요?

A: 현재는 단일 학생만 조회 가능합니다. 여러 학생을 조회하려면 각 학생마다 API를 호출해야 합니다.

지원

문의

문의 게시판: 그라운드 → 문의 게시판

관련 문서