Soonlife DOCS
API 레퍼런스

등록금 API

등록금 납부 내역, 학자금대출 상환, 등록 고지서 출력, 교육비 납입 증명서 발급

엔드포인트 목록

메서드경로설명
GET/api/tuition/등록금 납부 내역 · 장학금 · 학자금대출 상환 통합 조회
GET/api/tuition/reg-dema-paper/현재 학기 등록 고지서 정보 조회
POST/api/tuition/reg-dema-paper/report/등록 고지서 PDF URL 생성
GET/api/edupay/detail/특정 연도 교육비 납입 상세 조회
POST/api/edupay/cert/report/교육비 납입 증명서 PDF URL 생성

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

GET /api/tuition/

등록금 납부 세부내역(세금계산서용), 학자금대출 상환 내역, 등록금 납부 이력, 장학금 수혜 이력을 한 번에 반환합니다.

항목별 SCH 서버 조회는 독립적으로 실행됩니다. 특정 항목 조회가 실패해도 나머지 항목은 정상 반환되며, 실패한 항목은 빈 배열([])로 대체됩니다. HTTP 에러는 반환되지 않습니다.

요청

쿠키 sch_session 포함. 별도 파라미터 없음.

응답

200 OK

{
  "tax_detail": [
    {
      "date":    "20250228",
      "gb":      "등록금",
      "dtl":     "2025-1학기 등록금",
      "edu_cst": 3520000
    },
    {
      "date":    "20250228",
      "gb":      "장학금",
      "dtl":     "성적우수장학금",
      "edu_cst": -500000
    }
  ],
  "repay": [
    {
      "date":    "20250228",
      "gb":      "상환",
      "dtl":     "한국장학재단 일반상환학자금",
      "edu_cst": 1200000
    }
  ],
  "registrations": [
    {
      "yy":             "2025",
      "smt_nm":         "1학기",
      "reg_div_nm":     "일반등록",
      "total_amt":      3520000,
      "real_paid_amt":  3020000,
      "schlsh_amt":     500000,
      "reg_amt_rtn_yn": "N"
    },
    {
      "yy":             "2024",
      "smt_nm":         "2학기",
      "reg_div_nm":     "일반등록",
      "total_amt":      3520000,
      "real_paid_amt":  2520000,
      "schlsh_amt":     1000000,
      "reg_amt_rtn_yn": "N"
    }
  ],
  "scholarships": [
    {
      "yy":            "2025",
      "smt_nm":        "1학기",
      "schlsh_div_nm": "성적우수장학금",
      "schlsh_amt":    500000
    },
    {
      "yy":            "2024",
      "smt_nm":        "2학기",
      "schlsh_div_nm": "교내근로장학금",
      "schlsh_amt":    1000000
    }
  ]
}

최상위 필드:

필드타입설명
tax_detailarray등록금 납부 세부내역 — 세금계산서 발급용 (양수=납부, 음수=장학금·대출 감면)
repayarray학자금대출 상환 상세 내역
registrationsarray학기별 등록금 납부 이력 목록
scholarshipsarray학기별 장학금 수혜 이력 목록

tax_detail · repay 항목 필드:

필드타입설명
datestring기준일 — SCH 원본 형식 YYYYMMDD
gbstring구분 레이블 (예: "등록금", "장학금", "상환")
dtlstring상세 레이블 (예: "2025-1학기 등록금")
edu_cstnumber금액 (원). 납부는 양수, 감면은 음수

registrations 항목 필드:

필드타입설명
yystring학년도 (예: "2025")
smt_nmstring학기 이름 (예: "1학기", "2학기")
reg_div_nmstring등록 구분명 (예: "일반등록")
total_amtnumber등록금 총액 (원)
real_paid_amtnumber실납부액 (원) — 장학금 차감 후 실제 납부한 금액
schlsh_amtnumber장학금 감면액 (원)
reg_amt_rtn_ynstring등록금 반환 여부 ("Y" / "N")

scholarships 항목 필드:

필드타입설명
yystring학년도
smt_nmstring학기 이름
schlsh_div_nmstring장학금 구분명 (예: "성적우수장학금", "교내근로장학금")
schlsh_amtnumber장학금 수혜액 (원)

에러 응답

에러 코드HTTP설명
UNAUTHORIZED401세션 없음 또는 만료
{
  "error": "UNAUTHORIZED"
}

tax_detail과 repay 배열이 비어 있더라도 에러가 아닙니다. SCH 서버에서 해당 연도의 등록금 세부내역을 조회하지 못했거나, 현재 학기에 아직 고지서가 발행되지 않은 경우에도 빈 배열을 반환합니다.

GET /api/tuition/reg-dema-paper/

현재 출력 가능한 학기의 등록 고지서 정보를 조회합니다. 서버가 현재 출력 가능한 학기를 자동으로 결정하며 (UCMCOM_dGetNowYySmt), 쿼리 파라미터를 받지 않습니다.

이 엔드포인트의 응답에 포함된 report_params 객체를 그대로 POST /api/tuition/reg-dema-paper/report/ Body에 전달하면 고지서 PDF URL을 받을 수 있습니다. report_params 내부 필드를 직접 구성하거나 수정하지 마세요.

