amazing-data-service/docs/API.md

AmazingData 金融数据服务平台 - API 开发文档

一、API 概述

1.1 基本信息

• Base URL: http://localhost:8000/api/v1
• 认证方式: JWT Bearer Token
• 数据格式: JSON
• 编码: UTF-8

1.2 认证说明

除登录接口外，所有接口都需要在请求头中携带 JWT Token：

Authorization: Bearer {access_token}

---

二、认证接口

2.1 用户登录

接口: POST /auth/login

功能: 用户登录获取 JWT Token

请求参数:

参数名	类型	必填	说明
username	string	是	用户名
password	string	是	密码

请求示例:

{
  "username": "admin",
  "password": "admin123"
}

响应参数:

参数名	类型	说明
code	int	状态码 (200成功)
message	string	消息
data.access_token	string	JWT Token
data.token_type	string	Token类型 (bearer)
data.expires_in	int	有效期(秒)

响应示例:

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "bearer",
    "expires_in": 86400
  }
}

调用示例:

import requests

response = requests.post(
    'http://localhost:8000/api/v1/auth/login',
    json={'username': 'admin', 'password': 'admin123'}
)
token = response.json()['data']['access_token']

---

2.2 获取当前用户信息

接口: GET /auth/me

功能: 获取当前登录用户信息

请求参数: 无

响应参数:

参数名	类型	说明
data.id	int	用户ID
data.username	string	用户名
data.email	string	邮箱
data.role	string	角色
data.is_active	bool	是否激活

调用示例:

headers = {'Authorization': f'Bearer {token}'}
response = requests.get('http://localhost:8000/api/v1/auth/me', headers=headers)
user_info = response.json()['data']

---

三、SDK配置接口

3.1 获取SDK配置列表

接口: GET /configs/sdk

功能: 获取所有SDK配置列表

请求参数: 无

响应参数:

参数名	类型	说明
data.items	array	配置列表
data.total	int	总数

调用示例:

response = requests.get('http://localhost:8000/api/v1/configs/sdk', headers=headers)
configs = response.json()['data']['items']

---

3.2 创建SDK配置

接口: POST /configs/sdk

功能: 创建新的SDK配置

请求参数:

参数名	类型	必填	说明
name	string	是	配置名称
username	string	是	SDK用户名
password	string	是	SDK密码
host	string	是	服务器地址
port	int	否	端口号 (默认8600)
local_path	string	否	本地路径
is_default	bool	否	是否默认配置

请求示例:

{
  "name": "生产环境SDK",
  "username": "your_username",
  "password": "your_password",
  "host": "140.206.44.234",
  "port": 8600,
  "is_default": true
}

调用示例:

response = requests.post(
    'http://localhost:8000/api/v1/configs/sdk',
    headers=headers,
    json={
        'name': '生产环境SDK',
        'username': 'your_username',
        'password': 'your_password',
        'host': '140.206.44.234',
        'port': 8600,
        'is_default': True
    }
)

---

3.3 测试SDK连接

接口: POST /configs/sdk/{id}/test

功能: 测试指定SDK配置的连接

请求参数: 无

响应参数:

参数名	类型	说明
data.success	bool	是否成功
data.message	string	消息
data.response_time	float	响应时间(秒)

调用示例:

response = requests.post(
    'http://localhost:8000/api/v1/configs/sdk/1/test',
    headers=headers,
    timeout=60
)
result = response.json()['data']

---

四、基础数据接口

4.1 获取代码列表

接口: GET /base/codes

功能: 获取指定类型的证券代码列表

请求参数:

参数名	类型	必填	说明
security_type	string	是	证券类型

证券类型:

• EXTRA_STOCK_A: 沪深A股
• EXTRA_FUTURE: 期货
• EXTRA_ETF: ETF
• EXTRA_INDEX_A: 指数

响应参数:

参数名	类型	说明
data	array	代码列表

调用示例:

