嵌入接口清单

概述

/api/embed/** 是 Sight Report 面向第三方系统开放的一组接口。这些接口不使用平台登录态（satoken），而是使用两种嵌入认证方式之一：

所有接口的响应统一为 {"code":200,"success":true,"message":"...","data":...} 的信封（导出类接口直接返回文件流）。

注意：每个客户端 IP 对 /api/embed/** 的请求上限为每分钟 120 次，超出返回 HTTP 状态 429，提示「请求频率超限，请稍后再试」。

功能入口

• 接口所属的应用在 系统 > 三方集成 中创建，参见三方集成应用。
• 「三方集成」页面的应用详情里带有各场景的调用说明与多语言代码样例，可与本文对照。

接口一览

以下示例中的变量沿用签名免登里的脚本。先定义一个生成 _s 的函数：

BASE=https://your-domain
APP_ID=erp-system
SECRET='在三方集成页面保存的 appSecret'

# 用法：make_s <account> <userName> <reportId，可为空>
make_s() {
  local EXPIRE=$(( $(date +%s) + 600 ))
  local SIGN=$(printf '%s' "$APP_ID|$1|$2|$3|$EXPIRE" \
    | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $NF}')
  printf '{"appId":"%s","account":"%s","userName":"%s","reportId":"%s","expireAt":%s,"signature":"%s"}' \
    "$APP_ID" "$1" "$2" "$3" "$EXPIRE" "$SIGN" | base64 | tr -d '\n=' | tr '+/' '-_'
}

报表查询接口

三个接口都用 _s 认证，签名里的 reportId 可以为空。如果应用配置了「允许访问的报表」白名单，且签名里带了 reportId，该 reportId 必须在白名单内，否则返回「无权访问该报表」。

获取目录树

GET /api/embed/report/type-tree

data 是树形数组，节点包含 id、parentId、name、fileType、version、description、createTime、updateTime、creatorName、updaterName、tags，有子节点时带 children。

S=$(make_s zhangsan 张三 "")
curl -s "$BASE/api/embed/report/type-tree?fileType=grid&_s=$S"

按标签查询报表

GET /api/embed/report/tag-list

data 为报表数组，字段同目录树节点。

curl -s "$BASE/api/embed/report/tag-list?tag=%E6%9C%88%E6%8A%A5&_s=$S"

读取报表参数定义

GET /api/embed/report/parameters

data 结构：

三方自建查询表单时，可先读取参数定义，再把用户填写的值通过嵌入链接的 parameters 传给报表，见报表嵌入。

S=$(make_s zhangsan 张三 rpt_sales)
curl -s "$BASE/api/embed/report/parameters?reportId=rpt_sales&_s=$S"

后端直接导出

服务端可以不打开页面，直接下载导出文件。

GET /api/embed/export/{pdf|excel|word|csv|ofd}

使用 _s 时有两条规则：

1. 签名里的 reportId 必须非空，并与请求的 fileId 完全一致，否则返回「签名中的 reportId 与请求的 fileId 不匹配」。
2. 签名有效期内该链接可重复使用，服务端不保存会话。

S=$(make_s zhangsan 张三 rpt_sales)
curl -s -o sales.pdf \
  "$BASE/api/embed/export/pdf?fileId=rpt_sales&_s=$S&parameters=%7B%22dept%22%3A%22%E5%86%85%E7%A7%91%22%7D"

上例的 parameters 解码后是 {"dept":"内科"}。

大数据量 Excel 异步导出

浏览器嵌入页面在数据量大时使用异步任务：先创建任务，轮询状态，完成后下载。以下三个接口使用会话头认证。

1. 创建任务：POST /api/embed/export/excel，请求体 {"fileId":"...","fileVersion":"","parameters":"{\"dept\":\"内科\"}","fileName":"..."}。其中 parameters 是 JSON 字符串。
2. 查询状态：GET /api/embed/export/excel/task/{taskId}。
3. 下载：GET /api/embed/export/excel/download/{taskId}。

任务对象字段：taskId、status（pending、processing、completed、failed）、downloadUrl、fileName、progress、errorMsg、createTime、completeTime。任务只能由创建它的会话查询和下载。

curl -s -X POST "$BASE/api/embed/export/excel" \
  -H "X-Embed-Session: $TOKEN" -H 'Content-Type: application/json' \
  -d '{"fileId":"rpt_sales","parameters":"{}"}'

外部数据集

把宿主系统的数据推送给报表使用，适用于报表里配置了「外部数据集」的场景。配置方式见外部数据集。

上传

POST /api/embed/staged-dataset/set，请求体：

成功时 data 为 {"token":"...","datasetNames":["ds1"]}。数据总大小默认上限 5 MB，保留时间默认 24 小时（配置项 app.staged-dataset.max-payload-size、app.staged-dataset.ttl-hours）。使用时在嵌入链接或导出的 parameters 里加入 "_dataIds": "<token>"。

S=$(make_s zhangsan 张三 "")
curl -s -X POST "$BASE/api/embed/staged-dataset/set" \
  -H 'Content-Type: application/json' \
  -d "{\"signature\":\"$S\",\"datasets\":{\"ds1\":[{\"dept\":\"内科\",\"cnt\":12}]}}"

清除

POST /api/embed/staged-dataset/clear，请求体 {"signature":"...","token":"..."}。只能清除同一应用创建的 token，否则返回「未找到对应的数据集或无权清除」。

会话管理

curl -s "$BASE/api/embed/session/validate" -H "X-Embed-Session: $TOKEN"
curl -s -X POST "$BASE/api/embed/session/logout" -H "X-Embed-Session: $TOKEN"

会话访问报表时受范围限制：只能访问签名锚定的报表，以及从它出发经「嵌入报表」区块或单元格报表链接可达的报表，其他报表返回 403「无权访问该报表」。

读取模板正文

GET /api/embed/report-file/source?reportId=<id>[&fileVersion=<版本>]，需要会话头，且会话对该报表有权限。返回已发布的报表模板。前端嵌入页面使用此接口加载报表，第三方一般不需要直接调用。没有会话或越权时返回 403「无权查看该报表」。

续打接口

/api/embed/print/* 用于单据续打场景下宿主系统接管打印进度，支持 _s 或会话头认证：

reset 和 manual-set 需要在「三方集成」应用中开启「续打进度管理」开关（应用字段 allowPrintReset，默认关闭），未开启时返回 403。续打的报表设置见套打对位。

常见错误

相关文档

• 签名免登
• 三方集成应用
• 报表嵌入
• 宿主事件与方法调用
• 报表公开链接
• 外部数据集