Soonlife DOCS
API 레퍼런스

기숙사 API

기숙사비 고지서, 호실 배정, 입사 합격 고지서, 외박신청, 상벌점, 점호 마일리지

엔드포인트 목록

메서드경로설명
GET/api/dorm/bill/info/방학 중 생활관 고지서 정보
POST/api/dorm/bill/report/방학 중 생활관 고지서 출력 URL
GET/api/dorm/room/info/방학 중 호실 배정 조회
GET/api/dorm/pass/info/생활관 입사 합격 여부 + 고지서 정보
POST/api/dorm/pass/report/합격자 고지서 출력 URL 생성
GET/api/dorm/asgn/result/생활관 배정결과 조회
GET/api/dorm/rwpn/상벌점 조회
GET/api/dorm/sleepout/외박 신청 현황
GET/api/dorm/sleepout/sigungu/외박 목적지 시군구 목록
POST/api/dorm/sleepout/apply/외박 신청
POST/api/dorm/sleepout/cancel/외박 취소
GET/api/dorm/sleep-call-mileage/점호 마일리지 조회

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

GET /api/dorm/bill/info/

방학 중 생활관 고지서 정보를 조회합니다. yy, smt를 생략하면 서버가 오늘 날짜 기준으로 현재 방학 학기를 자동 계산합니다.

요청

쿼리 파라미터

파라미터타입필수허용값설명
yystring아니오4자리 연도학년도 (예: 2025). 생략 시 자동 판별
smtstring아니오12, 22방학 학기 코드. 12=하계, 22=동계. 생략 시 자동 판별

smt에 11(1학기)이나 21(2학기)를 전달하면 INVALID_SMT 오류가 반환됩니다. 이 엔드포인트는 방학 학기 코드(12, 22)만 허용합니다.

요청 예시 — 2025 하계방학 조회

GET /api/dorm/bill/info/?yy=2025&smt=12
Cookie: sch_session=<token>

요청 예시 — 자동 판별

GET /api/dorm/bill/info/
Cookie: sch_session=<token>

응답

200 OK

이후 POST /api/dorm/bill/report/ 호출 시 이 응답의 notice 객체와 period.pass_seq가 그대로 필요합니다.

{
  "period": {
    "pass_seq":   "20250701",
    "start_date": "2025-07-01",
    "end_date":   "2025-08-31"
  },
  "notice": {
    "yy":       "2025",
    "smt":      "12",
    "orgn_div": "01",
    "aply_div": "01",
    "wk_div":   "01",
    "gp_seq":   "001",
    "prsnl_no": "U000001234",
    "aply_cd":  "A"
  }
}

응답 필드

필드타입설명
period.pass_seqstring고지서 일련번호 — POST /api/dorm/bill/report/ 의 pass_seq로 전달
period.start_datestring생활관 입주 시작일 YYYY-MM-DD
period.end_datestring생활관 퇴소 종료일 YYYY-MM-DD
notice.yystring학년도
notice.smtstring방학 학기 코드 (12 / 22)
notice.orgn_divstring기관 구분 코드
notice.aply_divstring신청 구분 코드
notice.wk_divstring주간 구분 코드
notice.gp_seqstring그룹 시퀀스
notice.prsnl_nostringSCH 사용자 번호
notice.aply_cdstring신청 코드

에러 응답

에러 코드HTTP설명
UNAUTHORIZED401세션 없음 또는 만료
INVALID_YEAR400yy가 4자리 숫자가 아님
INVALID_SMT400smt가 12 또는 22가 아님
SCH_UNAVAILABLE503SCH 서버 연결 실패
// INVALID_SMT 예시
{
  "error": "INVALID_SMT",
  "message": "방학 학기 코드(12, 22)만 허용됩니다."
}

POST /api/dorm/bill/report/

방학 중 생활관 고지서 OZ 리포트 출력 URL을 생성합니다.

2단계 흐름: 먼저 GET /api/dorm/bill/info/로 고지서 정보를 받은 후, 그 응답의 notice 객체와 period.pass_seq를 그대로 이 요청에 전달합니다.

