快速开始
本指南帮助你在 5 分钟内完成首次 API 调用。
前置条件
- 拥有税鹰眼数据开放平台账号
- 已创建 API 密钥（在控制台 → 开放平台 → 凭证管理）
第一步：获取 API Key
登录后前往 开放平台 → 凭证管理，创建一个新的 API Key。密钥格式如下：
ek_live_xxxxxxxxxxxxxxxxxxxx # 生产环境
ek_test_xxxxxxxxxxxxxxxxxxxx # 测试环境
安全提醒
API Key 仅在创建时显示完整内容，请妥善保管。如果泄露，请立即在控制台撤销。
第二步：提交财务数据
使用 POST /api/v1/developer/reports/financial 提交结构化数据。
请求说明：
accounting_standard：small_enterprise（小企业准则）、general_new（一般准则·新）、general_old（一般准则·原）years_data：至少提供连续两个年份的数据，year_end > year_start- 每年至少提供
balance（资产负债表）和income（利润表）；cash_flow可选
curl -X POST https://api.shuiyingyan.com/api/v1/developer/reports/financial \
-H "Content-Type: application/json" \
-H "X-API-Key: ek_test_your_key_here" \
-d '{
"enterprise_name": "示例科技有限公司",
"accounting_standard": "general_new",
"year_start": 2023,
"year_end": 2024,
"years_data": [
{
"year": 2023,
"sheets": [
{
"sheet_type": "income",
"items": [
{"item_name": "revenue", "current_year_amount": "8500000.00", "last_year_amount": "7200000.00"},
{"item_name": "operating_cost", "current_year_amount": "6200000.00", "last_year_amount": "5400000.00"}
]
},
{
"sheet_type": "balance",
"items": [
{"item_name": "total_assets", "ending_balance": "22000000.00", "beginning_balance": "18000000.00"},
{"item_name": "cash_and_equivalents", "ending_balance": "4200000.00", "beginning_balance": "3500000.00"}
]
}
]
},
{
"year": 2024,
"sheets": [
{
"sheet_type": "income",
"items": [
{"item_name": "revenue", "current_year_amount": "10000000.00", "last_year_amount": "8500000.00"},
{"item_name": "operating_cost", "current_year_amount": "7000000.00", "last_year_amount": "6200000.00"}
]
},
{
"sheet_type": "balance",
"items": [
{"item_name": "total_assets", "ending_balance": "25000000.00", "beginning_balance": "22000000.00"},
{"item_name": "cash_and_equivalents", "ending_balance": "5000000.00", "beginning_balance": "4200000.00"}
]
}
]
}
]
}'
响应示例（HTTP 202 Accepted）：
{
"report_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"enterprise_id": "ent_示例科技有限公司",
"version_no": 1,
"status": "pending",
"share_url": null,
"validation_warnings": [],
"message": "报告创建任务已提交"
}
保存返回的 report_id，用于后续查询。
第三步：轮询报告状态
使用 report_id 查询报告创建进度（通常几秒到几十秒）：
curl https://api.shuiyingyan.com/api/v1/developer/reports/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
-H "X-API-Key: ek_test_your_key_here"
status 状态说明：
| 状态 | 含义 |
|---|---|
pending | 报告生成中，请稍后轮询 |
success | 报告生成完成，可获取分析结果 |
failed | 生成失败，查看 error_message 了解原因 |
当 status 为 "success" 时，响应中会包含 share 字段：
{
"report_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "示例科技有限公司",
"status": "success",
"share": {
"is_public": true,
"share_token": "abc123xyz",
"share_url": "/shared/reports/abc123xyz",
"share_expires_at": null
}
}
分享链接
share_url 是报告的公开分享链接路径。拼接上平台域名即可直接在浏览器中打开，查看包含图表、指标、AI 解读的完整网页版分析报告，无需 API Key 即可访问。
例如：https://app.shuiyingyan.com/shared/reports/abc123xyz
第四步：获取分析结果
当 status 为 "success" 时，获取全部分析数据：
curl https://api.shuiyingyan.com/api/v1/developer/reports/a1b2c3d4-e5f6-7890-abcd-ef1234567890/analysis \
-H "X-API-Key: ek_test_your_key_here"
响应示例：
{
"report_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"total": 5,
"items": [
{
"slug": "profitability",
"label": "盈利能力",
"sp_result": { "gross_margin": 0.30, "net_margin": 0.12 },
"risk_items": [],
"ai_content": "该企业近两年毛利率稳定在 30% 左右...",
"cached_at": "2024-01-15T10:30:00Z"
}
]
}
也可单独获取某项分析（通过 slug）：
curl https://api.shuiyingyan.com/api/v1/developer/reports/{report_id}/analysis/profitability \
-H "X-API-Key: ek_test_your_key_here"