API Reference · 영어 퀴즈

퀴즈 슬롯 시작

슬롯 풀이를 시작합니다. 시작 전에 시청한 보상형 광고의 티켓(impression_id)을 서버가 소비하고, 이후 답안 제출을 받을 수 있는 상태(in_progress)가 됩니다.

POST/api/v1/contents/{content_id}/quiz/slots/{slot_key}/start

요청 파라미터

content_id (path, uuid, required) — 퀴즈 콘텐츠 ID.
slot_key (path, string, required) — today 응답의 슬롯 키(YYYYMMDD-N).
impression_id (body, string, required) — 광고 SDK 가 placement quiz_start 보상형 광고 노출 보고로 받은 티켓. 최소 시청 시간을 채워야 유효합니다.

요청예시

shell

curl -X POST -H "Authorization: Bearer sess_prod_0193a1b2-3c4d-7e6f-8890-abcdef012345" \
     -H "Content-Type: application/json" \
     -d '{"impression_id":"01a0f522-bd38-7cd5-a21e-5716c168722f"}' \
     "https://added.blomics.net/api/v1/contents/0193a1b2-3c4d-5e6f-7890-abcdef012345/quiz/slots/20261001-2/start"

재호출은 안전합니다

이미 시작한 슬롯에 다시 호출하면 티켓을 소비하지 않고 현재 상태를 그대로 돌려줍니다(already_started: true, impression_id 생략 가능). 앱 재진입·네트워크 재시도 때 광고를 다시 보여줄 필요가 없습니다. 세션이 바뀌어도 같은 사용자의 같은 슬롯이면 동일합니다.

응답 필드

200 OK — 오늘의 퀴즈 조회의 슬롯 필드(slot_key, status, solved_count, answer_deadline …)에 더해:

already_started (boolean) — 이번 호출 전에 이미 시작돼 있었는지.
items (array, 3개) — 문항(정답 제외). 필드는 today 의 items 와 같습니다.

응답예시

json

{
  "slot_key": "20261001-2", "serve_date": "2026-10-01", "slot": 2,
  "start_at": "2026-10-01T00:00:00.000Z", "end_at": "2026-10-01T03:00:00.000Z",
  "answer_deadline": "2026-10-01T03:10:00.000Z",
  "status": "in_progress", "solved_count": 0, "item_count": 3,
  "already_started": false,
  "items": [
    { "item_id": "01a0f522-0000-7000-8000-000000000004", "position": 1, "word": "surge",
      "question": "여행 수요 surge…연휴 항공권 매진 행렬", "answers": ["급증", "감소", "정체"],
      "source_url": "https://news.example.com/articles/1", "solved": false }
    // … position 2, 3
  ]
}

에러처리

400 INVALID_PARAM — slot_key 형식 오류, impression_id 형식 오류.
401 UNAUTHORIZED / SESSION_EXPIRED — 세션 인증 실패·만료.
404 NOT_FOUND — 퀴즈 콘텐츠가 아니거나 세션 콘텐츠 불일치.
499 QUIZ_AD_REQUIRED — 티켓 없음·무효. data.reason: impression_invalid(없는 티켓/다른 세션), impression_consumed(이미 사용), impression_superseded(더 새 광고에 밀림), impression_mismatch(퀴즈용 아닌 지면), dwell_too_short(시청 시간 미달).
499 QUIZ_SLOT_NOT_OPEN — 지금 시작할 수 없는 슬롯(시작 전·종료). data.start_at · data.end_at 포함.
499 QUIZ_NOT_READY — 오늘 문제 편성 없음(데이터 준비 전).
500 INTERNAL_ERROR — 서버 오류.