환율 API / 개발자
개발자

하나은행 고시환율 API 개발자 가이드 (Apify, 코드 포함)

2026-09-01·약 11분·환율 · API · 하나은행 · Apify · Python · 개발자

환율 데이터를 자동으로 수집하려고 하면 생각보다 빨리 브라우저 자동화 문제를 만나게 됩니다. 하나은행 환율 페이지에서 날짜와 고시 회차를 선택해 값을 확인하는 일은 간단하지만, 이 과정을 매일 프로그램으로 반복하려면 페이지 로딩, AJAX 요청, 대기 시간, HTML 파싱 등을 직접 처리해야 합니다.

이 글에서는 제가 만든 하나은행 고시환율 API Apify Actor를 이용해, Selenium이나 Playwright 없이 하나은행 최초·현재 최종 고시환율을 REST API로 조회하는 방법을 소개합니다.

  • Actor 페이지: https://apify.com/consnam/hana-fx-rates
  • 개발자용 API 사용법이 궁금하신 분, 또는 Google Sheets·엑셀 자동화에 붙이고 싶으신 분에게 유용합니다.

핵심만 먼저 보기

오늘의 USD·JPY·EUR 최초 고시환율은 다음 요청 하나로 조회할 수 있습니다.

curl -X POST \
  "https://api.apify.com/v2/acts/consnam~hana-fx-rates/run-sync-get-dataset-items" \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{"round":"first","currencies":["USD","JPY","EUR"]}'
  • round는 first(최초·1회차) 또는 latest(현재 최종)를 사용할 수 있습니다.
  • currencies를 생략하면 제공되는 전체 통화(약 58종)를 반환합니다.
  • date를 생략하면 한국 시간 기준 오늘을 조회합니다.
  • 요청이 끝나면 환율 데이터가 JSON 배열로 반환됩니다.

직접 입력하지 않고 먼저 결과를 확인하고 싶다면 아래 공개 예제를 실행해볼 수 있습니다.

하나은행 환율 자동화가 번거로운 이유

사람이 브라우저에서 환율표를 확인하는 것과 프로그램이 안정적으로 데이터를 가져오는 것은 다른 문제입니다. 화면에 보이는 웹페이지는 데이터를 모두 담고 있는 정적인 HTML 문서가 아니라, 조건을 선택한 뒤 내부 요청으로 결과를 불러오는 구조입니다.

브라우저 자동화로 접근하면 보통 다음 작업이 필요합니다.

# 개념을 보여주기 위한 예시입니다.
driver.get(HANA_EXCHANGE_RATE_PAGE)
wait.until(page_is_ready)
select_date(...)
select_round(...)
click_search_button()
wait.until(result_table_is_visible)
rows = parse_result_table(...)

여기에 브라우저 드라이버 관리, 선택자 변경 대응, 로딩 대기, 실패 재시도까지 추가됩니다. 하루 한두 번 환율을 기록하려는 목적에는 유지보수 부담이 큰 편입니다.

이 API는 그 과정을 Actor 안에서 처리합니다. 사용자는 날짜, 회차, 통화만 JSON으로 전달하고 정리된 결과를 받으면 됩니다.

Apify API 토큰 준비하기

API로 실행하려면 Apify 계정과 API 토큰이 필요합니다. 토큰은 코드에 직접 적지 말고 환경 변수에 보관하는 편이 안전합니다.

macOS나 Linux에서는 다음과 같이 설정할 수 있습니다.

export APIFY_TOKEN="your_apify_token"

Git 저장소에 올리는 .env 파일이나 소스 코드에 실제 토큰을 포함하지 않도록 주의하세요.

최초(1회차) 고시환율 조회하기

업무 기준 환율이나 매일 아침의 고정된 기준값이 필요하다면 round에 first를 지정합니다.

{
  "round": "first",
  "currencies": ["USD", "JPY", "EUR"]
}

실행 결과는 다음과 같은 JSON 배열입니다. 아래 값은 2026년 7월 27일 실제 실행 결과 중 USD 항목을 간추린 것입니다.

[
  {
    "date": "2026-07-27",
    "round": 1,
    "roundType": "first",
    "announcedAt": "08:24",
    "currency": "USD",
    "currencyName": "미국",
    "unit": 1,
    "baseRate": 1466.3,
    "cashBuy": 1491.96,
    "cashSell": 1440.64,
    "wireSend": 1480.6,
    "wireReceive": 1452.0,
    "source": "KEB Hana Bank"
  }
]