response = requests.get(
    'http://localhost:8000/api/v1/base/codes',
    params={'security_type': 'EXTRA_STOCK_A'},
    headers=headers
)
codes = response.json()['data']

---

4.2 获取交易日历

接口: GET /base/calendar

功能: 获取指定市场的交易日历

请求参数:

参数名	类型	必填	说明
market	string	是	市场代码 (SH, SZ, CFE)
start_date	string	否	开始日期 (YYYYMMDD)
end_date	string	否	结束日期 (YYYYMMDD)

响应参数:

参数名	类型	说明
data	array	交易日列表

调用示例:

response = requests.get(
    'http://localhost:8000/api/v1/base/calendar',
    params={
        'market': 'SH',
        'start_date': '20240101',
        'end_date': '20240131'
    },
    headers=headers
)
trading_days = response.json()['data']

---

4.3 获取证券信息

接口: GET /base/codes/{code}/info

功能: 获取指定代码的证券信息

请求参数:

参数名	类型	必填	说明
code	string	是	证券代码 (URL路径参数)

响应参数:

参数名	类型	说明
data.code	string	代码
data.name	string	名称
data.market	string	市场
data.type	string	类型

调用示例:

response = requests.get(
    'http://localhost:8000/api/v1/base/codes/600000.SH/info',
    headers=headers
)
info = response.json()['data']

---

五、股票数据接口

5.1 获取股票K线数据

接口: GET /stock/kline

功能: 获取股票K线数据

请求参数:

参数名	类型	必填	说明
codes	string	是	代码列表 (逗号分隔)
start_date	string	是	开始日期 (YYYYMMDD)
end_date	string	是	结束日期 (YYYYMMDD)
period	string	否	周期 (daily, min1, min5等)

响应参数:

参数名	类型	说明
data.{code}	array	K线数据列表
data.{code}[].trade_date	string	交易日期
data.{code}[].open	float	开盘价
data.{code}[].high	float	最高价
data.{code}[].low	float	最低价
data.{code}[].close	float	收盘价
data.{code}[].volume	int	成交量
data.{code}[].amount	float	成交额

调用示例:

response = requests.get(
    'http://localhost:8000/api/v1/stock/kline',
    params={
        'codes': '600000.SH,000001.SZ',
        'start_date': '20240101',
        'end_date': '20240131',
        'period': 'daily'
    },
    headers=headers
)
kline_data = response.json()['data']

---

5.2 获取股票K线图表数据

接口: GET /stock/kline/{code}/chart

功能: 获取股票K线图表数据 (ECharts格式)

请求参数:

参数名	类型	必填	说明
code	string	是	股票代码 (URL路径参数)
start_date	string	是	开始日期
end_date	string	是	结束日期
period	string	否	周期

响应参数:

参数名	类型	说明
data.categoryData	array	日期列表
data.values	array	K线值 [open, close, low, high, volume]
data.volumes	array	成交量数据

调用示例:

response = requests.get(
    'http://localhost:8000/api/v1/stock/kline/600000.SH/chart',
    params={
        'start_date': '20240101',
        'end_date': '20240131',
        'period': 'daily'
    },
    headers=headers
)
chart_data = response.json()['data']

---

5.3 批量获取股票K线

接口: POST /stock/kline/batch

功能: 批量获取多个股票的K线数据

请求参数:

参数名	类型	必填	说明
codes	array	是	代码列表
start_date	string	是	开始日期
end_date	string	是	结束日期
period	string	否	周期

请求示例:

{
  "codes": ["600000.SH", "000001.SZ", "000002.SZ"],
  "start_date": "20240101",
  "end_date": "20240131",
  "period": "daily"
}

调用示例:

response = requests.post(
    'http://localhost:8000/api/v1/stock/kline/batch',
    headers=headers,
    json={
        'codes': ['600000.SH', '000001.SZ'],
        'start_date': '20240101',
        'end_date': '20240131',
        'period': 'daily'
    }
)

---

六、期货数据接口

6.1 获取期货K线数据

接口: GET /future/kline

功能: 获取期货K线数据

请求参数:

