# A股历史时点财务数据 / A-Share Historical Point-in-Time Financials

## REST 调用

`GET /api/v1/pit/financials`

请求头使用现有 FFD API Key。主要参数：

- `codes`: 标准 A 股代码，多个代码用英文逗号分隔，单批最多 300 只。
- `report_periods`: 报告期，格式 `YYYY-MM-DD`，支持多个季度末日期。
- `fields`: `revenue_yoy,net_profit_yoy,gross_margin`。第一阶段不把派生的 `financial_roe_ttm` 晋升为正式 PIT。
- `as_of`: 市场公开时间截止点。必须使用带时区的 ISO 8601 时间，只返回该时点及之前已由官方公开的报告版本。
- `recorded_before`: FFD 采入时间截止点，可选 ISO 8601 时区时间；与 `as_of` 分开。
- `validation_generation`: `strict`（默认）或 `legacy`；单次请求不混合两代数据。
- `coverage_policy`: `strict`、`return_available` 或 `coverage_only`。
- `decision_use`: 决策用途建议传 `true`，只允许完整证据事实。

示例：

```http
GET /api/v1/pit/financials?codes=600519.SH&report_periods=2025-03-31&fields=revenue_yoy,net_profit_yoy,gross_margin&as_of=2025-04-30T23:59:59%2B08:00&decision_use=true&validation_generation=strict&coverage_policy=return_available
Authorization: Bearer <FFD_API_KEY>
```

## 字段口径

- `revenue_yoy`: 单季度营业收入同比，统一语义为 `single_quarter_operating_revenue_yoy_pct`，不是年初至报告期末累计同比。
- `net_profit_yoy`: 单季度归属于母公司股东净利润同比，统一语义为 `single_quarter_parent_net_income_yoy_pct`。
- `gross_margin`: 报告期累计毛利率，统一语义为 `cumulative_gross_margin_pct`。
- 对外仅使用上述 FFD 通用字段名，不暴露或依赖 数据源专用字段名。单季度同比必须由官方季报直接披露，或由同口径官方累计金额按相邻报告期差分复算；两条路径都不满足时保持缺失或隔离。

## MCP / SDK

继续使用兼容工具 `ffd_financial_metrics`，传入 `codes`、`report_date`、`metrics` 和时点参数。直接 REST PIT 与 MCP 财务工具使用同一正式资产和同一基本面额度池。

## 计费

- 用户额度池：`fundamental`（基本面），不扣行情额度池。
- 扣点单位：每个实际返回的“证券 × 报告期”记录 1 点，同一记录请求多个已支持字段不重复计点。
- `coverage_only` 成功返回时，按请求的证券×报告期覆盖记录从基本面额度池扣点，不再免费。
- `strict` 完整交付时按实际交付的证券×报告期记录从基本面额度池扣点；存在任一缺失、冲突或证据不完整时整单失败关闭，扣点为 0。
- `return_available` 只按实际返回的证券×报告期记录从基本面额度池扣点，并同时披露缺失原因。
- 正式 PIT/缓存命中仍按用户产品规则扣点，但不会消耗新的上游点数。
- 空结果、来源失败、身份冲突、修订分支冲突和日志写入失败均不得形成净扣点。

## 证据边界

正式事实必须同时具备请求绑定的正向上游租约、持久化原始资产、官方原文哈希、官方公开时间、完整且无分支冲突的修订关系，以及数值核验。多版本或冲突报告保持隔离，不自动选择分支。

## 验证代次与兼容规则

- `validation_generation=strict` 为默认值，返回按严格证据门禁验证的事实。
- `validation_generation=legacy` 仅用于历史兼容，必须显式指定。
- 单次请求不会混合 `strict` 与 `legacy`；缺口不以 legacy 值自动填充 strict 结果。
- `coverage.breakdown` 按年份、季度、字段和验证代次返回覆盖记录计数；不应将该计数解读为通过验证的事实数。
- 数据集整体仍标记为 `partial`。