API Reference · 룰렛·티켓

당첨 보상 받기

지연 지급(claim: deferred)으로 뽑은 포인트 당첨을 당첨 팝업의 '보상 받기' 시점에 지급합니다.

POST/api/v1/contents/{content_id}/roulettes/draws/{draw_id}/claim

요청

Authorization: Bearer sess_* — 콘텐츠 세션 토큰.
content_id (path) — 토큰의 콘텐츠와 일치해야 합니다.
draw_id (path) — 룰렛 추첨 또는 미수령 당첨 조회 응답의 draw_id(UUID).
session_id (body, 필수) — 토큰의 세션 ID와 일치해야 합니다.

세션의 회원·매체가 그 추첨의 회원·룰렛 매체와 같아야 합니다. 추첨한 콘텐츠와 달라도 같은 매체의 룰렛이면 받을 수 있습니다. 별도의 멱등 키는 없으며, 추첨 한 건당 지급은 한 번만 일어납니다.

shell

curl -X POST \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{"session_id":"<session_uuid>"}' \
  "https://added-dev.blomics.net/api/v1/contents/<content_id>/roulettes/draws/<draw_id>/claim"

성공 응답

200 — 룰렛 추첨 응답과 같은 모양이며 claim_status: "claimed"가 붙습니다. 이때 포스트백(또는 내부 적립)이 만들어지므로 postback_id·delivery·delivery_code가 채워집니다. remaining_tickets는 그 추첨에 쓴 티켓 유형의 현재 잔여 수량입니다.

json

{
  "draw_id": "<draw_uuid>",
  "roulette_group_id": "<group_uuid>",
  "roulette_id": "<roulette_uuid>",
  "roulette_version": 1,
  "ticket_id": "<consumed_ticket_uuid>",
  "reward": { "slot_id": "<slot_uuid>", "label": "100P", "display_order": 0,
    "reward_type": "point", "point": 100 },
  "event_log_id": "<event_log_uuid>",
  "postback_id": "<postback_uuid>",
  "delivery": "delivered",
  "delivery_code": null,
  "remaining_tickets": 2,
  "duplicate": false,
  "claim_status": "claimed"
}

지급 결과 필드

delivery — 매체 포스트백 상태. delivered는 매체가 적립을 확인했고, pending은 발송 대기·결과 확인 중이며, failed는 매체가 거절했습니다. 포스트백이 없는 매체(내부 적립)에는 포함되지 않습니다.
delivery_code — 매체가 돌려준 결과 코드. 아직 없으면 null입니다.
user_message — 매체가 적립을 거절했을 때 그 매체 설정의 사용자 안내 문구(예: 적립 한도 초과). 있으면 그대로 표시하세요. 다시 호출해도 같은 문구를 돌려줍니다.
balance_after — 내부 적립 매체의 적립 후 잔액.

동기 발송을 쓰는 매체는 응답 전에 매체 1차 발송 결과를 기다려 delivered 또는 failed로 돌려줍니다. 그 밖의 매체는 발송을 큐에 등록하고 pending을 돌려주므로 "적립 처리 중"으로 안내하세요. failed인데 user_message가 없으면 일반 실패 문구를 표시하세요.

중복 호출과 재시도

추첨 한 건당 지급은 한 번입니다. 이미 지급된 추첨에 다시 호출하면 새로 지급하지 않고 같은 결과를 duplicate: true로 돌려줍니다(동시에 두 번 호출해도 지급은 한 건). 따라서 네트워크 오류·시간 초과·서버 오류 후에는 같은 draw_id로 안전하게 다시 호출할 수 있습니다. 즉시 지급(claim 생략)으로 뽑은 추첨이나 꽝에 호출해도 이중 지급 없이 현재 상태를 돌려줍니다.

오류 처리

400 INVALID_PARAM — 본문의 session_id 누락.
401 UNAUTHORIZED / SESSION_EXPIRED — 세션 인증 실패·만료.
404 NOT_FOUND — 경로의 콘텐츠 또는 본문 세션 ID가 세션 토큰과 불일치하거나, draw_id가 UUID가 아니거나 없는 추첨이거나, 다른 회원·다른 매체의 추첨입니다. 남의 추첨은 존재 여부를 드러내지 않도록 모두 404로 응답합니다.

예산·한도 등 지급 조건 판정은 추첨 시점에 끝났으므로 보상 받기에서 499 지급 조건 거부는 나오지 않습니다. 매체의 적립 거절은 오류가 아니라 200 응답의 delivery: "failed"로 전달됩니다. 오류 본문은 공통 { code, message, data } 형식입니다.