参数名	类型	必填	说明
codes	string	是	代码列表 (逗号分隔)
start_date	string	是	开始日期
end_date	string	是	结束日期
period	string	否	周期

响应参数:

参数名	类型	说明
data.{code}	array	K线数据
data.{code}[].trade_date	string	交易日期
data.{code}[].open	float	开盘价
data.{code}[].high	float	最高价
data.{code}[].low	float	最低价
data.{code}[].close	float	收盘价
data.{code}[].volume	int	成交量
data.{code}[].settle	float	结算价
data.{code}[].open_interest	int	持仓量

调用示例:

response = requests.get(
    'http://localhost:8000/api/v1/future/kline',
    params={
        'codes': 'IF2401.CFE',
        'start_date': '20240101',
        'end_date': '20240131',
        'period': 'daily'
    },
    headers=headers
)

---

6.2 获取期货品种列表

接口: GET /cache/future-varieties

功能: 获取所有期货品种列表

请求参数: 无

响应参数:

参数名	类型	说明
data.varieties	array	品种列表

调用示例:

response = requests.get(
    'http://localhost:8000/api/v1/cache/future-varieties',
    headers=headers
)
varieties = response.json()['data']['varieties']

---

6.3 获取主力合约

接口: GET /cache/main-contracts

功能: 获取所有品种的主力合约

请求参数: 无

响应参数:

参数名	类型	说明
data.main_contracts	object	{品种: 主力合约}

调用示例:

response = requests.get(
    'http://localhost:8000/api/v1/cache/main-contracts',
    headers=headers
)
main_contracts = response.json()['data']['main_contracts']

---

七、缓存管理接口

7.1 一键检测所有数据

接口: POST /cache/detect-all-missing

功能: 检测所有数据的缺失情况

请求参数:

参数名	类型	必填	说明
security_type	string	是	证券类型 (stock, future)
period_type	string	否	周期类型 (daily)
start_date	string	是	开始日期
end_date	string	是	结束日期
contract_type	string	否	合约类型 (all, main)

请求示例:

{
  "security_type": "stock",
  "period_type": "daily",
  "start_date": "20240101",
  "end_date": "20240131",
  "contract_type": "all"
}

响应参数:

参数名	类型	说明
data.task_id	int	任务ID
data.status	string	任务状态
data.total_count	int	检测总数
data.complete_count	int	完整数量
data.missing_count	int	缺失数量
data.error_count	int	错误数量
data.daily_stats	object	每日统计
data.missing_codes	array	缺失代码列表

调用示例:

response = requests.post(
    'http://localhost:8000/api/v1/cache/detect-all-missing',
    headers=headers,
    json={
        'security_type': 'stock',
        'period_type': 'daily',
        'start_date': '20240101',
        'end_date': '20240131',
        'contract_type': 'all'
    }
)
result = response.json()['data']

---

7.2 一键缓存所有数据

接口: POST /cache/cache-all-missing

功能: 缓存所有数据 (异步执行)

请求参数: 同检测接口

响应参数:

参数名	类型	说明
data.task_id	int	任务ID
data.status	string	任务状态
data.total_count	int	总数
data.progress	float	进度

调用示例:

response = requests.post(
    'http://localhost:8000/api/v1/cache/cache-all-missing',
    headers=headers,
    json={
        'security_type': 'stock',
        'period_type': 'daily',
        'start_date': '20240101',
        'end_date': '20240131'
    }
)
task_id = response.json()['data']['task_id']

---

7.3 一键补齐缺失数据

接口: POST /cache/fill-missing

功能: 只补齐检测到的缺失数据 (异步执行)

请求参数: 同检测接口

响应参数:

参数名	类型	说明
data.task_id	int	任务ID
data.missing_count	int	缺失代码数量
data.status	string	任务状态

调用示例:

response = requests.post(
    'http://localhost:8000/api/v1/cache/fill-missing',
    headers=headers,
    json={
        'security_type': 'stock',
        'period_type': 'daily',
        'start_date': '20240101',
        'end_date': '20240131'
    }
)