요청

Body (application/json)

필드타입필수설명
noticeobjectOGET /api/dorm/bill/info/ 응답의 notice 객체 전체
notice.yystringO학년도
notice.smtstringO방학 학기 코드
notice.orgn_divstringO기관 구분
notice.aply_divstringO신청 구분
notice.wk_divstringO주간 구분
notice.gp_seqstringO그룹 시퀀스
notice.prsnl_nostringOSCH 사용자 번호
notice.aply_cdstringO신청 코드
pass_seqstringOGET /api/dorm/bill/info/ 응답의 period.pass_seq 값

요청 예시

{
  "notice": {
    "yy":       "2025",
    "smt":      "12",
    "orgn_div": "01",
    "aply_div": "01",
    "wk_div":   "01",
    "gp_seq":   "001",
    "prsnl_no": "U000001234",
    "aply_cd":  "A"
  },
  "pass_seq": "20250701"
}

응답

200 OK

{
  "url": "https://portal.sch.ac.kr/oz/report?session=...&params=..."
}
필드타입설명
urlstringOZ 리포트 출력 URL. 브라우저에서 열거나 iframe으로 삽입

에러 응답

에러 코드HTTP설명
UNAUTHORIZED401세션 없음 또는 만료
MISSING_NOTICE400notice 필드가 없음
INVALID_NOTICE400notice 객체에 필수 필드 누락
REPORT_FAILED500SCH 서버에서 리포트 URL 생성 실패
SCH_UNAVAILABLE503SCH 서버 연결 실패
// INVALID_NOTICE 예시 — notice.gp_seq 누락
{
  "error": "INVALID_NOTICE",
  "message": "notice 객체의 필수 필드가 누락되었습니다."
}

GET /api/dorm/room/info/

방학 중 호실 배정 정보를 조회합니다.

요청

쿼리 파라미터 — 없음 (서버가 현재 방학 학기 자동 감지)

GET /api/dorm/room/info/
Cookie: sch_session=<token>

응답

200 OK — SCH 서버의 호실 배정 정보

{
  "yy":       "2025",
  "smt":      "12",
  "bldg_nm":  "향설생활관2",
  "room_no":  "204",
  "bed_no":   "A",
  "room_type": "하층"
}

에러 응답

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

GET /api/dorm/pass/info/

생활관 입사 합격 여부와 합격자 고지서 출력에 필요한 데이터를 조회합니다. 파라미터 없음 — 기준 연도/학기는 서버가 자동 결정합니다.

2단계 흐름: 이 응답의 pass_data 객체와 period.pass_seq를 POST /api/dorm/pass/report/에 그대로 전달하면 고지서 출력 URL을 받을 수 있습니다.

요청

쿼리 파라미터 — 없음

GET /api/dorm/pass/info/
Cookie: sch_session=<token>

응답

200 OK

{
  "period": {
    "pass_seq": "20250301"
  },
  "pass_data": {
    "yy":       "2025",
    "smt":      "11",
    "wk_div":   "01",
    "gp_seq":   "001",
    "prsnl_no": "U000001234",
    "aply_div": "01",
    "orgn_div": "01",
    "aply_cd":  "A"
  },
  "result": {
    "pass_yn":   "Y",
    "bldg_nm":   "향설생활관2",
    "room_no":   "204",
    "bed_no":    "A",
    "in_date":   "2025-03-01",
    "out_date":  "2025-08-31"
  }
}
필드타입설명
period.pass_seqstring고지서 일련번호 — POST /api/dorm/pass/report/의 pass_seq로 전달
pass_dataobject고지서 출력에 필요한 파라미터 묶음 — POST /api/dorm/pass/report/에 그대로 전달
result.pass_ynstring합격 여부 ("Y" / "N")
result.bldg_nmstring배정 생활관 건물명
result.room_nostring호실 번호
result.bed_nostring침대 위치 ("A" / "B")
result.in_datestring입소 예정일 YYYY-MM-DD
result.out_datestring퇴소 예정일 YYYY-MM-DD

