회사 탭 API

회사 상세 페이지는 7개의 탭으로 구성되며, 각 탭은 전용 API 엔드포인트를 사용합니다.

탭 구성

탭	ID	주요 엔드포인트	설명
개요	overview	/companies/{id}	회사 프로필, 통계, 요약 카드
재무제표	financials	/companies/{id}/financials	손익계산서, 재무상태표, 현금흐름표
차트	chart	TradingView 위젯	인터랙티브 주가 차트
공시	disclosure	/companies/{id}/dart	DART 기업 공시
내부자	insider	/companies/{id}/insider	내부자 거래 데이터
분석	analysis	/companies/{id}/snapshot + /technical	기술적 신호 및 AI 분석
컨센서스	consensus	/companies/{id}/consensus	전문가 전망치 및 목표가

---

회사 상세 정보

회사 프로필, 재무 지표, 밸류에이션, 성장성, 재무 건전성 정보를 반환합니다.

GET /v1/financial_v4/companies/{company_id}

경로 파라미터

파라미터	타입	설명
company_id	integer	회사 ID

응답

{
  "id": 1,
  "name": "Samsung Electronics",
  "alias_name": "삼성전자",
  "symbol": "005930",
  "exchange": "KRX",
  "currency": "KRW",
  "current_price": 58000,
  "price_change": 1200,
  "price_change_percent": 2.11,
  "description": "삼성전자 ...",
  "ceo": "한종희",
  "website": "https://www.samsung.com",
  "sector": "Technology",
  "industry": "Semiconductors",
  "employees": 267800,
  "fiscal_year": 2024,
  "fiscal_date": "2024-12-31",
  "profile": {
    "market_cap": 346000000000000,
    "revenue": 258935000000000,
    "shares_outstanding": 5969783000,
    "employees": 267800
  },
  "margins": {
    "gross_margin": 32.8,
    "ebitda_margin": 18.5,
    "operating_margin": 2.54,
    "pretax_margin": 3.12,
    "net_margin": 5.98
  },
  "valuation": {
    "pe_ratio": 37.4,
    "pb_ratio": 1.03,
    "ps_ratio": 1.34,
    "ev_ebitda": 7.22,
    "pfcf_ratio": 11.5
  },
  "growth": {
    "sales_growth_3y_cagr": -2.1,
    "sales_growth_5y_cagr": 3.8,
    "operating_income_growth_3y_cagr": -15.2,
    "operating_income_growth_5y_cagr": -8.4,
    "net_income_growth_3y_cagr": -10.5,
    "net_income_growth_5y_cagr": -5.1
  },
  "returns": {
    "roa": 3.4,
    "roe": 4.6,
    "roic": 3.9
  },
  "financial_health": {
    "cash": 65000000000000,
    "net_debt": -20000000000000,
    "debt_to_equity_ratio": 0.36,
    "interest_coverage_ratio": 8.5
  }
}

사용처: 개요 탭 — 회사 헤더, 통계 그리드, 재무 지표 카드

---

회사 슬러그 해석

URL 슬러그 또는 티커 심볼을 회사 ID로 변환합니다. 라우팅에 사용됩니다.

GET /v1/financial_v4/companies/by-slug/{slug}

경로 파라미터

파라미터	타입	설명
slug	string	회사 슬러그 또는 티커 (예: samsung-electronics, 005930)

응답

{
  "id": 1,
  "name": "Samsung Electronics",
  "symbol": "005930",
  "exchange": "KRX"
}

---

회사 재무제표

시계열 재무제표 데이터를 반환합니다 (손익계산서, 재무상태표, 현금흐름표).

GET /v1/financial_v4/companies/{company_id}/financials

쿼리 파라미터

파라미터	타입	기본값	설명
period	string	"Annual"	"Annual" 또는 "Quarterly"
years	integer	5	조회 연도 수

응답

{
  "statements": [
    {
      "fiscal_date": "2024-12-31",
      "year": 2024,
      "quarter": null,
      "period": "Annual",
      "currency": "KRW",
      "sales": 258935000000000,
      "operating_income": 6570000000000,
      "net_income": 15490000000000,
      "total_assets": 455000000000000,
      "free_cash_flow": 30000000000000
    }
  ]
}

전체 필드 목록: 아래 재무제표 필드 참조.

사용처: 재무제표 탭 — 손익계산서, 재무상태표, 현금흐름표 서브탭 (연간/분기 토글)

---

회사 스냅샷

yfinance 기반 실시간 시장 데이터와 애널리스트 추천을 반환합니다.

GET /v1/financial_v4/companies/{company_id}/snapshot

사용처: 분석 탭 — 핵심 지표 디스플레이, AI 시그널 배너

---

회사 기술적 지표

주가 데이터로 계산된 기술적 지표를 반환합니다.

GET /v1/financial_v4/companies/{company_id}/technical

응답 포함 항목

• RSI (상대강도지수)

• MACD (이동평균수렴확산)

• 볼린저 밴드 (상단, 중단, 하단)

• ATR (평균실질범위)

• SMA (단순이동평균 — 20, 50, 200일)

사용처: 분석 탭 — 기술적 신호 컴포넌트

---

회사 뉴스

Perigon API 및 Google News RSS 기반 뉴스 기사를 반환합니다.

GET /v1/financial_v4/companies/{company_id}/news

쿼리 파라미터