요청

쿠키 sch_session 포함. 파라미터 없음.

응답

status 필드값에 따라 응답 구조가 다릅니다.

status 값설명
"OK"출력 가능 — report_params 포함
"NOT_PERIOD"현재 등록 고지서 출력 기간이 아님
"NO_DATA"이번 학기 고지서 데이터 없음
"FREE_REG"무료(이중)등록 — 별도 일괄 처리됨

200 OK — status: "OK" (출력 가능)

{
  "status":   "OK",
  "yy":       "2025",
  "smt":      "11",
  "tab_page": "RegAmt",
  "paid_loc": "신한은행",
  "report_params": {
    "tab_page":       "RegAmt",
    "yy":             "2025",
    "smt":            "11",
    "orgn_div":       "U0120001",
    "actual_std_no":  "20201234",
    "paid_loc":       "신한은행",
    "reg_term_start": "20250224",
    "reg_term_end":   "20250228",
    "add_term_start": "20250303",
    "add_term_end":   "20250307"
  }
}

200 OK — status: "NOT_PERIOD" (출력 기간 아님)

{
  "status":  "NOT_PERIOD",
  "message": "등록고지서 출력기간이 아닙니다."
}

200 OK — status: "NO_DATA" (데이터 없음)

{
  "status":  "NO_DATA",
  "yy":      "2025",
  "smt":     "11",
  "message": "고지서 데이터가 없습니다."
}

200 OK — status: "FREE_REG" (무료등록)

{
  "status":  "FREE_REG",
  "yy":      "2025",
  "smt":     "11",
  "message": "무료(이중)등록이므로 별도 등록수수료 없이 일괄 등록처리됩니다. 문의: 041-530-1056"
}

status: "OK" 응답 필드:

필드타입설명
yystring출력 가능 학년도
smtstring출력 가능 학기 코드 (11=1학기, 21=2학기, 12=하계, 22=동계)
tab_pagestring고지서 유형 — "RegAmt" (일반등록금) / "SesnAmt" (계절학기수강료)
paid_locstring납부 장소·은행 정보
report_paramsobjectPOST /api/tuition/reg-dema-paper/report/ 에 그대로 전달할 파라미터 묶음

에러 응답

에러 코드HTTP설명
UNAUTHORIZED401세션 없음 또는 만료
SCH_UNAVAILABLE503SCH 서버 연결 실패
{
  "error":   "SCH_UNAVAILABLE",
  "message": "고지서 정보를 불러오지 못했습니다."
}

POST /api/tuition/reg-dema-paper/report/

등록 고지서 PDF를 출력할 수 있는 OZ 리포트 URL을 생성합니다. GET /api/tuition/reg-dema-paper/에서 받은 report_params 객체를 그대로 Body에 전달해야 합니다.

요청

Body (application/json)

필드타입필수설명
report_paramsobjectOGET /api/tuition/reg-dema-paper/ 응답의 report_params 객체 그대로 전달
{
  "report_params": {
    "tab_page":       "RegAmt",
    "yy":             "2025",
    "smt":            "11",
    "orgn_div":       "U0120001",
    "actual_std_no":  "20201234",
    "paid_loc":       "신한은행",
    "reg_term_start": "20250224",
    "reg_term_end":   "20250228",
    "add_term_start": "20250303",
    "add_term_end":   "20250307"
  }
}

report_params는 반드시 GET /api/tuition/reg-dema-paper/ 응답에서 받은 객체 그대로 전달해야 합니다. 필드를 임의로 수정하거나 누락하면 고지서 URL 생성에 실패합니다. report_params가 객체 타입이 아니면 MISSING_PARAMS 에러가 반환됩니다.

응답

200 OK

{
  "url": "https://st.sch.ac.kr/upj/ure/objm/UreRegUserDemaPaper_2?ODI_NM=UreRegUserDemaPaper_2&..."
}
필드타입설명
urlstringOZ 리포트 URL — 브라우저에서 바로 열거나 <iframe>에 삽입하여 고지서 PDF를 출력합니다

에러 응답

에러 코드HTTP설명
UNAUTHORIZED401세션 없음 또는 만료
MISSING_PARAMS400report_params가 누락되었거나 객체 타입이 아님
REPORT_FAILED500SCH OZ 리포트 URL 생성 실패 (등록기간 정보 없음 등)
SCH_UNAVAILABLE503SCH 서버 연결 실패
// 예: report_params 누락
{
  "error":   "MISSING_PARAMS",
  "message": "고지서 정보가 없습니다. 먼저 조회하세요."
}
// 예: 리포트 생성 실패
{
  "error":   "REPORT_FAILED",
  "message": "등록기간 정보가 없어 고지서 URL을 만들 수 없습니다."
}

GET /api/edupay/detail/

특정 연도의 교육비 납입 상세 내역과 학자금대출 상환 내역을 조회합니다. 연말정산 신고, 교육비 증명서 발급 전 내역 확인에 사용합니다.

요청

쿼리 파라미터

파라미터타입필수설명
yearstringO조회 연도 — 4자리 숫자 (예: 2025)
GET /api/edupay/detail/?year=2025

