학습 URL 발급 API 제안

POST /integrations/v1/student-launches

http

Authorization: Bearer <PARTNER_SERVER_KEY>
Idempotency-Key: <REQUEST_UUID>
Content-Type: application/json

json

{
  "class_task_id": 12345,
  "studyType": "WR",
  "memIdx": "001234567",
  "level": "MA",
  "layer": "RED",
  "unitCd": "1",
  "regYear": "2026",
  "season": "3",
  "regYm": "202609"
}

응답 예시:

json

{
  "success": true,
  "regDate": "2026-09-14 10:00:00",
  "data": {
    "learningRunId": "example-run-id",
    "runNumber": 1,
    "launchUrl": "https://student.example/partner/launch#code=EXAMPLE_ONE_TIME_CODE",
    "expiresAt": "2026-09-14T01:05:00Z"
  }
}

예시 ID·URL은 설명용입니다. 실제 환경 주소와 키는 별도로 제공합니다. learningRunId는 결과 조회에 사용할 학습 차시 식별자이므로 아발론 서버에서 보관합니다.

일회용 URL과 재시도

URL은 한 번만 사용할 수 있습니다. 사용기한은 발급 후 5분으로 제안하며 응답의 expiresAt을 기준으로 처리합니다.
URL 사용기한과 이미 시작한 학습의 실행 권한 유효기간은 구분합니다. URL 사용기한이 지났다는 이유만으로 진행 중 학습이 종료되지는 않습니다.
같은 발급 요청을 네트워크 문제로 재시도할 때는 같은 Idempotency-Key와 같은 내용을 사용합니다.
같은 키에 다른 요청 내용을 보내면 충돌로 처리합니다.
이미 사용했거나 만료된 URL은 새 요청 키로 다시 발급받습니다.
같은 학습 문맥에 미완료 차시가 있으면 이어합니다. 완료된 학습을 다시 시작하면 새 차시를 생성하고 이전 결과를 보존합니다.

unitCd는 교재 회차이고 runNumber는 해당 학습의 재수행 순번입니다. URL 재발급 자체는 신규 차시를 의미하지 않습니다.

학습 창 열기

학생의 시작 버튼 클릭 시 window.open()으로 창을 먼저 열고, 아발론 서버가 받은 URL을 해당 창에 설정하는 방식을 권장합니다. 비동기 API 응답을 받은 뒤 처음 창을 열면 브라우저가 팝업을 차단할 수 있습니다.

팝업 차단·URL 발급 실패는 아발론 화면에서 안내합니다. 브라우저 정책상 자동 닫기가 허용되지 않는 경우 플랭은 학습 완료 화면과 수동 닫기 안내를 표시합니다. 창 닫힘 여부를 학습 완료의 유일한 근거로 사용하지 않고 결과 API에서 완료 상태를 확인합니다.

학습 URL 발급 API 제안 ​

일회용 URL과 재시도 ​

학습 창 열기 ​

학습 URL 발급 API 제안

일회용 URL과 재시도

학습 창 열기