하나은행 고시환율 (KEB Hana Bank FX Rates)

What does 하나은행 고시환율 Actor do?

하나은행 고시환율(KEB Hana Bank published exchange rates) Actor는 하나은행 환율 조회 페이지에서 최초 고시·현재 최종 고시·특정 회차 환율을 조회해, 통화별로 구조화된 JSON으로 반환합니다. 브라우저(Selenium 등) 없이 데이터 엔드포인트에 직접 요청하므로 수 초 안에 결과가 나옵니다.

하나은행 최초 고시환율은 무역 계약·사내 회계·정산 기준으로 널리 쓰이지만, 무료 환율 API(Frankfurter, ECB, ExchangeRate-API 등)에는 존재하지 않는 데이터입니다. 조회 페이지가 iframe + JavaScript AJAX 구조라 프로그래밍 접근이 까다로운데, 이 Actor가 그 부분을 대신 처리합니다.

Apify 플랫폼에서 실행하면 API 접근, 스케줄링, 통합(Integrations), 모니터링을 그대로 활용할 수 있습니다.

Why use 하나은행 고시환율 Actor?

• 무료 API에 없는 데이터: 하나은행 고시 기준 환율(매매기준율, 현찰/송금/외화수표, 환가료율, 미화환산율)을 그대로 제공합니다.
• 회차 지정 조회: 하루 첫 고시(최초)뿐 아니라 특정 회차(예: 3회차)와 현재 최종 고시를 골라 조회할 수 있습니다.
• 과거 일자 조회: 지난 영업일의 고시환율을 날짜로 조회할 수 있습니다.
• 즉시성 & 경량: 요청 1번 + 파싱으로 동작해 빠르고 비용이 낮습니다.
• 자동화 연동: ERP·회계 시스템, Google Sheets, Make, Zapier 등과 API로 연결하기 쉽습니다.

How to use 하나은행 고시환율 Actor

1. Input 탭에서 조회할 일자(date), 회차 유형(round), 필요 시 회차 번호(roundNumber), **통화(currencies)**를 설정합니다.
2. Start 버튼을 눌러 실행합니다. (아무 것도 설정하지 않으면 오늘(KST) 최초 고시를 전체 통화로 조회합니다.)
3. 실행이 끝나면 Output/Dataset 탭에서 결과를 확인하고, JSON·CSV·Excel 등으로 내려받거나 API로 가져갑니다.

Input

필드	타입	설명
date	string	조회 일자 YYYY-MM-DD. 생략 시 한국시간(KST) 기준 오늘. 주말·공휴일에는 하나은행과 동일하게 직전 영업일 고시환율이 반환됩니다(date 필드가 실제 고시일).
round	string	first=최초 고시, latest=현재 최종, specific=특정 회차. 기본값 first.
roundNumber	integer	round=specific일 때만 사용하는 고시 회차 번호.
currencies	array	ISO 통화 코드 목록(예: ["USD","JPY","EUR"]). 생략 시 전체(약 58종).

입력 예시:

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

Output

통화당 1개의 dataset item이 생성됩니다. 결과는 JSON, HTML, CSV, Excel 등 다양한 형식으로 내려받을 수 있습니다.

{
    "date": "2026-07-03",
    "round": 1,
    "roundType": "first",
    "announcedAt": "08:26",
    "announcedDateTime": "2026-07-03T08:26:54",
    "currency": "USD",
    "currencyName": "미국",
    "unit": 1,
    "baseRate": 1554.10,
    "cashBuy": 1581.29,
    "cashBuySpread": 1.75,
    "cashSell": 1526.91,
    "cashSellSpread": 1.75,
    "wireSend": 1569.30,
    "wireReceive": 1538.90,
    "checkSell": 1536.52,
    "conversionFeeRate": 5.51738,
    "usdConversionRate": 1.0000,
    "source": "KEB Hana Bank",
    "fetchedAt": "2026-07-04T06:14:14+00:00"
}

Data fields

필드	설명
date	고시 기준일 (YYYY-MM-DD)
round	고시 회차 번호
roundType	회차 유형 (first / latest / specific)
announcedAt	고시 시각 (HH:MM)
announcedDateTime	고시 일시 (ISO 8601)
currency	통화 코드 (ISO 4217)
currencyName	통화명(국가)
unit	고시 단위 (1, JPY·VND·IDR은 100)
baseRate	매매기준율
cashBuy / cashBuySpread	현찰 사실 때 환율 / 스프레드
cashSell / cashSellSpread	현찰 파실 때 환율 / 스프레드
wireSend	송금 보낼 때
wireReceive	송금 받을 때
checkSell	외화수표 파실 때
conversionFeeRate	환가료율
usdConversionRate	미화환산율
source	데이터 출처 (KEB Hana Bank)
fetchedAt	수집 시각 (ISO 8601, UTC)

