사전 준비와 역할

항목	준비 내용
조직	플랭에서 아발론 조직을 사전 설정합니다. 학습 요청마다 조직을 생성하지 않습니다.
학습 활동	플랭이 아발론의 studyType·level·layer·unitCd·regYear·season 6개 값을 플랭 활동에 연결하는 대응표를 관리합니다. 아발론 서버는 진입 정보에 6개 값만 넣고 플랭 활동 ID는 보내지 않습니다. 활동 목록 CSV로 등록된 대응을 확인합니다. 활동 하나는 RA·WR·SP 중 한 유형이며 복합 활동은 제공하지 않습니다.
진입 암호화 키	플랭이 환경별로 256비트 비밀키와 키 ID(`kid`)를 생성해 보안 경로로 전달합니다. 아발론 서버와 플랭 서버에만 보관합니다. 교체 절차는 암호화 규약을 따릅니다.
조회 API 키	활동 CSV·학습 결과·학습이력 조회용 Bearer key(`plk_`로 시작)를 환경별로 별도 발급합니다. 진입 암호화 키와 구분하며 아발론 서버에서만 사용합니다. 플랭은 키의 해시만 보관하므로 분실 시 재발급합니다.
학생	아발론의 고정 학생 ID만 전달합니다. 학생 이름은 받지 않으며, 아발론 연동 범위의 학생 ID로 동일 학생을 판별합니다.
그룹	`level`을 OrgGroupSet, `layer`를 그 아래 OrgGroup에 연결합니다. 별도 그룹 ID·이름은 전달하지 않습니다.
기수	`regYear + season`으로 구분합니다. 둘 중 하나라도 바뀌면 새 기수의 OrgGroupSetBundle 아래에 같은 level·layer여도 새 OrgGroupSet·OrgGroup을 생성합니다. 학생 ID와 이전 기수 이력은 유지합니다.
루브릭	아발론이 제공한 루브릭을 대상 태스크에 항상 설정합니다. 실제 평가항목·점수 범위·배점 기준을 사용합니다.

학생 사전 일괄 등록은 필요하지 않습니다. 학습 요청 시 학생 ID를 확인하고 없으면 자동 생성합니다. 아발론은 사용량 기반으로 이용하며, 학생 수 상한 없이 추가할 수 있습니다. 좌석 수나 개인 이용권으로 등록·학습을 제한하지 않으며 학생 비활성화 절차도 없습니다. 같은 학생의 동일 기수 내 level·layer는 고정이며, 학적 변경과 기존 계정 연결·병합은 연동 범위에 포함하지 않습니다.

활동 목록 CSV 다운로드

GET /integrations/v1/class-tasks.csv

아발론 서버가 서버 전용 키로 호출하면 현재 진입할 수 있는 대응표 항목 목록을 CSV 파일로 받습니다. 한 행이 6개 값 조합 하나이며, 그 조합이 연결된 플랭 활동의 ID·활동명을 함께 보여 줍니다. 생성이 완료된 단일 태스크이고 지원 유형(RA V3·WR·SP)이며 studyType과 활동 유형이 맞는 항목만 나옵니다. 대응이 추가되거나 활동명이 변경되면 다시 다운로드하여 목록을 갱신합니다.

http

Authorization: Bearer <PARTNER_SERVER_KEY>
Accept: text/csv

성공 응답은 JSON이 아닌 CSV 파일입니다.

http

Content-Type: text/csv; charset=utf-8
Content-Disposition: attachment; filename="class-tasks.csv"

CSV 컬럼	의미
studyType, level, layer, unitCd, regYear, season	진입 정보에 넣을 6개 값. 이 조합 하나가 활동 하나입니다
class_task_container_id	그 조합에 연결된 플랭 활동 ID. 확인용 참고 값이며 진입·조회 요청에는 넣지 않습니다
class_task_name	플랭 활동명

csv

studyType,level,layer,unitCd,regYear,season,class_task_container_id,class_task_name
RA,MA,RED,U01,2026,3,12345,MA RED Unit 1 읽기
SP,MA,RED,U01,2026,3,12347,MA RED Unit 1 말하기
WR,MA,RED,U01,2026,3,12346,MA RED Unit 1 쓰기
WR,MA,RED,U01,2026,4,12348,MA RED Unit 1 쓰기 (2026 겨울)

위 값은 설명용입니다. 실제 응답은 다운로드 시점의 대응표이며 studyType·level·layer·regYear·season·unitCd 순으로 정렬합니다. 조합 하나는 플랭 활동 하나에 연결되며, 한 플랭 활동이 여러 조합에 함께 쓰이지 않습니다. 그래서 같은 class_task_container_id는 한 행에만 나옵니다. 마지막 행처럼 같은 단원이라도 기수가 다르면 별도의 플랭 활동입니다. 엑셀·구글 시트에서 한글이 깨지지 않도록 UTF-8 BOM을 붙이고 행은 CRLF로 끝납니다. 경로는 .csv 확장자까지 포함해야 합니다. 대상이 없으면 헤더만 있는 CSV를 반환합니다. 인증 오류 등 실패 시에는 아래 공통 JSON 오류 응답을 반환합니다. CSV는 아발론 서버가 내려받으며 학생 학습 창에는 활동 목록을 제공하지 않습니다.

조회 API 공통 응답

조회 API의 오류 응답은 모두 아래 JSON 형식입니다. 성공 응답은 활동 CSV가 CSV 파일, 학습이력 조회가 연동문서 v0.5 형식(request, totalCount, data[])이며, 그 외는 아래 성공 형식입니다.

json

{ "success": true, "regDate": "2026-09-30 16:00:00", "data": { } }

json

{
  "success": false,
  "regDate": "2026-09-30 16:00:00",
  "data": null,
  "error": { "code": "INVALID_INPUT", "message": "…", "requestId": "…", "fields": ["from"] }
}

regDate는 응답 생성 시각(한국시간 YYYY-MM-DD HH:mm:ss)입니다. fields는 입력 오류에만 붙습니다. 문의할 때 requestId를 함께 알려 주세요.

HTTP	코드	의미
401	`INVALID_PARTNER_KEY`	Bearer key 누락·불일치
422	`INVALID_INPUT`	요청 형식·범위 오류
422	`CONTAINER_NOT_READY`	활동 CSV: 연동 대상 활동 중 활동명이 비어 있는 활동이 있음. 플랭이 수정
503	`TEMPORARILY_UNAVAILABLE`	일시 장애. 잠시 후 재시도

사전 준비와 역할 ​

활동 목록 CSV 다운로드 ​

조회 API 공통 응답 ​

사전 준비와 역할

활동 목록 CSV 다운로드

조회 API 공통 응답