모듈 3 — 주식 현재가 시세 조회

이 모듈에서 할 일 모듈 2에서 발급받은 토큰을 사용해 삼성전자(또는 원하는 종목)의 현재가·등락률·거래량을 조회하고, 응답 JSON에서 필요한 필드만 추려 다음 모듈에서 쓰기 좋은 형태로 정리합니다. 이 모듈에서 처음으로 노드 간 데이터 전달 표현식이 등장합니다.

0. 이 모듈의 흐름

flowchart TD
    A[1.API 문서 읽기] --> B[2.HTTP Request1<br/>추가]
    B --> C[3.Method·URL]
    C --> D[4.Query Parameters]
    D --> E[5.Headers<br/>토큰 전달]
    E --> F[6.실행·응답 해석]
    F --> G[7.Edit Fields<br/>필드 정제]
    G --> H[8.검증]

이번 모듈을 마치면 워크플로는 4개 노드가 됩니다.

flowchart TD
    A[Schedule Trigger] --> B[HTTP Request<br/>토큰]
    B --> C[HTTP Request1<br/>현재가]
    C --> D[Edit Fields<br/>5개 필드]

1. API 문서 읽기 — 호출하기 전에 먼저 알아야 할 것

1.1 왜 문서를 먼저 읽어야 하나요?

API 호출은 빈칸 채우기 시험과 비슷합니다. URL·헤더·쿼리·바디 각 칸에 정확한 값을 채워야 정상 응답이 옵니다. 어떤 칸이 있는지, 무엇이 필수인지는 API 문서에만 적혀 있습니다.

1.2 어디로 가나요?

🌐 한국투자 Open API 개발자센터: apiportal.koreainvestment.com

다음 경로로 들어갑니다.

[API 문서] → [국내주식] 기본시세 → [주식현재가 시세]

flowchart TD
    A[API 문서] --> B[OAuth인증]
    A --> C[국내주식 주문·계좌]
    A --> D[국내주식 기본시세]
    D --> E[주식현재가 시세<br/>v1_국내주식-008]
    D --> F[주식현재가 시세2]
    D --> G[주식현재가 체결]
    D --> H[국내주식기간별시세<br/>모듈 4용]

[주식현재가 시세] 페이지를 클릭하면 호출에 필요한 모든 정보가 표 형태로 정리되어 있습니다.

1.3 문서에서 확인할 4가지 영역

flowchart TD
    A[API 문서 페이지] --> B[기본정보<br/>Method·URL·TR ID]
    A --> C[Header<br/>인증·식별 정보]
    A --> D[Query Parameters<br/>조회 조건]
    A --> E[응답<br/>받게 될 데이터]

1.4 문서에서 본 모듈 핵심 정보

💡 TR ID란? 한투 API가 어떤 거래(Transaction)를 처리하는지 구분하는 코드입니다. 같은 URL이라도 TR ID에 따라 처리 로직이 달라질 수 있습니다. 본 강의에서 사용하는 시세 조회 TR ID는 실전·모의가 같지만, 주문 API는 실전·모의 TR ID가 다릅니다.

⚠️ 함정 — Required 컬럼 문서의 Header·Query Parameters 표에 Required 컬럼이 있습니다. Y로 표시된 항목은 필수입니다. 본 강의는 필수 항목만 입력합니다(N 항목은 선택).

2. HTTP Request1 노드 추가

2.1 어디에 추가하나요?

캔버스에서 모듈 2의 HTTP Request 노드(토큰 발급용) 우측 [+] 아이콘을 클릭합니다.

검색창에 "http" 입력 → [HTTP Request] 선택

n8n이 자동으로 노드 이름을 HTTP Request1로 부여합니다(첫 번째 HTTP Request 노드는 그대로 “HTTP Request”).

2.2 노드 이름 그대로 둡니다

