Soonlife DOCS
API 레퍼런스

성적 API

누적성적, 학기성적, 성적표(가정통신문), 졸업진도 조회

엔드포인트 목록

메서드경로설명
GET/api/grades/overview/누적성적 — 학기별 평점/학점 현황
GET/api/grades/subjects/누적성적 — 학기별 과목 성적 상세
GET/api/grades/semester/해당 학기 성적 조회
GET/api/grades/semester-report/성적표(가정통신문) 메타 정보
GET/api/grades/semester-report/url/성적표(가정통신문) 출력 URL
GET/api/graduation/detail/졸업진도 상세 (학점 매트릭스 + 필수과목)
POST/api/graduation/sync/졸업진도 이수내용 새로고침

모든 엔드포인트는 sch_session 쿠키 인증이 필요합니다.

GET /api/grades/overview/

학기별 누적 현황(평점평균·취득학점)을 반환합니다. SCH 서버에서 실시간 조회합니다.

응답

200 OK

{
  "semesters": [
    {
      "yy":      "2021",
      "smt":     "11",
      "sust_cd": "01",
      "label":   "2021-1",
      "gpa":     3.8,
      "credits": 18,
      "sust_rank":      "12",
      "sust_rank_rcnt": "84",
      "univ_rank":      "203",
      "univ_rank_rcnt": "1450"
    },
    {
      "yy":      "2021",
      "smt":     "21",
      "sust_cd": "01",
      "label":   "2021-2",
      "gpa":     4.0,
      "credits": 19,
      "sust_rank":      "",
      "sust_rank_rcnt": "",
      "univ_rank":      "",
      "univ_rank_rcnt": ""
    }
  ]
}
필드타입설명
semesters[].yystring학년도
semesters[].smtstring학기 코드 (11=1학기, 21=2학기, 12=하계, 22=동계)
semesters[].sust_cdstring학적 구분 코드 — grades/subjects/ 조회 시 함께 전달 필요
semesters[].labelstring표시용 레이블 ("YYYY-N" 형식)
semesters[].gpanumber해당 학기 평점평균
semesters[].creditsnumber해당 학기 취득학점
semesters[].sust_rankstring학과 석차 — 석차가 산출되지 않은 학기는 빈 문자열
semesters[].sust_rank_rcntstring학과 전체 인원
semesters[].univ_rankstring대학(단과대) 석차
semesters[].univ_rank_rcntstring대학(단과대) 전체 인원

sust_cd는 예체능/논문 계열 등 학적 구분에 따라 다른 성적 컬럼을 반환받기 위해 필요한 값입니다. grades/subjects/ 요청 시 반드시 함께 전달하세요.

에러 응답

에러 코드HTTP설명
UNAUTHORIZED401세션 없음
SCH_UNAVAILABLE503SCH 서버에서 성적 정보를 가져오지 못함

GET /api/grades/subjects/

특정 학기의 과목별 성적 상세를 반환합니다.

쿼리 파라미터

파라미터필수설명
yyO학년도 (예: 2024)
smtO학기 코드 (11 / 21 / 12 / 22)
sust_cd권장grades/overview/ 응답의 sust_cd 값
GET /api/grades/subjects/?yy=2024&smt=11&sust_cd=01

응답

200 OK

{
  "subjects": [
    {
      "과목코드": "CS3001",
      "과목명":   "자료구조",
      "학점":     "3",
      "등급":     "A+",
      "점수":     "97.5",
      "이수구분": "전공필수"
    }
  ]
}

subjects 배열의 각 항목은 Record<string, string> 타입입니다. SCH 서버가 학적 구분에 따라 다른 컬럼명을 반환할 수 있으므로, 원본 컬럼 ID를 키로 그대로 전달합니다.

에러 응답

에러 코드HTTP설명
UNAUTHORIZED401세션 없음
MISSING_PARAMS400yy 또는 smt 누락
SCH_UNAVAILABLE503SCH 서버 연결 실패

GET /api/grades/semester/

해당 학기 성적을 조회합니다. yy, smt를 생략하면 현재 학기를 자동으로 판별합니다.

쿼리 파라미터

파라미터필수설명
yy아니오학년도 — 생략 시 현재 학기 자동 판별
smt아니오학기 코드 (11 / 21 / 12 / 22)

응답

200 OK

{
  "yy":       "2025",
  "smt":      "11",
  "can_view": true,
  "eval_yn":  "N",
  "ums_yn":   "Y",
  "grades": [
    {
      "과목코드": "CS4001",
      "과목명":   "졸업프로젝트",
      "학점":     "3",
      "등급":     "A0"
    }
  ]
}
필드타입설명
yystring조회된 학년도
smtstring조회된 학기 코드
can_viewboolean성적 공개 여부 — false이면 grades는 빈 배열
eval_ynstring강의평가 완료 여부 ("Y" / "N" / "") — 미완료 시 성적 비공개
ums_ynstringUMS 인증 여부 ("Y" / "N" / "")
gradesarray과목별 성적 목록 (can_view=false이면 빈 배열)

can_view가 false인 경우, 강의평가(eval_yn="N")나 기타 선행 조건 미완료 때문입니다. 이 경우 grades는 항상 빈 배열입니다.

에러 응답

에러 코드HTTP설명
UNAUTHORIZED401세션 없음
NO_PERIOD404현재 성적 조회 기간이 아님 (yy/smt 생략 시)
INVALID_SMT400허용되지 않은 smt 값
SCH_UNAVAILABLE503SCH 서버 연결 실패

GET /api/grades/semester-report/