baseRate뿐 아니라 현찰 살 때와 팔 때, 송금 보낼 때와 받을 때의 환율도 함께 받을 수 있습니다.

필드 의미
date 실제 환율 기준일
round / roundType 고시 회차 / first 또는 latest
announcedAt 고시 시각
currency / currencyName 통화 코드 / 통화명
unit 환율 표시 단위
baseRate 매매기준율
cashBuy / cashSell 현찰 매수·매도 환율
wireSend / wireReceive 송금 보낼 때·받을 때 환율

Python에서 환율 데이터 가져오기

Python에서는 requests로 동일한 API를 호출할 수 있습니다.

import os
import requests

url = (
    "https://api.apify.com/v2/acts/"
    "consnam~hana-fx-rates/run-sync-get-dataset-items"
)

response = requests.post(
    url,
    headers={"Authorization": f"Bearer {os.environ['APIFY_TOKEN']}"},
    json={"round": "first", "currencies": ["USD", "JPY", "EUR"]},
    timeout=60,
)
response.raise_for_status()

for rate in response.json():
    print(rate["date"], rate["currency"], rate["baseRate"])

이 결과를 데이터베이스에 저장하거나 Slack 알림, 사내 대시보드, 회계 시트와 연결할 수 있습니다. Apify의 스케줄 기능을 사용하면 별도의 서버 없이 정해진 시간에 Actor를 실행할 수도 있습니다.

현재 최종 고시환율과 전체 통화 조회하기

업무를 실행하는 시점의 최신 고시 회차가 필요하면 latest를 사용합니다.

{
  "round": "latest"
}

currencies를 생략했기 때문에 지원되는 전체 통화가 반환됩니다.

두 옵션은 다음처럼 구분하면 쉽습니다.

  • 매일 변하지 않는 하나의 기준값이 필요하다면 first
  • 실행 시점의 가장 최근 환율이 필요하다면 latest
  • 특정 통화만 필요하다면 currencies에 ["USD", "JPY"]처럼 지정
  • 전체 통화가 필요하다면 currencies를 생략

날짜를 직접 지정하는 방법

과거 환율을 조회하려면 date를 YYYY-MM-DD 형식으로 전달합니다.

{
  "date": "2026-07-10",
  "round": "first",
  "currencies": ["USD", "JPY", "EUR"]
}

주말이나 공휴일처럼 고시가 없는 날짜를 요청하면 하나은행이 제공하는 이전 영업일 데이터가 반환될 수 있습니다. 따라서 요청한 날짜와 같다고 가정하지 말고, 결과의 date 필드로 실제 기준일을 확인해야 합니다.

사용할 때 주의할 점

  • JPY, VND, IDR은 단위를 확인해야 합니다. 일부 통화는 1단위가 아니라 100단위로 표시됩니다. 계산에 사용할 때는 unit 값도 함께 확인하세요.
  • 최신 고시는 하루 중 달라질 수 있습니다. latest 결과는 실행 시점에 따라 회차와 환율이 바뀝니다. 매일 비교 가능한 고정 기준이 필요하다면 first가 더 적합합니다.
  • 결과의 기준일을 확인해야 합니다. 주말·공휴일·미래 날짜에는 요청일과 실제 기준일이 다를 수 있습니다. 자동화 로직에서는 항상 응답의 date를 저장하는 것이 안전합니다.
  • 공식 증빙을 대신하지 않습니다. 회계·세무·계약상 공식 증빙이 필요한 경우에는 은행이 제공하는 공식 자료와 조직의 업무 기준을 함께 확인해야 합니다.

직접 사용해보기

하나은행 고시환율 API는 제가 반복적인 환율 수집을 간단하게 만들기 위해 개발한 Apify Actor입니다. 코드 없이 Console에서 실행할 수도 있고, REST API·스케줄·Webhook·Google Sheets 같은 자동화 흐름에 연결할 수도 있습니다.

개발자가 아니라 Google Sheets에서 바로 사용하고 싶다면 복사해서 쓰는 환율 자동화 템플릿도 참고할 수 있습니다. 최초(1회차)와 현재 최종의 차이가 궁금하다면 최초 고시환율 vs 현재 최종 고시환율 차이도 함께 보세요.

다음 글 →
고시환율 1회차(최초) vs 최종 - 헷갈리는 개념 정리