> For the complete documentation index, see [llms.txt](https://docs.alpha-lenz.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.alpha-lenz.com/ko/api-reference/company/page-5.md).

# 회사 탭 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 |

### 응답

```json
{
  "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`) |

### 응답

```json
{
  "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`        | 조회 연도 수                     |

### 응답

```json
{
  "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` | 분석 기간 (개월) |

### 응답

```json
{
  "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로 지연 로딩됩니다. 각 탭 컴포넌트는 활성화될 때만 데이터를 가져옵니다.

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