Integration · 수업별

수업별 API 연동 안내

두 수업에서 실제 연동이 필요한 API(메일·증권·구글시트·LLM)를 발급처·인증·.env·비용·주의까지 수업별로 정리.

Doc.08

연동 안내 요약

공통 패턴

가입→키→.env→호출

어떤 API든 같은 순서. 키는 .env에.

최지혜

메일 발송(SMTP)

보고서 PDF를 승인 후 발송. Gmail 앱비밀번호.

김성범

증권 시세(KIS/키움)

조회까지 자동·모의투자 우선·주문은 사람.

이 문서는 두 수업에서 실제로 연동이 필요한 API를 정리한 실무 안내입니다. 각 API마다 "무엇을 위해 / 어디서 발급 / 어떻게 인증 / .env 키 / 비용·주의"를 담았습니다. (개념 설명은 [개발 개념·용어 사전]을, 보안은 항상 §6을 따르세요.)

Section 01

① 서비스 가입·앱 등록      → ② 키 발급(API키 또는 앱키/시크릿)
→ ③ 키를 .env 에 저장(깃 제외) → ④ (필요시) 토큰 발급/갱신
→ ⑤ 코드가 호출(요청→응답) → ⑥ 받은 데이터 저장·사용

어떤 API든 큰 틀은 같습니다. "가입 → 키 → .env → 호출". 메일·증권·시트·AI가 전부 이 패턴입니다.

Section 02

API	무엇을 위해	발급처	인증	.env 예시	비용·주의
LLM API (Gemini)	요약·분류·문안 정리를 코드에서 호출	Google AI Studio	API 키	`GEMINI_API_KEY`	토큰 단위 과금(무료 티어 있음), 기밀 전송 주의
LLM API (Claude)	동일 (정리·생성)	Anthropic Console	API 키	`ANTHROPIC_API_KEY`	토큰 과금, 기밀 전송 주의
Google Sheets API	입력이 시트이거나 결과를 시트에 기록	Google Cloud Console	OAuth 또는 서비스 계정	`GOOGLE_CREDENTIALS`(키파일 경로)	무료, 인증키 보관 철저

참고: 입력이 CSV 파일이면 LLM·시트 API 없이도 동작합니다. 위 셋은 "한 단계 더"가 필요할 때.

Section 03

핵심 연동은 메일 발송입니다. (PDF 변환은 Playwright로 로컬에서 — API 아님)

API	무엇을 위해	발급처	인증	.env 예시	비용·주의
메일 — SMTP (Gmail 등)	보고서 PDF를 고객에게 발송	Gmail 계정	앱 비밀번호(2단계 인증 후 발급)	`SMTP_HOST,SMTP_PORT,SMTP_USER,SMTP_PASS,MAIL_FROM`	개인계정 일일 발송 한도, 발송 전 승인 필수
메일 — 발송 API (SendGrid·Mailgun)	대량·전달률·발송기록 관리	각 서비스	API 키	`SENDGRID_API_KEY`	무료 티어 한도, 도메인 인증 권장
(선택) Google Sheets	고객/자산 입력이 구글 시트일 때	Google Cloud	서비스 계정	`GOOGLE_CREDENTIALS`	위 1번과 동일

연동 위치: pipeline/send_mail.py(승인된 건만, 기본 dry-run) — .env에 SMTP를 넣고 --send일 때만 실제 발송.
PDF는 API 아님: playwright로 보고서 HTML을 열어 page.pdf()로 자동 변환 → 메일에 첨부.
Gmail SMTP 빠른 안내: 구글 계정 → 2단계 인증 켜기 → "앱 비밀번호" 발급 → SMTP_HOST=smtp.gmail.com, SMTP_PORT=587, SMTP_PASS=앱비밀번호.

Section 04

핵심 연동은 증권사 시세 API입니다. (조회까지 자동, 주문은 사람이 직접)

API	무엇을 위해	발급처	인증	.env 예시	비용·주의
한국투자증권 KIS	시세·일봉·잔고 조회(REST/websocket)	KIS Developers(개발자센터)	앱키/시크릿 → 토큰 발급·갱신	`KIS_APPKEY,KIS_APPSECRET,KIS_ACCOUNT`	모의투자부터, 조회는 보통 무료, 주문은 신중
키움증권 Open API/REST	시세·체결·잔고	키움 개발자	앱키/인증	`KIWOOM_APPKEY...`	모의투자 지원, 환경 요건 확인
뉴스/검색 API (또는 Perplexity)	종목·환율 뉴스 수집	각 서비스	API 키	`NEWS_API_KEY`	티어 한도, 출처 보존
(선택) 시장데이터(지수·환율)	보조 지표	데이터 제공처	API 키	—	별도 신청

인증 흐름(증권 공통): 앱키/시크릿 → 액세스 토큰 발급(만료 시 재발급) → 토큰으로 시세·잔고 조회.
자동화 범위: 시세·잔고 조회·계산까지 자동. 매수/매도 주문 자동 실행은 강의 범위 밖(주문 API가 있어도 사람이 직접).
반드시 모의투자(paper) 환경부터 테스트.

Section 05

실제 키 발급은 가입·승인에 시간이 걸리므로, 수업에서는 흐름·구조를 먼저 보여주고 키는 미리 발급해 둔 것으로(또는 모의/샘플) 시연.
키가 없으면: 최지혜는 메일 dry-run(발송 안 함), 김성범은 샘플 prices.csv로 지표·레짐 로직만 시연 가능.

Section 06

수업	꼭 필요한 연동	선택	안전 포인트
최지혜	메일 발송(SMTP)	메일API·시트·LLM	발송 전 승인, 개인정보 익명화
김성범	증권 시세(KIS/키움)	뉴스·시장데이터·LLM	모의투자 우선, 주문은 사람

Section 07