Esef Filings

@pipeworx/esef-filings

XBRL 文件索引 MCP — 收录由 XBRL International 运营的 filings.xbrl.org 索引中发布的公司年报，以及每份报告中的 IFRS 财务事实。无需密钥。

属于 Pipeworx — 一个将 AI Agent 连接到 1879+ 个实时数据源的 MCP 网关。这是一个独立的非官方集成，与上游提供方无关联、未经其认可，也未由其发布。

这是 sec-xbrl 的欧洲对应工具：思路相同（直接从监管机构的 XBRL 中获取会计事实），但申报制度不同。

工具

• esef_search_filings(entity_name?, country?, regime?, year?, period_end?, period_end_from?, period_end_to?, with_errors?, sort?, limit?, page?) — 搜索索引。返回公司名称、LEI 或国家标识符、国家、制度、期末日期、XBRL 验证错误／警告数量、报告语言，以及指向 xBRL-JSON、HTML 报告、查看器和文件包的链接。任何不在此列表中的参数都会被拒绝，并通过 user_error 列出可接受的参数；绝不会被静默丢弃（参见 GOTCHA 1）。
• esef_entity_filings(entity, limit?) — 获取一家公司的所有文件，可通过名称、LEI 或国家注册号解析实体。返回解析结果及其解析方式，并按不同报告对文件进行分组（参见下文“语言版本”）。
• esef_filing_facts(fxo_id? | entity?, year?, concept?, include_dimensioned?, limit?) — 第二步。打开文件的 xBRL-JSON 报告，返回带名称的 IFRS 事实，包括数值、货币、期间和概念。

esef_search_filings 和 esef_entity_filings 用于确认文件是否存在；只有 esef_filing_facts 会返回财务数据。

范围

共 25,640 份文件，属于两个报告制度：

制度	文件数	国家
ESEF	~15,996	AT BE CY CZ DK ES FI FR GB GR IS IT LT NL NO PL PT RO SE
UAIFRS	~9,644	UA

工具包名称中包含 ESEF，但数据源的范围比 ESEF 更广。country 和 regime 都是一级筛选条件，调用方可以据此限定所需范围。参见下文 GOTCHA 2 — 这不是无关紧要的细节。

除了上表中的国家，还接受 country: "LU"、"SI" 和 "EE" — 这些数据是从各国 OAM 实时查询的，而非来自此索引（参见 GOTCHA 23）。同样也接受 "IE" 和 "BG"（参见 GOTCHA 24）；"GR" 已在上表中，现在也会补充实时数据。

身份验证

无需身份验证。无需密钥或账户，也未发布速率限制说明。

