고객센터어드민

API Reference · 세션

세션 조회

콘텐츠사가 게이트웨이로부터 리다이렉트로 받은 session_id 를 검증하고, 어떤 매체사·사용자·콘텐츠로 발행된 세션인지 확인합니다.

GET/api/v1/sessions/{session_id}

요청 파라미터

  • session_id (path, uuid, required) — 검증할 세션 식별자 (게이트웨이가 콘텐츠 URL 의 query 로 전달).
  • include (query, string, optional) — 추가로 받을 항목을 콤마로 나열합니다. 현재 promo_claims(경품 당첨 목록) 하나를 지원하며, 지정하지 않으면 응답에 그 키가 아예 없습니다. 세션 조회는 게임이 자주 부르는 경로이므로 당첨 안내가 필요한 시점(부팅· 화면 복귀)에만 붙이는 것을 권장합니다.

요청예시

shell
curl -H "Authorization: Bearer sess_prod_0192a1b2-3c4d-7e8f-9012-3456789abcde" \
     "https://added.blomics.net/api/v1/sessions/0192a1b2-3c4d-5e6f-7890-abcdef012345"

응답 필드

  • session_id (uuid)
  • user_id (uuid) — Blomics 내부 사용자 식별자.
  • publisher_id (uuid) — 발행 매체사.
  • content_id (uuid) — 진입한 콘텐츠.
  • campaign_id (uuid) — 세션이 속한 캠페인. 세션 발급 시점에 고정되는 스냅샷입니다. 플레이로그 등 기록/보상 경로는 이 값을 사용합니다.
  • ranking_campaign_id (uuid) — 랭킹 조회에 사용할 캠페인. 진행 중이면서 랭킹을 제공하는 캠페인 중 가장 최근에 시작한 것을 요청 시점에 골라 반환합니다(진행 중인 프로모션이 있으면 그것). 후보가 없으면 campaign_id 와 같은 값이므로 이 필드만 그대로 사용하면 됩니다. 프로모션 랭킹은 부모 상시 캠페인의 기록을 프로모션 기간으로 잘라 집계한 결과입니다.
  • nickname (string | null) — 매체사가 게이트웨이로 전달한 사용자 닉네임. 전달하지 않은 경우 user_id 값으로 대체됩니다.
  • expired_at (ISO 8601) — 세션 만료 시각. 이 시각 이후 이벤트는 거부됩니다.
  • promo_claims (array) — include=promo_claims 를 지정했을 때만 포함됩니다. 이 사용자가 당첨된 경품 수집 목록이며, 당첨이 없으면 빈 배열입니다(진행 중인 프로모션의 존재 여부도 알려주지 않습니다). 한 사용자가 동시에 둘 이상 당첨될 수 있으므로항목마다 캠페인이 다릅니다 — 안내 팝업과 링크를 항목 단위로 다루세요. 신청 가능한 건이 앞에 옵니다.
    • campaign_id (uuid) — 어느 프로모션의 당첨인지.
    • available (boolean) — 항상 true(당첨 목록이므로).
    • claimed (boolean) — 수령정보 신청을 마쳤는지.
    • claim_id (uuid | null) — 신청을 마친 건의 접수 식별자. 신청 전에는 null.
    • title, description (string | null) — 신청 화면의 제목·안내문.
    • prize_brand, prize_detail, win_notice (string | null) — 게임 당첨 안내에 쓸 브랜드·당첨내용·안내 문구. 어드민 경품 수집 설정에서 캠페인별로 입력하며, 비어 있으면 콘텐츠 공통 설정으로 폴백하도록 클라이언트가 처리합니다.
    • url (string) — 수령정보 신청 페이지의 절대 URL (세션·캠페인 포함). 외부 브라우저로 열어야 합니다.

응답예시

json
{
  "session_id": "0192a1b2-3c4d-5e6f-7890-abcdef012345",
  "user_id": "0195d4e5-6f78-90ab-cdef-012345678901",
  "publisher_id": "0194c3d4-5e6f-7890-abcd-ef0123456789",
  "content_id": "0193b2c3-4d5e-6f78-90ab-cdef01234567",
  "campaign_id": "0196e5f6-7890-abcd-ef01-234567890123",
  "ranking_campaign_id": "0197f607-8901-bcde-f012-3456789abcde",
  "nickname": "초코나라",
  "expired_at": "2026-05-02T12:00:00.000Z"
}

응답예시 — ?include=promo_claims

json
{
  "session_id": "0192a1b2-3c4d-5e6f-7890-abcdef012345",
  "user_id": "0195d4e5-6f78-90ab-cdef-012345678901",
  "…": "(위 응답 필드 동일)",
  "promo_claims": [
    {
      "campaign_id": "0196e5f6-7890-abcd-ef01-234567890123",
      "available": true,
      "claimed": false,
      "claim_id": null,
      "title": "쿠폰 신청",
      "description": "당첨을 축하드립니다. 쿠폰을 받으실 정보를 입력해주세요.",
      "prize_brand": "누구나홀딱반한닭",
      "prize_detail": "2만원 쿠폰",
      "win_notice": "자세한 내용은 공지사항을 확인해 주세요",
      "url": "https://added.blomics.net/cs/promo?session_id=0192a1b2-3c4d-5e6f-7890-abcdef012345&campaign_id=0196e5f6-7890-abcd-ef01-234567890123"
    }
  ]
}

에러처리

  • 400 INVALID_PARAM — session_id 형식 오류.
  • 401 UNAUTHORIZED — 인증 실패.
  • 404 NOT_FOUND — 세션 없음, 만료, 또는 다른 콘텐츠사 소속.
  • 500 INTERNAL_ERROR — 서버 오류.