> ## 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.

# 쿠폰 유효성 검사



## OpenAPI

````yaml /api_docs/openapi-ko.yaml post /v1/client/coupons/validate
openapi: 3.0.3
info:
  title: PlayCamp SDK API
  description: |
    PlayCamp SDK API - 게임 분석 및 크리에이터 캠페인 연동 API

    ## 필수 연동 API (Server API)
    캠페인 진행을 위해 반드시 연동해야 하는 API 3개:
    - `POST /v1/server/sponsors` - 유저가 크리에이터를 부스트
    - `POST /v1/server/coupons/validate` - 쿠폰 코드 유효성 검사
    - `POST /v1/server/payments` - 인게임 결제 등록

    ## 인증 방식
    - **Client API**: `Authorization: Bearer {CLIENT_KEY_ID}:{CLIENT_SECRET}`
    - **Server API**: `Authorization: Bearer {SERVER_KEY_ID}:{SERVER_SECRET}`

    ## 서버
    - **Live**: https://sdk-api.playcamp.io (실제 데이터)
    - **Sandbox**: https://sandbox-sdk-api.playcamp.io (테스트 데이터)

    ## 키 타입
    - **Client 키**: 게임 클라이언트용 (읽기 전용 - 캠페인, 크리에이터 조회)
    - **Server 키**: 게임 서버용 (읽기/쓰기 - 쿠폰 사용, 결제 등록 등)

    ## 테스트 모드 (isTest)
    캠페인 실행 전에 `isTest: true` 파라미터를 사용하여 API 연동을 테스트할 수 있습니다.
    - 요청 파라미터 검증은 실제와 동일하게 수행
    - 모의 데이터를 반환하며 실제 DB에 기록되지 않음
    - 캠페인 시작 전 Sandbox 환경에서 연동 검증 후, 실제 캠페인 시 `isTest` 파라미터 제거
  version: 1.1.0
  contact:
    name: PlayCamp Support
servers:
  - url: https://sdk-api.playcamp.io
    description: Live Server
  - url: https://sandbox-sdk-api.playcamp.io
    description: Sandbox Server
  - url: http://localhost:3001
    description: Local Live Server
  - url: http://localhost:3003
    description: Local Sandbox Server
security: []
tags:
  - name: Health
    description: 서버 상태 확인
  - name: Client Campaign
    description: 캠페인 조회 (Client API)
  - name: Client Creator
    description: 크리에이터 조회 (Client API)
  - name: Client Coupon
    description: 쿠폰 유효성 검사 (Client API)
  - name: Client Sponsor
    description: 부스트 상태 조회 — Sponsor API (Client API)
  - name: Server Campaign
    description: 캠페인 조회 (Server API)
  - name: Server Creator
    description: 크리에이터 조회 (Server API)
  - name: Server Coupon
    description: 쿠폰 관리 (Server API)
  - name: Server Sponsor
    description: 부스트 관리 — Sponsor API (Server API)
  - name: Server Payment
    description: 결제 관리 (Server API)
  - name: Server Playtime
    description: 플레이타임 세션 관리 (Server API)
  - name: Server Webhook
    description: 웹훅 관리 (Server API)
  - name: Server Webview
    description: WebView 관리 (Server API)
paths:
  /v1/client/coupons/validate:
    post:
      tags:
        - Client Coupon
      summary: 쿠폰 유효성 검사
      operationId: clientValidateCoupon
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - couponCode
              properties:
                couponCode:
                  type: string
      responses:
        '200':
          description: 성공
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    $ref: '#/components/schemas/CouponValidation'
      security:
        - ClientAuth: []
components:
  schemas:
    CouponValidation:
      type: object
      description: 쿠폰 유효성 검사 결과 (valid 여부에 따라 필드 다름)
      properties:
        valid:
          type: boolean
          description: 쿠폰 유효 여부
        couponCode:
          type: string
          description: 쿠폰 코드 (대문자)
        reward:
          type: array
          description: 보상 아이템 (유효할 때만)
          items:
            type: object
            properties:
              itemName:
                type: object
                description: 다국어 아이템 이름
                additionalProperties:
                  type: string
              itemId:
                type: string
              itemQuantity:
                type: integer
              itemImageUrl:
                type: string
                format: uri
                nullable: true
                description: 보상 아이템 이미지 URL
        itemName:
          type: object
          description: 다국어 아이템 이름 (유효할 때만)
          additionalProperties:
            type: string
        errorCode:
          type: string
          description: |
            실패 사유 코드 (valid: false일 때만):
            - `COUPON_NOT_FOUND`: 유효하지 않은 쿠폰 코드
            - `COUPON_INACTIVE`: 비활성화된 쿠폰
            - `COUPON_NOT_YET_VALID`: 사용 기간 전
            - `COUPON_EXPIRED`: 만료된 쿠폰
            - `USER_CODE_LIMIT`: 유저별 코드 사용 한도 초과
            - `USER_PACKAGE_LIMIT`: 유저별 패키지 사용 한도 초과
            - `TOTAL_USAGE_LIMIT`: 전체 사용 한도 초과
        errorMessage:
          type: string
          description: '오류 메시지 (valid: false일 때만)'
  securitySchemes:
    ClientAuth:
      type: http
      scheme: bearer
      description: 'Client API Key (format: {keyId}:{secret})'

````