openapi: 3.1.0
info:
  title: TickFlow 行情数据 API
  description: |-
    高性能行情数据服务，支持 A股、ETF、美股、港股。

    ## 认证方式

    所有接口需要通过 `x-api-key` 请求头传递 API Key 进行认证。

    ## 速率限制

    根据 API Key 配置的权限，可能会有请求频率和配额限制。

    ## 批量查询

    部分接口同时支持 GET 和 POST 方法：
    - **GET**: 通过 URL 参数传递，适合少量数据
    - **POST**: 通过 JSON Body 传递，适合大批量查询，不受 URL 长度限制

    ## K线周期

    支持的周期：1m, 5m, 10m, 15m, 30m, 60m, 1d, 1w, 1M, 1Q, 1Y
    - 日内周期(5m/15m/30m/60m)从1m数据聚合
    - 周线(1w)/月线(1M)/季线(1Q)/年线(1Y)从日线聚合
    - intraday 接口当前为 Beta 版本
  contact:
    name: TickFlow Team
  license:
    name: ''
  version: 1.0.0
servers:
  - url: https://api.tickflow.org
security:
  - api_key: []
paths:
  /v1/financials/balance-sheet:
    get:
      tags:
        - 财务数据
      summary: 查询资产负债表
      description: 获取指定标的的资产负债表数据，包含资产、负债、权益核心科目。
      operationId: get_balance_sheet
      parameters:
        - name: symbols
          in: query
          description: 逗号分隔的标的代码，如 600519.SH,000001.SZ
          required: true
          schema:
            type: string
        - name: start_date
          in: query
          description: 起始日期过滤（可选，YYYY-MM-DD），筛选 period_end >= start_date
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: end_date
          in: query
          description: 截止日期过滤（可选，YYYY-MM-DD），筛选 period_end <= end_date
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: latest
          in: query
          description: 仅返回最新一期（默认 false）
          required: false
          schema:
            type:
              - boolean
              - 'null'
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceSheetResponse'
        '400':
          description: 参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: 认证失败
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: 无权限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
        - api_key: []
components:
  schemas:
    BalanceSheetResponse:
      type: object
      description: 资产负债表响应
      required:
        - data
      properties:
        data:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/BalanceSheetRecord'
          propertyNames:
            type: string
    ApiError:
      type: object
      description: API 错误响应体
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: 错误代码 (如 "INVALID_PERIOD", "SYMBOL_NOT_FOUND")
          example: INVALID_PERIOD
        details:
          description: 详细信息 (可选，用于调试)
        message:
          type: string
          description: 错误消息 (人类可读)
          example: 'Invalid period: 2d'
    BalanceSheetRecord:
      type: object
      description: 资产负债表单期记录
      required:
        - period_end
      properties:
        accounts_payable:
          type:
            - number
            - 'null'
          format: double
          description: 应付账款 (Accounts Payable)
        accounts_receivable:
          type:
            - number
            - 'null'
          format: double
          description: 应收账款 (Accounts Receivable)
        announce_date:
          type:
            - string
            - 'null'
          description: 公告日期 (YYYY-MM-DD)
        cash_and_equivalents:
          type:
            - number
            - 'null'
          format: double
          description: 货币资金 (Cash and Cash Equivalents)
        equity_attributable:
          type:
            - number
            - 'null'
          format: double
          description: 归属于母公司股东权益 (Equity Attributable to Parent)
        fixed_assets:
          type:
            - number
            - 'null'
          format: double
          description: 固定资产 (Fixed Assets)
        goodwill:
          type:
            - number
            - 'null'
          format: double
          description: 商誉 (Goodwill)
        intangible_assets:
          type:
            - number
            - 'null'
          format: double
          description: 无形资产 (Intangible Assets)
        inventory:
          type:
            - number
            - 'null'
          format: double
          description: 存货 (Inventory)
        long_term_borrowing:
          type:
            - number
            - 'null'
          format: double
          description: 长期借款 (Long-term Borrowing)
        minority_interest:
          type:
            - number
            - 'null'
          format: double
          description: 少数股东权益 (Minority Interest)
        period_end:
          type: string
          description: 报告期末日期 (YYYY-MM-DD)
        retained_earnings:
          type:
            - number
            - 'null'
          format: double
          description: 未分配利润 (Retained Earnings)
        short_term_borrowing:
          type:
            - number
            - 'null'
          format: double
          description: 短期借款 (Short-term Borrowing)
        total_assets:
          type:
            - number
            - 'null'
          format: double
          description: 资产总计 (Total Assets)
        total_current_assets:
          type:
            - number
            - 'null'
          format: double
          description: 流动资产合计 (Total Current Assets)
        total_current_liabilities:
          type:
            - number
            - 'null'
          format: double
          description: 流动负债合计 (Total Current Liabilities)
        total_equity:
          type:
            - number
            - 'null'
          format: double
          description: 所有者权益合计 (Total Equity)
        total_liabilities:
          type:
            - number
            - 'null'
          format: double
          description: 负债合计 (Total Liabilities)
        total_non_current_assets:
          type:
            - number
            - 'null'
          format: double
          description: 非流动资产合计 (Total Non-current Assets)
        total_non_current_liabilities:
          type:
            - number
            - 'null'
          format: double
          description: 非流动负债合计 (Total Non-current Liabilities)
  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: x-api-key