ptrade API 教程：如何提取账户历史交割单进行盘后分析

在量化交易中，盘后对账与交易回溯是优化策略、发现交易偏差的重要环节。ptrade 提供了 get_deliver 接口，允许用户获取账户的历史交割单原数据。本文将详细介绍该接口的使用限制、参数说明，并提供一个完整的盘后分析代码示例。

1. get_deliver 接口核心要点

在使用 get_deliver 接口前，必须了解以下核心限制，否则可能导致调用失败或获取不到数据：

• 运行环境：仅在**交易模块（实盘/模拟盘）**有效，回测环境不支持。
• 调用时机：仅支持在盘前准备阶段 before_trading_start 和盘后处理阶段 after_trading_end 调用。
• 账户限制：该接口仅支持查询普通股票账户（非两融信用账户）。
• 时间范围：仅支持查询上一个交易日（包含）之前的历史交割单，无法查询当天的实时交割单。
• 数据格式：由于不同券商柜台返回的字段存在差异，接口返回的是柜台原数据（Raw Data），需要用户根据实际券商的字段进行解析。

2. 接口参数与返回值说明

接口原型

get_deliver(start_date, end_date)

参数说明

• start_date (str)：开始日期，格式必须为 "YYYYmmdd"，例如 "20230101"。
• end_date (str)：结束日期，格式必须为 "YYYYmmdd"，例如 "20231117"。

返回值

• 返回一个 list[dict] 类型的对象。每个 dict 代表一条交割单记录，包含券商柜台返回的原始字段（如 stock_code、business_price、occur_amount、business_balance 等）。
• 若查询失败或无数据，则返回空列表 []。

3. 盘后提取交割单实战代码

以下示例展示了如何在盘后事件 after_trading_end 中自动触发历史交割单提取，并将其打印输出以供分析：

def initialize(context):
    # 初始化策略，设置操作股票池
    g.security = '600570.SS'
    set_universe(g.security)

def handle_data(context, data):
    # 盘中常规交易逻辑
    pass

def after_trading_end(context, data):
    log.info("【盘后阶段】开始提取历史交割单...")
    
    # 设定查询的时间范围（例如：查询2023年10月1日至2023年10月31日的交割单）
    start_date = '20231001'
    end_date = '20231031'
    
    try:
        # 调用接口获取交割单
        deliver_list = get_deliver(start_date, end_date)
        
        if len(deliver_list) > 0:
            log.info(f"成功获取到 {len(deliver_list)} 条交割单数据。")
            
            # 遍历并打印前3条交割单的关键字段（具体字段名需根据您所在的券商柜台微调）
            for i, deliver in enumerate(deliver_list[:3]):
                stock_code = deliver.get('stock_code', '未知')
                stock_name = deliver.get('stock_name', '未知')
                business_price = deliver.get('business_price', 0.0)
                occur_amount = deliver.get('occur_amount', 0.0)
                business_name = deliver.get('business_name', '未知')
                
                log.info(f"记录 {i+1}: 证券: {stock_code}({stock_name}) | 动作: {business_name} | 价格: {business_price} | 数量: {occur_amount}")
        else:
            log.warning("该时间段内未查询到交割单数据。")
            
    except Exception as e:
        log.error(f"提取交割单出现异常: {str(e)}")

4. 盘后分析建议

1. 保存至本地：由于 get_deliver 返回的是原始 list[dict]，建议在盘后使用 Python 的 pandas 库将其转换为 DataFrame，并利用 to_csv() 保存到研究根目录下（可通过 get_research_path() 获取路径），便于后续进行深度数据挖掘。
2. 费用核对：交割单中通常包含印花税、过户费、佣金等字段（如 brokerage、exchange_fare 等），可用于精确计算策略的交易摩擦成本，从而优化回测模型中的手续费设置。