> 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` - 잉여현금흐름, 자본적지출


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.alpha-lenz.com/ko/api-reference/public-api/financial.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.