10-K / 10-Q
定期财务报表、经营叙述、内控和风险披露。
带来源的 SEC 数据
免费 SEC 申报 API：官方与免费方案指南
正确选择申报元数据、文档、XBRL 事实和表格记录，同时保留版本身份与证据。
把 EDGAR 当作一棵文档树
companyCIK、名称、股票代码、交易所和实体元数据。
submission表格、申报日期、accession number 和主文档。
filing index该次申报全部文档与附件的权威目录。
documentHTML、文本、XML、XBRL、图片或附件文件。
fact概念、分类标准、单位、期间、上下文和来源申报。
derived record你的提取结果、解析器版本和证据链接。
选择合适的免费 SEC 申报文件 API 路径
搜索免费 SEC 申报 API 往往从价格开始，但真正的选择取决于结果形态和工程责任。SEC 官方来源提供权威的提交元数据、申报文档、XBRL 事实和可下载数据集；第三方免费套餐可能增加股票代码查询、全文或章节搜索、表单专用标准化记录、webhook、批量导出或 SDK，同时带来账户、额度、保存和许可规则。
选择端点前，应先定义任务。“查询某公司最新申报”需要 submissions 索引；“按季度获取收入”需要 XBRL 事实、分类标准和期间逻辑；“提取风险因素”需要获取文档并解析章节；“内部人买入”或“机构持仓”需要解析所有权表单；“识别新的重大事件”则需要表单与项目分类。一个通用 filings 端点通常无法同时正确解决这五类问题。
来源权威优先时使用官方 EDGAR
自行控制采集、缓存、文档获取与标准化，并让每条记录链接到 SEC 原始来源。
快速原型可考虑第三方免费套餐
服务商可通过股票代码搜索、统一结构、章节提取或客户端库减少前期工作。
把单表格任务分开处理
申报索引不等同于标准化的 10-K 财务数据、Form 4 交易或 13F 持仓。
生产接入前完成验证
测试分页、修订、缺失股票代码、历史文件、429 响应与来源 URL 保存。
按问题选择接口
| 问题 | 最佳起点 | 不能默认 |
|---|---|---|
| 公司提交了什么？ | Submissions 元数据 | 主文档包含所有附件 |
| 一次申报有哪些文件？ | Filing index | 仅凭文件名就能判断角色 |
| 披露了哪些财务事实？ | Company Facts / XBRL Frames | 不看上下文也能直接比较概念 |
| 某个章节写了什么？ | 主文档 + 章节解析 | 解析器标题本身就是充分证据 |
| 哪些内容发生变化？ | 按 accession 保存的版本文档 | 最新申报可以代表过去版本 |
不同表格回答不同问题
8-K
带项目代码和附件的重大事件。
S-1 / S-3
注册声明和发行披露。
13D / 13G
受益所有权持仓及修订。
Form 4
内部人交易和持股变化。
DEF 14A
股东大会、治理和高管薪酬。
SEC EDGAR 官方免费 API 提供什么
SEC EDGAR API 官方文档说明了 data.sec.gov 上的公开 JSON 端点，包括申报历史与提取后的 XBRL 数据。这些端点无需 API 密钥，但自动化客户端必须标识自身并遵守 SEC 当前访问与安全政策。申报档案和主文档位于 SEC archive 路径中，应通过 CIK、申报编号和文档名建立关联，不能把它们当作没有身份的普通 HTML 页面。
Submissions JSON 是申报索引，不是申报正文
公司 submissions 响应包含近期表单类型、提交与报告日期、申报编号、主文档，以及指向更早 submissions 文件的引用。完整回填必须继续读取这些历史文件引用，把修订作为独立申报处理，并保留文件公开的先后顺序。索引只能说明“有哪些申报”，并不包含所有文档、附件、内联 XBRL 事实或叙述章节。
XBRL 端点用于事实级查询
companyfacts、companyconcept 与 frames 提供机器可读事实，但每个事实仍带有分类标准、单位、期间、表单、提交日、申报编号，有时还包含分部或维度语境。如果不区分期间型与时点型事实，也不处理修订，直接选择“最新值”可能混入不可比数据。XBRL 同样不能替代叙述章节、附件、签名或所有权表单字段。
设计保留来源的 SEC 申报请求模型
1. 把股票代码解析为 CIK
CIK 是稳定的 SEC 实体标识。应按端点要求规范化 CIK，并与股票代码一起保存，不要把股票代码当作永久标识。
2. 按表格与日期筛选
区分申报日期与报告期，明确是否纳入修订，并判断应用需要元数据、主 HTML 文档、附件还是 XBRL facts。
3. 保留 accession number 与来源 URL
将原始响应与标准化字段一起保存。accession number、表格类型、申报日期、CIK、获取时间和 SEC 官方 URL 构成最小可用来源记录。
4. 把文档、附件、事实和提取章节分层保存
申报索引、原始主文档、附件清单、结构化事实和派生章节文本应分别保存。每个派生产物都要指向来源申报编号、文档、解析器版本和提取范围，避免解析器升级时静默改变权威申报记录。
5. 建立时点化版本，而不是一条可变的“最新”记录
原始申报与修订应按照公开时间保留，再分别生成当前视图和“当时可知”视图。历史研究只能看到分析时点以前已经公开的文件；生产应用则可另行提供最新更正后的状态。
SEC 申报时间、处理状态与修订历史
一条申报记录不能只有一个日期。报告期说明文件覆盖的经营期间；申报日是日历层面的提交字段；SEC 受理时间表示文件何时进入 EDGAR；抓取时间表示系统何时取得文件。结构化事实通常还会晚于原始文档完成解析。只有把这些时间分别保存，提醒、历史研究和当前看板才能使用各自正确的时点。
1. 已建立索引
申报元数据已经给出申报编号、表单、日期和文档名。这只能证明索引记录存在，不能证明全部文件已经下载。
2. 已获取原始文件
主文档和所需附件已经下载、计算哈希并关联到申报编号。某个附件下载失败时，状态应为“部分完成”，而不是返回空申报。
3. 已完成解析
指定版本的解析器生成了章节或事实。应保存警告、不支持的表格和来源位置；解析成功不等于财务数据已经验证。
4. 已通过验证
字段结构、期间、单位、合计、修订链和来源链接通过明确检查。派生数值还应同时公开验证状态与未解决异常。
修订示例：原始值与更正值需要并存。
某份 10-Q 于 8 月 1 日被 SEC 受理，其中一项指标为 1.20 亿美元；8 月 20 日受理的 10-Q/A 把同一报告期的数值修正为 1.12 亿美元。查询“8 月 10 日当时可知信息”时，仍应返回原始申报编号对应的 1.20 亿美元；当前更正视图可以返回 1.12 亿美元，同时关联修订文件和被替代的旧值。如果直接覆盖原始记录，就等于让这次修正在实际公开前 19 天提前可知。
构建带来源证据的客户端
- 01
确认身份
解析 CIK，并核对公司身份。
- 02
列出申报
按表格和日期筛选申报元数据。
- 03
获取文件
通过 accession 和 filing index 选择文档。
- 04
解析
提取字段时保留文档和章节链接。
- 05
保存检查点
记录 accession、获取时间、ETag 和解析器版本。
- 06
对账
处理修订、重复、修正和分页。
比较免费 SEC 申报数据 API 的边界
| 检查项 | 官方 SEC EDGAR | 第三方免费套餐 |
|---|---|---|
| 鉴权 | 无需 API 密钥；需标识客户端。 | 通常需要账户与 API 密钥。 |
| 数据结构 | 原始 JSON、申报文档和 XBRL facts。 | 可能提供标准化记录与搜索能力。 |
| 免费边界 | 可按 SEC 当前政策公开访问。 | 可能存在调用额度、端点范围、历史数据或试用期限限制。 |
| 必须核对 | 客户端标识、缓存策略、请求频率与端点语义。 | 调用额度、数据新鲜度、来源追溯、使用许可和导出权。 |
| 历史完整性 | 近期与历史 submissions 文件、archive、修订、主文档和附件需要自行采集。 | 核对最早日期、表单范围、修订、删除或重处理记录和批量访问。 |
| 派生内容 | 章节解析、边界、分类逻辑和解析器版本由自身负责。 | 核对提取方法、证据位置、更正规则，以及输出是否由供应商派生。 |
| 来源可迁移性 | 官方标识和文档可按 SEC 政策访问。 | 检查原始申报、来源 URL、标准化导出和缓存历史能否迁出服务。 |
可靠性门槛
| 门槛 | 通过条件 | 失败处理 |
|---|---|---|
| 身份 | CIK 与发行人一致 | 停止并重新确认实体 |
| 版本 | 保留 accession | 不能合并记录 |
| 来源 | 每个结论都有文档链接 | 标记为缺乏支持 |
| 访问策略 | 配置 User-Agent、请求间隔和重试 | 退避并排队 |
| 解析器 | 保存版本和测试样本 | 隔离版式变化 |
用 Python 构建可靠的 SEC 申报 API 客户端
建立统一请求层，设置说明性 User-Agent、超时时间与预期响应格式。控制请求节奏，按资源性质使用条件缓存或不可变缓存，遵守 Retry-After，并对临时故障使用带随机抖动的指数退避。应分别处理 403、404、429 和 5xx，而不能一律返回空数据。
- 把 CIK 以字符串保存，并使用带有效期的股票代码映射，不能假设 ticker 永久不变。
- 采集近期 submissions 和其引用的历史文件，再核对申报编号、表单、提交日、报告期和主文档。
- 解析前先获取并计算原始申报产物的哈希；每条派生记录都应带解析器与分类版本。
- 即使并行回填，也要通过有界队列和全局节奏控制遵守当前访问政策。
- 每日核对新增与修订，并对申报编号异常消失、文档变化或解析行丢失发出提醒。
- 下游回答应附带来源 URL、申报编号、表单、提交日、报告期、获取时间和派生状态。
如需单表格实现细节，请参考 QVeris 的 10-K 数据、10-K 年报数据与 S-1 注册申报数据指南。
检查 SEC 数据能力
按任务搜索申报元数据、文档、事实、章节或所有权能力，再检查精确输入输出契约。 可继续打开SEC Submissions 工具，并通过QVeris REST API 参考核对调用契约。
FAQ
SEC 申报文件有免费 API 吗？
有。SEC 提供无需 API 密钥的公开 submissions 与 XBRL 接口、申报 archive 和数据集；第三方免费套餐在标准化、搜索、额度和权限上各不相同。
EDGAR 官方 API 需要密钥吗？
公开 data.sec.gov 端点无需密钥。自动化客户端应标识自身、遵守当前 SEC 访问政策、控制请求节奏并合理缓存。
可以按股票代码查询申报吗？
应先把 ticker 解析为 CIK，并保留带有效期的映射。第三方可以自动处理，但记录中仍应保存 CIK、申报编号、表单和文档身份。
Submissions JSON 是完整申报吗？
不是。它属于包含元数据与文档引用的索引。主文档和所需附件需另行获取；完整历史还要继续读取其引用的早期 submissions 文件。
XBRL company facts 等于财务报表吗？
不等于。它们是带分类、单位、期间、表单和来源语境的标签事实；报表展示、叙述、自定义标签、维度和修订仍需额外处理。
修订申报应该怎样保存？
按照公开时间保留每个申报编号和原始产物，再生成当前视图与时点化视图，不能用修订结果覆盖原文件。
如何比较免费 SEC 申报 API？
应测试元数据、完整文档、修订、历史申报、XBRL 事实、表单专用记录、来源、分页、延迟、导出、许可和失败行为。