Soonlife DOCS
API 레퍼런스

장학 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": "특기자장학금" }
]
필드타입설명
codestring장학 성격 코드 — scholarship/search/scho_type 파라미터에 전달
namestring장학 성격 한국어 명칭

에러 응답

에러 코드HTTP설명
UNAUTHORIZED401세션 없음 또는 만료
SCH_UNAVAILABLE503SCH 서버에서 성격 목록을 가져오지 못함
{
  "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_divstring아니오PERSONAL, NM검색 방식. PERSONAL=조건검색, NM=이름검색. 기본값 PERSONAL
in_outstring아니오T, I, O교내외 구분. T=전체, I=교내, O=교외. 기본값 T
dupl_bene_ynstring아니오T, Y, N중복 수혜 가능 여부. T=전체, Y=가능, N=불가. 기본값 T
earn_gradestring아니오0~10취득학점 기준 필터. 기본값 10
schlsh_div_nmstring아니오임의 문자열장학금 성격명 검색어. 빈 문자열=전체
acqst_cdtstring아니오임의 문자열이수학점 기준
avg_mrksstring아니오임의 문자열평균성적(GPA) 기준. 예: 3.5
rsco_avgstring아니오임의 문자열백분위 평균 기준
scho_typestring아니오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 이상인 학생이 대상입니다."
  }
]
필드타입설명
namestring장학금 성격명
in_outstring교내외 구분 (I=교내, O=교외)
acqst_cdtstring이수학점 기준
avg_mrksstring평균성적(GPA) 기준
rsco_avgstring백분위 평균 기준
sup_scastring지원 규모 또는 금액
earn_gradestring취득학점 기준
scho_typestring장학 성격 코드
dupl_bene_ynstring중복 수혜 가능 여부 (Y=가능, N=불가)
remarkstring비고 및 자격 요약
scho_descstring장학금 상세 설명

에러 응답

에러 코드HTTP설명
UNAUTHORIZED401세션 없음 또는 만료
SCH_UNAVAILABLE503SCH 서버 연결 실패 또는 검색 실패
{
  "error": "UNAUTHORIZED"
}
{
  "error": "SCH_UNAVAILABLE",
  "message": "장학금 검색에 실패했습니다."
}

GET /api/scholarship/cert/

장학수혜내역을 조회합니다. POST /api/scholarship/cert/report/로 증명서를 발급하기 전 반드시 이 엔드포인트를 먼저 호출하여 포함할 수혜 내역을 확인해야 합니다.

요청

파라미터타입필수허용값설명
search_divstring아니오1, 2조회 범위. 1=전체 기간, 2=학기 지정. 기본값 1
yystring조건부4자리 연도search_div=2일 때 필수. 예: 2025
smtstring조건부11, 21search_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
}

최상위 필드:

필드타입설명
regiarray학적 등록 정보 (이름, 학과 등)
schoarray장학수혜 내역 목록 — 증명서 발급 시 selected_items 구성에 사용
has_regboolean비수혜증명서 발급 가능 여부. true이면 cert/report/에서 prt_div=NONE_BENE 발급 가능

regi 항목 필드:

필드타입설명
std_nostring학번
nmstring이름
univstring단과대학명
suststring학과명
sch_regi_divstring학적 구분 (재학, 졸업, 휴학 등)
shyrstring학년

scho 항목 필드:

필드타입설명
yystring장학 수혜 학년도
smtstring장학 수혜 학기 코드 (11=1학기, 21=2학기)
smt_nmstring학기 표시명
schlsh_divstring장학 성격 코드 — cert/report/selected_items[].schlsh_div에 사용
schlsh_div_nmstring장학금 성격명
schlsh_ent_amtstring입학금 지원액 (원 단위 문자열)
schlsh_class_amtstring수업료 지원액 (원 단위 문자열)
sche_amtstring장학생 지원액 (원 단위 문자열)
schlsh_amtstring장학금 합계 (원 단위 문자열)

증명서 발급 흐름: cert/를 호출하여 scho 배열을 받은 뒤, 사용자가 선택한 항목에서 yy, smt, schlsh_div를 추출하여 cert/report/selected_items에 전달합니다. has_reg=false이면 비수혜증명서(NONE_BENE)도 발급할 수 없습니다.

에러 응답

