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

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

## 목차

1. [개요](https://#%EA%B0%9C%EC%9A%94)

2. [제공 API](https://#%EC%A0%9C%EA%B3%B5-api)

3. [빠른 시작](https://#%EB%B9%A0%EB%A5%B8-%EC%8B%9C%EC%9E%91)

4. [상세 가이드](https://#%EC%83%81%EC%84%B8-%EA%B0%80%EC%9D%B4%EB%93%9C)

5. [공통 사항](https://#%EA%B3%B5%ED%86%B5-%EC%82%AC%ED%95%AD)

6. [간단한 예제](https://#%EA%B0%84%EB%8B%A8%ED%95%9C-%EC%98%88%EC%A0%9C)

7. [FAQ](https://#faq)

---

## 개요

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

### 지원하는 기능

- ✅ **포인트 부여 API**: 학생에게 포인트 지급/차감

- ✅ **학생 정보 조회 API**: 포인트, 레벨, 드래곤, 아이템 등 조회

---

## 제공 API

### 1. 포인트 부여 API

외부 애플리케이션에서 학생들에게 포인트를 부여하거나 차감할 수 있습니다.

**주요 기능:**

- 학생에게 리워드 포인트 부여

- 학생에게 페널티 포인트 차감

- 포인트 부여 시 텃밭 보너스 적용 옵션

- 커스텀 메타데이터 저장

**엔드포인트:**

```
POST /api/v1/classes/{classId}/students/{studentCode}/points
```

**필요 권한:** `awardPoints`

📖 **[상세 가이드 보기 →](https://slashpage.com/grownd/grownd_API)**

---

### 2. 학생 정보 조회 API

학생의 상세 정보를 조회할 수 있습니다.

**조회 가능한 정보:**

- 포인트 및 레벨 정보 (50점 단위, 최대 레벨 50)

- 레벨 명칭 (식물 이름: 아몬드, 아티초크, 바질 등)

- 드래곤 정보 (이름, 단계, 레벨, 경험치, 먹이, 하트스톤)

- 보유 마켓 상품 (일반 마켓 + 공동구매 + 케이브)

- 텃밭 아이템 (배치 아이템, 인벤토리, 하트베리)

**엔드포인트:**

```
GET /api/v1/classes/{classId}/students/{studentCode}
```

**필요 권한:** `readStudents`

📖 **[상세 가이드 보기 →](https://slashpage.com/grownd/qrx6zk258y9n3mv314y5)**

### 3. 학급 미션 정보 조회 API

학급 포인트와 학급 미션의 상세 정보를 조회할 수 있습니다.

**조회 가능한 정보:**

- 해당 학급의 총 포인트 총점 조회

- 해당 학급의 미션 현황 조회

- 현재 총점 이상 달성한 미션은 자동으로 달성 처리 후 반환

**엔드포인트:**

```
GET /api/v1/classes/{classId}/missions
```

**필요 권한:** `readClassMissions`

📖 **[상세 가이드 보기 →](https://slashpage.com/grownd/1q3vdn2pxz6yx2xy49pr)**

---

## 빠른 시작

### 1단계: API 키 발급

1. [그라운드](https://growndcard.com)에 교사 계정으로 로그인

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 가이드](https://./api_award_points_guide.md)**

---

### 📗 학생 정보 조회 API

학생의 포인트, 레벨, 드래곤, 아이템 등을 조회하는 방법을 안내합니다.

**내용:**

- 조회 가능한 정보 상세

- 응답 데이터 구조 설명

- 에러 처리 방법

- 다양한 언어별 코드 예제 (JavaScript, Python, TypeScript, PHP)

➡️ **[학생 정보 조회 API 가이드](https://./api_student_info_guide.md)**

---

## 공통 사항

### 기본 정보

- **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 키 생성 시 `awardPoints`와 `readStudents` 권한을 모두 체크하면 됩니다.

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

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

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

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

---

## 지원

### 문의

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

---

## 관련 문서

[https://slashpage.com/grownd/n8pw9x2ze17rrmg7yrqv](https://slashpage.com/grownd/n8pw9x2ze17rrmg7yrqv)

[https://slashpage.com/grownd/qrx6zk258y9n3mv314y5](https://slashpage.com/grownd/qrx6zk258y9n3mv314y5)

[https://slashpage.com/grownd/1q3vdn2pxz6yx2xy49pr](https://slashpage.com/grownd/1q3vdn2pxz6yx2xy49pr)

- 해당 학급의 총 포인트 총점 조회

- 해당 학급의 미션 현황 조회

- 현재 총점 이상 달성한 미션은 자동으로 달성 처리 후 반환

For the site tree, see the [root Markdown](https://slashpage.com/grownd.md).