연동 개요

역할과 인증

• 관리자 — 룰렛 관리 화면에서 매체 공통·매체 콘텐츠 전용 룰렛, 허용 티켓 유형, 지급 경로를 설정합니다.
• 매체사 서버 — sk_pub_* Bearer 키로 자기 매체의 게시된 룰렛과 콘텐츠별 지급 경로를 조회합니다.
• 콘텐츠사 서버 — sk_prov_* Bearer 키로 자기 콘텐츠에 활성 지급 경로가 있는 룰렛을 조회합니다. 이 키를 웹 페이지에 넣지 마세요.
• 콘텐츠 웹 — 게이트웨이가 전달한 session_id의 세션 토큰(sess_*)으로 룰렛 목록·상세·티켓함을 조회하고 추첨합니다. 경로의 content_id는 토큰의 콘텐츠와 같아야 합니다.

콘텐츠 웹의 호출 순서

1. 세션 토큰을 준비하고 콘텐츠 룰렛 목록을 조회합니다.
2. 선택한 룰렛의 활성 칸 구성과 티켓함을 조회합니다.
3. 룰렛이 사용 가능하고 허용된 유형의 티켓이 있으면 추첨 API를 한 번 호출합니다. 네트워크 오류에는 같은 idempotency_key로 재시도합니다.
4. 응답의 reward.slot_id와 roulette_id를 기준으로 결과를 표시하고 티켓 수량을 갱신합니다. delivery가 있으면 지급 상태도 별도로 표시합니다.
5. 추첨을 claim: "deferred"로 했다면 포인트 당첨은 아직 지급되지 않은 상태(claim_status: "unclaimed")입니다. 당첨 팝업의 '보상 받기'에서 당첨 보상 받기를 호출해 지급합니다.
6. 다음 진입 때 미수령 당첨 조회로 받지 않은 당첨을 확인해 팝업을 다시 띄웁니다.

포인트 지급

관리자가 룰렛의 각 매체 콘텐츠에 campaign_id·event_id 지급 경로를 연결합니다. 서버가 티켓 소비, 추첨, 이벤트 기록과 지급을 처리합니다. 매체사 설정에 따라 포인트 포스트백 또는 내부 적립을 사용하며, 0포인트 칸은 포스트백을 보내지 않습니다. 콘텐츠 웹이 별도의 이벤트 API로 당첨을 보고하면 중복 지급 위험이 있으므로 추첨 결과만 사용하세요. 포스트백 수신 측은 postback_id로 중복 적립을 방지하세요.

지급 시점

추첨 요청의 claim으로 포인트 지급 시점을 고릅니다. 생략하거나 "auto"면 추첨 응답 전에 지급합니다(기존 방식). "deferred"면 추첨은 당첨 칸 결정·티켓 차감·결과 반환까지만 하고, 포스트백 또는 내부 적립은 사용자가 당첨 팝업에서 '보상 받기'를 눌러 보상 받기 API를 호출할 때 일어납니다. 예산·한도 판정과 당첨 기록은 두 방식 모두 추첨 시점에 합니다. 꽝은 받을 것이 없어 늘 즉시 완료됩니다. 받지 않은 당첨은 기간 제한 없이 남으며 미수령 당첨 조회로 다시 안내합니다.

API 목록