---

7.4 获取任务进度

接口: GET /cache/tasks/{task_id}

功能: 获取缓存任务进度

请求参数:

参数名	类型	必填	说明
task_id	int	是	任务ID (URL路径参数)

响应参数:

参数名	类型	说明
data.task.id	int	任务ID
data.task.status	string	状态
data.task.progress	float	进度
data.task.total_count	int	总数
data.task.success_count	int	成功数
data.task.error_count	int	错误数

调用示例:

response = requests.get(
    f'http://localhost:8000/api/v1/cache/tasks/{task_id}',
    headers=headers
)
task_status = response.json()['data']['task']

---

7.5 获取任务列表

接口: GET /cache/tasks

功能: 获取缓存任务列表

请求参数:

参数名	类型	必填	说明
page	int	否	页码 (默认1)
page_size	int	否	每页数量 (默认20)

调用示例:

response = requests.get(
    'http://localhost:8000/api/v1/cache/tasks',
    params={'page': 1, 'page_size': 10},
    headers=headers
)
tasks = response.json()['data']['items']

---

八、财务数据接口

8.1 获取资产负债表

接口: GET /finance/balance-sheet

功能: 获取资产负债表数据

请求参数:

参数名	类型	必填	说明
codes	string	是	代码列表
start_date	string	是	开始日期
end_date	string	是	结束日期

调用示例:

response = requests.get(
    'http://localhost:8000/api/v1/finance/balance-sheet',
    params={
        'codes': '600000.SH',
        'start_date': '20230101',
        'end_date': '20231231'
    },
    headers=headers
)

---

8.2 获取利润表

接口: GET /finance/income

功能: 获取利润表数据

请求参数: 同资产负债表

调用示例:

response = requests.get(
    'http://localhost:8000/api/v1/finance/income',
    params={
        'codes': '600000.SH',
        'start_date': '20230101',
        'end_date': '20231231'
    },
    headers=headers
)

---

8.3 获取现金流量表

接口: GET /finance/cash-flow

功能: 获取现金流量表数据

请求参数: 同资产负债表

调用示例:

response = requests.get(
    'http://localhost:8000/api/v1/finance/cash-flow',
    params={
        'codes': '600000.SH',
        'start_date': '20230101',
        'end_date': '20231231'
    },
    headers=headers
)

---

九、错误码说明

错误码	说明
200	成功
400	请求参数错误
401	未授权 (Token无效或过期)
403	禁止访问
404	资源不存在
500	服务器内部错误

---

十、最佳实践

10.1 Token 管理

class AmazingDataClient:
    def __init__(self, base_url, username, password):
        self.base_url = base_url
        self.token = None
        self.login(username, password)
    
    def login(self, username, password):
        response = requests.post(
            f'{self.base_url}/auth/login',
            json={'username': username, 'password': password}
        )
        self.token = response.json()['data']['access_token']
    
    def get_headers(self):
        return {'Authorization': f'Bearer {self.token}'}
    
    def request(self, method, path, **kwargs):
        kwargs['headers'] = self.get_headers()
        return requests.request(method, f'{self.base_url}{path}', **kwargs)

10.2 批量数据处理

# 分批处理大量代码
codes = ['600000.SH', '000001.SZ', ...]  # 大量代码
batch_size = 50

for i in range(0, len(codes), batch_size):
    batch = codes[i:i+batch_size]
    response = client.request('POST', '/stock/kline/batch', json={
        'codes': batch,
        'start_date': '20240101',
        'end_date': '20240131'
    })

10.3 异步任务轮询

import time

def wait_for_task(client, task_id, timeout=300):
    start_time = time.time()
    while time.time() - start_time < timeout:
        response = client.request('GET', f'/cache/tasks/{task_id}')
        task = response.json()['data']['task']
        
        if task['status'] == 'completed':
            return task
        elif task['status'] == 'failed':
            raise Exception(task['error_message'])
        
        time.sleep(2)
    
    raise Exception('任务超时')

