> ## Documentation Index
> Fetch the complete documentation index at: https://playcamp.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 쿠폰 사용

> 크리에이터 쿠폰 코드 검증 및 사용

크리에이터가 배포한 쿠폰 코드를 사용합니다.

## 흐름

```
1. 쿠폰 코드 입력  →  2. 검증  →  3. 쿠폰 사용  →  4. 보상 지급
```

## 쿠폰 검증

사용 전 쿠폰 유효성을 확인합니다.

**요청**

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST "https://sandbox-sdk-api.playcamp.io/v1/server/coupons/validate" \
      -H "Authorization: Bearer ak_server_xxx:secret" \
      -H "Content-Type: application/json" \
      -d '{
        "couponCode": "CREATOR-ABC12-001",
        "userId": "user_12345"
      }'
    ```
  </Tab>

  <Tab title="Node SDK">
    ```typescript theme={null}
    // Server SDK
    const validation = await server.coupons.validate({
      couponCode: 'CREATOR-ABC12-001',
      userId: 'user_12345',
    });

    // Client SDK (사용 가능)
    const validation = await client.coupons.validate({
      couponCode: 'CREATOR-ABC12-001',
    });
    ```
  </Tab>

  <Tab title="Go SDK">
    ```go theme={null}
    // Server SDK
    validation, err := server.Coupons.Validate(ctx, playcamp.ValidateCouponServerParams{
        CouponCode: "CREATOR-ABC12-001",
        UserID:     "user_12345",
    })

    // Client SDK (사용 가능)
    validation, err := client.Coupons.Validate(ctx, playcamp.ValidateCouponParams{
        CouponCode: "CREATOR-ABC12-001",
    })
    ```
  </Tab>
</Tabs>

**응답 (유효한 경우)**

```json theme={null}
{
  "data": {
    "valid": true,
    "couponCode": "CREATOR-ABC12-001",
    "reward": [
      { "itemId": "gem", "itemQuantity": 100, "itemImageUrl": "https://cdn.example.com/gem.png" }
    ],
    "packageName": { "ko": "웰컴 패키지", "en": "Welcome Package" },
    "creatorKey": "ABC12",
    "campaignId": "campaign_001"
  }
}
```

**응답 (유효하지 않은 경우)**

```json theme={null}
{
  "data": {
    "valid": false,
    "couponCode": "INVALID-CODE",
    "errorCode": "COUPON_NOT_FOUND",
    "errorMessage": "쿠폰을 찾을 수 없습니다"
  }
}
```

## 쿠폰 사용

검증 후 실제로 쿠폰을 사용합니다.

**요청**

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST "https://sandbox-sdk-api.playcamp.io/v1/server/coupons/redeem" \
      -H "Authorization: Bearer ak_server_xxx:secret" \
      -H "Content-Type: application/json" \
      -d '{
        "couponCode": "CREATOR-ABC12-001",
        "userId": "user_12345",
        "callbackId": "game-session-abc123"
      }'
    ```
  </Tab>

  <Tab title="Node SDK">
    ```typescript theme={null}
    const result = await server.coupons.redeem({
      couponCode: 'CREATOR-ABC12-001',
      userId: 'user_12345',
      callbackId: 'game-session-abc123', // optional
    });
    ```
  </Tab>

  <Tab title="Go SDK">
    ```go theme={null}
    result, err := server.Coupons.Redeem(ctx, playcamp.RedeemCouponParams{
        CouponCode: "CREATOR-ABC12-001",
        UserID:     "user_12345",
        CallbackID: "game-session-abc123", // optional
    })
    ```
  </Tab>
</Tabs>

**응답 (200 OK)**

```json theme={null}
{
  "data": {
    "success": true,
    "usageId": 5678,
    "couponCode": "CREATOR-ABC12-001",
    "reward": [
      { "itemId": "gem", "itemQuantity": 100, "itemImageUrl": "https://cdn.example.com/gem.png" }
    ],
    "packageName": { "ko": "웰컴 패키지" },
    "creatorKey": "ABC12",
    "campaignId": "campaign_001",
    "redeemedAt": "2024-01-15T10:30:00.000Z"
  }
}
```

## 에러 코드

| 코드                     | 설명            |
| ---------------------- | ------------- |
| `COUPON_NOT_FOUND`     | 존재하지 않는 쿠폰    |
| `COUPON_INACTIVE`      | 비활성화된 쿠폰      |
| `COUPON_NOT_YET_VALID` | 사용 기간 전       |
| `COUPON_EXPIRED`       | 만료됨           |
| `USER_CODE_LIMIT`      | 유저별 코드 한도 초과  |
| `USER_PACKAGE_LIMIT`   | 유저별 패키지 한도 초과 |
| `TOTAL_USAGE_LIMIT`    | 전체 한도 초과      |

## 전체 흐름 예시 (Node SDK)

```typescript theme={null}
import { PlayCampServer } from '@playcamp/node-sdk';

const server = new PlayCampServer('your_server_key:your_secret');

async function redeemCoupon(userId: string, couponCode: string) {
  // 1. 검증
  const validation = await server.coupons.validate({ couponCode, userId });

  if (!validation.valid) {
    return {
      success: false,
      error: validation.errorCode,
      message: validation.errorMessage,
    };
  }

  // 2. 사용
  const result = await server.coupons.redeem({ couponCode, userId });

  // 3. 게임 내 보상 지급
  for (const reward of result.reward) {
    await giveItemToUser(userId, reward.itemId, reward.itemQuantity);
  }

  return { success: true, reward: result.reward };
}
```