> ## 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. # 쿠폰 사용 > 쿠폰을 사용하고 보상 정보를 반환합니다. 사용 기록이 DB에 저장되며 웹훅이 발송됩니다. ## OpenAPI ````yaml /api_docs/openapi-ko.yaml post /v1/server/coupons/redeem 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/server/coupons/redeem: post: tags: - Server Coupon summary: 쿠폰 사용 description: | 쿠폰을 사용하고 보상 정보를 반환합니다. 사용 기록이 DB에 저장되며 웹훅이 발송됩니다. operationId: serverRedeemCoupon requestBody: required: true content: application/json: schema: type: object required: - couponCode - userId properties: couponCode: type: string description: 쿠폰 코드 userId: type: string description: 유저 ID gameUserUuid: type: string format: uuid description: 게임 내 유저 UUID (선택) callbackId: type: string description: 웹훅 추적용 ID (이 요청으로 발생하는 웹훅 이벤트에 포함됨) isTest: type: boolean default: false description: 테스트 모드 (실제 데이터 생성 안 함) responses: '200': description: 성공 content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/RedeemResult' '400': description: | 유효하지 않은 쿠폰 또는 사용 불가 - `COUPON_NOT_FOUND`: 존재하지 않는 쿠폰 코드 - `COUPON_INACTIVE`: 비활성화된 쿠폰 - `COUPON_NOT_YET_VALID`: 사용 기간 전 - `COUPON_EXPIRED`: 만료된 쿠폰 - `USER_CODE_LIMIT`: 유저별 코드 사용 한도 초과 - `USER_PACKAGE_LIMIT`: 유저별 패키지 사용 한도 초과 - `TOTAL_USAGE_LIMIT`: 전체 사용 한도 초과 content: application/json: schema: $ref: '#/components/schemas/Error' example: status: 400 error: Bad Request message: Coupon usage limit exceeded code: USER_CODE_LIMIT '401': $ref: '#/components/responses/Unauthorized' security: - ServerAuth: [] components: schemas: RedeemResult: type: object description: 쿠폰 사용 결과 properties: success: type: boolean description: 사용 성공 여부 usageId: type: integer description: 사용 기록 ID couponCode: type: string description: 쿠폰 코드 (대문자) userId: type: string description: 사용한 유저 ID packageId: type: integer description: 쿠폰 패키지 ID itemName: type: object description: 다국어 아이템 이름 additionalProperties: type: string quantity: type: integer description: 아이템 수량 creatorKey: type: string description: 쿠폰에 연결된 크리에이터 키 redeemedAt: type: string format: date-time description: 사용 시각 errorCode: type: string description: '오류 코드 (success: false일 때만)' errorMessage: type: string description: '오류 메시지 (success: false일 때만)' Error: type: object required: - status - error - message - code properties: status: type: integer description: HTTP 상태 코드 error: type: string description: HTTP 상태 이름 message: type: string description: 상세 에러 메시지 code: type: string description: | 에러 코드: - `VALIDATION_ERROR`: 요청 파라미터 검증 실패 - `BAD_REQUEST`: 잘못된 요청 - `UNAUTHORIZED`: 인증 실패 (API 키 오류) - `FORBIDDEN`: 권한 없음 - `NOT_FOUND`: 리소스를 찾을 수 없음 - `CONFLICT`: 중복 리소스 (이미 존재) - `INTERNAL_ERROR`: 서버 내부 오류 details: type: array description: 검증 오류 상세 (VALIDATION_ERROR의 경우) items: type: object properties: path: type: string message: type: string example: status: 404 error: Not Found message: 'Payment not found: txn-12345' code: NOT_FOUND responses: Unauthorized: description: 인증 실패 (API 키 오류) content: application/json: schema: $ref: '#/components/schemas/Error' example: status: 401 error: Unauthorized message: Invalid API key code: UNAUTHORIZED securitySchemes: ServerAuth: type: http scheme: bearer description: 'Server API Key (format: {keyId}:{secret})' ````