한국수출입은행(https://www.koreaexim.go.kr) 환율 API 주소 변경과 null 응답 원인

한국수출입은행 환율 API 주소 변경 — 옛 주소는 2026년 4월 중단

한국수출입은행 Open API 명세(수정일 2026년 4월 28일)의 변경 이력은 이렇습니다.

2025년 6월부터 새 도메인을 쓰라고 공지했고, 2026년 4월 30일 옛 도메인 병행 가동이 끝났습니다. 몇 년 전 블로그 예제를 그대로 복사한 코드라면 주소가 www.koreaexim.go.kr로 시작할 가능성이 높습니다. 이 부분만 oapi.koreaexim.go.kr로 바꾸면 됩니다.

회사 내부망에서 호출한다면 방화벽도 확인해야 합니다. 명세에는 홈페이지 접속 IP와 API 호출 IP가 다르게 적혀 있습니다. 누리집은 열리는데 API만 응답이 없다면 API 호출 IP(39.115.136.167)가 막혀 있는지 보세요.

한국수출입은행 현재환율 API 요청 방법

현재환율 API는 GET으로 부르고 결과를 JSON으로 받습니다.

• 요청 URL — https://oapi.koreaexim.go.kr/site/program/financial/exchangeJSON
• authkey(필수) — Open API 신청 시 발급된 인증키
• searchdate — 2015-01-01 또는 20150101 형식, 생략하면 현재일
• data(필수) — AP01 환율 · AP02 대출금리 · AP03 국제금리
• 일일 제한 — 1000회
• 제공 부서 — 정보시스템부 (02-3779-6549)

호출 순서는 이렇습니다.

1. 누리집 Open API 메뉴에서 현재환율 API를 고르고 인증키 발급을 신청합니다.
2. 요청 URL 뒤에 authkey, searchdate, data=AP01을 붙입니다.
3. 응답 배열의 각 항목에서 result가 1인지 먼저 확인합니다.
4. 통화코드(cur_unit)로 원하는 통화를 골라 씁니다.

data 값을 빠뜨리거나 오타를 내면 result 2(DATA코드 오류)가 납니다. 대출금리와 국제금리는 요청 URL 자체가 다르니(interestJSON, internationalJSON) data 값만 바꿔서는 안 됩니다.

한국수출입은행 API 결과코드와 인증키 파기

응답 배열의 result 값으로 원인을 가립니다.

• 1 — 성공
• 2 — DATA코드 오류
• 3 — 인증코드 오류
• 4 — 일일 제한횟수 마감(1000회 초과)
• 키 보유기간 — 개인정보 보유기간 2년
• 재동의 — 파기 전 이메일 안내 → 재동의 시 2년 연장

가장 헷갈리는 것이 잘 쓰던 키에서 갑자기 result 3이 나오는 경우입니다. 한국수출입은행은 최초 신청 때 받은 개인정보의 보유기간(2년)이 지나면 개인정보보호법에 따라 개인정보와 사용정보를 파기하고, 이때 API 키도 함께 파기된다고 안내합니다.

파기 전에 등록한 이메일로 '개인정보 수집 재동의' 메일이 가고, 재동의하면 2년이 늘어납니다. 메일을 놓쳐 키가 파기됐다면 그 키는 다시 쓸 수 없어 신규 발급을 받아야 합니다. 담당자 이메일 주소를 회사 공용 메일로 등록해 두면 재동의 메일을 놓칠 일이 줄어듭니다.

result 4는 하루 1000회를 넘긴 경우입니다. 이때는 데이터를 주지 않습니다. 환율은 하루 한 번만 바뀌므로 매번 부르지 말고 한 번 받아 저장해 쓰는 것이 맞습니다.

한국수출입은행 환율 null 응답 — 11시와 영업일

result가 1인데 값이 비어 있다면 호출 시점 문제입니다.

• 데이터 성격 — 일환율(하루 단위)
• 업데이트 — 영업일 11시 전후
• 비영업일 요청 — null 반환
• 당일 11시 전 요청 — null 반환
• searchdate 생략 — 현재일로 조회
• 해결 — 직전 영업일 날짜로 재요청 또는 11시 이후 호출

명세의 '이용 시 유의사항'에 비영업일의 데이터, 또는 영업일 당일 11시 이전에 해당일 데이터를 요청하면 null이 반환된다고 적혀 있습니다. 누리집 환율정보 화면에서도 자료가 없는 날은 '해당일의 환율정보가 존재하지 않습니다'라고만 나옵니다.

그래서 searchdate를 비워 '오늘'을 부르는 코드는 주말·공휴일과 평일 오전에 늘 빈 값을 받습니다. 프로그램에서는 이렇게 처리하는 것이 안전합니다.

1. 오늘 날짜로 먼저 부릅니다.
2. 값이 null이면 하루씩 앞 날짜로 바꿔 다시 부릅니다.
3. 값이 나온 날짜와 함께 저장해 화면에 '기준일'을 표시합니다.

한국수출입은행 환율 응답 항목과 값 처리

현재환율 API가 돌려주는 항목입니다.

• CUR_UNIT · CUR_NM — 통화코드 · 국가/통화명
• TTB · TTS — 전신환(송금) 받으실때 · 보내실때
• DEAL_BAS_R — 매매 기준율
• BKPR — 장부가격
• YY_EFEE_R · TEN_DD_EFEE_R — 년환가료율 · 10일환가료율
• KFTC_DEAL_BAS_R · KFTC_BKPR — 서울외국환중개 매매기준율 · 장부가격

값을 계산에 쓸 때 막히는 지점이 두 군데 있습니다.

• 값이 숫자가 아니라 문자열이고, 명세의 응답 예시처럼 천 단위 쉼표가 들어간 값이 있습니다. 쉼표를 지운 뒤 숫자로 바꿔야 합니다.
• 일본 엔은 JPY(100), 인도네시아 루피아는 IDR(100)처럼 100단위로 고시되는 통화가 있습니다. 1엔당 값을 쓰려면 100으로 나눠야 합니다.

또 응답 예시에는 이미 쓰지 않는 옛 유럽 통화가 거래 환율 0으로 함께 들어 있습니다. 전신환 값이 0인 통화는 걸러 내고 쓰는 것이 좋습니다.

한국수출입은행 환율정보 화면과 대출·국제금리 API

코드를 짜지 않고 환율만 볼 때는 누리집 화면을 씁니다. '금리/환율정보 → 환율정보'에서 기준일을 골라 조회하고, 엑셀이나 CSV로 내려받을 수 있습니다.

• 환율정보 화면 — 기준일 선택 · 조회 · 엑셀/CSV 다운로드
• 대출금리 API — interestJSON · 대출기간별 고정기준금리
• 국제금리 API — internationalJSON · SOFR 등 국제금리
• CIRR — 표시통화국 국채 수익률 + 1%, OECD가 매월 15일 기준 고시
• 대표전화 — 02-3779-6114 / 02-6255-5114
• 주소 — 서울 영등포구 은행로 38

대출금리 API는 대출기간(SFLN_INTRC_NM)과 고정기준금리(INT_R)를, 국제금리 API는 통화(CUR_FUND), 기간, 금리를 돌려줍니다. 두 API도 2026년 4월 30일부터 oapi 도메인만 씁니다.

Open API 목록의 조회수를 보면 현재환율 API가 37만 회를 넘어 세 API 가운데 압도적으로 많이 쓰입니다. 그만큼 옛 예제 코드도 많이 돌아다니니, 예제를 가져다 쓸 때는 주소와 data 값부터 확인하세요.