按 CIK 查询公司的 SEC 申报文件
先把股票代码解析为十位补零 CIK，再请求公司的 submissions JSON。响应包含近期表格、申报日期、accession number、主要文件及更早历史文件的引用。
SEC EDGAR 开发者指南
免费 SEC 申报 API
安全获取 EDGAR 数据
比较免费 SEC 申报 API 的 EDGAR 数据、XBRL、章节提取、提醒、额度、来源追溯与生产架构。
免费获取 SEC 申报文件：选官方 EDGAR 还是第三方 API？
简单来说，SEC 本身提供无需密钥的 EDGAR 公共数据接口，商业服务商则可能围绕同一批源文件提供有限免费套餐。真正影响选择的不是“免费”二字，而是你需要权威原文、标准化字段、正文搜索、章节提取，还是生产级提醒。只验证一家公司的开发者，与持续监控数千家发行人的研究产品，适合的方案并不相同。
比较服务前，先写出一条可验收任务，例如：“返回该 CIK 在某一时间点之后提交的全部 8-K，包含 accession number 与主要文件 URL，并把修订文件单独标出。”有了具体任务，历史缺口、更新时间含糊和免费套餐描述不清等问题，几分钟内就能暴露出来。
官方公开数据
通过 data.sec.gov 获取申报历史与 XBRL 公司事实，无需 API 密钥；但股票代码映射、正文下载、缓存、解析与监控仍需自行实现。
标准化 API 服务
第三方服务可能提供股票代码查询、统一 JSON、全文搜索、章节提取、SDK 或 webhook；还要测试派生字段能否回溯到准确的文件版本。
免费不代表可以无限调用
应核对日/月额度、突发限制、历史范围、受限端点、试用期限，以及署名、再分发与商业使用权。
来源追溯不可缺少
保留 CIK、accession number、受理时间、申报日与报告期、表格类型、修订状态及 SEC 官方文件 URL。
免费 SEC EDGAR API 如何工作
官方 SEC EDGAR API 文档说明了 data.sec.gov 的 JSON 申报历史与 XBRL 数据端点。这些接口无需 API 密钥，但自动访问必须遵守 SEC 隐私与安全政策，并标识请求应用。
免费的 SEC XBRL API 端点
companyfacts、companyconcept 与 frames 端点提供机器可读的 XBRL facts，适合财务指标；但它们不能替代完整的 10-K、10-Q、8-K、S-1、Form 4 或附件正文。
应把每类端点视为不同的数据契约：submissions 回答“这家主体提交了什么”，归档正文回答“文件披露了什么”，XBRL 端点则回答“某个上下文中报告了哪些标签化事实”。组合这些数据时，应明确按 CIK、accession number、表格、期间、单位和文件版本关联，不能只按公司名称与财年粗略合并。
当来源可靠性与自主控制最重要时，官方接口通常更合适；但工程成本会出现在后续环节，包括读取更早的 submissions 文件、下载附件、提取叙述章节、处理修订申报，以及维护符合访问规范的增量采集器。只有当第三方服务节省的工程时间大于额度、字段、延迟或许可带来的限制时，它才真正有价值。
如何比较免费的 SEC 申报数据 API
| 检查项 | 官方 SEC EDGAR | 第三方免费套餐 |
|---|---|---|
| 鉴权 | 无需 API 密钥；需使用说明性 User-Agent。 | 通常需要账户与 API 密钥。 |
| 响应 | 申报 JSON、原始文件与申报态 XBRL。 | 可能标准化股票代码、章节、财务事实与表格字段。 |
| 免费边界 | 公开访问，受公平访问政策约束。 | 可能有月度额度、端点限制、试用或测试期。 |
| 适合场景 | 权威来源与自建采集处理。 | 需要更干净字段或搜索能力的快速原型。 |
| 历史与修订 | 可获取公开申报历史，但较早元数据与正文可能需要读取多个归档路径。 | 覆盖范围可能从服务商指定日期开始；需测试 /A 修订文件与历史回填方式。 |
| 叙述正文 | 完整正文与附件具备权威性，但章节提取需要自行完成。 | 可能直接提供风险因素、MD&A、8-K 项目或附件搜索；应与原始 HTML 核验边界。 |
| 交付方式 | 轮询、检查点、去重与重放机制需自行构建。 | webhook 或数据流可减少开发量，但要核对延迟、重试、顺序与漏报恢复机制。 |
| 必须核对 | 当前访问政策、缓存、限流与端点语义。 | 额度、历史、更新频率、来源链接、许可与导出权。 |
SEC EDGAR API 的 Python 与 JSON 工作流
步骤 1：确定公司与申报表格
把股票代码映射到 CIK，再确定需要的是申报元数据、完整正文、XBRL facts，还是表格专用的标准化记录。查询免费 10-K API 与订阅 Form 4 交易流是不同的数据任务。
发行人映射应能处理股票代码变更、多类别股份和非美国代码，并保存解析后的 CIK、映射来源与观察日期。设置表格筛选时，还要先确定 10-K/A、8-K/A 等修订表格是并入原结果，还是进入单独的修订数据流。
步骤 2：发送合规且可追踪的请求
设置包含应用与联系信息的说明性 User-Agent，配置超时，处理 429 与 5xx，缓存未变化的数据并使用指数退避。无需密钥并不代表可以无限请求。
多个工作进程应共享统一限流器，而不是各自独立控制频率。缓存股票代码映射与不可变申报文件，在适用时使用条件请求，遵守 Retry-After，并记录状态码、延迟、URL、尝试次数与响应大小。反复下载未变化归档的“免费”接入既不稳定，也不符合合理访问原则。
步骤 3：标准化但不丢失来源
把原始 JSON 与来源 URL 和标准化字段一起保存。使用 accession number 作为稳定文件标识，区分申报日期与报告期，并保留修订记录，不要静默覆盖旧版本。
上线前应准备一组小型评测样本：一家历史很长的发行人、一家近期 IPO 公司、一家拥有多类别股份的公司、一份修订文件、一份附件较多的申报，以及一个在不同单位或上下文中出现的 XBRL fact。先与 EDGAR 核对数量与标识并人工检查来源链接，再测试增量更新和模拟故障后的重放。
用 QVeris 查找 SEC 申报数据 API 能力
QVeris 帮助开发者与 AI Agent 发现并检查可用的数据能力。在 QVeris 工具详情中，建议按任务而不是只按服务商名称搜索，例如“最新 8-K 元数据”“10-K 风险因素正文”“按 CIK 查询公司事实”或“Form 4 交易”。Agent 调用前应检查必填标识、输出字段、来源链接、更新频率和服务要求；下游记录还应保留 EDGAR 官方标识，使标准化结果可以独立核验。能力调用流程可参考 QVeris 文档。
常见问题
是否真的有免费的 SEC 申报文件 API？
有。官方 EDGAR 数据接口无需付费订阅或 API 密钥；代价是股票代码映射、归档下载、解析、缓存与监控等能力需要自行建设。商业服务所称的“免费 API”通常会限制请求量、历史范围、可用端点或生产用途。
应该用官方 EDGAR，还是第三方免费套餐？
如果最看重权威原文、完整附件与自主控制，优先选择 EDGAR；如果统一字段、全文搜索、章节提取、SDK 或提醒能明显节省工程时间，可以评估第三方服务。两种方案都应使用相同的表格、日期与修订案例测试。
能否按股票代码查询 SEC 申报文件？
官方申报记录以 CIK 为核心，而不是以股票代码为核心。应先把 ticker 解析为 CIK，保留映射来源与日期，并考虑代码变更和多类别股份。第三方 API 可以代做这一步，但响应中仍应显示最终使用的 CIK。
submissions JSON 与 XBRL company facts 是同一种数据吗？
不是。submissions 描述申报历史与文件元数据；XBRL 端点提供带有概念、单位、期间、表格和申报上下文的标签化事实。完整的叙述性披露与附件仍位于申报正文中。
如何测试免费的 SEC 申报文件 API？
样本应覆盖近期与较早文件、修订申报、附件较多的文件、多类别股份、缺失可选字段，以及已知新申报后的增量更新。先用 EDGAR 核对 accession number 与来源 URL，再测试延迟、额度行为和错误恢复。
为了审计追踪，至少要保存哪些字段？
至少保留 CIK、accession number、表格与修订状态、受理时间、申报日、报告期、主要文件、官方 URL、抓取时间、数据服务商及原始响应版本。对提取后的事实或正文，还要记录来源位置与转换版本。