⚠️ 함정 — 노드 이름 변경 시 표현식 수정 필요 n8n 표현식은 노드 이름으로 다른 노드의 데이터를 참조합니다. 본 강의는 HTTP Request·HTTP Request1 같은 기본 이름을 그대로 사용합니다. 만약 이름을 바꾼다면 모든 표현식의 노드명도 같이 바꿔야 합니다.

2.3 워크플로 위치 확인

flowchart TD
    A[Schedule Trigger] --> B[HTTP Request<br/>POST 토큰]
    B --> C[HTTP Request1<br/>GET 현재가<br/>← 지금 추가]

3. Method와 URL 설정

3.1 Method를 GET으로

토큰 발급(POST)과 달리 시세 조회는 데이터를 가져오는 동작이라 GET을 사용합니다.

3.2 URL 입력

🔀 환경별 URL 모듈 2에서 선택한 환경에 맞는 URL을 사용하세요. 도메인·포트만 다르고 경로(/uapi/domestic-stock/...)는 동일합니다.

3.3 URL 구조 분해

flowchart TD
    A[전체 URL] --> B[Domain<br/>openapi.koreainvestment.com:9443]
    A --> C[경로]
    C --> D[/uapi/domestic-stock]
    C --> E[/v1]
    C --> F[/quotations]
    C --> G[/inquire-price]

이 구조 덕분에 다른 시세 API의 URL도 짐작이 가능합니다. 예를 들어 모듈 4의 기간별 시세는 /inquire-daily-itemchartprice로 끝납니다.

3.4 Authentication 유지

모듈 2와 마찬가지로 None입니다. 인증은 헤더에 토큰을 넣어 처리합니다.

4. Query Parameters 설정

4.1 Query Parameters란?

URL 끝에 ?key=value&key2=value2 형태로 붙는 조회 조건입니다. n8n은 별도 입력 필드로 받아서 자동으로 URL 끝에 붙여줍니다.

flowchart TD
    A[기본 URL] --> B[+ Query Parameters]
    B --> C[?FID_COND_MRKT_DIV_CODE=J<br/>&FID_INPUT_ISCD=005930]
    C --> D[전체 URL 완성]

4.2 Send Query Parameters 토글 ON

기본은 비활성입니다. 토글을 ON으로 바꿉니다.

4.3 Specify Query Parameters 방식

폼처럼 Name·Value 쌍으로 입력합니다.

4.4 [Add Parameter]로 2개 필드 만들기

[Add Parameter] 버튼을 2번 눌러 다음 2개 필드를 만듭니다.

4.5 시장 분류 코드 J·NX·UN

flowchart TD
    A[FID_COND_MRKT_DIV_CODE] --> B[J<br/>KRX 한국거래소]
    A --> C[NX<br/>NXT 넥스트레이드]
    A --> D[UN<br/>KRX+NXT 통합]
    B --> E[코스피·코스닥<br/>대부분 종목]
    C --> F[ATS<br/>일부 종목만]
    D --> G[시세조회만 가능<br/>주문은 제한]

💡 일반 개인 투자자가 보는 코스피·코스닥 종목은 모두 J입니다. NXT는 2025년 등장한 대체거래소로, 일부 종목에 한해 거래되며, 일반적인 종목 모니터링에는 거의 사용하지 않습니다.

4.6 종목 코드 입력

FID_INPUT_ISCD는 6자리 종목 코드입니다.

⚠️ 함정 — 앞 0 누락 종목코드는 항상 6자리입니다. 삼성전자를 5930으로 입력하면 오류납니다. 반드시 005930처럼 앞에 0을 채워주세요.

💡 ETN 종목 입력 ETN은 6자리 코드 앞에 Q를 붙여 7자리로 입력합니다(예: Q500001). 본 강의는 일반 주식만 다루므로 신경 쓸 필요 없습니다.

✅ 체크포인트 3-1 Query Parameters 영역에 2개 필드(FID_COND_MRKT_DIV_CODE=J, FID_INPUT_ISCD=005930)가 채워졌나요?

