장학 API
장학금 검색, 장학수혜내역, 장학증명서 발급, 장학모집게시판 조회
엔드포인트 목록
| 메서드 | 경로 | 설명 |
|---|---|---|
GET | /api/scholarship/types/ | 장학금 성격(유형) 코드 목록 |
GET | /api/scholarship/search/ | 내게 맞는 장학금 조건/이름 검색 |
GET | /api/scholarship/cert/ | 장학수혜내역 조회 |
POST | /api/scholarship/cert/report/ | 장학증명서 OZ 리포트 URL 생성 |
GET | /api/scholarship/board/ | 장학모집게시판 목록 (페이지네이션) |
GET | /api/scholarship/board/detail/ | 장학모집게시판 게시물 상세 |
모든 엔드포인트는 sch_session 쿠키 인증이 필요합니다.
GET /api/scholarship/types/
장학금 성격(유형) 공통 코드 목록을 반환합니다. GET /api/scholarship/search/의 scho_type 필터 값으로 사용합니다.
이 목록은 SCH 통합정보시스템의 U310 공통코드에서 실시간으로 조회합니다. scholarship/search/에서 scho_type을 비워두면 서버가 이 목록을 순회하며 성격별로 각각 검색 후 결과를 합산하므로, 검색 성격을 미리 좁히면 응답 속도가 빨라집니다.
요청
쿼리 파라미터 없음. 쿠키 sch_session 포함.
응답
200 OK
[
{ "code": "01", "name": "성적우수장학금" },
{ "code": "02", "name": "가계곤란장학금" },
{ "code": "03", "name": "교외장학금" },
{ "code": "04", "name": "국가장학금" },
{ "code": "05", "name": "근로장학금" },
{ "code": "06", "name": "특기자장학금" }
]| 필드 | 타입 | 설명 |
|---|---|---|
code | string | 장학 성격 코드 — scholarship/search/의 scho_type 파라미터에 전달 |
name | string | 장학 성격 한국어 명칭 |
에러 응답
| 에러 코드 | HTTP | 설명 |
|---|---|---|
UNAUTHORIZED | 401 | 세션 없음 또는 만료 |
SCH_UNAVAILABLE | 503 | SCH 서버에서 성격 목록을 가져오지 못함 |
{
"error": "UNAUTHORIZED"
}{
"error": "SCH_UNAVAILABLE",
"message": "장학금 성격 목록을 불러오지 못했습니다."
}GET /api/scholarship/search/
조건 또는 이름으로 장학금을 검색합니다. 평점·학점·교내외 여부·중복 수혜 가능 여부 등의 조건을 조합하여 결과를 반환합니다.
scho_type을 생략하거나 빈 문자열로 전달하면, 서버가 GET /api/scholarship/types/로 전체 성격 코드를 가져온 뒤 각 코드별로 SCH API를 순차 호출하여 결과를 합산합니다. 이름 기준 중복이 자동으로 제거됩니다. 특정 성격만 필요하다면 scho_type에 코드를 지정하여 호출 횟수를 줄이세요.
search_div, in_out, dupl_bene_yn에 허용되지 않는 값을 전달해도 에러를 반환하지 않습니다. 서버가 기본값으로 조용히 재설정합니다. earn_grade도 0~10 범위를 벗어나면 기본값 10으로 재설정됩니다.
요청
| 파라미터 | 타입 | 필수 | 허용값 | 설명 |
|---|---|---|---|---|
search_div | string | 아니오 | PERSONAL, NM | 검색 방식. PERSONAL=조건검색, NM=이름검색. 기본값 PERSONAL |
in_out | string | 아니오 | T, I, O | 교내외 구분. T=전체, I=교내, O=교외. 기본값 T |
dupl_bene_yn | string | 아니오 | T, Y, N | 중복 수혜 가능 여부. T=전체, Y=가능, N=불가. 기본값 T |
earn_grade | string | 아니오 | 0~10 | 취득학점 기준 필터. 기본값 10 |
schlsh_div_nm | string | 아니오 | 임의 문자열 | 장학금 성격명 검색어. 빈 문자열=전체 |
acqst_cdt | string | 아니오 | 임의 문자열 | 이수학점 기준 |
avg_mrks | string | 아니오 | 임의 문자열 | 평균성적(GPA) 기준. 예: 3.5 |
rsco_avg | string | 아니오 | 임의 문자열 | 백분위 평균 기준 |
scho_type | string | 아니오 | types/ 응답의 code 값 | 장학 성격 코드. 빈 문자열=전체 성격 합산 검색 |
예시 — GPA 3.5 이상 교내 장학금, 15학점 이상 취득 기준 조건검색
GET /api/scholarship/search/?search_div=PERSONAL&in_out=I&avg_mrks=3.5&earn_grade=15&dupl_bene_yn=T예시 — 이름으로 검색 (성적우수 성격 한정)
GET /api/scholarship/search/?search_div=NM&scho_type=01&schlsh_div_nm=성적우수응답
200 OK — 조건에 해당하는 장학금 배열. 조건에 맞는 장학금이 없으면 빈 배열 []를 반환합니다.
[
{
"name": "성적우수 A 장학금",
"in_out": "I",
"acqst_cdt": "15",
"avg_mrks": "3.5",
"rsco_avg": "",
"sup_sca": "등록금 전액",
"earn_grade": "15",
"scho_type": "01",
"dupl_bene_yn": "N",
"remark": "직전 학기 평점 3.5 이상, 15학점 이상 취득자 대상",
"scho_desc": "매 학기 성적 우수자에게 등록금 전액을 지원하는 교내 장학금입니다. 재학생 중 직전 학기 평점평균이 3.5 이상이고 15학점 이상 취득한 자를 대상으로 합니다."
},
{
"name": "성적우수 B 장학금",
"in_out": "I",
"acqst_cdt": "15",
"avg_mrks": "3.0",
"rsco_avg": "",
"sup_sca": "등록금 50%",
"earn_grade": "15",
"scho_type": "01",
"dupl_bene_yn": "N",
"remark": "직전 학기 평점 3.0 이상, 15학점 이상 취득자 대상",
"scho_desc": "직전 학기 평점평균 3.0 이상, 취득학점 15학점 이상인 재학생에게 등록금의 50%를 지원합니다."
},
{
"name": "가계곤란 장학금",
"in_out": "I",
"acqst_cdt": "12",
"avg_mrks": "2.0",
"rsco_avg": "",
"sup_sca": "등록금 30%",
"earn_grade": "12",
"scho_type": "02",
"dupl_bene_yn": "Y",
"remark": "소득분위 4분위 이하, 직전 학기 평점 2.0 이상",
"scho_desc": "경제적으로 어려운 학생을 지원하기 위한 교내 장학금입니다. 소득분위 4분위 이하이며 직전 학기 평점평균 2.0 이상인 학생이 대상입니다."
}
]| 필드 | 타입 | 설명 |
|---|---|---|
name | string | 장학금 성격명 |
in_out | string | 교내외 구분 (I=교내, O=교외) |
acqst_cdt | string | 이수학점 기준 |
avg_mrks | string | 평균성적(GPA) 기준 |
rsco_avg | string | 백분위 평균 기준 |
sup_sca | string | 지원 규모 또는 금액 |
earn_grade | string | 취득학점 기준 |
scho_type | string | 장학 성격 코드 |
dupl_bene_yn | string | 중복 수혜 가능 여부 (Y=가능, N=불가) |
remark | string | 비고 및 자격 요약 |
scho_desc | string | 장학금 상세 설명 |
에러 응답
| 에러 코드 | HTTP | 설명 |
|---|---|---|
UNAUTHORIZED | 401 | 세션 없음 또는 만료 |
SCH_UNAVAILABLE | 503 | SCH 서버 연결 실패 또는 검색 실패 |
{
"error": "UNAUTHORIZED"
}{
"error": "SCH_UNAVAILABLE",
"message": "장학금 검색에 실패했습니다."
}GET /api/scholarship/cert/
장학수혜내역을 조회합니다. POST /api/scholarship/cert/report/로 증명서를 발급하기 전 반드시 이 엔드포인트를 먼저 호출하여 포함할 수혜 내역을 확인해야 합니다.
요청
| 파라미터 | 타입 | 필수 | 허용값 | 설명 |
|---|---|---|---|---|
search_div | string | 아니오 | 1, 2 | 조회 범위. 1=전체 기간, 2=학기 지정. 기본값 1 |
yy | string | 조건부 | 4자리 연도 | search_div=2일 때 필수. 예: 2025 |
smt | string | 조건부 | 11, 21 | search_div=2일 때 필수. 11=1학기, 21=2학기 |
예시 — 전체 기간 수혜내역 조회
GET /api/scholarship/cert/?search_div=1예시 — 2024년 1학기 수혜내역 조회
GET /api/scholarship/cert/?search_div=2&yy=2024&smt=11응답
200 OK
{
"regi": [
{
"std_no": "20201234",
"nm": "홍길동",
"univ": "공과대학",
"sust": "컴퓨터소프트웨어공학과",
"sch_regi_div": "재학",
"shyr": "4학년"
}
],
"scho": [
{
"yy": "2025",
"smt": "11",
"smt_nm": "2025년도 1학기",
"schlsh_div": "01",
"schlsh_div_nm": "성적우수 A 장학금",
"schlsh_ent_amt": "0",
"schlsh_class_amt": "2100000",
"sche_amt": "0",
"schlsh_amt": "2100000"
},
{
"yy": "2024",
"smt": "21",
"smt_nm": "2024년도 2학기",
"schlsh_div": "04",
"schlsh_div_nm": "국가장학금 I 유형",
"schlsh_ent_amt": "0",
"schlsh_class_amt": "1500000",
"sche_amt": "0",
"schlsh_amt": "1500000"
},
{
"yy": "2024",
"smt": "11",
"smt_nm": "2024년도 1학기",
"schlsh_div": "01",
"schlsh_div_nm": "성적우수 A 장학금",
"schlsh_ent_amt": "0",
"schlsh_class_amt": "2100000",
"sche_amt": "0",
"schlsh_amt": "2100000"
}
],
"has_reg": true
}최상위 필드:
| 필드 | 타입 | 설명 |
|---|---|---|
regi | array | 학적 등록 정보 (이름, 학과 등) |
scho | array | 장학수혜 내역 목록 — 증명서 발급 시 selected_items 구성에 사용 |
has_reg | boolean | 비수혜증명서 발급 가능 여부. true이면 cert/report/에서 prt_div=NONE_BENE 발급 가능 |
regi 항목 필드:
| 필드 | 타입 | 설명 |
|---|---|---|
std_no | string | 학번 |
nm | string | 이름 |
univ | string | 단과대학명 |
sust | string | 학과명 |
sch_regi_div | string | 학적 구분 (재학, 졸업, 휴학 등) |
shyr | string | 학년 |
scho 항목 필드:
| 필드 | 타입 | 설명 |
|---|---|---|
yy | string | 장학 수혜 학년도 |
smt | string | 장학 수혜 학기 코드 (11=1학기, 21=2학기) |
smt_nm | string | 학기 표시명 |
schlsh_div | string | 장학 성격 코드 — cert/report/의 selected_items[].schlsh_div에 사용 |
schlsh_div_nm | string | 장학금 성격명 |
schlsh_ent_amt | string | 입학금 지원액 (원 단위 문자열) |
schlsh_class_amt | string | 수업료 지원액 (원 단위 문자열) |
sche_amt | string | 장학생 지원액 (원 단위 문자열) |
schlsh_amt | string | 장학금 합계 (원 단위 문자열) |
증명서 발급 흐름: cert/를 호출하여 scho 배열을 받은 뒤, 사용자가 선택한 항목에서 yy, smt, schlsh_div를 추출하여 cert/report/의 selected_items에 전달합니다. has_reg=false이면 비수혜증명서(NONE_BENE)도 발급할 수 없습니다.
에러 응답
| 에러 코드 | HTTP | 설명 |
|---|---|---|
UNAUTHORIZED | 401 | 세션 없음 또는 만료 |
INVALID_SEARCH_DIV | 400 | search_div가 1 또는 2가 아님 |
MISSING_YEAR | 400 | search_div=2인데 yy 누락 또는 4자리 숫자가 아님 |
MISSING_SEMESTER | 400 | search_div=2인데 smt가 11 또는 21이 아님 |
SCH_UNAVAILABLE | 503 | SCH 서버 연결 실패 |
{
"error": "INVALID_SEARCH_DIV"
}{
"error": "MISSING_YEAR",
"message": "연도를 선택하세요."
}{
"error": "MISSING_SEMESTER",
"message": "학기를 선택하세요."
}{
"error": "SCH_UNAVAILABLE",
"message": "장학수혜내역을 불러오지 못했습니다."
}POST /api/scholarship/cert/report/
장학증명서 OZ 리포트 출력 URL을 생성합니다. 반환된 url을 새 탭으로 열거나 iframe에 삽입하면 PDF 형식의 증명서를 확인할 수 있습니다.
prt_div가 CERT_KOR(국문 수혜증명서) 또는 CERT_ENG(영문 수혜증명서)인 경우 selected_items가 반드시 포함되어야 합니다. 먼저 GET /api/scholarship/cert/를 호출하고, 응답의 scho 배열에서 증명서에 포함할 항목의 yy, smt, schlsh_div를 추출하여 전달하세요.
요청
Body (application/json)
| 필드 | 타입 | 필수 | 허용값 | 설명 |
|---|---|---|---|---|
prt_div | string | O | CERT_KOR, CERT_ENG, NONE_BENE | 증명서 종류. 국문수혜 / 영문수혜 / 비수혜 |
yy | string | 아니오 | 4자리 연도 | 발급 기준 연도. 생략 시 서버가 현재 연도로 보완 |
smt | string | 아니오 | 11, 21, "" | 발급 기준 학기. 빈 문자열=학기 전체 |
selected_items | array | 조건부 | — | CERT_KOR / CERT_ENG일 때 필수. NONE_BENE일 때는 무시됨 |
selected_items[].yy | string | O | 4자리 연도 | cert/ 응답의 scho[].yy 값 |
selected_items[].smt | string | O | 11, 21 | cert/ 응답의 scho[].smt 값 |
selected_items[].schlsh_div | string | O | — | cert/ 응답의 scho[].schlsh_div 값 |
예시 — 국문 장학수혜증명서 발급 (두 학기 내역 포함)
{
"prt_div": "CERT_KOR",
"yy": "2025",
"smt": "",
"selected_items": [
{ "yy": "2025", "smt": "11", "schlsh_div": "01" },
{ "yy": "2024", "smt": "21", "schlsh_div": "04" }
]
}예시 — 영문 장학수혜증명서 발급
{
"prt_div": "CERT_ENG",
"yy": "2025",
"smt": "11",
"selected_items": [
{ "yy": "2025", "smt": "11", "schlsh_div": "01" }
]
}예시 — 비수혜증명서 발급 (selected_items 불필요)
{
"prt_div": "NONE_BENE",
"yy": "2025",
"smt": ""
}응답
200 OK
{
"url": "https://st.sch.ac.kr/oz/viewer?enc=eyJyZXBvcnROYW1lIjoidXBqL3Vzcy9zdGF0L1Vzc0JlbmVDZXJ0SXNzS29yIn0%3D"
}| 필드 | 타입 | 설명 |
|---|---|---|
url | string | OZ 리포트 뷰어 URL — 새 탭으로 열거나 iframe에 삽입하여 PDF 증명서 확인 |
에러 응답
| 에러 코드 | HTTP | 설명 |
|---|---|---|
UNAUTHORIZED | 401 | 세션 없음 또는 만료 |
INVALID_PRT_DIV | 400 | prt_div가 허용값이 아님 |
MISSING_ITEMS | 400 | CERT_KOR 또는 CERT_ENG인데 selected_items가 비어있거나 누락 |
INVALID_ITEMS | 400 | selected_items 항목에 yy, smt, schlsh_div 중 하나 이상 누락 |
REPORT_FAILED | 500 | SCH OZ 리포트 URL 생성 실패 (인증 오류 등) |
SCH_UNAVAILABLE | 503 | SCH 서버 연결 실패 |
{
"error": "INVALID_PRT_DIV"
}{
"error": "MISSING_ITEMS",
"message": "증명서에 포함할 내역을 선택하세요."
}{
"error": "INVALID_ITEMS"
}{
"error": "REPORT_FAILED",
"message": "PrintParamEnc 실패 (UssBeneCertIssKor) ErrorCode=9000 ncMsg=세션이 만료되었습니다."
}{
"error": "SCH_UNAVAILABLE",
"message": "증명서 URL 생성에 실패했습니다."
}GET /api/scholarship/board/
장학모집게시판 목록을 페이지 단위로 반환합니다. 1페이지당 15건이며, 학생 공개 게시물만 조회됩니다.
요청
| 파라미터 | 타입 | 필수 | 허용값 | 설명 |
|---|---|---|---|---|
page | number | 아니오 | 1 이상의 정수 | 페이지 번호. 기본값 1. 정수로 변환되지 않거나 1 미만이면 1로 재설정 |
예시 — 1페이지 조회 (기본)
GET /api/scholarship/board/예시 — 2페이지 조회
GET /api/scholarship/board/?page=2응답
200 OK
{
"total": 42,
"page": 1,
"total_pages": 3,
"has_next": true,
"items": [
{
"seq_no": "2025042801",
"scho_nm": "2025학년도 1학기 순천향대학교 성적우수장학금 모집",
"orgn_nm": "장학처",
"scho_type": "교내",
"aply_dt_tm": "2025-04-28 09:00:00",
"drwup_dt": "2025-05-15"
},
{
"seq_no": "2025041502",
"scho_nm": "2025년 한국장학재단 국가장학금 2차 신청 안내",
"orgn_nm": "한국장학재단",
"scho_type": "교외",
"aply_dt_tm": "2025-04-15 10:30:00",
"drwup_dt": "2025-05-09"
},
{
"seq_no": "2025040301",
"scho_nm": "SK하이닉스 드림장학금 모집 공고",
"orgn_nm": "SK하이닉스",
"scho_type": "교외",
"aply_dt_tm": "2025-04-03 11:00:00",
"drwup_dt": "2025-04-30"
}
]
}최상위 필드:
| 필드 | 타입 | 설명 |
|---|---|---|
total | number | 전체 게시물 수 |
page | number | 현재 페이지 번호 (요청한 값) |
total_pages | number | 전체 페이지 수 (total이 0이면 1) |
has_next | boolean | 다음 페이지 존재 여부 |
items | array | 현재 페이지 게시물 목록 (최대 15건) |
items 항목 필드:
| 필드 | 타입 | 설명 |
|---|---|---|
seq_no | string | 게시물 고유 번호 — board/detail/의 seq_no 파라미터로 전달 |
scho_nm | string | 장학금 명칭 |
orgn_nm | string | 운영 기관명 |
scho_type | string | 장학 유형 (교내, 교외 등) |
aply_dt_tm | string | 게시 일시 (YYYY-MM-DD HH:MM:SS 형식) |
drwup_dt | string | 신청 마감일 (YYYY-MM-DD 형식) |
에러 응답
| 에러 코드 | HTTP | 설명 |
|---|---|---|
UNAUTHORIZED | 401 | 세션 없음 또는 만료 |
SCH_UNAVAILABLE | 503 | SCH 서버 연결 실패 |
{
"error": "UNAUTHORIZED"
}{
"error": "SCH_UNAVAILABLE",
"message": "게시판을 불러오지 못했습니다."
}GET /api/scholarship/board/detail/
장학모집게시판 특정 게시물의 상세 내용을 반환합니다.
요청
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
seq_no | string | O | 게시물 고유 번호. board/ 응답의 items[].seq_no 값 |
예시
GET /api/scholarship/board/detail/?seq_no=2025042801응답
200 OK
{
"seq_no": "2025042801",
"scho_nm": "2025학년도 1학기 순천향대학교 성적우수장학금 모집",
"scho_type": "교내",
"orgn_nm": "장학처",
"as_dt_tm": "2025-04-28 09:00:00",
"ae_dt_tm": "2025-05-15 23:59:59",
"rel_url": "https://www.sch.ac.kr/scholarship/notice/2025042801",
"show_yn": "Y",
"drwup_dt_tm": "2025-05-15 23:59:59",
"mod_dt_tm": "2025-04-28 09:05:00",
"scho_desc": "2025학년도 1학기 성적우수장학금 모집 안내입니다.\n\n■ 지원 자격\n- 직전 학기 평점평균 3.5 이상\n- 15학점 이상 취득한 재학생 (1학년 2학기부터 신청 가능)\n\n■ 선발 규모\n- 학과별 재학생의 10% 이내\n\n■ 지원 금액\n- 등록금 전액 (입학금 제외)\n\n■ 신청 방법\n- SCH 통합정보시스템 포털 온라인 신청\n- 신청 기간: 2025.05.01 ~ 2025.05.15\n\n문의: 학생처 장학팀 041-530-1234"
}| 필드 | 타입 | 설명 |
|---|---|---|
seq_no | string | 게시물 고유 번호 |
scho_nm | string | 장학금 명칭 |
scho_type | string | 장학 유형 |
orgn_nm | string | 운영 기관명 |
as_dt_tm | string | 공고 시작 일시 (YYYY-MM-DD HH:MM:SS) |
ae_dt_tm | string | 공고 종료 일시 (YYYY-MM-DD HH:MM:SS) |
rel_url | string | 관련 외부 링크 URL (없으면 빈 문자열) |
show_yn | string | 공개 여부 (Y=공개, N=비공개) |
drwup_dt_tm | string | 신청 마감 일시 (YYYY-MM-DD HH:MM:SS) |
mod_dt_tm | string | 최종 수정 일시 (YYYY-MM-DD HH:MM:SS) |
scho_desc | string | 장학금 상세 내용. 줄바꿈(\n)이 포함된 원문 그대로 반환 |
에러 응답
| 에러 코드 | HTTP | 설명 |
|---|---|---|
UNAUTHORIZED | 401 | 세션 없음 또는 만료 |
MISSING_SEQ_NO | 400 | seq_no 파라미터 누락 또는 빈 문자열 |
NOT_FOUND | 404 | 해당 seq_no의 게시물이 존재하지 않음 |
SCH_UNAVAILABLE | 503 | SCH 서버 연결 실패 |
{
"error": "MISSING_SEQ_NO",
"message": "게시물 번호가 필요합니다."
}{
"error": "NOT_FOUND",
"message": "게시물을 찾을 수 없습니다."
}{
"error": "SCH_UNAVAILABLE",
"message": "상세 정보를 불러오지 못했습니다."
}증명서 발급 흐름 요약
장학증명서를 발급하는 전체 흐름은 다음과 같습니다.
1단계 — 수혜내역 조회
GET /api/scholarship/cert/?search_div=1응답에서 scho 배열과 has_reg 값을 확인합니다.
2단계 — 발급 유형 결정
scho배열에 항목이 있으면 국문(CERT_KOR) 또는 영문(CERT_ENG) 수혜증명서 발급 가능has_reg=true이면 비수혜증명서(NONE_BENE) 발급 가능
3단계 — 증명서 URL 요청
POST /api/scholarship/cert/report/
{
"prt_div": "CERT_KOR",
"yy": "2025",
"smt": "",
"selected_items": [
{ "yy": "2025", "smt": "11", "schlsh_div": "01" }
]
}4단계 — URL 열기
응답의 url 값을 새 탭으로 열거나 iframe에 삽입합니다.
window.open(data.url, "_blank")