API가 처음이라면 - 오픈API 개념부터, 요청 보내기
API에 대해서
API(Application Programming Interface)는 프로그램끼리 대화하는 규칙을 말합니다. 상대 프로그램이 어떻게 구현되었는지 모르는 상황에서, 정해진 규칙에 따라 요청을 보내면 정해진 형태의 응답을 제공해주는 일명 "창구" 역할을 합니다.
식당에 비유하면 주방(서버 내부 로직)은 손님에게 공개되지 않고, 손님은 메뉴판(API 명세)을 보고 웨이터(API)에게 주문합니다. 주방에 주방장이 바뀌던, 어떤 방식으로 요리를 하던 메뉴판이 동일하면 손님은 동일한 주문에 동일한 음식(결과물)을 받습니다. 이게 API의 핵심 가치인 캡슐화와 느슨한 결합입니다.
- 캡슐화 : 어떻게 하는지는 감추고, 무엇을 할 수 있는지만 보여준다. API를 호출하는 쪽은 어떤 주소로 어떤 파라미터를 보내는가, 어떤 형태의 응답이 오는가 두가지에만 의존하고, 서버 안에서의 일은 알 필요가 없음.
- 느슨한 결합 : 서버의 DB 테이블을 변경하던, 서버의 구현 방식을 새로 갈아 엎던, 동일한 요청에 대해 동일한 응답만 주어지면 API를 호출하는 사용자는 영향을 받지 않습니다. 이를 느슨하게 결합되어 있다고 합니다.
웹 API의 구성요소
| 요 소 | 설 명 | 예 |
| 엔드포인트 | 기능이 놓인 주소 | https://api.example.com/v1/weather |
| 메서드 | 무엇을 할지 | GET(조회) POST(생성) PUT(수정) DELETE(삭제) |
| 요청 파라미터 | 조건 전달 | ?city=seoul&date=2026-09-18 |
| 인증 | 누가 부르는지 확인 | API Key, OAuth 토큰 |
| 응답 | 결과 데이터 | 주로 JSON 형태 |
API는 웹 뿐만 아니라 여러 층위에 존재합니다. 운영체제가 제공하는 시스템 API(파일 읽기/쓰기), 프로그래밍 언어의 라이브러리 API, 그리고 네트워크 상에서의 웹 API. 하지만 일상에서 "API"라고 하면 대개 웹API를 말합니다.
Open API란
Open API는 외부 개발자 누구나 쓸 수 있도록 공개된 API를 말합니다. 개방의 대상은 '코드'가 아니라 '사용 권한'입니다. 열려있다고 해서 서비스 내부 소스가 공개되는 것이 아닙니다. 다만, 앞에서 말한 것과 같이 데이터와 기능에 접근하는 통로(창구)를 열어두고, 누구나 요청을 할 수 있게 하는 것을 말합니다.
- 비공개(Private) API - 회사 내부 시스템끼리만 사용. 사내 결제 서버 <-> 주문 서버
- 파트너 API - 계약한 제휴사에만 개방. 항공사 <-> 여행 예약 플랫폼
- 오픈(Public) API - 가입만 하면 누구나 키를 발급받아 사용. 공공데이터포털, 카카오맵, 네이버 검색, 기상청 날씨 등
API 요청해보기
먼저 OpenDART에서 인증키를 신청해서 받습니다. 인증키를 받는 방법은 아래 기존 블로그에 정리되어 있습니다.
2026.09.16 - [분류 전체보기] - DART 재무제표를 API로 받는 방법 - 인증키부터 계정 목록까지
인증키는 코드 구문 상에서 "<발급키>"라고 표시합니다. 사용자는 "<발급키>" 대신에 발급받은 인증키를 대입하면 됩니다.
API 요청
아래는 OpenDART에 회사의 기본 정보를 요청하는 API 구문입니다. 맨 뒤의 "00108241"은 ㈜농심의 고유번호입니다.
https://opendart.fss.or.kr/api/company.json?crtfc_key=<발급키>&corp_code=00108241
| 구성 요소 | 요소 이름 | 설 명 |
| https://opendart.fss.or.kr | 서버 주소 | 어느 사이트에 요청을 보내는가 |
| /api/company.json | 엔드포인트(창구 경로) | 해당 사이트의 어느 창구에 요청을 보내는가. 창구마다 제공하는 응답이 다릅니다. |
| ?...&... | 쿼리 파라미터(조건) | 요청 기준들을 말하며, &로 여러개를 이어 붙임. |
| ctrtfc_key=<발급키> | 인증키 | 요청자를 확인하는 값 |
| corp_code=00108241 | 고유번호 설정 | 어느 고유번호 기준으로 응답을 생성할지. |
첫 번째 도구 : 브라우저 주소창
브라우저의 주소창으로 API 요청을 보낼 수 있습니다. 위 API 요청 구문을 브라우저의 주소창에 복사해서 넣고 엔터를 칩니다.
아래와 같이 결과가 바로 뜹니다. 특별히 설치할 것이 없고, 결과는 바로 화면에 뜹니다.
브라우저에서는 결과 값들이 자동으로 테이블 구조로 정리가 되서 표시됩니다. 실제 돌아오는 응답은 아래와 같이 한 줄로 길게 늘어진 텍스트 덩어리 입니다.
{"status":"000","message":"정상","corp_code":"00108241","corp_name":"(주)농심",
"corp_name_eng":"NONGSHIM CO.,LTD","stock_name":"농심","stock_code":"004370",
"ceo_nm":"조용철","corp_cls":"Y","jurir_no":"1101110057574","bizr_no":"1188103914",
"adres":"서울특별시 동작구 여의대방로 112","hm_url":"www.nongshim.com","ir_url":"",
"phn_no":"02-820-7114","fax_no":"02-820-7044","induty_code":"108",
"est_dt":"19650918","acc_mt":"12"}
- 필드가 19개 들어 있고, 회사명부터 대표자, 주소, 설립이, 결산월까지 사람이 사람이 그대로 읽을 수 있습니다.
두번째 도구 : Windows PowerShell 또는 Mac Terminal
윈도우즈 PowerShell
윈도우즈에는 PowerShell을 이용해서 간단하게 API 요청을 해볼 수 있습니다. 시작 메뉴에서 "Windows PowerShell"을 검색해서 실행할 수 있습니다.
Invoke-RestMethod와 Invoke-WebRequest 두개의 명령어가 있습니다.
| 명령어 | 별칭 | 반환값 | 언제 사용하는지 |
| Invoke-RestMethod | irm | JSON을 객체로 자동 변환 | API 호출 |
| Invoke-WebRequest | iwr | 상태코드, 헤더, 본문이 담긴 응답 객체 | 헤더/상태코드가 필요할 때, HTML 스크래핑 |
응답의 Content-Type이 JSON이면 Invoke-RestMethod를 사용하면 됩니다.
PS> $key = "<발급키>"
PS> $res = Invoke-RestMethod "https://opendart.fss.or.kr/api/company.json?crtfc_key=$key&corp_code=00108241"
PS> $res
status: 000
message: 정상
corp_code: 00108241
corp_name: (주)농심
corp_name_eng: NONGSHIM CO.,LTD
stock_name: 농심
stock_code: 004370
ceo_nm: 조용철
corp_cls: Y
jurir_no: 1101110057574
bizr_no: 1188103914
adres: 서울특별시 동작구 여의대방로 112
hm_url: www.nongshim.com
ir_url:
phn_no: 02-820-7114
fax_no: 02-820-7044
induty_code: 108
est_dt: 19650918
acc_mt: 12
PS> $res.corp_name
(주)농심발급키는 key 변수에 저장해서 사용하도록 했습니다. JSON이 객체로 풀려서 오기 때문에 $res.corp_name과 같이 필드를 바로 꺼낼 수 있습니다.
Mac Terminal
맥을 사용하시는 분들은 터미널에서 curl 명령어를 사용해서 동일한 요청을 해볼 수 있습니다. 다만, Invoke-RestMethod의 경우 JSON 데이터의 파싱을 자동으로 해주지만, 맥에서 curl은 요청해서 결과를 가져오는 기능만 있고, JSON 파싱은 jq 명령어를 사용합니다.
$ key="<발급키>"
$ curl -s "https://opendart.fss.or.kr/api/company.json?crtfc_key=$key&corp_code=00108241" | jq
{
"status": "000",
"message": "정상",
"corp_code": "00108241",
"corp_name": "(주)농심",
"corp_name_eng": "NONGSHIM CO.,LTD",
"stock_name": "농심",
"stock_code": "004370",
"ceo_nm": "조용철",
"corp_cls": "Y",
"jurir_no": "1101110057574",
"bizr_no": "1188103914",
"adres": "서울특별시 동작구 여의대방로 112",
"hm_url": "www.nongshim.com",
"ir_url": "",
"phn_no": "02-820-7114",
"fax_no": "02-820-7044",
"induty_code": "108",
"est_dt": "19650918",
"acc_mt": "12"
}
$ res=$(curl -s "https://opendart.fss.or.kr/api/company.json?crtfc_key=$key&corp_code=00108241" | jq)
$ echo $res
{ "status": "000", "message": "정상", "corp_code": "00108241", "corp_name": "(주)농심", "corp_name_eng": "NONGSHIM CO.,LTD", "stock_name": "농심", "stock_code": "004370", "ceo_nm": "조용철", "corp_cls": "Y", "jurir_no": "1101110057574", "bizr_no": "1188103914", "adres": "서울특별시 동작구 여의대방로 112", "hm_url": "www.nongshim.com", "ir_url": "", "phn_no": "02-820-7114", "fax_no": "02-820-7044", "induty_code": "108", "est_dt": "19650918", "acc_mt": "12" }
$ jq -r '.corp_name' <<< "$res"
(주)농심
회사정보 외 다른 정보를 요청해보고 싶을 때
OpenDART의 개발가이드(https://opendart.fss.or.kr/guide/main.do?apiGrpCd=DS001)에 API 사용 방법이 잘 정리가 되어 있습니다. 거의 모든 API가 기업 고유번호(corp_code)를 요구하기 때문에, API 사용을 위해서는 기업 고유번호를 확인하는 것이 우선입니다.
주요 엔드포인트
| 엔드포인트 | 내 용 |
| fnlttSinglAcnt.json | 단일회사 주요계정 — 요약 재무제표 |
| fnlttSinglAcntAll.json | 단일회사 전체 재무제표 |
| fnlttMultiAcnt.json | 다중회사 주요계정 (여러 회사 비교) |
| fnlttSinglIndx.json | 단일회사 주요 재무지표 |
| fnlttCmpnyIndx.json | 회사별 재무지표 |
| fnlttXbrl.xml | 재무제표 원본 XBRL (ZIP) |
재무제표 주요계정 요청해보기
PS> $res = Invoke-RestMethod 'https://opendart.fss.or.kr/api/fnlttSinglAcnt.json' -Body @{
crtfc_key = $key
corp_code = '00126380'
bsns_year = '2025'
reprt_code = '11011'
fs_div = 'CFS'
}
PS> $res.list | Select-Object account_nm, thstrm_amount | Format-Table -AutoSize
account_nm thstrm_amount
---------- -------------
유동자산 247,684,612,000,000
비유동자산 319,257,498,000,000
자산총계 566,942,110,000,000
유동부채 106,411,348,000,000
비유동부채 24,210,425,000,000
부채총계 130,621,773,000,000
자본금 897,514,000,000
이익잉여금 402,135,600,000,000
자본총계 436,320,337,000,000
매출액 333,605,938,000,000
영업이익 43,601,051,000,000
법인세차감전 순이익 49,481,471,000,000
당기순이익(손실) 45,206,805,000,000
당기순이익(손실) 45,206,805,000,000
총포괄손익 51,290,524,000,000
유동자산 101,439,429,000,000
비유동자산 257,462,622,000,000
자산총계 358,902,051,000,000
유동부채 72,935,381,000,000
비유동부채 31,636,587,000,000
부채총계 104,571,968,000,000
자본금 897,514,000,000
이익잉여금 254,566,830,000,000
자본총계 254,330,083,000,000
매출액 238,043,009,000,000
영업이익 23,603,619,000,000
법인세차감전 순이익 33,436,082,000,000
당기순이익(손실) 33,686,601,000,000
당기순이익(손실) 33,686,601,000,000
총포괄손익 35,219,970,000,000$ curl -s --get 'https://opendart.fss.or.kr/api/fnlttSinglAcnt.json' \
> --url-query "crtfc_key=$key" \
> --url-query 'corp_code=00126380' \
> --url-query 'bsns_year=2025' \
> --url-query 'reprt_code=11011' \
> --url-query 'fs_div=CFS' \
> | jq -r '.list[] | [.account_nm, .thstrm_amount] | @tsv' | column -t -s $'\t'
유동자산 247,684,612,000,000
비유동자산 319,257,498,000,000
자산총계 566,942,110,000,000
유동부채 106,411,348,000,000
비유동부채 24,210,425,000,000
부채총계 130,621,773,000,000
자본금 897,514,000,000
이익잉여금 402,135,600,000,000
자본총계 436,320,337,000,000
매출액 333,605,938,000,000
영업이익 43,601,051,000,000
법인세차감전 순이익 49,481,471,000,000
당기순이익(손실) 45,206,805,000,000
당기순이익(손실) 45,206,805,000,000
총포괄손익 51,290,524,000,000
유동자산 101,439,429,000,000
비유동자산 257,462,622,000,000
자산총계 358,902,051,000,000
유동부채 72,935,381,000,000
비유동부채 31,636,587,000,000
부채총계 104,571,968,000,000
자본금 897,514,000,000
이익잉여금 254,566,830,000,000
자본총계 254,330,083,000,000
매출액 238,043,009,000,000
영업이익 23,603,619,000,000
법인세차감전 순이익 33,436,082,000,000
당기순이익(손실) 33,686,601,000,000
당기순이익(손실) 33,686,601,000,000
총포괄손익 35,219,970,000,000reprt_code : 11011 사업보고서, 11012 반기, 11013 1분기, 11014 3분기
fs_div : CFS 연결, OFS 별도
위 두 파라미터는 재무 API 전반에서 똑같이 사용됩니다.
API를 이용하면 일정한 형식의 데이터를 쉽게 읽어올 수 있습니다. 여기서 "쉽게"라는 말은 한번 설정해 놓으면 주기적으로 자동으로 읽어올 수 있다는 의미입니다. 일정한 형식으로 정리정돈 된 데이터를 가져오는 문제가 해결되면, 이를 편집하고, 정리하는 작업은 상대적으로 쉽습니다.