# 하나은행 고시환율 (KEB Hana Bank FX Rates) (`consnam/hana-fx-rates`) Actor 하나은행 고시환율(최초/현재최종/특정회차)을 조회해 통화별 구조화 JSON으로 반환합니다. 브라우저 없이 데이터 엔드포인트에 직접 요청합니다. - **URL**: https://apify.com/consnam/hana-fx-rates.md - **Developed by:** [SangSu Nam](https://apify.com/consnam) (community) - **Categories:** Developer tools, Automation, Integrations - **Stats:** 4 total users, 2 monthly users, 97.9% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing Pay per usage This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## 하나은행 고시환율 (KEB Hana Bank FX Rates) ### What does 하나은행 고시환율 Actor do? **하나은행 고시환율(KEB Hana Bank published exchange rates) Actor**는 [하나은행 환율 조회 페이지](https://www.kebhana.com/cms/rate/wpfxd651_01i.do)에서 **최초 고시·현재 최종 고시·특정 회차** 환율을 조회해, 통화별로 **구조화된 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종). | 입력 예시: ```json { "date": "2026-07-03", "round": "first", "currencies": ["USD", "JPY", "EUR"] } ```` ### Output 통화당 1개의 dataset item이 생성됩니다. 결과는 **JSON, HTML, CSV, Excel** 등 다양한 형식으로 내려받을 수 있습니다. ```json { "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 ```bash 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 '{"date":"2026-07-03","round":"first","currencies":["USD","EUR","GBP"]}' ``` #### Python (apify-client) ```python from apify_client import ApifyClient client = ApifyClient("") 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 ```javascript 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** 탭을 이용해 주세요. # Actor input Schema ## `date` (type: `string`): 조회할 고시 일자 (YYYY-MM-DD). 생략하면 한국시간(KST) 기준 오늘. 주말·공휴일에는 하나은행과 동일하게 직전 영업일 고시환율이 반환됩니다. ## `round` (type: `string`): first = 최초 고시(하루 첫 고시), latest = 현재 최종 고시, specific = 특정 회차(아래 회차 번호 필요). ## `roundNumber` (type: `integer`): round = specific 일 때만 사용합니다. 조회할 고시 회차 번호(예: 3). ## `currencies` (type: `array`): ISO 통화 코드 목록 (예: USD, JPY, EUR). 생략하면 전체 통화(약 58종)를 반환합니다. ## Actor input object example ```json { "round": "first", "currencies": [ "USD", "JPY", "EUR" ] } ``` # Actor output Schema ## `results` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "currencies": [ "USD", "JPY", "EUR" ] }; // Run the Actor and wait for it to finish const run = await client.actor("consnam/hana-fx-rates").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "currencies": [ "USD", "JPY", "EUR", ] } # Run the Actor and wait for it to finish run = client.actor("consnam/hana-fx-rates").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "currencies": [ "USD", "JPY", "EUR" ] }' | apify call consnam/hana-fx-rates --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=consnam/hana-fx-rates", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "하나은행 고시환율 (KEB Hana Bank FX Rates)", "description": "하나은행 고시환율(최초/현재최종/특정회차)을 조회해 통화별 구조화 JSON으로 반환합니다. 브라우저 없이 데이터 엔드포인트에 직접 요청합니다.", "version": "0.1", "x-build-id": "SESitHnpho58IC55N" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/consnam~hana-fx-rates/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-consnam-hana-fx-rates", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/consnam~hana-fx-rates/runs": { "post": { "operationId": "runs-sync-consnam-hana-fx-rates", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/consnam~hana-fx-rates/run-sync": { "post": { "operationId": "run-sync-consnam-hana-fx-rates", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "date": { "title": "조회 일자 (Date)", "type": "string", "description": "조회할 고시 일자 (YYYY-MM-DD). 생략하면 한국시간(KST) 기준 오늘. 주말·공휴일에는 하나은행과 동일하게 직전 영업일 고시환율이 반환됩니다." }, "round": { "title": "고시 회차 유형 (Round type)", "enum": [ "first", "latest", "specific" ], "type": "string", "description": "first = 최초 고시(하루 첫 고시), latest = 현재 최종 고시, specific = 특정 회차(아래 회차 번호 필요).", "default": "first" }, "roundNumber": { "title": "회차 번호 (Round number)", "minimum": 1, "type": "integer", "description": "round = specific 일 때만 사용합니다. 조회할 고시 회차 번호(예: 3)." }, "currencies": { "title": "통화 코드 (Currencies)", "uniqueItems": true, "type": "array", "description": "ISO 통화 코드 목록 (예: USD, JPY, EUR). 생략하면 전체 통화(약 58종)를 반환합니다.", "items": { "type": "string" } } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```