# 使用
response = client.request('POST', '/cache/fill-missing', json={...})
task_id = response.json()['data']['task_id']
result = wait_for_task(client, task_id)

---

十一、指数数据接口

11.1 获取指数列表

接口: GET /index/list

功能: 获取所有指数基础信息列表

请求参数: 无

响应参数:

参数名	类型	说明
data	array	指数列表
data[].code	string	指数代码
data[].name	string	指数名称
data[].component_count	int	成分个数

调用示例:

response = requests.get(
    'http://localhost:8000/api/v1/index/list',
    headers=headers
)
indexes = response.json()['data']

---

11.2 获取指数交易数据

接口: GET /index/trade

功能: 获取指数交易数据（含基础信息）

请求参数:

参数名	类型	必填	说明
codes	string	是	指数代码列表 (逗号分隔)
start_date	string	是	开始日期 (YYYYMMDD)
end_date	string	是	结束日期 (YYYYMMDD)

响应参数:

参数名	类型	说明
data.{code}.basic	object	指数基础信息
data.{code}.basic.code	string	指数代码
data.{code}.basic.name	string	指数名称
data.{code}.basic.component_count	int	成分个数
data.{code}.trades	array	交易数据列表
data.{code}.trades[].trade_date	string	交易日期
data.{code}.trades[].open	float	开盘价
data.{code}.trades[].close	float	收盘价
data.{code}.trades[].high	float	最高价
data.{code}.trades[].low	float	最低价
data.{code}.trades[].change_pct	float	涨跌幅(%)
data.{code}.trades[].volume	int	成交量
data.{code}.trades[].amount	float	成交额(百万元)
data.{code}.trades[].total_market_value	float	总市值(百万元)
data.{code}.trades[].float_market_value	float	流通市值(百万元)
data.{code}.trades[].up_count	int	上涨家数
data.{code}.trades[].down_count	int	下跌家数
data.{code}.trades[].flat_count	int	平盘家数
data.{code}.trades[].limit_up_count	int	涨停家数
data.{code}.trades[].limit_down_count	int	跌停家数
data.{code}.trades[].suspend_count	int	停牌家数
data.{code}.trades[].pe_ratio	float	市盈率
data.{code}.trades[].pe_median	float	市盈率中位值
data.{code}.trades[].is_new_high	bool	是否创近期新高
data.{code}.trades[].is_new_low	bool	是否创近期新低

调用示例:

response = requests.get(
    'http://localhost:8000/api/v1/index/trade',
    params={
        'codes': 'BK0001,BK0002',
        'start_date': '20240101',
        'end_date': '20240131'
    },
    headers=headers
)
data = response.json()['data']

---

11.3 获取指数K线图表数据

接口: GET /index/{code}/chart

功能: 获取指数K线图表数据 (ECharts格式，含基础信息)

请求参数:

参数名	类型	必填	说明
code	string	是	指数代码 (URL路径参数)
start_date	string	是	开始日期
end_date	string	是	结束日期

响应参数:

参数名	类型	说明
data.basic	object	指数基础信息
data.basic.code	string	指数代码
data.basic.name	string	指数名称
data.basic.component_count	int	成分个数
data.categoryData	array	日期列表
data.values	array	K线值 [open, close, low, high, volume]
data.volumes	array	成交量数据

调用示例:

response = requests.get(
    'http://localhost:8000/api/v1/index/BK0001/chart',
    params={
        'start_date': '20240101',
        'end_date': '20240131'
    },
    headers=headers
)
chart_data = response.json()['data']

---

十二、数据导入接口

12.1 导入指数数据

接口: POST /import/index-data

功能: 导入指数数据（同时更新指数基础表和指数交易表）

请求参数:

参数名	类型	必填	说明
file	file	是	Excel文件 (multipart/form-data)
trade_date	string	是	交易日期 (YYYY-MM-DD格式，Query参数)

Excel文件格式:

第一行标题：