파라미터	타입	기본값	설명
limit	integer	3	반환할 기사 수
locale	string	"ko"	언어 로케일 ("ko", "en")

사용처: 개요 탭 — 뉴스 카드 (지연 로딩)

---

회사 DART 공시

DART 시스템 기업 공시 정보를 반환합니다.

GET /v1/financial_v4/companies/{company_id}/dart

쿼리 파라미터

파라미터	타입	기본값	설명
limit	integer	3	반환할 공시 수

사용처: 공시 탭, 개요 탭 — DART 카드

---

회사 리서치 하이라이트

증권사 리서치 보고서 요약을 반환합니다.

GET /v1/financial_v4/companies/{company_id}/research-highlights

쿼리 파라미터

파라미터	타입	기본값	설명
limit	integer	3	반환할 보고서 수

사용처: 개요 탭 — 리서치 하이라이트 카드

---

회사 섹터 분석

해당 회사의 섹터 레벨 분석을 반환합니다.

GET /v1/sector-analyst/company/{company_id}

쿼리 파라미터

파라미터	타입	기본값	설명
locale	string	—	언어 로케일

사용처: 개요 탭 — 섹터 분석 카드 (지연 로딩)

---

회사 컨센서스

전문가 전망 컨센서스 (목표가, 투자의견 등)를 반환합니다.

GET /v1/financial_v4/companies/{company_id}/consensus

쿼리 파라미터

파라미터	타입	기본값	설명
months	integer	12	분석 기간 (개월)

응답

{
  "company_id": 1,
  "company_name": "Samsung Electronics",
  "symbol": "005930",
  "currency": "KRW",
  "has_consensus": true,
  "message": null,
  "current_price": 58000,
  "target_prices": {
    "average": 85000,
    "high": 110000,
    "high_broker": "미래에셋증권",
    "low": 65000,
    "low_broker": "대신증권",
    "std_dev": 12500,
    "expert_count": 25
  },
  "upside_downside": {
    "current_price": 58000,
    "to_high": 89.66,
    "to_average": 46.55,
    "to_low": 12.07
  },
  "investment_opinions": [
    { "opinion": "매수", "count": 18, "percentage": 72.0 },
    { "opinion": "중립", "count": 5, "percentage": 20.0 },
    { "opinion": "매도", "count": 2, "percentage": 8.0 }
  ],
  "target_price_trend": [
    {
      "date": "2024-03-15",
      "target_price": 90000,
      "broker": "삼성증권",
      "opinion": "매수"
    }
  ],
  "price_history": [
    { "date": "2024-01-02", "close": 52000 }
  ],
  "analysis_period_months": 12,
  "last_report_date": "2024-03-20",
  "total_reports": 42
}

사용처: 컨센서스 탭 — 목표가 차트, 투자의견 분포, 증권사별 상세 테이블

---

회사 내부자 거래

내부자 거래 데이터를 반환합니다.

GET /v1/financial_v4/companies/{company_id}/insider

사용처: 내부자 탭, 공시 탭 — 내부자 거래 임베드

---

재무제표 필드

재무제표 엔드포인트가 각 기간별로 반환하는 필드 목록입니다:

손익계산서

필드	설명
sales	매출액
cost_of_goods	매출원가
gross_profit	매출총이익
research_and_development	연구개발비
selling_general_and_administrative	판매관리비
operating_income	영업이익
ebit	EBIT
ebitda	EBITDA
pretax_income	세전이익
net_income	당기순이익
eps_basic	기본주당순이익
eps_diluted	희석주당순이익

재무상태표

필드	설명
total_assets	자산총계
total_current_assets	유동자산
cash_and_cash_equivalents	현금및현금성자산
accounts_receivable	매출채권
inventory	재고자산
total_non_current_assets	비유동자산
properties	유형자산
intangible_assets	무형자산
goodwill	영업권
total_liabilities	부채총계
total_current_liabilities	유동부채
total_non_current_liabilities	비유동부채
total_shareholders_equity	자본총계
retained_earnings	이익잉여금

현금흐름표

필드	설명
operating_cash_flow	영업활동현금흐름
investing_cash_flow	투자활동현금흐름
financing_cash_flow	재무활동현금흐름
capital_expenditures	유형자산취득
free_cash_flow	잉여현금흐름
common_dividends	배당금지급

---

프론트엔드 Hooks 참조

각 API 엔드포인트는 React Query hook으로 래핑되어 캐싱이 최적화되어 있습니다:

Hook	엔드포인트	Stale Time	Cache Time
useCompanyDetail()	/companies/{id}	5분	10분
useCompanyFinancials()	/companies/{id}/financials	1시간	2시간
useCompanySnapshot()	/companies/{id}/snapshot	1분	—
useCompanyTechnical()	/companies/{id}/technical	—	—
useCompanyNews()	/companies/{id}/news	1분	—
useCompanyDart()	/companies/{id}/dart	1분	—
useCompanyResearch()	/companies/{id}/research-highlights	1분	—
useStockAnalysis()	Stock analysis 서비스	5분	10분

탭 네비게이션

탭은 URL 해시 라우팅(#overview, #financials 등)을 사용하며, Next.js dynamic() import로 지연 로딩됩니다. 각 탭 컴포넌트는 활성화될 때만 데이터를 가져옵니다.

type TabId = "overview" | "financials" | "chart" | "disclosure" 
           | "insider" | "analysis" | "consensus";