5. Headers 설정 — 가장 중요한 단계

5.1 왜 Header가 중요한가?

이전 노드(토큰 발급)에서 받은 access_token을 이 노드의 헤더에 전달하는 것이 본 모듈의 핵심입니다. 이 연결이 안 되면 다음 모든 모듈이 작동하지 않습니다.

flowchart TD
    A[HTTP Request<br/>토큰 발급] --> B[output<br/>access_token]
    B --> C[HTTP Request1<br/>현재가 조회]
    C --> D[Header<br/>authorization]
    D --> E[Bearer eyJ0eXAi...]

5.2 Send Headers 토글 ON

토글을 ON으로 바꿉니다.

5.3 [Add Parameter]로 6개 필드 만들기

문서에서 Required = Y인 항목만 입력합니다. 총 6개입니다.

5.4 authorization 필드 상세 — 표현식 첫 등장

이 강의에서 처음 등장하는 n8n 표현식입니다. 차분히 읽어주세요.

5.4.1 입력해야 할 정확한 값

Bearer {{ $node["HTTP Request"].json["access_token"] }}

⚠️ 하나도 빠뜨리지 마세요

• Bearer 다음에 공백 한 칸
• {{ ... }} 중괄호 두 개씩
• $node 앞에 달러 기호 필수
• "HTTP Request" 양쪽 쌍따옴표
• 문자열 사이에 공백·줄바꿈 없음

5.4.2 각 부분의 의미

flowchart TD
    A[Bearer] --> B[OAuth 표준 접두사]
    C["{{ }}"] --> D[표현식 시작·종료]
    E[$node] --> F[다른 노드 참조]
    G["HTTP Request"] --> H[참조할 노드 이름]
    I[.json] --> J[그 노드 출력의 JSON]
    K[access_token] --> L[가져올 필드명]

5.4.3 Fixed mode와 Expression mode

n8n의 Value 입력 칸은 두 모드가 있습니다.

flowchart TD
    A[Value 입력 칸] --> B[Fixed mode<br/>고정 텍스트]
    A --> C[Expression mode<br/>표현식]
    B --> D[그대로 보냄]
    C --> E["{{ }}안의 코드 평가"]

authorization Value 칸 좌측의 fx 아이콘을 클릭하면 Expression mode로 전환됩니다. Expression mode 상태에서 위 표현식을 입력하세요. 정상 인식되면 입력 칸 아래에 현재 평가된 결과가 회색으로 미리 보입니다.

Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

5.4.4 더 짧은 버전도 가능

다음 두 표현식은 결과가 동일합니다.

{{ $node["HTTP Request"].json["access_token"] }}
{{ $node["HTTP Request"].json.access_token }}

본 강의는 가독성을 위해 점 표기(.access_token)를 권장합니다.

✅ 체크포인트 3-2 authorization 필드 아래에 Bearer eyJ0eXAi...로 시작하는 회색 미리보기가 표시되나요? 표시되면 표현식이 정상입니다.

5.5 나머지 5개 필드

5.5.1 content-type

application/json; charset=utf-8

; 다음 공백 한 칸을 지우지 마세요. 문서 명시값 그대로입니다.

5.5.2 appkey·appsecret

모듈 1에서 발급받은 값을 그대로 입력합니다. Fixed mode입니다.

5.5.3 tr_id

💡 현재가 조회는 환경 공통 시세 조회 API의 TR ID는 실전·모의가 동일합니다. 모듈 4(기간별 시세)도 동일하지만, 주문·잔고 등 거래 API는 환경별로 다릅니다. 본 강의의 시세 조회 범위에서는 환경 간 TR ID 차이가 없습니다.

5.5.4 custtype

본 강의는 개인 계좌 기준이므로 P입니다.

6. 노드 실행과 응답 해석

6.1 [Execute step] 클릭