• 证券代码
• 证券名称
• 成分个数 [交易日期]最新
• 开盘价 [交易日期]最新
• 收盘价 [交易日期]最新
• 成交量 [交易日期]最新 [单位]股
• 成交额 [交易日期]最新 [单位]百万元
• 总市值 [截止日期]最新 [单位]百万元
• 自由流通市值 [交易日期]最新 [单位]百万元
• 涨跌幅 [交易日期]最新 [单位]%
• 最高价 [交易日期]最新
• 最低价 [交易日期]最新
• 上涨家数 [交易日期]最新
• 下跌家数 [交易日期]最新
• 平盘家数 [交易日期]最新
• 涨停家数 [交易日期]最新
• 跌停家数 [交易日期]最新
• 停牌家数 [交易日期]最新
• 近期创历史新高 [交易日期]最新 [近N日内]300 [复权方式]不复权
• 近期创历史新低 [交易日期]最新 [近N日内]300 [复权方式]不复权
• 市盈率PE(TTM) [交易日期]最新 [剔除规则]不调整
• 市盈率PE(TTM)中位值 [交易日期]最新 [剔除规则]不调整

响应参数:

参数名	类型	说明
data.success_count	int	成功导入数量
data.error_count	int	失败数量
data.total_count	int	总数量
data.index_basic_added	int	新增指数基础数据数量
data.index_basic_updated	int	更新指数基础数据数量
data.trade_date	string	交易日期

调用示例:

import requests

files = {'file': open('index_data.xlsx', 'rb')}
response = requests.post(
    'http://localhost:8000/api/v1/import/index-data?trade_date=2024-01-31',
    files=files,
    headers=headers
)
result = response.json()['data']
print(f"成功: {result['success_count']}, 新增指数: {result['index_basic_added']}")

---

12.2 导入股票基础数据

接口: POST /import/stock-basic

功能: 导入股票基础数据

请求参数:

参数名	类型	必填	说明
file	file	是	Excel文件

Excel文件格式:

必须列：code, name, total_shares, float_shares, industry_index_name, industry_index_code, institution_hold_ratio, industry_level3, list_date

响应参数:

参数名	类型	说明
data.success_count	int	成功导入数量
data.error_count	int	失败数量
data.total_count	int	总数量

---

12.3 导入指数基础数据

接口: POST /import/index-basic

功能: 导入指数基础数据

请求参数:

参数名	类型	必填	说明
file	file	是	Excel文件

Excel文件格式:

必须列：code, name, component_count

---

12.4 导入指数交易数据

接口: POST /import/index-trade

功能: 导入指数交易数据

请求参数:

参数名	类型	必填	说明
file	file	是	Excel文件

Excel文件格式:

必须列：index_code, trade_date, open, close, high, low

可选列：change_pct, volume, amount, total_market_value, float_market_value, up_count, down_count, flat_count, limit_up_count, limit_down_count, suspend_count, pe_ratio, pe_median, is_new_high, is_new_low

---

十三、股票基础信息接口

13.1 获取股票基础信息

接口: GET /stock/basic/{code}

功能: 获取指定股票的基础信息

请求参数:

参数名	类型	必填	说明
code	string	是	股票代码 (URL路径参数)

响应参数:

参数名	类型	说明
data.code	string	股票代码
data.name	string	股票名称
data.total_shares	int	总股本
data.float_shares	int	流通股本
data.industry_index_name	string	所属东财行业指数
data.industry_index_code	string	所属东财行业指数代码
data.institution_hold_ratio	float	机构持股比例合计(%)
data.industry_level3	string	所属东财3级行业
data.list_date	string	上市日期

调用示例:

response = requests.get(
    'http://localhost:8000/api/v1/stock/basic/600000.SH',
    headers=headers
)
stock_info = response.json()['data']
print(f"股票名称: {stock_info['name']}")
print(f"总股本: {stock_info['total_shares']}")
print(f"所属行业: {stock_info['industry_index_name']}")

---

十四、联系与支持

如有问题，请联系技术支持团队。