에러 코드HTTP설명
UNAUTHORIZED401세션 없음 또는 만료
INVALID_SEARCH_DIV400search_div1 또는 2가 아님
MISSING_YEAR400search_div=2인데 yy 누락 또는 4자리 숫자가 아님
MISSING_SEMESTER400search_div=2인데 smt11 또는 21이 아님
SCH_UNAVAILABLE503SCH 서버 연결 실패
{
  "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_divCERT_KOR(국문 수혜증명서) 또는 CERT_ENG(영문 수혜증명서)인 경우 selected_items가 반드시 포함되어야 합니다. 먼저 GET /api/scholarship/cert/를 호출하고, 응답의 scho 배열에서 증명서에 포함할 항목의 yy, smt, schlsh_div를 추출하여 전달하세요.

요청

Body (application/json)

필드타입필수허용값설명
prt_divstringOCERT_KOR, CERT_ENG, NONE_BENE증명서 종류. 국문수혜 / 영문수혜 / 비수혜
yystring아니오4자리 연도발급 기준 연도. 생략 시 서버가 현재 연도로 보완
smtstring아니오11, 21, ""발급 기준 학기. 빈 문자열=학기 전체
selected_itemsarray조건부CERT_KOR / CERT_ENG일 때 필수. NONE_BENE일 때는 무시됨
selected_items[].yystringO4자리 연도cert/ 응답의 scho[].yy
selected_items[].smtstringO11, 21cert/ 응답의 scho[].smt
selected_items[].schlsh_divstringOcert/ 응답의 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"
}
필드타입설명
urlstringOZ 리포트 뷰어 URL — 새 탭으로 열거나 iframe에 삽입하여 PDF 증명서 확인

에러 응답

에러 코드HTTP설명
UNAUTHORIZED401세션 없음 또는 만료
INVALID_PRT_DIV400prt_div가 허용값이 아님
MISSING_ITEMS400CERT_KOR 또는 CERT_ENG인데 selected_items가 비어있거나 누락
INVALID_ITEMS400selected_items 항목에 yy, smt, schlsh_div 중 하나 이상 누락
REPORT_FAILED500SCH OZ 리포트 URL 생성 실패 (인증 오류 등)
SCH_UNAVAILABLE503SCH 서버 연결 실패
{
  "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건이며, 학생 공개 게시물만 조회됩니다.

요청

파라미터타입필수허용값설명
pagenumber아니오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"
    }
  ]
}

최상위 필드:

필드타입설명
totalnumber전체 게시물 수
pagenumber현재 페이지 번호 (요청한 값)
total_pagesnumber전체 페이지 수 (total이 0이면 1)
has_nextboolean다음 페이지 존재 여부
itemsarray현재 페이지 게시물 목록 (최대 15건)

items 항목 필드:

필드타입설명
seq_nostring게시물 고유 번호 — board/detail/seq_no 파라미터로 전달
scho_nmstring장학금 명칭
orgn_nmstring운영 기관명
scho_typestring장학 유형 (교내, 교외 등)
aply_dt_tmstring게시 일시 (YYYY-MM-DD HH:MM:SS 형식)
drwup_dtstring신청 마감일 (YYYY-MM-DD 형식)

에러 응답

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

GET /api/scholarship/board/detail/

장학모집게시판 특정 게시물의 상세 내용을 반환합니다.

요청

파라미터타입필수설명
seq_nostringO게시물 고유 번호. 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_nostring게시물 고유 번호
scho_nmstring장학금 명칭
scho_typestring장학 유형
orgn_nmstring운영 기관명
as_dt_tmstring공고 시작 일시 (YYYY-MM-DD HH:MM:SS)
ae_dt_tmstring공고 종료 일시 (YYYY-MM-DD HH:MM:SS)
rel_urlstring관련 외부 링크 URL (없으면 빈 문자열)
show_ynstring공개 여부 (Y=공개, N=비공개)
drwup_dt_tmstring신청 마감 일시 (YYYY-MM-DD HH:MM:SS)
mod_dt_tmstring최종 수정 일시 (YYYY-MM-DD HH:MM:SS)
scho_descstring장학금 상세 내용. 줄바꿈(\n)이 포함된 원문 그대로 반환

에러 응답

에러 코드HTTP설명
UNAUTHORIZED401세션 없음 또는 만료
MISSING_SEQ_NO400seq_no 파라미터 누락 또는 빈 문자열
NOT_FOUND404해당 seq_no의 게시물이 존재하지 않음
SCH_UNAVAILABLE503SCH 서버 연결 실패
{
  "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")

On this page