설정이 모두 끝났으면 노드 패널 우측 상단의 [Execute step]을 클릭합니다.

6.2 정상 응답의 모양

OUTPUT의 Schema 탭에서 다음 구조를 확인할 수 있습니다.

flowchart TD
    A[output1 = 1 item] --> B[rt_cd<br/>0=성공]
    A --> C[msg_cd<br/>응답코드]
    A --> D[msg1<br/>응답메시지]
    A --> E[output<br/>실제 시세 데이터]
    E --> F[stck_prpr<br/>주식 현재가]
    E --> G[prdy_ctrt<br/>전일 대비율]
    E --> H[acml_vol<br/>누적 거래량]
    E --> I[기타 50+ 필드]

6.3 응답 필드가 너무 많아서 당황하지 마세요

응답에는 50개 이상의 필드가 있습니다. 모두 알 필요는 없습니다. 본 강의에서 사용하는 것은 다음 4개뿐입니다.

6.4 응답 필드 이름 해독법

한투 API 응답 필드는 약어로 되어 있어 처음엔 어렵습니다. 패턴을 알면 추측할 수 있습니다.

flowchart TD
    A[필드명 패턴] --> B[stck_<br/>주식 stock]
    A --> C[prdy_<br/>전일 previous day]
    A --> D[d250_<br/>250일]
    A --> E[w52_<br/>52주]
    A --> F[acml_<br/>누적 accumulated]
    A --> G[hgpr<br/>고가 high price]
    A --> H[lwpr<br/>저가 low price]

조합 예시:

• stck_prpr = stock present price = 현재가
• prdy_ctrt = previous day contract rate = 전일 대비 등락률
• w52_hgpr = 52주 고가
• acml_vol = 누적 거래량

응답 필드 이름이 외계어처럼 보였다면, 이 패턴을 한 번만 외워두면 됩니다.

6.5 응답에서 가장 자주 쓰는 필드들

본 강의 범위 밖이지만, PER·PBR·EPS·BPS도 응답에 포함되어 있어 확장 분석에 활용 가능합니다.

6.6 검증 체크리스트

✅ 체크포인트 3-3 다음 4가지가 모두 충족되면 호출이 정상입니다.

• OUTPUT에 output1이 표시된다
• rt_cd 값이 0이다 (성공)
• msg1 값이 정상처리되었습니다. 류이다
• output.stck_prpr에 현재가가 들어 있다

6.7 시간대에 따른 값 차이

flowchart TD
    A[조회 시점] --> B[장중 09:00~15:30]
    A --> C[장 마감 직후]
    A --> D[장 종료 후]
    B --> E[실시간 가격 변동]
    C --> F[종가 확정 중]
    D --> G[당일 종가 고정]

본 강의 워크플로는 16:00에 호출하므로 당일 종가를 받게 됩니다.

7. Edit Fields 노드 추가 — 응답 정제

7.1 왜 정제가 필요한가?

응답에 50개 이상의 필드가 있어 그대로 다음 노드로 흘려보내면 워크플로가 복잡해집니다. 필요한 5개만 골라 깔끔한 형태로 만들어 다음 모듈에 넘깁니다.

flowchart TD
    A[원본 응답<br/>50+ 필드] --> B[Edit Fields<br/>5개로 정제]
    B --> C[종목코드]
    B --> D[현재가]
    B --> E[등락률]
    B --> F[오늘거래량]
    B --> G[날짜]

7.2 노드 추가

HTTP Request1 우측 [+] → 검색 edit fields → [Edit Fields] 선택. n8n 버전에 따라 Set이라는 이름일 수도 있습니다(같은 노드).

7.3 Mode 설정

7.4 [Add Field]로 5개 필드 만들기

각 필드는 이름(Name), 타입(Type), 값(Value) 3가지로 구성됩니다.

7.5 표현식 변형 — $node vs $json

지난 절(Header 설정)에서 $node["HTTP Request"]를 썼는데, 여기서는 $json만 씁니다. 차이는 다음과 같습니다.