에러 응답

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

POST /api/dorm/pass/report/

합격자 고지서 OZ 리포트 출력 URL을 생성합니다.

GET /api/dorm/pass/info/로 먼저 데이터를 조회한 후, 응답의 pass_data와 period.pass_seq를 그대로 이 요청에 전달하세요.

요청

Body (application/json)

필드타입필수설명
pass_dataobjectOGET /api/dorm/pass/info/ 응답의 pass_data 객체 전체
pass_data.yystringO학년도
pass_data.smtstringO학기 코드
pass_data.wk_divstringO주간 구분
pass_data.gp_seqstringO그룹 시퀀스
pass_data.prsnl_nostringOSCH 사용자 번호
pass_data.aply_divstringO신청 구분
pass_data.orgn_divstringO기관 구분
pass_data.aply_cdstringO신청 코드
pass_seqstringOGET /api/dorm/pass/info/ 응답의 period.pass_seq 값

요청 예시

{
  "pass_data": {
    "yy":       "2025",
    "smt":      "11",
    "wk_div":   "01",
    "gp_seq":   "001",
    "prsnl_no": "U000001234",
    "aply_div": "01",
    "orgn_div": "01",
    "aply_cd":  "A"
  },
  "pass_seq": "20250301"
}

응답

200 OK

{
  "url": "https://portal.sch.ac.kr/oz/report?session=...&params=..."
}

에러 응답

에러 코드HTTP설명
UNAUTHORIZED401세션 없음
MISSING_DATA400pass_data가 없거나 객체가 아님
INVALID_DATA400pass_data에 필수 필드 누락
REPORT_FAILED500SCH 서버에서 고지서 URL 생성 실패
SCH_UNAVAILABLE503SCH 서버 연결 실패
// MISSING_DATA 예시
{
  "error": "MISSING_DATA",
  "message": "합격 데이터가 없습니다. 먼저 조회하세요."
}

GET /api/dorm/asgn/result/

생활관 배정결과를 조회합니다. 합격 발표 후 호실 배정이 완료된 결과를 반환하며, 기준 연도/학기는 서버(TDMBASE_pSearchBaseYear)가 자동 결정합니다.

요청

쿼리 파라미터 — 없음

응답

200 OK — SCH 서버의 배정결과 (배정 생활관, 호실, 입소일 등)

에러 응답

에러 코드HTTP설명
UNAUTHORIZED401세션 없음
AUTH_ERROR401SCH 서버 인증 오류
SCH_UNAVAILABLE503SCH 서버 연결 실패

GET /api/dorm/rwpn/

생활관 상벌점 현황을 반환합니다. 학기를 지정하지 않으면 SCH 서버에서 현재 학기를 자동 감지합니다.

요청

쿼리 파라미터

파라미터타입필수설명
yystring아니오학년도 (예: 2025). 생략 시 자동
smtstring아니오학기 코드 (11 / 21). 생략 시 자동

요청 예시

GET /api/dorm/rwpn/?yy=2025&smt=11
Cookie: sch_session=<token>

응답

200 OK — 상벌점 합계 및 상세 내역

{
  "yy":    "2025",
  "smt":   "11",
  "total": -5,
  "items": [
    {
      "date":   "2025-04-10",
      "type":   "벌점",
      "reason": "점호 불참",
      "score":  -5
    },
    {
      "date":   "2025-03-15",
      "type":   "상점",
      "reason": "기숙사 청결 우수",
      "score":  3
    }
  ]
}
필드타입설명
yystring조회 학년도
smtstring조회 학기
totalnumber상벌점 합계 (음수 = 벌점 초과)
items[].datestring부여 일자 YYYY-MM-DD
items[].typestring구분 (상점 / 벌점)
items[].reasonstring부여 사유
items[].scorenumber점수 (상점 양수, 벌점 음수)

에러 응답

에러 코드HTTP설명
UNAUTHORIZED401세션 없음
AUTH_ERROR401SCH 서버 인증 오류
SCH_UNAVAILABLE503SCH 서버 연결 실패