참고 — 단위(unit): 일본 엔(JPY), 베트남 동(VND), 인도네시아 루피아(IDR)는 100단위로 고시됩니다. 환율을 1단위 기준으로 환산하려면 값을 unit으로 나누세요.

API로 호출하기 (Use via API)

이 Actor는 MCP뿐 아니라 표준 REST API로 어디서든 호출할 수 있습니다. run-sync-get-dataset-items 엔드포인트는 실행 후 결과(dataset items)를 응답으로 바로 돌려줍니다. Console의 API 탭에서 내 Actor ID가 채워진 스니펫을 언제든 복사할 수 있고, 아래 문서를 AI 코딩 도구(Claude 등)에 그대로 주면 원하는 언어의 연동 코드를 즉시 생성할 수 있습니다.

토큰은 Apify Console → Settings → API & Integrations에서 발급합니다.

cURL

curl -X POST \
  "https://api.apify.com/v2/acts/consnam~hana-fx-rates/run-sync-get-dataset-items" \
  -H "Authorization: Bearer <APIFY_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"date":"2026-07-03","round":"first","currencies":["USD","EUR","GBP"]}'

Python (apify-client)

from apify_client import ApifyClient

client = ApifyClient("<APIFY_TOKEN>")
run = client.actor("consnam/hana-fx-rates").call(run_input={
    "date": "2026-07-03",
    "round": "first",
    "currencies": ["USD", "EUR", "GBP"],
})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item["currency"], item["baseRate"])

Google Apps Script

function getHanaRates() {
  const res = UrlFetchApp.fetch(
    'https://api.apify.com/v2/acts/consnam~hana-fx-rates/run-sync-get-dataset-items',
    {
      method: 'post',
      contentType: 'application/json',
      headers: { Authorization: 'Bearer ' + PropertiesService.getScriptProperties().getProperty('APIFY_TOKEN') },
      payload: JSON.stringify({ round: 'first', currencies: ['USD', 'EUR', 'GBP'] }),
      muteHttpExceptions: true,
    }
  );
  return JSON.parse(res.getContentText()); // 통화별 환율 배열
}

How much does it cost?

MVP 단계에서는 무료로 공개됩니다(플랫폼 사용량에 대한 Apify 기본 요금만 적용). 이 Actor는 요청 1번 + 파싱으로 동작하는 매우 가벼운 작업이라 실행당 컴퓨트 비용이 낮습니다. 정상 사용 패턴은 하루 수 회 조회이며 대량 수집용이 아닙니다. 추후 수요가 확인되면 회차/과거일자 조회 가치에 맞춰 pay-per-event(PPE) 과금으로 전환될 수 있습니다.

Tips & advanced options

• 매일 최초 고시가 필요하다면 Apify Schedule로 매 영업일 오전에 자동 실행하고, Integrations로 Google Sheets/Slack/Webhook에 연결하세요.
• 특정 회차 비교가 필요하면 round=specific + roundNumber로 회차별 값을 각각 조회하세요.
• 통화를 좁히면 결과가 간결해집니다(currencies에 필요한 코드만 지정). 생략하면 전체 통화를 반환합니다.
• 은행 사이트에 부담을 주지 않도록 이 Actor는 요청 간 최소 1초 간격과 **재시도(지수 백오프)**를 적용합니다. 저빈도·비침해적 사용을 유지해 주세요.

FAQ, disclaimer & support

Q. 주말/공휴일 날짜로 조회하면? 하나은행과 동일하게 직전 영업일의 고시환율이 반환됩니다. 이때 결과의 date 필드에는 요청한 날짜가 아니라 **실제 고시된 날짜(직전 영업일)**가 담기므로, 어느 날짜의 데이터인지 바로 확인할 수 있습니다.

Q. 어떤 통화를 지원하나요? 하나은행이 고시하는 약 58종 통화 전체를 지원합니다(USD, JPY, EUR, CNY 등).

Q. 데이터가 갑자기 비거나 오류가 나요. 하나은행 사이트 구조가 바뀌면 "사이트 구조가 변경된 것 같습니다" 메시지와 함께 종료됩니다. 이 경우 Issues 탭으로 알려 주시면 신속히 업데이트하겠습니다.

Disclaimer: 본 Actor는 로그인이 필요 없는 공개 고시 정보(비개인·사실 데이터)를 조회합니다. 이용자는 대상 사이트의 이용약관을 준수하고, 저빈도·비침해적 사용을 유지할 책임이 있습니다. 본 도구는 하나은행과 제휴·보증 관계가 없습니다.

문의·버그 제보·커스텀 요청은 Apify Console의 Issues 탭을 이용해 주세요.