flowchart TD
    A["$json"] --> B[바로 직전 노드<br/>출력]
    C["$node 노드명"] --> D[지정한 이름의<br/>노드 출력]
    B --> E[Edit Fields는<br/>HTTP Request1 다음]
    E --> F["$json = HTTP Request1"]

Edit Fields 노드의 직전 노드는 HTTP Request1(현재가 조회)이므로 $json은 그 출력을 가리킵니다.

⚠️ 함정 — 같은 표현식이 모듈 2 토큰을 가리키지 않습니다 토큰을 참조하려면 직전이 아니므로 $node["HTTP Request"]를 써야 합니다. 본 모듈에서는 토큰 참조가 필요 없으므로 $json만 씁니다.

7.6 타입을 Number로 지정해야 하는 이유

flowchart TD
    A[원본 응답] --> B["문자열 117000"]
    B --> C[Number 타입 강제]
    C --> D[숫자 117000]
    D --> E[모듈 4에서<br/>나눗셈 계산 가능]

응답의 stck_prpr는 문자열로 옵니다("117000"). 그대로 두면 다음 모듈에서 나누기·곱하기 같은 산술 연산이 안 되거나 문자열 결합으로 처리됩니다.

오늘거래량을 Number로 지정하지 않으면 모듈 5의 거래량 비율 계산이 동작하지 않습니다. 가장 자주 빠뜨리는 함정입니다.

7.7 날짜 표현식 풀이

{{ new Date().toISOString().slice(0, 10) }}

flowchart TD
    A["new Date()"] --> B[현재 시각<br/>객체]
    B --> C["toISOString()"]
    C --> D["2026-05-03T14:30:25.123Z"]
    D --> E["slice(0, 10)"]
    E --> F["2026-05-03"]

왜 ISO 문자열인가? 정렬 가능하고, 나라마다 형식이 달라 혼란스러운 5/3/26 같은 표현 대신 표준 형식(YYYY-MM-DD)을 쓰기 위함입니다.

⚠️ 함정 — UTC 자정 부근 toISOString()은 UTC 기준입니다. 한국 시간 09:00 이전이면 UTC 기준 어제 날짜가 나올 수 있습니다. 본 강의 워크플로는 16:00 실행이라 문제없지만, 새벽에 수동 실행하면 어제 날짜가 잡힐 수 있습니다.

7.8 [Execute step] 후 결과

✅ 체크포인트 3-4 Edit Fields의 OUTPUT에 정확히 5개 필드가 표시되고, 현재가·등락률·오늘거래량 옆에 # 아이콘(Number 타입 표시)이 보이나요? 종목코드·날짜 옆은 AB(String) 아이콘이어야 합니다.

8. 워크플로 현재 상태

이 모듈을 완료하면 워크플로는 4개 노드입니다.

flowchart TD
    A[Schedule Trigger] --> B[HTTP Request<br/>POST 토큰]
    B --> C[HTTP Request1<br/>GET 현재가]
    C --> D[Edit Fields<br/>5개 필드]

다음 모듈에서 Edit Fields 뒤에 HTTP Request2(기간별 시세 35일)와 Code in JavaScript(평균거래량 계산)를 붙입니다.

9. 다른 종목으로 바꿔보기 — 학습 도전

9.1 1분 도전

Query Parameters의 FID_INPUT_ISCD 값만 바꾸고 [Execute step]을 다시 누르면 다른 종목 시세가 즉시 조회됩니다.

9.2 종목 코드 찾는 법

한국거래소 또는 증권사 HTS의 종목 검색에서 6자리 코드를 확인할 수 있습니다. 또는 Q + 종목명 검색으로 빠르게 찾을 수 있습니다.

💡 검증 팁 익숙한 종목으로 호출해보고, 응답의 현재가가 실제 시세(네이버 금융·다음 금융 등)와 일치하는지 확인하면 워크플로가 제대로 동작하는지 빠르게 검증할 수 있습니다.

