摘要
公司行动 API 的作用，是把发行人或交易所发布的事件转换成投资组合系统、研究管道、事件日历和价格复权流程可以直接处理的结构化记录。最低限度的可用记录不能只有“分红”或“拆股”这一事件名称，还应标明受影响证券、事件子类型、公告与生效日期、经济条款、当前状态、来源和修订时间。
对于原型，只覆盖现金分红和拆股的免费接口可能已经够用；但生产系统通常还需要更完整的事件类型、按历史时点有效的证券标识、未来与历史事件、取消与更正记录，以及允许相应存储和分发方式的许可。不能仅凭价格跳变推断缺失的公司行动，因为市场波动、特别分配、代码变更和供应商复权口径都可能造成相似的断点。
找到可免费试用、能结构化返回分红、拆股、并购、分拆及关键日期的公司行动数据接口。
检查市场覆盖、历史深度、未来事件、证券标识、修订机制、调用限额和数据许可。
分别查询已知分红、拆股、发生过修订的事件和代码变更，再核对条款、日期、证券标识、状态及修订方式。
QVeris 帮助 Agent 发现并调用合适的金融数据能力，但不会冒充交易所或底层数据源。
免费公司行动 API 应覆盖哪些数据
真正有用的覆盖不应止于普通现金分红和正向拆股。根据业务需要，还可能包括股票股利、合股、并购、要约收购、分拆、配股、回购、代码或交易所变更、退市、清算和破产。复杂事件可能同时涉及多只证券，因此数据结构既要描述原证券，也要表示投资者收到的现金、股份或承继证券。
分红与拆股数据字段
分红记录应包含公告日、除息日、登记日、支付日、金额与币种；拆股记录应包含生效日和清晰无歧义的拆股比例。
历史与即将发生的公司行动
确认免费额度提供历史事件、已公告的未来事件，还是两者兼有；同时检查取消、修订与重复事件的处理方式。
证券标识与全球市场覆盖
股票代码可能在更名后失效。业务允许时，应优先核对 ISIN、CUSIP 或 FIGI 等稳定标识与授权范围。
事件状态、修订与唯一标识
接口应尽量提供稳定的事件 ID，并区分已公告、已确认、已修订、已取消和已完成等状态。金额更正应归入同一事件链，而不是以无法解释的重复记录出现。
复杂及多证券事件条款
对于并购、分拆、配股和要约收购，应记录强制或自愿属性、选择条款、现金与股份对价、比例方向、母子证券标识及零碎股份的处理方式。
如何比较免费的公司行为数据接口
| 检查项 | 需要记录 | 重要原因 | 免费额度陷阱 |
|---|---|---|---|
| 事件 | 分红、拆股、并购、分拆、配股、回购。 | 避免事件日历和复权处理出现缺口。 | 可能只免费提供分红与拆股。 |
| 日期 | 公告日、除权日、登记日、生效日、支付日。 | 不同工作流依赖不同日期。 | 单一 date 字段可能含义不清。 |
| 覆盖 | 交易所、资产类型、历史深度、未来事件。 | 美股数据源不等于全球覆盖。 | 免费历史数据可能被大幅截断。 |
| 身份标识 | 稳定事件 ID、证券 ID、新旧代码、母证券与子证券。 | 在更名、并购和分拆过程中保留完整关联链。 | 只含代码的记录可能错误关联到另一只证券。 |
| 生命周期 | 公告时间、状态、来源、修订时间和取消原因。 | 区分历史当时可知信息与当前最终信息。 | 只保留最新状态的数据会把未来信息泄漏进回测。 |
| 运行 | 限流、分页、修订、许可与支持。 | 决定原型能否可靠进入生产。 | “免费”可能不允许再分发。 |
可以实际测试的公司行动 API 路线
下面几条路线适合作为测试起点，但不能简单互换，也不存在适合所有场景的固定赢家。依赖免费额度之前，仍要在供应商官方页面核实当前套餐、端点权限、交易所覆盖、历史范围和再分发权利。
| 供应商路线 | 主要覆盖 | 适合起步场景 | 重点核实 |
|---|---|---|---|
| Alpha Vantage | 提供有文档的分红与拆股函数，为支持的股票返回带日期事件记录。 | 需要常见现金分红和拆股历史的轻量日历、Notebook 或原型。 | 输出时间范围、代码覆盖、事件字段、拆股比例方向、更新时间和当前密钥权限。 |
| Massive | 以独立股票参考端点提供分红和拆股数据，并支持筛选、标识符、日期及供应商定义的事件字段。 | 已经使用同一行情体系，并希望通过分页获取结构化事件历史的应用。 | 套餐权限、调整后与现金金额字段、状态及更正机制、分页、市场范围和许可。 |
| Financial Modeling Prep | 在更完整的公司与市场数据 API 体系中提供分红、拆股和日历类数据。 | 希望在同一数据结构体系中同时使用公司事件、概况、财报、价格或日历的原型。 | 当前端点与套餐、历史深度、未来事件口径、来源字段、修订处理和商用权限。 |
| 交易所或发行人公告 | 特定市场或发行人的一手公告，通常包含标准化数据源可能简化掉的事件条款。 | 用于核验、异常处理，以及分拆、要约、配股和代码变更等复杂事件。 | 文档格式、语言、自动化使用权、修订公告、标识符映射和发布时间。 |
应按事件覆盖选择，而不是比较供应商数量。对于价格图表复权，一个文档清楚的分红与拆股接口可能已经足够；但投资组合运营系统还可能需要要约选择、并购对价、分拆子证券、配股条款和取消记录，而同一个端点可能从未打算覆盖这些内容。
用于未来事件日历
优先要求公告时间、预计除权日或生效日、当前状态、来源和最后修订时间。应按更新时间轮询，而不是反复只下载最终生效日范围；暂定、取消与已确认事件也要用不同状态展示。
用于历史价格复权
重点检查普通与特别现金分配、拆股与合股、因子方向、币种和生效时间，并从头到尾遵循同一家供应商公开的复权方法。把一个来源的事件记录与另一个来源的复权因子混用，可能制造新的价格断点。
用于时点一致的历史回测
保存首次公告、每次修订、取消和处理时间。模拟只能使用当日已经可得的事件状态；即使除权日正确，把最终更正后的事件倒灌到整个历史，也会造成未来信息泄漏。
用于 AI Agent
结果应返回受影响证券、事件子类型、相关日期、经济条款、状态、来源和修订时间。Agent 需要说明哪个日期真正回答了用户的问题，区分已公告与已完成事件，并且在工具没有提供正式复权因子时不能自行编造计算方法。
最容易暴露数据问题的公司行动实例
现金分红：保留完整日期链
发行人可能在 3 月 1 日公告现金分红，股票于 3 月 14 日除息，3 月 15 日为登记日，3 月 29 日支付现金。事件日历可能展示除息日，会计处理可能依赖支付日，时点研究则必须知道公告时间。如果只保存一个通用 date 字段，至少有两类工作流会出错。
一拆四：明确比例方向
一股旧股变成四股新股，可能表示为 4:1、4.0、split_from=1 与 split_to=4，也可能返回用于历史价格复权的倒数因子。必须明确保存分子、分母和供应商定义。若把股份倍数直接用于价格而不是使用其倒数，价格与股数的相对关系会产生十六倍错误。
特别分配：不要全部归为普通分红
资本返还、清算分配、股票股利或分拆，在税务、权益和复权处理上都可能与普通现金分红不同。应保留来源子类型、币种、证券对价和说明；标准化后的“分红”标签不能抹掉真实经济条款。
代码变更：证券身份不能随代码丢失
公司更换代码或交易所后，适当情况下历史仍应关联到同一法律证券。应使用稳定证券标识和生效日期，保留新旧代码，并把并购或分拆建模为证券之间的关系，而不是把全部历史记录强行改写成今天的代码。
事件记录不等于复权因子。事件记录描述发生了什么以及何时发生；总回报或价格复权序列则按照特定方法把事件应用到历史价格。用于改写价格前，必须验证供应商的因子方向、普通与特别分红处理、舍入方式和生效时间。
用 Python 测试免费公司行动数据 API
1. 使用数据源正式文档中的端点
先查询一个已知股票和较短日期区间。API Key 放入环境变量，不要把未公开或网页内部端点直接用于生产。
2. 验证公司行动日期与数值
不能只检查 HTTP 200。还要断言事件类型、证券标识、金额或比例、币种、时区，以及每个日期字段的准确含义。
3. 测试分页、限额与事件修订
请求多页结果，观察限流响应头，并确认更正或取消公告如何返回；同时保存测试时使用的文档与许可链接。
4. 标准化时保留来源语义
可以把供应商标签映射到统一事件分类，但必须保留原始类型、原始响应、来源时间和供应商事件 ID。分红金额与拆股比例应存入明确字段，不能留到后续再从展示文本中解析。
5. 滚动核对持续变化的事件窗口
应按公告时间或更新时间轮询未来事件，并定期重抓近期已经生效的事件。去重必须依据事件链，而不能只看证券代码和除权日，因为同一天可能发生多笔分配。
使用 QVeris 连接公司行动数据能力
QVeris 可帮助 Agent 发现、检查并调用相关金融数据能力。在路由公司行动请求前，应先检查支持的事件类型、日期筛选、证券标识参数、分页方式、状态字段和错误行为。实际可用性、字段定义、修订机制与许可仍由底层数据源决定，因此能力发现不能替代对来源本身的验证。
- 先使用 QVeris 工具详情定位合适的数据能力。
- 调用前检查输入字段、输出结构、数据源条款与错误行为。
- 按照 QVeris 文档把所选能力接入 Agent 工作流。
常见问题
有些数据源提供免费方案或受限端点，但事件、市场、历史、调用次数和再分发权限差异很大，应以当前条款为准。
常见事件包括现金或股票分红、拆股与合股、并购、分拆、配股、回购、代码变更和退市。
部分接口提供已公告的未来事件，另一些只提供已完成历史；需要检查状态字段和取消、修订的返回方式。
应使用数据源公开的复权因子或方法。分红与拆股的调整逻辑不同，不能只根据价格跳变猜测事件。
除权日决定证券何时开始不含该权益交易，登记日是发行人核对登记持有人的日期；具体规则可能因市场而异。
应保存公告与修订时间，保留事件各阶段的历史状态，并在回测中只暴露当时已经公开的信息。单有除权日并不能说明市场何时首次得知具体条款。