API 레퍼런스

기본 정보

인증 방식

SCH Web Portal은 Authorization 헤더 대신 HttpOnly 쿠키 기반 세션을 사용합니다.

1. POST /api/auth/login/  → Set-Cookie: sch_session=<token>; HttpOnly; SameSite=Lax
2. 이후 모든 요청에 브라우저가 자동으로 sch_session 쿠키 포함
3. 세션 만료 D-30분 전 POST /api/auth/refresh/ 호출로 갱신

쿠키 속성:

공통 에러 응답 형식

모든 에러는 동일한 JSON 구조를 따릅니다.

{
  "error": "ERROR_CODE",
  "message": "사람이 읽을 수 있는 에러 메시지"
}

전역 에러 코드

요청 오류 코드

// UNAUTHORIZED 예시
{
  "error": "UNAUTHORIZED",
  "message": "세션이 만료되었거나 유효하지 않습니다."
}

// SCH_UNAVAILABLE 예시
{
  "error": "SCH_UNAVAILABLE",
  "message": "학교 서버와 연결할 수 없습니다. 잠시 후 다시 시도하세요."
}

데이터 흐름 패턴

패턴 1 — 실시간 SCH 프록시

학적정보, 성적, 시간표 등 대부분의 데이터는 DB에 저장되지 않고 SCH 서버에서 실시간 조회합니다.

Client → Portal API → SCH 서버 → 응답 변환 → Client

이 패턴의 API는 SCH 서버가 응답하는 한 항상 최신 데이터를 반환하며, SCH 서버 장애 시 SCH_UNAVAILABLE (503)을 반환합니다.

패턴 2 — DB 저장

즐겨찾기, 시간표 테마, 공지사항, 학사일정은 Portal DB에 저장됩니다.

Client → Portal API → Portal DB → Client

이 데이터는 SCH 서버와 무관하게 조회할 수 있습니다.

패턴 3 — 2단계 리포트

OZ 리포트(증명서·고지서) URL 생성 패턴. 먼저 화면용 정보를 조회하고, 이어서 출력 URL을 받습니다.

1. GET  /api/{resource}/info/     → 화면에 보여줄 정보 + 출력 가능 여부
2. POST /api/{resource}/report/   → { url: "https://report.sch.ac.kr/..." }

프론트엔드는 받은 URL을 window.open()으로 엽니다.

이 패턴을 사용하는 API: 해당학기 성적표, 등록 고지서, 기숙사비 고지서, 생활관 합격자 고지서, 장학 증명서, 교육비 납입 증명서, 각종 편람·현황 리포트

패턴 4 — 웹메일 SSO 중계

웹메일(mail.sch.ac.kr)만 인증 체계가 다릅니다. 종합정보시스템의 jsessionid/ecd_key로는 접근할 수 없어 SSO(sso.sch.ac.kr) RSA 로그인을 따로 태우고, 받은 메일 쿠키를 세션 페이로드에 넣어 다시 쿠키로 내려줍니다.

1. 첫 메일 요청     → 서버가 SSO 체인 수립 → Set-Cookie: sch_session(메일 쿠키 포함)
2. 이후 메일 요청   → 세션에서 메일 쿠키를 바로 읽어 mail.sch.ac.kr JSON API 중계

이 패턴을 사용하는 API: /api/mail/* 전체. 자세한 내용은 웹메일 API를 참고하세요.

전체 엔드포인트 목록

학기 코드 일람

모든 API에서 공통으로 사용하는 smt (학기 코드) 값입니다.

_current_semester() 서버 함수는 오늘 날짜로 (yy, smt)를 자동 반환합니다 (38월 → 11, 912월 → 21, 1~2월 → 전년도 21).