GET /api/dorm/sleepout/

현재 외박 신청 현황과 기존 신청 목록을 반환합니다.

요청

쿼리 파라미터

파라미터타입필수형식설명
yyyymmstring아니오YYYYMM (6자리 숫자)조회 월. 생략 시 현재 월

요청 예시 — 2025년 7월 조회

GET /api/dorm/sleepout/?yyyymm=202507
Cookie: sch_session=<token>

응답

200 OK

{
  "period": {
    "is_open":    true,
    "start_date": "2025-07-01",
    "end_date":   "2025-07-31"
  },
  "aply_list": [
    {
      "aply_seq":  "2025070001",
      "aply_dt":   "2025-07-03",
      "out_dt":    "2025-07-05",
      "in_dt":     "2025-07-06",
      "sido_nm":   "서울특별시",
      "sigungu_nm": "강남구",
      "destination": "서울특별시 강남구 역삼동",
      "reason":    "가족 행사",
      "status":    "승인"
    }
  ]
}
필드타입설명
period.is_openboolean외박 신청 가능 기간 여부
period.start_datestring신청 가능 시작일
period.end_datestring신청 가능 종료일
aply_listarray해당 월 외박 신청 내역
aply_list[].aply_seqstring신청 일련번호 — 취소 시 이 값이 필요한 row에 포함
aply_list[].out_dtstring외박 시작일
aply_list[].in_dtstring귀숙 예정일
aply_list[].statusstring처리 상태 (승인 / 대기 / 반려)

에러 응답

에러 코드HTTP설명
UNAUTHORIZED401세션 없음
INVALID_MONTH400yyyymm이 6자리 숫자가 아님
SCH_UNAVAILABLE503SCH 서버 연결 실패
// INVALID_MONTH 예시
{
  "error": "INVALID_MONTH",
  "message": "조회 월은 YYYYMM 형식이어야 합니다."
}

GET /api/dorm/sleepout/sigungu/

외박 목적지 선택용 시군구 목록을 반환합니다. 외박 신청 폼의 2단계 지역 선택에 사용합니다.

요청

쿼리 파라미터

파라미터타입필수설명
sidostringO시도 코드. 값을 생략하거나 빈 문자열이면 빈 목록 반환

요청 예시 — 서울특별시 시군구 목록

GET /api/dorm/sleepout/sigungu/?sido=11
Cookie: sch_session=<token>

응답

200 OK

{
  "items": [
    { "sigungu_cd": "11110", "sigungu_nm": "서울특별시 종로구" },
    { "sigungu_cd": "11140", "sigungu_nm": "서울특별시 중구" },
    { "sigungu_cd": "11170", "sigungu_nm": "서울특별시 용산구" }
  ]
}

sido 미제공 시 {"items": []} 반환.

에러 응답

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

POST /api/dorm/sleepout/apply/

외박을 신청합니다.

요청

Body (application/json)

필드타입필수설명
datestringO외박 날짜 (YYYYMMDD 형식)
sido_codestringO시도 코드 (예: "11" = 서울특별시)
sigungu_codestringO시군구 코드 (예: "11110" = 종로구). sigungu/ API로 조회
destinationstringO목적지 상세 주소
reason_codestringO외박 사유 코드 (SCH 서버 코드)
emergency_contactstringO비상 연락처
remarkstring아니오비고

요청 예시

{
  "date":              "20250705",
  "sido_code":         "11",
  "sigungu_code":      "11110",
  "destination":       "서울특별시 종로구 인사동 123",
  "reason_code":       "01",
  "emergency_contact": "010-1234-5678",
  "remark":            "가족 행사 참석"
}

응답

200 OK — SCH 서버 처리 결과

{
  "ok": true
}

에러 응답

에러 코드HTTP설명
UNAUTHORIZED401세션 없음
APPLY_FAILED400신청 실패 (SCH 서버 거부 — 기간 외, 중복 신청 등)
// APPLY_FAILED 예시 — 신청 기간 외
{
  "error": "APPLY_FAILED",
  "message": "외박 신청 기간이 아닙니다."
}