응답

200 OK

{
  "tax_detail": [
    {
      "ord":     "1",
      "date":    "20250228",
      "gb":      "등록금",
      "dtl":     "2025-1학기 등록금",
      "edu_cst": 3520000
    },
    {
      "ord":     "2",
      "date":    "20250228",
      "gb":      "장학금",
      "dtl":     "성적우수장학금",
      "edu_cst": -500000
    },
    {
      "ord":     "3",
      "date":    "20240829",
      "gb":      "등록금",
      "dtl":     "2024-2학기 등록금",
      "edu_cst": 3520000
    },
    {
      "ord":     "4",
      "date":    "20240829",
      "gb":      "장학금",
      "dtl":     "교내근로장학금",
      "edu_cst": -1000000
    }
  ],
  "repay": [
    {
      "ord":     "1",
      "date":    "20250228",
      "gb":      "상환",
      "dtl":     "한국장학재단 일반상환학자금",
      "edu_cst": 1200000
    }
  ]
}

tax_detail · repay 항목 필드:

필드타입설명
ordstring항목 순번
datestring기준일 — SCH 원본 형식 YYYYMMDD
gbstring구분 레이블 (예: "등록금", "장학금", "상환")
dtlstring상세 레이블 (예: "2025-1학기 등록금")
edu_cstnumber금액 (원). 납부·상환은 양수, 감면은 음수

tax_detail은 교육비 납입 증명서(RS_URE_REG_USER_CERT)를, repay는 계절학기·기숙사 등 대출상환 내역(RS_URE_SEAS_DORM_CERT)을 각각 담습니다. 연말정산 교육비 공제 신청 시 tax_detail을 기준으로 확인합니다.

에러 응답

에러 코드HTTP설명
UNAUTHORIZED401세션 없음 또는 만료
MISSING_YEAR400year 파라미터 누락 또는 4자리 숫자가 아님
SCH_UNAVAILABLE503SCH 서버 연결 실패
// 예: year 파라미터 누락
{
  "error":   "MISSING_YEAR",
  "message": "연도를 입력하세요."
}

POST /api/edupay/cert/report/

교육비 납입 증명서 PDF를 출력할 수 있는 OZ 리포트 URL을 생성합니다. 연말정산 교육비 공제, 은행 제출, 장학 신청 등에 사용하는 공식 증명서입니다.

요청

Body (application/json)

필드타입필수허용값설명
yearstringO4자리 연도 (예: "2025")증명서 발급 연도
cert_typestringO"annual" / "payment" / "enroll"증명서 종류 (아래 표 참고)
semesterstring조건부"11" / "21"학기 코드 — cert_type이 "payment" 또는 "enroll"일 때 필수

cert_type 허용값:

값증명서 이름semester 필요 여부
"annual"연간 교육비 납입 증명서 (연말정산용)불필요
"payment"납입금 증명서 (학기별)필수
"enroll"등록금 증명서 (학기별)필수

예시 1 — 연간 교육비 납입 증명서 (연말정산용)

{
  "year":      "2025",
  "cert_type": "annual"
}

예시 2 — 1학기 납입금 증명서

{
  "year":      "2025",
  "cert_type": "payment",
  "semester":  "11"
}

예시 3 — 2학기 등록금 증명서

{
  "year":      "2025",
  "cert_type": "enroll",
  "semester":  "21"
}

응답

200 OK

{
  "url": "https://st.sch.ac.kr/upj/ure/regi/UreEduPaidCert?ODI_NM=UreEduPaidCert&..."
}
필드타입설명
urlstringOZ 리포트 URL — 브라우저에서 바로 열거나 <iframe>에 삽입하여 증명서 PDF를 출력합니다

에러 응답

에러 코드HTTP설명
UNAUTHORIZED401세션 없음 또는 만료
MISSING_YEAR400year 누락 또는 4자리 숫자가 아님
INVALID_CERT_TYPE400cert_type이 허용값이 아님
MISSING_SEMESTER400cert_type이 "payment" 또는 "enroll"인데 semester 누락 또는 허용값이 아님
REPORT_FAILED500SCH OZ 리포트 URL 생성 실패
SCH_UNAVAILABLE503SCH 서버 연결 실패
// 예: 잘못된 cert_type
{
  "error": "INVALID_CERT_TYPE"
}
// 예: payment/enroll에서 semester 누락
{
  "error":   "MISSING_SEMESTER",
  "message": "학기를 선택하세요."
}
// 예: year 누락
{
  "error":   "MISSING_YEAR",
  "message": "연도를 선택하세요."
}

활동 API

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

AI 챗봇 API

순라이프 AI 공지 챗봇 — 메시지 전송(NDJSON 스트리밍), 중단, 대화 기록, 답변 평가

On this page

엔드포인트 목록GET /api/tuition/요청응답에러 응답GET /api/tuition/reg-dema-paper/요청응답에러 응답POST /api/tuition/reg-dema-paper/report/요청응답에러 응답GET /api/edupay/detail/요청응답에러 응답POST /api/edupay/cert/report/요청응답에러 응답