10. 자주 발생하는 오류

10.1 401 발생 시 추가 체크

flowchart TD
    A[401 발생] --> B[1.토큰 노드<br/>먼저 실행했나?]
    B --> C[2.Bearer<br/>공백 확인]
    C --> D[3.표현식 미리보기<br/>토큰 보이나?]
    D --> E[4.appkey·appsecret<br/>실전·모의 일치?]

순서가 중요합니다. HTTP Request 노드(토큰)를 먼저 실행하지 않으면 그 출력이 없으므로 표현식이 빈 값으로 평가됩니다. 캔버스에서 한 번에 모두 실행하거나, 두 노드를 순차적으로 [Execute step] 하세요.

11. 30초 점검 — 모듈 4로 넘어갈 자격

12. 자주 묻는 질문

Q1. 토큰 표현식을 $node["HTTP Request"] 대신 더 짧게 쓸 수 있나요? 바로 직전 노드라면 $json.access_token도 가능합니다. 단 본 모듈에서 HTTP Request1의 직전은 토큰 노드이므로 $json이 작동하지만, 모듈 4에서는 직전이 Edit Fields가 되어 토큰을 참조하려면 반드시 $node["HTTP Request"]로 명시해야 합니다. 헷갈림을 피하려면 토큰 참조는 항상 $node["HTTP Request"]로 통일하는 것이 안전합니다.

Q2. 응답 필드를 더 추가하고 싶어요. 예를 들어 PER도 받아오려면? Edit Fields에 새 필드 PER을 추가하고 Type=Number, Value={{ $json.output.per }}로 입력하면 됩니다. 응답에는 PER·PBR·EPS·BPS·52주 고저가 등 다양한 정보가 이미 들어 있어 추가 호출 없이 활용 가능합니다.

Q3. 매번 [Execute step]을 누르기 번거로워요. 캔버스 우측 상단의 [Execute Workflow] 버튼을 누르면 트리거부터 끝까지 한 번에 실행됩니다. 다만 Schedule Trigger가 있는 워크플로는 수동 실행도 트리거에서 시작됩니다.

Q4. 종목명도 응답에 있나요? 직접적인 한글 종목명 필드는 없습니다. 대신 별도의 [상품기본조회] API를 호출하면 종목명을 받을 수 있습니다. 본 강의는 종목코드만 사용하지만, 실제 알림 메시지에는 한글명이 보이는 것이 좋아 모듈 6에서 다시 다룹니다.

Q5. Number 타입인데 응답값이 너무 커서 정확도를 잃지 않나요? JavaScript의 Number는 약 9,007조까지 정수를 정확히 표현합니다. 거래량(수천만~수억)·금액(수십억)은 모두 안전 범위입니다.

Q6. tr_id 표는 어디서 보나요? 한투 개발자센터의 각 API 문서 페이지 상단에 명시되어 있습니다. 시세 API는 실전·모의가 같지만, 주문·잔고는 다릅니다. 의심스러우면 항상 문서에서 재확인하세요.

13. 다음 모듈 미리보기

모듈 4 — 기간별 시세 + 평균거래량 계산

다음 모듈에서는 HTTP Request2(기간별 시세 35일)와 Code in JavaScript(평균거래량 계산) 두 노드를 추가합니다. 동적 날짜 계산(오늘 기준 35일 전), output1과 output2의 차이, JavaScript 코드로 배열 처리하는 패턴을 학습합니다.

flowchart TD
    A[모듈 3<br/>현재가 정제 완료] --> B[모듈 4<br/>HTTP Request2]
    B --> C[GET 기간별 시세]
    C --> D[35일치 일봉 데이터]
    D --> E[Code in JavaScript]
    E --> F[최근 20일<br/>평균거래량]

준비가 되었다면 모듈 4로 이동하세요.