filings.xbrl.org 是一个非营利索引，因此该工具包刻意保持低调：每次调用只发起一次索引请求，最多获取一份报告，不进行探测或扇出请求，并使用可实际联系的 User-Agent（Pipeworx/1.0 (+https://pipeworx.io; [email protected])）。

注意事项

易踩坑 1 — 错误的筛选参数会被静默忽略，而不会被拒绝

这是最危险的问题，也是筛选条件的构造只放在一个辅助函数中的原因。

API 接受两种形式的 JSON:API 筛选条件：

?filter%5Bcountry%5D=FI     bracketed shortcut, percent-encoded  -> meta.count 1168, Finnish records
?country=FI                 bracketed form written WITHOUT the brackets
                            -> HTTP 200, meta.count 25640, first record Ukrainian

第二种形式就是给未筛选的索引穿上成功筛选查询的外衣。状态码相同、封装结构相同、字段名也相同——没有任何明显迹象能发现问题。

src/index.ts 中有两道防线：

1. 此工具包绝不会在筛选条件中使用带方括号的快捷形式。 它使用 flask-rest-jsonapi 的复杂形式：?filter=[{"name":"country","op":"eq","val":"FI"}]——这是一个不带方括号的单一参数，因此不会有方括号编码错误的问题，并且错误的属性名会明确报错（HTTP 400 "FilingSchema has no attribute bogus"），而不是被忽略。只有 page[size] / page[number] 使用方括号，并且会通过使用 URLSearchParams 的 buildUrl() 处理（它会对方括号进行百分号编码）。
2. verifyFilters() 会根据请求的筛选条件重新检查返回的行。 每个 esef_search_filings 响应都包含 filters_applied、filters_verified 和 filter_mismatches，因此，如果某个筛选条件未能生效，就会显示在载荷中，而不是悄悄扩大结果范围。

同样的故障模式也曾出现在上一层的我们自己的工具边界上，并以相同方式修复（fleet #2317）。 esef_search_filings 从未声明 period_end_from / period_end_to，因此，调用方如果猜测使用了这些参数（它们是日期范围的合理名称），处理程序就会静默丢弃这些参数——没有架构错误，filters_requested 会将它们回显为 null，响应却仍声称 filters_verified: true。对葡萄牙进行日期范围查询，返回的未筛选总数仍是 128 条，与完全不带日期条件的查询相同。现已通过两种方式修复：period_end_from / period_end_to 现在是实际声明的范围筛选条件（对 period_end 使用 op: 'ge' / 'le'，并像其他筛选条件一样由 verifyFilters() 验证）；此外，rejectUnknownArgs() 会针对调用方可能猜测的其他参数抛出 user_error，并列出可接受的参数，因此，无论未声明参数叫什么，都不会再被静默丢弃。

易踩坑 2 — 此索引并非仅包含 ESEF，声称它仅包含 ESEF 就是错误答案

未筛选探测的第一条记录来自乌克兰：EDRPOU-32033791-2020-12-31-UAIFRS-UA-0。索引中有 38% 属于 UAIFRS。如果此工具包可能返回乌克兰的申报，却将其描述为“欧洲申报”，就会陷入解析粒度陷阱——调用方会在错误的粒度上得到一个看似可靠的答案。

因此：每个工具描述都会明确列出这两种制度，regime 是筛选条件，每条返回的记录都会注明自身的 country 和 regime，搜索响应还会包含 scope_note。如果你修改描述，请保留其中关于范围的句子。

易踩坑 3 — 同一份年度报告会按不同语言版本分别编入索引

Citycon 的 FY2022 出现了两次——…-ESEF-FI-1（芬兰语）和 …-ESEF-FI-0（英语）——数据完全相同，但 fxo_id 不同。把索引行数当成报告数会夸大公司的申报历史：Citycon 有 11 份申报，但只有 6 个不同的财年。

因此，esef_entity_filings 会同时返回 filing_count（索引行数）和 report_count（不同年份数），并将不同版本归组到 preferred_edition 下——如果有英语版本，就优先选择英语，因为这样更容易读懂叙述性事实。通过公司名称解析时，esef_filing_facts 会选择英语版本。

请注意，这与报告内部的语言维度不同。每份 xBRL-JSON 文档都是单语文档；语言差异发生在更高一层，即不同申报之间。

陷阱 4 — 同一报告中一项数值被标记多次

Citycon FY2022 的 ifrs-full:ProfitLoss（5,100,000 欧元）以字节完全相同的维度出现了 三次（主报表、附注、权益调节表），此外还有按 ComponentsOfEquityAxis 拆分的副本。若直接返回，就会把同一项利润数值误认为六项不同数值。

esef_filing_facts 会按除语言以外的所有维度分组，合并相同的值，并报告 occurrences（该值对应的标记次数）和 dedup.repeat_taggings_collapsed。默认排除带有轴维度的拆分项（include_dimensioned: false），并在 dedup.dimensioned_facts_excluded 中计数。同一维度组合下确有矛盾的值会显示在 conflicting_values 中，而不会被悄悄择一采用。

陷阱 5 — json_url 可能为 null

约 1.5% 的索引行没有机器可读报告；在抽样案例中，report_url 和 viewer_url 也为 null——该行只有元数据（例如 Cloetta AB 549300CSLHPO6Y1AZN37-2021-12-31-ESEF-SE-1，其 error_count: 1，且只有一个打包 zip 文件）。esef_filing_facts 会返回 {found: false, reason: 'no_machine_readable_report'}，并注明仍然存在的 URL，而不是抛出错误。

陷阱 6 — 实体通过 identifier 而不是 id 寻址

JSON:API 实体记录同时包含 id: "1597" 和 attributes.identifier: "549300P8N0P6KDGTJ206"。只有 identifier 可用于寻址：/api/entities/1597 会返回 404。

更麻烦的是，identifier 并不总是 fxo_id 的前缀。乌克兰申报文件的 fxo_id 中使用 EDRPOU-32033791-…，但寻址时使用的是纯数字 32033791。按 fxo_id 前缀将申报文件与实体名称关联，会导致所有乌克兰申报文件的 entity_name: null；此工具包则会关联 relationships.entity.links.related 的末尾部分。

陷阱 7 — xBRL 时点日期晚标了一天

xBRL-JSON 的时点期间 2023-01-01T00:00:00 对应的是 2022-12-31 的资产负债表——该时点是次日的开始。直接读取原始字符串会造成整整一年的误差。describePeriod() 会对这两种形式进行规范化，因此 period_end 和 period_label（"截至 2022-12-31"、"2022-01-01 至 2022-12-31"）已完成校正。

陷阱 8 — 叙述性附注也会被标记为事实

Citycon FY2022 报告中的 DisclosureOfShareCapitalReservesAndOtherEquityInterestExplanatory 是一段 2,500 字符的正文。文本值会截断至 600 个字符，并设置 value_truncated / value_length；同一期间内，度量数值会排在叙述文本之前，因此 concept: "Equity" 会优先显示 2,310,300,000 欧元的余额，而不是数页附注文本。

陷阱 9 — 索引滞后于申报季；当前年份的覆盖几乎为空

这不是工具包的 bug，但这是实际会给用户造成损失的陷阱，而且有一段时间没有记录（fleet #2317 — 一位外部开发者独立测出了相同的数量，并因此拒绝使用该工具包）。filings.xbrl.org 是一个自愿参与的社区索引，而不是实时监管机构数据源：公司的年度报告通常会在报告期结束数周至数月后，且在 XBRL International（或国家级收集机构）处理完毕后才被收录。

通过 esef_search_filings 的 year 筛选条件，于 2026-09-23 实时测得：

Country	2023	2024	2025
PT	7	7	0（在 CMVM 收录之前 — 见陷阱 10）
ES	125	113	1（在 CNMV 收录之前 — 见陷阱 11）

搜索当前日历年通常只会返回很少甚至没有结果 — 这反映的是上游延迟，而不是查询出错或该国家没有申报者。如果你要构建一个期望近乎实时覆盖当前财年的管道，这个索引会让你失望；前 1-2 个日历年才是实际有数据的年份。现在，每个 esef_search_filings 响应（无论匹配或未匹配）都会附带机器可读的 coverage_note，让调用方通过工具获知这一点，而不是通过一次悄无声息地返回零结果的查询得知。该说明按响应生成，不包含任何数量（fleet #2379 — 一条固定的“Spain 2025 = 1”与 CNMV 合并当天实时的 total_matching 118 并列）：搜索范围限定为 PT、ES、NO 或 SE 时，说明会指出其结果遵循监管机构的发布情况；如果无法读取该监管机构的索引，则会说明相反的情况；其他搜索则会收到延迟警告。每条结果都会标明自己的 source。上表是仅针对该索引的日期快照，并不代表当前覆盖情况。

陷阱 10 — 葡萄牙数据来自两个来源，每条结果都会标明来源

filings.xbrl.org 收录了 7 份 2024 年葡萄牙申报文件和 0 份 2025 年申报文件；而每年大约有 50 家葡萄牙发行方会向 CMVM（Comissão do Mercado de Valores Mobiliários，葡萄牙监管机构及官方指定的存储机制）发布 ESEF 文件包。Jerónimo Martins 的 FY2025 报告于 2026-03-30 发布在 CMVM 上，六个月后仍未出现在 filings.xbrl.org 上（fleet #2320）。

因此，葡萄牙申报文件也来自 CMVM：

• esef_search_filings 使用 country: "PT"（或不指定国家且公司名称为 CMVM 所知）时，会合并两个来源，并按 LEI + 期间结束日期去重 — 同时出现在两个来源中的报告只会显示一次。source 的值为 cmvm 或 xbrl.org；另一份副本会标记在 also_on_xbrl_org / also_on_cmvm 中；merge.duplicates_collapsed 会统计合并的重复项。
• CMVM 结果包含 published_at（CMVM 的官方发布时间，里斯本时区偏移）、first_published_at（发行方通常会先发布“供股东周年大会审议”的报告，之后再发布经股东周年大会批准的版本 — 只显示一条结果，两个版本都会列在 versions 中）、indexed_at、文件包的 package_sha256 和 CMVM 自己的 ESEF viewer_url。xbrl.org 结果仅包含 date_added，即该索引收录报告的日期 — 并非发布日期。
• CMVM 申报文件 ID 的格式如 cmvm-1355933；将其作为 fxo_id 传给 esef_filing_facts。按公司名称或 LEI 解析时，最新期间优先使用 CMVM 副本。
• CMVM 结果没有验证运行，因此 error_count/warning_count 为 null，带有 with_errors: true 的搜索会跳过 CMVM 结果。
• 每个查询过 CMVM 的响应都会包含 cmvm_status，其中有 last_successful_check、last_error 和 stale（48 小时内没有成功检查）。这一区别决定了“CMVM 没有发布新内容”和“无法检查 CMVM”之间的差异 — 绝不能把后者误认为前者。在 Pipeworx 网关之外（直接运行 npm install），cmvm_status.available 为 false，葡萄牙结果仅来自 filings.xbrl.org。
• 少数 2023 年 CMVM 文件包包含不带任何内嵌 XBRL 的纯 XHTML 报告；这些结果会列出 has_machine_readable_report: false。

易踩坑 11 — 西班牙也有两个来源（CNMV）

filings.xbrl.org 收录了 2024 年的 113 份西班牙申报文件，以及 2025 年的 1 份；而每家西班牙上市发行人都会在 CNMV（Comisión Nacional del Mercado de Valores，西班牙监管机构）的官方登记处提交年度财务报告及 ESEF 套件。Técnicas Reunidas 的 FY2025 套件于 2026-02-26 在此发布（fleet #2351）。

因此，西班牙申报文件也来自 CNMV，正如葡萄牙申报文件来自 CMVM（易踩坑 10）一样；合并、按 LEI + 期间结束日期去重，以及数据新鲜度约定也相同：

• source 为 cnmv；另一份副本标记为 also_on_xbrl_org / also_on_cnmv。每个查询过 CNMV 的响应都包含 cnmv_status（字段与 cmvm_status 相同；连续 48 小时未成功检查后标记为 stale）。
• CNMV 申报文件 ID 为登记编号：cnmv-20912。记录还包含 national_identifier（发行人的西班牙 NIF，例如 A-28092583）和 report_scope（consolidated 或 individual）。如果发行人将个别和合并财务报表放在同一个套件中，则各生成一条记录，分别为 cnmv-<n> 和 cnmv-<n>-2，并注明类型；与 filings.xbrl.org 匹配的是合并报表记录。
• published_at 使用 CNMV 自身的时间：如果 CNMV 披露源中包含该申报文件，则精确到分钟（马德里时区偏移）；否则仅使用登记处的发布日期。first_published_at 和 versions 的处理方式与 CMVM 相同。
• 发行人范围涵盖自 2023 年以来在 CNMV 披露源中提交过年度财务报告的所有发行人，每日读取。

易踩坑 12 — 挪威数据来自 Oslo Børs NewsWeb，因为 filings.xbrl.org 已停止收录

filings.xbrl.org 自 2025-05-21 起不再添加挪威申报文件：FY2024 有 220 份挪威申报文件，FY2025 仅有 0-2 份。每家在 Oslo 上市的发行人都会在 Oslo Børs NewsWeb 发布年度财务报告公告（类别 1001，ÅRSRAPPORT / ANNUAL FINANCIAL REPORT），并附上 ESEF 套件。Equinor 的 FY2025 套件于 2026-03-19 附在该公告中发布，且从未出现在 filings.xbrl.org 上（fleet #2356）。

合并、按 LEI + 期间结束日期去重，以及数据新鲜度约定与易踩坑 10/11 相同：

• source 为 newsweb；另一份副本标记为 also_on_xbrl_org / also_on_newsweb。每个查询过 NewsWeb 的响应都包含 newsweb_status（字段与 cmvm_status 相同）。
• NewsWeb 申报文件 ID 格式为 newsweb-<messageId>-<attachmentId>，例如 newsweb-668785-321602（Equinor FY2025）。viewer_url 是公告页面；published_at 是公告时间（UTC）。
• 套件只会附在公告的两个语言版本之一中；更正内容则作为单独公告发布。字节完全相同的重复附件会合并为一条记录。同一 LEI + 期间对应的不同套件（更正后的套件、第二种语言版本）会合并为一条记录，并通过 versions 标记。
• LEI 来自内嵌 XBRL，绝不会从附件名称中获取（附件名称由发行人自行选择，例如 eqnr-2025-12-31-1-nb.zip）。
• 类别 1001 也包含仅有 PDF 的报告（债券发行人、外国发行人）；此处不会为这些报告创建记录。

注意事项 13 — 瑞典数据来自 Finansinspektionen (FI)

filings.xbrl.org 于 2025-05-08 停止收录瑞典数据：最新一条瑞典记录在当天添加，FY2025 的瑞典报告数量为 0（FY2024 为 339 份）。每家瑞典发行人都会在 Finansinspektionen 的 Börsinformation 数据库提交年度报告及 ESEF 套件。该数据库是瑞典官方指定机制（调查：docs/esef-freshness-survey.md 第 5 部分）。

因此，瑞典申报文件也来自 FI，采用与注意事项 10-12 相同的合并、按 LEI + 期间结束日去重及数据新鲜度约定：

• source 为 fi；另一处副本标记为 also_on_xbrl_org / also_on_fi。每个查询过 FI 的响应都包含 fi_status（字段与 cmvm_status 相同）。
• FI 申报文件 ID 是 FI 的文件 ID：fi-61807（Ericsson FY2025）。published_at 是 FI 记录的发布时间，精确到分钟，并带有斯德哥尔摩时区偏移量。
• 同时提交瑞典语和英语版本的发行人，会有两个 FI 套件对应同一个 LEI + 期间；它们合并为一条记录，提供英语版本，两个版本都列在 versions 中。
• LEI 来自报告的 inline XBRL（其次是套件的根目录，再其次是 FI 的发行人页面），绝不会从文件名提取：Volvo 的套件名为 abvolvo-…。

注意事项 14 — 公司名称可能会匹配到错误的发行人

名称解析首先在 filings.xbrl.org 上进行，并优先选择匹配名称最短的发行人。"Ericsson" 在那里会匹配到克罗地亚的 ERICSSON NIKOLA TESLA d.d.，而 Telefonaktiebolaget LM Ericsson 的 FY2025 报告只在 FI 索引中，因此 esef_filing_facts {entity:"Ericsson", year:2025} 过去会给出很肯定的 no_filing_for_year 答案（fleet #2372）。

当 esef_filing_facts 按名称解析，且选中的发行人没有请求年份 year 的申报文件时，现在会搜索监管机构索引（CMVM、CNMV、NewsWeb、FI、FSMA STORI、MSE、HANFA SRPI），查找名称匹配且有相关申报文件的其他发行人：

• 恰好一个 → 使用该发行人的报告，并通过 resolved_by 说明名称最初匹配到了其他发行人；
• 多个 → 返回 reason: "ambiguous_entity" 及 candidates（名称、国家、LEI、来源、申报文件 ID）；该工具绝不会猜测。

如果错误的发行人有该年份的申报文件，这种方法就无济于事："Santander" 搭配 year: 2025 会在 filings.xbrl.org 上匹配到 Santander UK plc，而不是 Banco Santander。名称常见时，请传入 LEI。

注意事项 15 — 比利时数据来自两个地方：FSMA STORI 补齐缺失部分

filings.xbrl.org 仅部分收录比利时数据：来自 33 家发行人的 47 份 FY2025 申报文件，且自 2026-05-12 后没有新增比利时记录。FSMA 的 STORI 数据库是比利时官方指定机制，其中列出了 106 家拥有 inline-XBRL FY2025 年度报告的发行人；xbrl.org 上的 33 家发行人全部包含在其中（调查：docs/esef-freshness-survey.md 第 7 部分，fleet #2405）。

采用与注意事项 10-13 相同的合并、按 LEI + 期间结束日去重及数据新鲜度约定：

• source 为 fsma；另一处副本标记为 also_on_xbrl_org / also_on_fsma。每个查询过 STORI 的响应都包含 fsma_status（字段与 cmvm_status 相同）。
• STORI 申报文件 ID 是 STORI 的文件 ID：fsma-5c08f790-404c-4121-bd0b-0cf3350455da（AB InBev FY2025）。published_at 是 STORI 记录的发行人发布时间（布鲁塞尔时区偏移量）；received_at 是 STORI 收到报告的时间，通常晚几天（AB InBev FY2025：发布时间为 2026-02-12，接收时间为 2026-02-19）。national_identifier 是 KBO/BCE 公司编号。
• STORI 每份报告最多保存三种语言版本（nl、fr、en）；系统会收录其中一个版本，优先选择英语。发行人以 .zip 或 .xbri（Report Package 1.0）格式提交套件；少数发行人只提交未打包的 .xhtml，系统会按原样转换。
• 不含 inline XBRL 的发布内容（仅 PDF：证书、基金及部分非欧盟发行人的文件）不会生成记录；索引会在 publications_without_inline_xbrl 下列出这些内容。
• LEI 来自 inline XBRL，其次是套件根目录，再其次是 STORI 列表，绝不会从文件名提取（abinbev-2023-12-31-en (1).zip）。

易踩坑 16——FY2025 的马耳他数据仅来自马耳他证券交易所 OAM

filings.xbrl.org 于 2025-05-21 停止收录马耳他数据：MT FY2024 = 46 份申报，FY2025 = 0 份。马耳他证券交易所运营着马耳他官方指定机制，该机制上的每则年度报告公告都附有发行人的 ESEF ZIP 文件。过去 12 个月内，共有来自 92 家发行人的 97 个 FY2025 文件包（截至 2026-09-25 测得；调查：docs/esef-freshness-survey.md 第 9 部分，fleet #2431）。

合并、按 LEI + 期间结束日去重，以及数据新鲜度约定均与易踩坑 10-15 相同：

• source 为 mse；另一个副本标记为 also_on_xbrl_org / also_on_mse。所有查询过该来源的响应都带有 mse_status（字段与 cmvm_status 相同）。
• MSE 申报 ID 是 CDN 文件夹名称，其中包含代码、期间结束日、范围、LEI 和上传时间：mse-BOV_20251231_CON_AFR_529900RWC8ZYB066JF16_20260326114707204（Bank of Valletta FY2025）。published_at 是 OAM 公告时间（马耳他时区）。
• 大多数马耳他发行人是发行债券的金融公司，提交的是公司单体账目：97 个 FY2025 文件包中，41 个为 IND（report_scope: "individual"），其余 56 个为 CON（"consolidated"）。ESEF 仅要求对合并 IFRS 报表进行标记；已测得的每个 IND 文件包都是未标记的普通 XHTML：这些行标记为 has_machine_readable_report: false，且 esef_filing_facts 中没有相关数字。
• 非 12 月年末很常见（MaltaPost 为 9 月 30 日，Farsons 为 1 月 31 日）。与本数据集中的其他来源一样，year 筛选依据期间结束日。
• 交易所的条款允许任何人保存和复制文件，条件是“注明来源，且不得更改或歪曲材料”：每行都会注明来源，文件包按下载时的原样存储。

易踩坑 17——克罗地亚数据仅来自 HANFA SRPI

filings.xbrl.org 于 2025-05-21 停止新增克罗地亚申报：HR FY2024 = 30 份，FY2025 = 0 份。HANFA 的 SRPI 是克罗地亚官方指定机制，2026 年接收了来自 77 家发行人的 178 份附带 ESEF 文件包的年度报告提交（调查：docs/esef-freshness-survey.md 第 11 部分，fleet #2435）。

• source 为 hanfa；存在另一个副本时，标记为 also_on_xbrl_org / also_on_hanfa。所有查询过 SRPI 的响应都带有 hanfa_status（字段与 cmvm_status 相同）。
• SRPI 申报 ID 为 SRPI 的提交编号：hanfa-1214588（Hrvatski Telekom FY2025，英语，合并）。published_at 是 SRPI 收到提交的时间（萨格勒布时区）。
• 克罗地亚发行人分别提交合并和非合并文件包，每个文件包都是单独的提交，而且通常还会提供克罗地亚语和英语版本。这些是不同的行，按 report_scope（consolidated / individual）标记；同一范围的不同语言版本作为一行提供英语版本，并全部列在 versions 下。
• 更正会作为新的 SRPI 提交，旧提交仍会保留。每个文件包都会留存；每个 LEI + 期间 + 范围只提供最新转换的文件包。
• 未附带 ESEF 文件包的提交（PDF，或 HANFA 自有的 XLSX“GFI”表格）不会生成对应行；索引会在 submissions_without_esef 下列出这些提交。
• 列表中的联系人列（申报人指定的联系人姓名、电话和电子邮件）绝不会被收集。

易错点 18——匈牙利数据来自 MNB：filings.xbrl.org 于 2025 年 5 月停止更新

filings.xbrl.org 于 2025-05-21 停止添加匈牙利申报文件（HU FY2024 = 29 份，FY2025 = 0 份），且从未收录 OTP Bank 或 Richter Gedeon。每家发行方都会将 ESEF 套件提交至 MNB 的 Közzétételek 网站（kozzetetelek.mnb.hu），这是匈牙利官方指定的机制（调查：docs/esef-freshness-survey.md 第 12 部分，fleet #2437）。

采用与易错点 10-17 相同的合并、按 LEI + 期末去重，以及数据时效性约定：

• source 为 mnb；另一份副本标记为 also_on_xbrl_org / also_on_mnb。每个查询过 MNB 的响应都会包含 mnb_status。
• 申报文件 ID 是 MNB 文档 ID：mnb-909016（OTP Bank FY2025，英文套件）。published_at 是 MNB 的发布时间（布达佩斯时区偏移）。national_identifier 是 MNB 的“Intézmény törzsszáma”公司编号，并非 LEI；LEI 依次从内嵌 XBRL、套件根目录，再到 <LEI>-<period>-… 文件名中获取。
• 发行方会为每种语言附上一个套件（…-en.zip、…-hu.zip）；只收集其中一个，优先选择英文版。一份包含两份报告（单独报告和合并报告）的披露会生成各一条记录。
• 有些与套件一同附上的 ZIP 只包含 PDF（MOL 的“其他文档”）；这些文件不会生成记录，并会列在 publications_without_inline_xbrl 下。
• MNB 的版权声明允许免费复用，但须注明任何转换，因此 MNB 申报文件中的 esef_filing_facts 会包含一行 transformation：相关数据由发行方的 iXBRL 转换而来，归发行方所有，而非 MNB。

易错点 19——立陶宛将 oam.lt 与 filings.xbrl.org 合并

filings.xbrl.org 仅部分收录立陶宛数据（FY2025：17 家发行方，自 2026-05-12 起未再新增），且从未收录 Ignitis Group。oam.lt 是纳斯达克维尔纽斯证券交易所运营的受监管信息中央存储库，也是立陶宛官方指定的机制，收录了每家发行方的年度报告（调查：docs/esef-freshness-survey.md 第 13 部分，fleet #2453）。LT 记录按 LEI + 期末合并。

• source 为 oamlt；另一份副本标记为 also_on_xbrl_org / also_on_oamlt。每个查询过 oam.lt 的响应都会包含 oamlt_status。
• 申报文件 ID 的格式为 oamlt-<messageId>-<attachmentId>：oamlt-468051-338788（Ignitis grupė FY2025）。published_at 是公告时间（维尔纽斯时区偏移）。
• oam.lt 上的发行方名称是纳斯达克的简称（“Ignitis grupe”）；LEI 只能从内嵌 XBRL 中获取。
• 并非每个年度报告附件都是 ESEF 套件：Ignitis 将套件封装在 ZIP 内的 .7z 文件中（已解包）；许多发行方将其电子签名为 ASiC-E 容器（.asice）；Telia Lietuva 则提交了不含内嵌 XBRL 的裸 XHTML（列在 publications_without_inline_xbrl 下，不生成记录）。Amber Grid 的 FY2025 年度报告收录于 filings.xbrl.org，但回填时未能从 oam.lt 收集到套件（仅找到其“Operating Results”消息，其中不含套件）；该公司的记录来自索引。
• 更正后的报告会作为一条新的 oam.lt 消息发布；系统会提供每个 LEI + 期间最新转换的套件。

注意事项 20 — 2025 财年罗马尼亚数据仅来自 ASF OAM

filings.xbrl.org 上没有罗马尼亚 2025 财年的申报文件。ASF OAM（oam.asfromania.ro）是由 Autoritatea de Supraveghere Financiară 运营、罗马尼亚官方指定的机制，收录所有发行人的年度财务报告（RFA）（调查：docs/esef-freshness-survey.md 第 15 部分，fleet #2487）。RO 行会按 LEI 和期末日期与任何 xbrl.org 副本合并。

• source 为 asf；每个查询过该来源的响应都会带有 asf_status。申报文件 ID 的格式为 asf-<symbol>-<upload stamp>：asf-SNP-20260319180945（OMV Petrom 2025 财年，合并报表）。published_at 为上传时间（布加勒斯特时区偏移）。
• 只有合并报表包包含内联 XBRL。 单独报表（个别报表）是纯 XHTML，不含 ix: 标签。系统会将其保留为一行，但不包含事实（has_machine_readable_report: false、report_scope: "individual"），发行人的 LEI 和期间取自其带标签的报表包。按实体和年份查询 esef_filing_facts 时会选取合并报表行。
• 如果发行人的上传说明中写有“consolidat…”或“individual…”，则据此确定 report_scope；否则，带标签的报表包标记为合并报表，不带标签的标记为个别报表（索引中 scope_source: "inferred_from_tagging"）。
• 发行人会上传罗马尼亚语和英语版本，并将更正作为新上传文件（“Corectare”）；这些都属于同一行的 versions，系统提供最新转换的版本。
• 切勿从 bvb.ro 获取数据：布加勒斯特证券交易所也托管这些报表包，但其条款禁止自动化程序。

注意事项 21 — 当前报告中的塞浦路斯数据仅来自塞浦路斯证券交易所 OAM

自 2022 财年以来，filings.xbrl.org 未再添加塞浦路斯申报文件（共 34 份，最新日期为 2023-05-30）。publicoam.cse.com.cy 是塞浦路斯证券交易所官方指定的机制，通过无需密钥的 JSON API 收录所有发行人的年度财务报告（调查：docs/esef-freshness-survey.md 第 15 部分，fleet #2489）。

• source 为 cse；另一份副本标记为 also_on_xbrl_org / also_on_cse。每个查询过 CSE 的响应都会带有 cse_status。
• 申报文件 ID 的格式为 cse-<listingVersionId>-<fileId>：cse-222818-223858（Bank of Cyprus Holdings 2025 财年，英语报表包）。published_at 为 OAM 发布时间（尼科西亚时区偏移）。
• 报告及其译文是两则独立的 OAM 公告，各自附有报表包（…-el.zip、…-en.zip）；系统会收集两者，并按 LEI 和期末日期对报表包分组，因此其中一份会显示为 versions 条目。
• 年度报告类别还包含董事会决议、股东周年大会通知和仅提供 PDF 的业绩报告；部分发行人提交的 ZIP 包仅包含未加标签的 XHTML（单一实体账目，ESEF 不要求加标签）：Interfund 和 Dome Investments 2025 财年。这些均不会生成数据行；它们列在 publications_without_inline_xbrl 下。
• 列表 API 的 registryTimestamp 参数确实限定了日期下限，但 sort 参数不起作用，而且小页面会漏掉数据（每页 500 条只返回了 3,592 条中的 2,817 条不同记录）。采集器使用每页 2,000 条的设置，并拒绝不完整的读取。详情见：scripts/esef-cmvm/cse.py。

注意事项 22 — FY2024 和 FY2025 的拉脱维亚数据仅来自 CSRI

filings.xbrl.org 上有 36 份拉脱维亚申报文件，最新的也不晚于 FY2023（最后添加于 2024-07-09）。CSRI（csri.investinfo.lv）是受监管信息中央存储库，由 Latvijas Banka 运营，也是拉脱维亚官方指定的机制；当前报告由其提供（调查：docs/esef-freshness-survey.md 第 15 部分，舰队 #2492）。LV 行按 LEI + 期末合并，因此 FY2023 及更早的内容仍可能来自该索引。

• source 为 csri；另一份副本标记为 also_on_xbrl_org / also_on_csri。每个查询过 CSRI 的响应都会带有 csri_status。
• 申报文件 ID 格式为 csri-<docId>-<docVersion>：csri-24777-1（Citadele banka FY2025）。published_at 是所提供文档版本的日期时间（里加时区）；重新提交的版本会使用新的 ID。
• 每份公告都会提交两次，分别为 EN 和 LV 文档，且 ID 不同。如果 EN 版本已提供文件包，则会跳过 LV 版本。与另一份文档内容逐字节相同的文件包会列在 duplicate_documents 下，而不会作为一行列出。只有拉脱维亚语文件包时（Longo、AST FY2025），该行即为拉脱维亚语报告。
• 类别 1.1 还包含新闻稿、未经审计的全年业绩和日历更正；还有几家发行人会提交未标记的 XHTML（Altum、Siguldas CMAS、Rīgas ūdens，以及 PN Project FY2025 的单独财务报表：这些是独立财务报表，ESEF 不要求为其添加标记）。这些内容列在 publications_without_inline_xbrl 下，不会作为行列出。
• 发行人的 LEI 位于 CSRI 详情页；该行的 LEI 仍优先取自内联 XBRL。

注意事项 23 — 卢森堡、斯洛文尼亚和爱沙尼亚仅进行实时查询，不做镜像，也不提供事实数据

这是这三个 OAM 的条款所决定的。LuxSE 要求事先取得书面同意，才能“传播、展示、出售或分发”其信息（付费的 Documents + Dissemination 许可涵盖此类用途）；SEOnet 禁止在未取得书面同意的情况下“以任何形式”将其数据用于商业用途或复制；爱沙尼亚 FSA 要求在复制或分发其网站上的内容前取得许可，但新闻报道和非营利用途除外。这三个机构都没有禁止自动访问。根据 CLAUDE.md 的 mirror-needs-grant-proxy-does-not 规则（舰队 #1389）：代表调用方按请求实时调用的是客户端，而非发布方，因此无需许可。存储后转售的副本——也就是上述其他监管机构所用的 R2 支持模式——才是这些条款实际限制的再分发行为。因此，这三家机构有意不配置 OamSpec/R2 索引：每次调用都会实时访问源站，仅保留按分钟计时的进程内缓存，不会写入任何存储。

仅实时查询、不做镜像所带来的后果：

• 仅查询已固定的国家/地区。 当 country 为 LU、SI 或 EE 时，esef_search_filings 才会尝试这三个来源——按开放的国家/地区名称搜索，不会每次调用都扩展到另外三个实时上游。esef_entity_filings 以前会对每个已解析的实体都尝试全部三个来源，不论其国家/地区；自 #2573（GOTCHA 25）起，它只调用与实体已知国家/地区相符的来源；如果国家/地区确实无法确定，则会退回尝试全部六个来源。
• 不提供事实数据。 对于这些来源，esef_filing_facts 不会打开 ESEF 套件——按设计，这里没有已转换的 xBRL-JSON。若传入实时查询的 fxo_id（luxoam-…、seonet-…、fi_ee-…），它会返回拒绝结果，附带 reason: "no_machine_readable_report"，并指向该行的 package_url/source_url，而不会抛出错误或猜测。
• 卢森堡（source: "luxoam"、luxoam_status）：graphqlaz.luxse.com 的 oamSubmissionsSearch（存档类型 10001 =「年度财务和审计报告」）会在服务器端接收 issuerName，因此带名称的 esef_entity_filings/esef_search_filings{entity_name} 调用会缩小上游查询范围，而不是先获取大量数据再过滤。仅当结果集范围较小且带有名称（≤10 行）时，才会获取下载令牌（oamSubmissionDetail → dl.luxse.com/dl?v=<token>）——不会用于广泛的国家/地区列表，以避免每行都调用一次详情接口。列表不包含 LEI（只有套件中的内联 XBRL 才包含，但本工具包不会打开套件），因此 LU 行的 entity_identifier 为 null。
• 斯洛文尼亚（source: "seonet"、seonet_status）：seonet.ljse.si 的 RSS 源（doc_type_id:1020）最多返回最近约 20 条年度/半年度报告公告，不受 max_results_special 参数影响——这是实时查询，不是完整列表。发行方名称取自 RSS 的 <author>/<category> 字段。该源未注明报告期，因此会从（斯洛文尼亚语）公告标题中的四位数年份推断 period_end，并标记 period_end_inferred: true——这是猜测，并非来源提供的事实。同一发行方在相同 pubDate 下的两条 RSS 条目（Krka 的 SL/EN 版本，均为 2026-04-09 06:15）其实是一份使用两个文档 ID 的申报，因此会合并为一行，并优先采用不带变音符号（看起来像英文）的标题；相隔至少一天的第二条公告（更正或后续公告）不会合并，可能会与对应的 xbrl.org/CMVM 风格记录相似，但其法定名称拼写不同——SEOnet 列表不包含 LEI，无法据此去重，因此这是仅依赖实时 RSS 查询所导致的已知且可接受的缺口，不应继续将其视为 bug 追查。
• 爱沙尼亚（source: "fi_ee"、fi_ee_status）：oam.fi.ee 的 category=57（「Majandusaasta aruanne」）列表会直接提供发行方、标题和提交日期；LEI 和期末日期则直接从详情页附件文件名（<LEI>-<period>-<lang>.zip）读取——不会打开套件本身。每次调用的详情获取次数（用于获取 LEI/套件链接）最多为 8 行。

GOTCHA 24 — 希腊和爱尔兰尽管禁止机器人，仍采用实时查询；保加利亚采用实时查询是为保持一致，而非因为它有此需要

情况与 GOTCHA 23 不同。Euronext Athens 和 Euronext 自身的使用条款不只是限制转载，还明确全面禁止「机器人或其他自动化方法」、抓取、爬虫和深层链接。2026-09-25/28 的调查（fleet #2434、#2493，以及一次同类型的爱尔兰调查）到此为止，因此没有为这两个国家/地区构建任何内容。Bruce 于 2026-09-30 在聊天中推翻了这一决定：「这两个也用代理。」 这两个来源仍会通过实时查询响应——按需获取，从不存储，并以礼貌的方式抓取（使用真实且可联系的 User-Agent，不轮换 IP，不伪造身份，低请求量，只使用本工具包中其他实时来源已有的进程内缓存）。如果任一网站开始主动拦截（403/CAPTCHA/机器人拦截页），不得绕过拦截——2026-09-30 时并未发生这种情况，当天尝试的所有礼貌请求均获成功响应。

• 仅查询指定国家，与 GOTCHA 23 相同：当 country 为 GR、IE 或 BG 时，esef_search_filings 才会尝试查询希腊、爱尔兰或保加利亚；过去，esef_entity_filings 会针对每个已解析实体尝试查询全部六个实时来源（本 GOTCHA 中的三个，加上 GOTCHA 23 中的三个），不论国家/地区如何——参见 GOTCHA 25：现在已按国家/地区限制，不再一概查询。
• 无事实数据，与 GOTCHA 23 相同：如果 esef_filing_facts 收到来自实时查询的 fxo_id（athex-…、oamie-…、beis-…），就会拒绝处理并返回 reason: "no_machine_readable_report"，改为指向 package_url/source_url。
• 希腊（source: "athex"、athex_status）：athens.euronext.com/en/market-data/financial-data 是无需密钥的服务器渲染页面（与该网站通用的“公告”搜索不同；后者只通过 Drupal Views AJAX 端点返回条目，而实时探测发现该端点不遵循文本或公司 ID 筛选条件——本工具包不会使用该端点）。field_mig_category=2 用于选择“Financial Statements ESEF”；field_mig_category_1=2 用于选择“Twelve months”——经实时验证，这些筛选条件会返回标题为 (<year>,Annual report,<Consolidated|Parent>) 或 (<year>,Year Statement,<scope>) 的条目，两者均为年度报告。按名称查询时，会将调用方提供的名称与页面自身的发行方选项列表（field_mig_category_3，该网站专用的数字 ID，不是 LEI 或股票代码）进行匹配；该列表作为公司目录，会在进程内缓存 6 小时，而不是像结果集那样缓存。如果名称与目录不匹配，则会退回到未筛选页面，逐条匹配其发行方名称。列表只注明报告年份，未注明确切的期末日期，因此 period_end 设为 <year>-12-31，并标记 period_end_inferred: true（与 GOTCHA 23 对斯洛文尼亚采用的日历财政年度假设相同）——页面也未注明 LEI，因此 entity_identifier 为 null。条目 ID 是从 ZIP 自身的下载路径中提取的 UUID（由于标题链接在不同条目中有时是 Drupal 节点 ID，有时是 slug 路径，因此两者都不用作 ID）。
• 爱尔兰（source: "oamie"、oamie_status）：direct.euronext.com/api/PublicAnnouncements/OAMs 是一个 JSON POST 接口。direct.euronext.com 的大部分内容受 Euronext 的 B2C 登录保护（已通过其自身的 /api/gate/configuration.js 确认），直接向此端点发送 POST 会返回 401；但同一 POST 若带上浏览器会发送的 Origin/Referer 请求头，则会以 200 响应，并返回真实的近期爱尔兰受监管公告。这是 CORS 检查，不是身份验证。请求体：{startDate, endDate, page, companyName, firstLetter}；companyName 会在服务器端缩小查询范围，与卢森堡的 issuerName 用法相同。条目会在客户端按 regulatoryCategory === "Annualfinancialandauditreports" 筛选——服务器端没有提供类别筛选条件。period_end 有意设为 null——与希腊和斯洛文尼亚不同，爱尔兰发行方的财政年度结束日期各不相同（Ryanair 的财政年度在 3 月 31 日结束，而不是 12 月 31 日）；因此从标题推断 <year>-12-31，对于一种常见的真实情况来说会是明显错误，而不只是精度不足。下载 URL（api/PublicAnnouncements/OAMDocument/<name>?id=<id>）也需要相同的 Origin/Referer 请求头。
• 保加利亚（source: "beis"、beis_status）：BEIS（beis.bia-bg.com）是保加利亚发行方用于披露信息的三个代理机构之一（调查 #2493）。另两个代理机构 x3news 和 infostock.bg 都禁止自动访问，因此从不调用；而 BEIS 的条款只要求注明来源，所以此处无需覆盖限制。其公开信息流（index.php?p=publicinfo）是一个很长且未筛选的单页，混合展示该平台所有发行方的各种公告；本工具包会在进程内缓存并获取此页面，然后自行查找发行方和 ESEF 文件包，因为信息流没有提供服务器端筛选条件。ESEF 年度文件包的文件名始终以 <20-char LEI>-<YYYYMMDD>-BG-<CON|SEP>.<zip|xhtml> 结尾，不受 LEI 前缀中股票代码内容的影响（已根据 BEIS 实际使用的全部三种文件名模式进行验证）；带 .p7m 后缀的文件是单独签名的封装文件，并非报告，因此会跳过。范围有限，这是有意为之：只有约三家发行方（Vipom AD - Vidin、KMM AD - Shumen、Nash Dom / HDOM）使用 BEIS 作为其代理机构，因此大多数保加利亚 ESEF 申报方都不会出现在这里——每次查询 beis_status 时，返回的说明都会指出这一点。

注意事项 25 — 只有当实体所属国家确实可能与之匹配时，esef_entity_filings 才会调用实时数据源

Fleet #2573，继 #2549 和 #2571 之后。在此之前，无论解析出的实体实际位于哪个国家，esef_entity_filings 都会并行调用注意事项 23 + 24 中的全部六个实时数据源（LU、SI、EE、GR、IE、BG）——查询芬兰实体时也会在后台向雅典、都柏林等地发送请求，这正是 CLAUDE.md 中 mirror-needs-grant-proxy-does-not 的判断要求保持低频、按请求发起，而不是一概而论的那类负载。

现在，只有在实体所属国家已知且匹配的情况下，才会调用这六个数据源：

• 当实体通过 filings.xbrl.org 或 R2 镜像的 OAM 解析出来时（注意事项 23/24 本身没有 R2 索引，但这个数据包中的其他所有国家都有），其所属国家已在刚获取的行中——xbrlRows 包含申报文件自身的 country 属性，oamRows 则包含 OAM 的固定国家。只有所属国家匹配的那个实时数据源（如果有）才会被调用；芬兰、西班牙、挪威等地的实体不会调用这六个数据源中的任何一个。
• 将 ISIN 作为 entity 传入时（2 位国家前缀 + 9 位字母数字 + 1 位校验码），同样会将其作为国家提示，即使尚未解析也适用——IE00BWT6H894 会直接指向爱尔兰。
• 确实无法确定所属国家时，仍会回退到全部六个数据源——如果普通公司名称无法解析到任何结果（filings.xbrl.org 无匹配、OAM 无匹配，也不符合 ISIN 格式），仍会按名称尝试所有实时数据源。这是唯一能让仅在爱尔兰/保加利亚存在的公司（从未出现在 filings.xbrl.org 上，也没有 R2 OAM）可被查询到的路径（保留了 #2571 的修复）。
• 未调用的数据源仍会返回状态块——available: false, skipped: true, reason: "not_applicable"——而不会悄然消失，因此调用方可以看到，例如 oamie_status 是被跳过了，而不是已经探测过爱尔兰但未找到结果。

数据源

• 索引：https://filings.xbrl.org/api/filings（JSON:API，标头 Accept: application/vnd.api+json）
• 实体：https://filings.xbrl.org/api/entities、…/api/entities/<identifier>/filings
• 报告：将根相对路径 json_url 解析为相对于 https://filings.xbrl.org 的 URL — xBRL-JSON（OIM），{documentInfo, facts}，通常为 500 KB–1 MB
• 葡萄牙：CMVM 年度账目披露（https://www.cmvm.pt），发行方发布的 ESEF 包，事实采用相同的 xBRL-JSON 格式
• 西班牙：CNMV 年度财务报告登记处（https://www.cnmv.es/portal/consultas/ifa/listadoifa.aspx?id=0&nif=<NIF>），发行方发布的 ESEF 包，以相同方式转换（scripts/esef-cmvm/collect_cnmv.py）
• 挪威：Oslo Børs NewsWeb 年报公告（https://api3.oslo.oslobors.no/v1/newsreader/list?category=1001，无需密钥），发行方附上的 ESEF 包，以相同方式转换（scripts/esef-cmvm/collect_newsweb.py）
• 瑞典：Finansinspektionen Börsinformation（https://finanscentralen.fi.se/search/SearchByRegistrationDate.aspx，文件 GetFile.aspx?fid=<N>），发行方发布的 ESEF 包，以相同方式转换（scripts/esef-cmvm/collect_fi.py）
• 比利时：FSMA STORI（https://webapi.fsma.be/api/v1/en/stori/result，无需密钥的 JSON；文件 …/stori/download?fileDataId=<uuid>），发行方发布的 ESEF 包，以相同方式转换（scripts/esef-cmvm/collect_fsma.py）
• 马耳他：马耳他证券交易所的 Officially Appointed Mechanism（仅提及名称，不提供链接：交易所条款禁止未经书面许可链接到其网站），发行方发布的 ESEF 包，以相同方式转换（scripts/esef-cmvm/collect_mse.py）。出于相同原因，马耳他条目不含 source_url / viewer_url。
• 克罗地亚：HANFA SRPI（https://www.hanfa.hr/Api/SRPI/GetData，无需密钥的表单 POST；文件 https://www.hanfa.hr/SRPI/<HR|EN>/<year>/<date>-<id>_zip.zip），发行方发布的 ESEF 包，以相同方式转换（scripts/esef-cmvm/collect_hanfa.py）。HANFA 声明，根据克罗地亚《信息获取权法》，任何用户均可将其信息用于商业或非商业目的
• 匈牙利：MNB Közzétételek（https://kozzetetelek.mnb.hu/search/advanced，HTML 表单；查看 …/kozzetetelek?viewid=K<n>/<year>；文件 …/downloadkozzetetel?id=<n>&did=K<n>/<year>），发行方发布的 ESEF 包，以相同方式转换（scripts/esef-cmvm/collect_mnb.py）
• 立陶宛：oam.lt，由 Nasdaq Vilnius 运营的立陶宛 OAM（https://oam.lt/，HTML 表单 POST，类别 171 = 年度财务报告；消息 /view/<messageId>；文件 /cns-web/oam/viewAttachment.action?messageAttachmentId=<N>），发行方发布的 ESEF 包，以相同方式转换（scripts/esef-cmvm/collect_oamlt.py）
• 罗马尼亚：ASF OAM（https://oam.asfromania.ro/oam/loadedPDFReportsForPublic.jsp，筛选条件保存在会话中的报告引擎：RFA 类型 1267 + 发布日期区间；每行上传内容位于 participants/loadedPDFReportsVersions.jsp；文件 /oam/DownloadPDFFile.do?nume_raportare=<name>），发行方发布的 ESEF 包，以相同方式转换（scripts/esef-cmvm/collect_asf.py）
• 塞浦路斯：塞浦路斯证券交易所公共 OAM（https://publicoam.cse.com.cy/xak-public-pages-server/api/fetch-listing-versions?informationCategoryId=16&registryTimestamp=<YYYY-MM-DD>，无需密钥的 JSON；文件以 base64 内嵌于 …/fetch-files?listingVersionId=<id>），发行方发布的 ESEF 包，以相同方式转换（scripts/esef-cmvm/collect_cse.py）
• 拉脱维亚：CSRI，由 Latvijas Banka 运营的拉脱维亚 OAM（https://csri.investinfo.lv/en/?view=csridocuments&doc_types[]=111，无需密钥的 GET，每页 20 条；详情 ?view=csridocumentsdetails&id=<docId>；文件 /?task=download&doc_id=<docId>&doc_version=<v>&f_id=<fileId>），发行方发布的 ESEF 包，以相同方式转换（scripts/esef-cmvm/collect_csri.py）
• 卢森堡（实时，GOTCHA 23）：LuxSE OAM（https://graphqlaz.luxse.com/v1/graphql，无需密钥的 GraphQL，oamSubmissionsSearch/oamSubmissionDetail；下载 https://dl.luxse.com/dl?v=<token>）—按请求获取，绝不镜像
• 斯洛文尼亚（实时，GOTCHA 23）：SEOnet（https://seonet.ljse.si/rss/default.aspx?...doc_type_id:1020...，无需密钥的 RSS，最多约 20 条）—按请求获取，绝不镜像
• 爱沙尼亚（实时，GOTCHA 23）：FSA 的 OAM（https://oam.fi.ee/et/borsiteated?category=57，无需密钥的 HTML 列表；详情页包含以 LEI 命名的附件）—按请求获取，绝不镜像
• 希腊（实时，GOTCHA 24）：Euronext Athens（https://athens.euronext.com/en/market-data/financial-data，无需密钥，由服务器渲染）—按请求获取，绝不镜像，尽管该网站的使用条款禁止机器人（Bruce，2026-09-30）
• 爱尔兰（实时，GOTCHA 24）：Euronext Dublin OAM（https://direct.euronext.com/api/PublicAnnouncements/OAMs，无需密钥的 JSON POST，带有一对 Origin/Referer）—按请求获取，绝不镜像，尽管 Euronext 的使用条款禁止机器人（Bruce，2026-09-30）
• 保加利亚（实时，GOTCHA 24）：BEIS（http://beis.bia-bg.com/index.php?p=publicinfo，无需密钥的 HTML 订阅源；文件位于 /pubinfo/ 下）—按请求获取，绝不镜像

快速开始

添加到你的 MCP 客户端（Claude Desktop、Cursor、Windsurf 等）：

{
  "mcpServers": {
    "esef-filings": {
      "url": "https://gateway.pipeworx.io/esef-filings/mcp"
    }
  }
}

此端点实际提供的内容

https://gateway.pipeworx.io/esef-filings/mcp 上的 tools/list 会返回上表中的工具，以及 Pipeworx 共享元工具——ask_pipeworx、 discover_tools、search_within、remember/recall 和网关范围内的其他工具。因此，你看到的工具数量会多于此表中的数量：目前，单个工具包端点除了列出该工具包自身的工具，还会列出大约 30 个共享工具。连接的 initialize 响应会说明其确切范围，也是当天范围的权威说明。

这是有意为之，并非意外的多路复用。元工具让范围受限的连接也能回答此工具包未涵盖的问题——通过 ask_pipeworx 路由到整个目录——而无需你再添加第二个 MCP 服务。目前无法挂载不包含这些元工具的工具包端点；如果额外的架构定义占用的上下文超过了路由带来的价值，请连接完整网关，而不是连接多个工具包端点。

或者连接完整的 Pipeworx 网关，直接获取所有工具包的工具，而不只是此工具包的工具：

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

两个 URL 都连接到同一个网关和相同的 1879+ 个数据源。唯一的区别是哪些工具包的工具会被直接列出；通过任一端点，ask_pipeworx 都可以访问所有工具。

没有 MCP 客户端？通过 HTTP 调用

curl -X POST https://gateway.pipeworx.io/v1/tools/esef_search_filings \
  -H 'Content-Type: application/json' \
  -d '{"entity_name":"Citycon","country":"FI"}'

首次调用无需账户。查看任意工具：GET https://gateway.pipeworx.io/v1/tools/esef_search_filings。查找工具包：使用 {"query":"..."} 向 https://gateway.pipeworx.io/v1/tools/search_packs 发送 POST 请求。

独立运行（无需网关账户）

此软件包也可作为本地 stdio MCP 服务运行——无需 Pipeworx 账户，也无需往返网关：

{
  "mcpServers": {
    "esef-filings": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-esef-filings"]
    }
  }
}

或者直接运行它，确认其能启动：

npx -y @pipeworx/mcp-esef-filings

它通过 stdin/stdout 使用 MCP 通信，并响应 initialize/tools/list/tools/call，但仅包含此工具包的工具——不包含上述网关连接额外提供的任何共享元工具。使用相同的源代码和工具，但没有 ask_pipeworx 路由。

使用 ask_pipeworx

你可以用简单的英文提问，而不是直接调用工具——这既适用于上面的工具包端点，也适用于完整网关：

ask_pipeworx({ question: "your question about Esef Filings data" })

网关会自动选择合适的工具并填入参数。

更多信息

• 文档和指南
• pipeworx.io

许可证

MIT