请求流程

了解 Developer API 的完整数据处理流程。

概览

客户端                    税鹰眼 API                    后端服务
  │                            │                              │
  │─── POST /reports/financial ──→│                              │
  │                            │── 校验数据格式 ──────────────→│
  │                            │← 返回 task_id (202) ─────────│
  │←── { task_id, status } ────│                              │
  │                            │                   ┌──────────┤
  │                            │                   │ 异步处理  │
  │                            │                   │ - 数据入库│
  │                            │                   │ - 财务分析│
  │                            │                   │ - 风险评估│
  │                            │                   └──────────┤
  │─── GET /tasks/{task_id} ───→│                              │
  │←── { status: "success" } ──│                              │
  │                            │                              │
  │─── GET /reports/{id}/analysis →│                              │
  │←── { items: [...] } ───────│                              │

处理阶段

1. 数据提交（同步）

请求： POST /api/v1/developer/reports/financial

校验请求体结构与字段格式
校验通过后创建异步任务
立即返回 202 Accepted + task_id

2. 异步处理

提交成功后，系统在后台执行：

数据入库 — 将财务数据规范化存储
财务分析 — 执行各维度的指标计算
风险评估 — AI 模型进行风险判断
报告生成 — 汇总分析结果生成报告

3. 状态轮询

请求： GET /api/v1/developer/tasks/{task_id}

任务状态流转：

状态	说明
`processing`	处理中
`success`	完成，可读取分析结果
`failed`	失败，查看 `error_message`

轮询建议

建议轮询间隔：首次 2 秒，之后每次间隔翻倍（最大 30 秒）。也可使用 Webhook 接收完成通知（即将支持）。

4. 获取结果

请求： GET /api/v1/developer/reports/{report_id}/analysis

返回所有分析维度的结果数据。也可通过 slug 获取单项：

GET /api/v1/developer/reports/{report_id}/analysis/{slug}

幂等性

提交相同数据会创建新的独立报告（非幂等）
读取操作均为幂等（GET 请求安全重试）

超时与重试

操作	建议超时	重试策略
数据提交	30s	网络错误重试，4xx 不重试
状态查询	10s	自动重试
结果读取	15s	自动重试

概览​

处理阶段​

1. 数据提交（同步）​

2. 异步处理​

3. 状态轮询​

4. 获取结果​

幂等性​

超时与重试​

概览