> 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/public-api/financial.md).

# Financial API

기업 정보 및 재무제표 데이터에 액세스합니다.

**필요 스코프:** `read:financial` 또는 `read:all`

## 기업 목록 조회

선택적 필터링과 함께 기업 목록을 조회합니다.

```
GET /api/public/v1/financial/companies
```

### Query Parameters

| 파라미터      | 타입      | 설명                         |
| --------- | ------- | -------------------------- |
| `search`  | string  | 이름 또는 심볼로 검색               |
| `sector`  | string  | 섹터별 필터링                    |
| `country` | string  | 국가별 필터링                    |
| `limit`   | integer | 페이지당 결과 수 (1-100, 기본값: 50) |
| `offset`  | integer | 페이지네이션 오프셋 (기본값: 0)        |

### 요청 예시

```bash
curl -X GET "https://api.alpha-lenz.com/api/public/v1/financial/companies?search=samsung&limit=10" \
     -H "X-API-Key: ak_your_key"
```

### 응답

```json
{
  "companies": [
    {
      "company_id": 1,
      "symbol": "005930",
      "name": "Samsung Electronics",
      "alias_name": "삼성전자",
      "exchange": "KRX",
      "sector": "Technology",
      "country": "KR"
    }
  ],
  "total": 1
}
```

***

## 심볼로 기업 조회

주식 심볼로 기업 정보를 조회합니다.

```
GET /api/public/v1/financial/companies/{symbol}
```

### Path Parameters

| 파라미터     | 타입     | 설명                  |
| -------- | ------ | ------------------- |
| `symbol` | string | 주식 심볼 (예: "005930") |

### 요청 예시

```bash
curl -X GET "https://api.alpha-lenz.com/api/public/v1/financial/companies/005930" \
     -H "X-API-Key: ak_your_key"
```

### 응답

```json
{
  "company_id": 1,
  "symbol": "005930",
  "name": "Samsung Electronics",
  "alias_name": "삼성전자",
  "exchange": "KRX",
  "sector": "Technology",
  "country": "KR"
}
```

***

## 기업 재무제표 조회

기업의 재무제표 시계열 데이터를 조회합니다.

```
GET /api/public/v1/financial/companies/{symbol}/financials
```

### Path Parameters

| 파라미터     | 타입     | 설명    |
| -------- | ------ | ----- |
| `symbol` | string | 주식 심볼 |

### Query Parameters

| 파라미터     | 타입      | 설명                                                |
| -------- | ------- | ------------------------------------------------- |
| `period` | string  | "Annual" (연간) 또는 "Quarterly" (분기) (기본값: "Annual") |
| `years`  | integer | 조회할 연도 수 (1-20, 기본값: 5)                           |

### 요청 예시

```bash
curl -X GET "https://api.alpha-lenz.com/api/public/v1/financial/companies/005930/financials?period=Annual&years=5" \
     -H "X-API-Key: ak_your_key"
```

### 응답

```json
{
  "statements": [
    {
      "fiscal_date": "2023-12-31",
      "year": 2023,
      "quarter": null,
      "period": "Annual",
      "currency": "KRW",
      "sales": 258935000000000,
      "gross_profit": 85000000000000,
      "operating_income": 6570000000000,
      "net_income": 15490000000000,
      "total_assets": 455000000000000,
      "total_liabilities": 120000000000000,
      "total_shareholders_equity": 335000000000000,
      "operating_cash_flow": 50000000000000,
      "free_cash_flow": 30000000000000
    }
  ]
}
```

### 재무제표 필드

**손익계산서 (Income Statement):**

* `sales`, `cost_of_goods`, `gross_profit` - 매출, 매출원가, 매출총이익
* `operating_income`, `net_income` - 영업이익, 당기순이익
* `ebit`, `ebitda` - 법인세차감전영업이익, EBITDA
* `eps_basic`, `eps_diluted` - 기본주당이익, 희석주당이익

**재무상태표 (Balance Sheet):**

* `total_assets`, `total_current_assets`, `total_non_current_assets` - 자산총계, 유동자산, 비유동자산
* `total_liabilities`, `total_current_liabilities`, `total_non_current_liabilities` - 부채총계, 유동부채, 비유동부채
* `total_shareholders_equity` - 자본총계
* `cash`, `inventory`, `accounts_receivable` - 현금, 재고자산, 매출채권

**현금흐름표 (Cash Flow):**

* `operating_cash_flow`, `investing_cash_flow`, `financing_cash_flow` - 영업활동현금흐름, 투자활동현금흐름, 재무활동현금흐름
* `free_cash_flow`, `capital_expenditures` - 잉여현금흐름, 자본적지출