POST /api/dorm/sleepout/cancel/

외박 신청을 취소합니다.

요청

Body (application/json)

필드타입필수설명
rowobjectOGET /api/dorm/sleepout/ 응답의 aply_list 항목 원본. SCH 서버가 취소에 필요한 모든 식별자를 포함

요청 예시

{
  "row": {
    "aply_seq":  "2025070001",
    "aply_dt":   "2025-07-03",
    "out_dt":    "2025-07-05",
    "in_dt":     "2025-07-06",
    "sido_nm":   "서울특별시",
    "sigungu_nm": "강남구",
    "destination": "서울특별시 강남구 역삼동",
    "reason":    "가족 행사",
    "status":    "승인"
  }
}

row 객체를 직접 구성하지 말고, GET /api/dorm/sleepout/ 응답의 aply_list 배열에서 받은 항목을 그대로 전달하세요.

응답

200 OK — SCH 서버 처리 결과

{
  "ok": true
}

에러 응답

에러 코드HTTP설명
UNAUTHORIZED401세션 없음
INVALID_ROW400row가 없거나 객체가 아님
CANCEL_FAILED400SCH 서버 취소 거부 (이미 취소됨, 처리 완료 등)
// INVALID_ROW 예시
{
  "error": "INVALID_ROW",
  "message": "취소할 외박 신청 정보를 찾지 못했습니다."
}

GET /api/dorm/sleep-call-mileage/

점호 마일리지 적립 현황을 반환합니다. 학기를 지정하지 않으면 SCH 서버에서 현재 학기를 자동 감지합니다.

요청

쿼리 파라미터

파라미터타입필수설명
yystring아니오학년도 (예: 2025). 생략 시 자동
smtstring아니오학기 코드 (11 / 21). 생략 시 자동

요청 예시

GET /api/dorm/sleep-call-mileage/?yy=2025&smt=11
Cookie: sch_session=<token>

응답

200 OK

{
  "yy":   "2025",
  "smt":  "11",
  "total_mileage": 180,
  "items": [
    {
      "date":    "2025-03-03",
      "type":    "적립",
      "amount":  10,
      "reason":  "저녁 점호 참여",
      "balance": 10
    },
    {
      "date":    "2025-03-10",
      "type":    "차감",
      "amount":  -10,
      "reason":  "점호 불참",
      "balance": 0
    }
  ]
}
필드타입설명
total_mileagenumber누적 점호 마일리지 합계
items[].datestring적립/차감 일자
items[].typestring구분 (적립 / 차감)
items[].amountnumber마일리지 (차감은 음수)
items[].reasonstring사유
items[].balancenumber적립/차감 후 잔액

에러 응답

에러 코드HTTP설명
UNAUTHORIZED401세션 없음
AUTH_ERROR401SCH 서버 인증 오류
SCH_UNAVAILABLE503SCH 서버 연결 실패

장학 API

장학금 검색, 장학수혜내역, 장학증명서 발급, 장학모집게시판 조회

활동 API

봉사활동, 비교과과정, 봉사학습 신청·조회·취소·평가 제출 전체 명세

On this page

엔드포인트 목록GET /api/dorm/bill/info/요청응답에러 응답POST /api/dorm/bill/report/요청응답에러 응답GET /api/dorm/room/info/요청응답에러 응답GET /api/dorm/pass/info/요청응답에러 응답POST /api/dorm/pass/report/요청응답에러 응답GET /api/dorm/asgn/result/요청응답에러 응답GET /api/dorm/rwpn/요청응답에러 응답GET /api/dorm/sleepout/요청응답에러 응답GET /api/dorm/sleepout/sigungu/요청응답에러 응답POST /api/dorm/sleepout/apply/요청응답에러 응답POST /api/dorm/sleepout/cancel/요청응답에러 응답GET /api/dorm/sleep-call-mileage/요청응답에러 응답