§ API REFERENCE

签发报告免登 token

POST/executions/{id}/report-accessscope: reports:read

为某执行已 READY 的报告签发免登访问凭证，可选择 JSON 投影或平台托管模板页面。

鉴权：Authorization: Bearer <access_token>。

§ 1

请求信息

REQUEST

POST https://api.lingxiguangnian.com/api/open/v1/executions/{id}/report-access

请求头

参数	类型	必填	说明
`Authorization`	string	是	Bearer <access_token>。由 POST /token 换取，有效期 2 小时；api_secret 不得直连业务端点（→ 401）。

路径参数

参数	类型	必填	说明
`id`	uuid	是	执行 ID。

请求体参数

参数	类型	必填	说明
`delivery_mode`	json \| hosted_view	否	交付方式，默认 json；只影响入口，不改变报告已冻结的模板版本。
`ttl_seconds`	number	否	token 有效期（默认 7d，上限 30d）。
`max_uses`	number	否	最大使用次数（缺省=窗口内不限次）。

§ 2

调用示例

EXAMPLES

POST /executions/{id}/report-access

curl -X POST "https://api.lingxiguangnian.com/api/open/v1/executions/9b8e0c2a-3d4f-4a5b-8c6d-7e8f9a0b1c2d/report-access" \
  -H "Authorization: Bearer oat_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" -d '{ "delivery_mode": "hosted_view", "ttl_seconds": 3600 }'

§ 3

返回结果

RESPONSE

返回字段

参数	类型	必填	说明
`access_token`	string	是	报告免登 token（仅此一次）；JSON 模式作 Bearer 调 view-data，页面模式已置于 viewer_url 的 #fragment。
`report_status`	string	是	READY。
`access_url`	string	是	机器消费状态端点路径，兼容保留。
`content_url`	string \| null	是	delivery_mode=json 时的 PII-safe 内容端点。
`viewer_url`	string \| null	是	delivery_mode=hosted_view 时的模板化报告页面；token 位于 #fragment。

RESPONSE · JSON

{ "success": true, "data": { "report_access_token_id": "...", "access_token": "rt_xxxxxxxx", "report_id": "...", "report_kind": "item", "report_status": "READY", "expires_at": "...", "access_url": "/api/open/v1/report-access/session", "delivery_mode": "hosted_view", "content_url": null, "viewer_url": "https://api.lingxiguangnian.com/report-access/view/...#rt=rt_xxxxxxxx" } }

§ 4

端点错误码

ERRORS

通用鉴权、scope 与限流错误见「使用概述」；下表为本端点专属错误。

HTTP	error_code	触发条件
409	`open_api.report_not_ready`	报告未生成 / 不可访问。
404	`open_api.execution_not_found`	执行不存在或不属本 APP。

使用说明

报告 token 与业务 access_token 不同；不要写入日志。
hosted_view 使用报告生成时冻结的机构业务模板，不会在访问时重新套用机构当前默认模板。
viewer_url 的明文 token 位于 #fragment，不进入服务端请求路径、查询参数或 Referer。

契约真源：apps/m-master/src/app/api/open/v1/executions/[id]/report-access/route.ts