성적표(가정통신문) 출력에 필요한 메타 정보를 반환합니다.

응답 — 200 OK: 출력 파라미터 정보 (SCH 서버 응답)

GET /api/grades/semester-report/url/

성적표(가정통신문) 출력 URL을 반환합니다.

응답 — 200 OK

{
  "url": "https://..."
}

GET /api/graduation/detail/

졸업진도 상세 정보를 반환합니다. 학점 매트릭스, 비교과 역량 점수, 필수 이수 교과목 목록을 포함합니다.

응답

200 OK

{
  "student": {
    "nm":       "홍길동",
    "shyr":     "4 학년/7 학기이수",
    "sust_nm":  "컴퓨터소프트웨어공학과",
    "univ_nm":  "공과대학",
    "entn_yy":  "2021",
    "med_yn":   "N",
    "yy_cnt":   7
  },
  "credits": {
    "lib_cdt":   36,
    "tlib_cdt":  36,
    "clib_cdt":  36,
    "cr_lib_cdt":  12,
    "tcr_lib_cdt": 12,
    "dr_lib_cdt":  12,
    "tdr_lib_cdt": 12,
    "s_lib_cdt":   12,
    "ts_lib_cdt":  12,
    "mjr_cdt":   60,
    "tmjr_cdt":  64,
    "cmjr_cdt":  60,
    "f_mjr_cdt": 30,
    "tf_mjr_cdt": 32,
    "r_mjr_cdt": 18,
    "tr_mjr_cdt": 20,
    "s_mjr_cdt": 12,
    "ts_mjr_cdt": 12,
    "gdt_cdt":   140,
    "tgdt_cdt":  140,
    "cgdt_cdt":  136,
    "symp_sco":  10,
    "cesymp_sco": 10,
    "rsymp_sco": 0,
    "cons_sco":  5,
    "ccons_sco": 5,
    "rcons_sco": 0,
    "gloc_sco":  10,
    "csgloc_sco": 10,
    "rsgloc_sco": 0,
    "comp_sco":  5,
    "ccomp_sco": 3,
    "rcomp_sco": 2,
    "mod_dt_tm": "2025-06-01 14:30:00"
  },
  "subjects": [
    {
      "unit_div_nm":      "교양",
      "sbjt_kor_nm":      "글쓰기와 의사소통",
      "cdt":              "3",
      "com_yn":           "이수",
      "com_yy_smt":       "2021-1",
      "com_sbjt_kor_nm":  "",
      "sngj_grade":       "A+"
    },
    {
      "unit_div_nm":      "전공",
      "sbjt_kor_nm":      "캡스톤디자인",
      "cdt":              "3",
      "com_yn":           "이수중",
      "com_yy_smt":       "",
      "com_sbjt_kor_nm":  "",
      "sngj_grade":       ""
    }
  ]
}

student 필드:

필드타입설명
nmstring이름
shyrstring학년/이수 학기
sust_nmstring학과명
univ_nmstring단과대학명
entn_yystring입학연도
med_ynstring의대생 여부 ("Y" / "N") — "Y"이면 학년이수로 표시
yy_cntnumber이수 학기 수

credits 주요 필드:

필드 패턴설명
lib_cdt교양 요구학점
tlib_cdt교양 수강 포함 이수학점
clib_cdt교양 확정 취득학점
mjr_cdt전공 요구학점
tmjr_cdt전공 수강 포함 이수학점
cmjr_cdt전공 확정 취득학점
gdt_cdt졸업 요구 총학점
tgdt_cdt수강 포함 이수 총학점
cgdt_cdt확정 취득 총학점
symp_sco심포지엄 요구점수
cesymp_sco심포지엄 취득점수
rsymp_sco심포지엄 잔여점수
mod_dt_tm마지막 갱신 일시

subjects 항목 필드:

필드타입설명
unit_div_nmstring이수구분 (교양, 전공필수, 학초 등)
sbjt_kor_nmstring과목명
cdtstring학점
com_ynstring이수 상태 (이수 / 이수중 / "" = 미이수)
com_yy_smtstring이수 완료 학기 ("2024-1")
com_sbjt_kor_nmstring대체 이수 과목명
sngj_gradestring성적 ("A+", "P" 등)

에러 응답

에러 코드HTTP설명
UNAUTHORIZED401세션 없음
SCH_UNAVAILABLE503SCH 서버에서 졸업 정보를 가져오지 못함

POST /api/graduation/sync/

졸업진도의 이수내용을 SCH 서버와 강제 동기화합니다.

이 요청은 SCH 서버에서 처리 시간이 최대 30초 소요될 수 있습니다. 타임아웃을 넉넉하게 설정하세요.

요청

Body 없음.

응답

200 OK

{
  "ok": true
}

에러 응답

에러 코드HTTP설명
UNAUTHORIZED401세션 없음
SYNC_FAILED500동기화 실패
SCH_UNAVAILABLE503SCH 서버 연결 실패

학적 API

학적정보, 메인 통합조회, 학적사항 탭별 조회, 학사일정, 공지사항, 즐겨찾기

시간표 API

시간표 테마 스토어, 교수/강의실별 조회, 수강 과목, 교과과정, 시간표 검색

On this page

엔드포인트 목록GET /api/grades/overview/응답에러 응답GET /api/grades/subjects/쿼리 파라미터응답에러 응답GET /api/grades/semester/쿼리 파라미터응답에러 응답GET /api/grades/semester-report/GET /api/grades/semester-report/url/GET /api/graduation/detail/응답에러 응답POST /api/graduation/sync/요청응답에러 응답