# 📦 그라운드 역량 카드 API 가이드

👉🏻 그라운드에서 학생에게 역량 카드를 부여하는 역량카드 API 기능을 설명합니다.

외부 애플리케이션에서 교사가 등록한 **역량 카드(칭찬/노력 카드)** 목록을 조회하고, 해당 카드를 통해 학생에게 학급 화폐를 부여하는 API입니다. 

## 기본 정보

- **Base URL**: `https://growndcard.com` 

- **인증**: `X-API-Key` 헤더

- **필요 권한**: `awardPoints` (API 설정에서 학급 화폐/역량카드 부여 권한 체크)

---

## 1. 역량 카드 목록 조회

### 엔드포인트

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

### 요청 헤더

| 헤더 | 값 | 필수 |
| --- | --- | --- |
| `X-API-Key` | 발급받은 API 키 | ✅ |

### 성공 응답 (200 OK)

```json
{
  "success": true,
  "data": {
    "cards": [
      {
        "templateId": "abc123",
        "type": "reward",
        "points": 5,
        "description": "수업 적극 참여",
        "categoryId": "cat_collab",
        "categoryName": "협업"
      }
    ]
  },
  "message": "역량 카드 목록 조회에 성공했습니다."
}
```

| 필드 | 설명 |
| --- | --- |
| `templateId` | 카드 부여 시 사용하는 카드 ID |
| `type` | `reward`(칭찬) / `penalty`(노력) |
| `points` | 카드에 설정된 점수 |
| `description` | 카드 설명 |
| `categoryId` / `categoryName` | 연결된 역량 카테고리 (없으면 `null`) |

---

## 2. 역량 카드 부여

### 엔드포인트

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

### URL 파라미터

| 파라미터 | 타입 | 설명 |
| --- | --- | --- |
| `classId` | string | 클래스 ID |
| `studentCode` | number | 학생 번호(출석번호) |

### 요청 본문 (JSON)

| 필드 | 타입 | 필수 | 설명 |
| --- | --- | --- | --- |
| `templateId` | string | ✅ | 부여할 역량 카드 ID (목록 조회로 획득) |
| `source` | string | ❌ | 출처 식별자 (기본값 `"cardTemplate"`) |
| `metadata` | object | ❌ | 추가 데이터 |

> 점수·설명·카테고리는 본문으로 받지 않습니다. 항상 카드 템플릿 값을 사용합니다.

### 요청 예시

```bash
curl -X POST \
  "https://growndcard.com/api/v1/classes/CLASS_ID/students/2/cards" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_xxx" \
  -d '{ "templateId": "abc123", "source": "QuizApp" }'
```

### 성공 응답 (200 OK)

```json
{
  "success": true,
  "data": {
    "recordId": "rec_xyz",
    "studentId": "stu_abc",
    "studentCode": 2,
    "type": "reward",
    "pointsAwarded": 5,
    "bonusApplied": 1,
    "totalPoints": 155,
    "currentLevel": 5,
    "leveledUp": false,
    "createdAt": "2026-06-15T01:23:45.000Z",
    "templateId": "abc123",
    "categoryId": "cat_collab"
  },
  "message": "역량 카드가 성공적으로 부여되었습니다."
}
```

---

## 에러 코드

| 상태 | 코드 | 설명 |
| --- | --- | --- |
| 400 | `invalid_student_code` | 학생 번호 누락 |
| 400 | `invalid_template_id` | templateId 누락 또는 형식 오류 |
| 401 | `unauthorized` | API 키 누락/무효 |
| 403 | `insufficient_permissions` | `awardPoints` 권한 없음 |
| 403 | `forbidden` | 해당 클래스 접근 권한 없음 |
| 404 | `card_not_found` | 해당 역량 카드 없음 |
| 404 | `student_not_found` | 학생을 찾을 수 없음 |
| 429 | `rate_limit_exceeded` | 호출 제한 초과 |
| 500 | `invalid_card_template` | 카드 템플릿 데이터 손상(type/points 이상) |
| 500 | `internal_error` | 서버 내부 오류 |

---

## 관련 문서

- [그라운드 학급 미션 조회 API 가이드](https://slashpage.com/grownd/1q3vdn2pxz6yx2xy49pr)

- [학생 정보 조회 API 가이드](https://slashpage.com/grownd/qrx6zk258y9n3mv314y5)

**API 버전**: v1

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