§ API 指引

使用概述

开放平台以标准 HTTP 接口对外提供能力。所有业务端点均在统一基址下，使用 client_credentials 两步鉴权，无需安装 SDK。

小程序业务域名、APP WebView 与摄像头权限的完整配置步骤，见终端配置。

灵犀光年开放平台提供标准的 HTTP API，正式覆盖AI 测评、量表测评、综合方案与六维画像四类托管产品。典型用法：发现机构已授权的能力 → 为终端用户创建一次执行 → 签发免登作答入口 → 轮询完成后获取 PII-safe 报告。完整端点契约以控制台内「API 文档」为准。

§ 1

API 端点

ENDPOINT

开放平台业务端点的统一基址如下，下文所有路径均相对此基址：

https://api.lingxiguangnian.com/api/open/v1

调用前提：需先在控制台「密钥申请」创建应用、勾选所需 scope，并经渠道审核通过，获取 app_key 与 api_secret（secret 仅在创建时展示一次）。

§ 2

身份验证

AUTHENTICATION

鉴权分两步。第一步用 api_secret 换取短期 access_token（有效 2 小时）；此后所有业务端点只认 access_token。

换 token 时凭据放在请求头（x-app-id + Authorization: Bearer <api_secret>），业务端点则携带 access_token：

Authorization: Bearer <access_token>

api_secret 只在服务端用于换 token，绝不进入前端、作答页面、URL、查询参数或日志；误用 api_secret 直连业务端点会返回 401。access_token 临近过期前再换取，服务端缓存复用。

§ 3

权限 Scope

SCOPE

应用按需申请 scope，实际授予为 申请 ∩ 渠道允许；token 仅携带已授予的 scope，端点超出授予范围返回 403。

Scope	说明
`capabilities:read`	查询本机构可调用能力目录。
`executions:read`	查询执行记录。
`executions:write`	创建执行；取消未完成执行并释放冻结点数。
`reports:read`	读报告状态 / 签发报告免登 token。
`runtime:launch:write`	签发免登 runtime launch token（终端用户作答）。
`usage:read`	读侧用量对账。
`webhook:manage`	自管理 webhook 订阅 + 查事件投递。

§ 4

接入流程

QUICKSTART

一次完整的「能力发现 → 创建执行 → 免登作答 → 获取报告」接入，按以下七步推进：

1创建应用 + 获取凭据
在「密钥申请」创建 APP、选申请 scope；渠道审核通过后签发 api_secret（仅展示一次）。
2服务端换 access_token
POST /token（x-app-id + Bearer secret，grant_type=client_credentials）→ access_token（2h）。secret 仅此处用。
3发现四类产品
GET /capabilities → 选择 AI 测评、量表测评、综合方案或六维认知，读取 resource_type/resource_id 与点数价格。
4创建执行
POST /executions（resource_type + resource_id + external_user_id + Idempotency-Key）→ execution_id，并按目录价冻结点数。
5终端用户免登完成服务
POST /runtime/launch-tokens（execution_id）→ entry_url；终端用户无需平台账号即可完成托管式服务。
6轮询执行 + 报告状态
GET /executions/{id} 轮询到 COMPLETED；GET /executions/{id}/report 到 READY。
7获取报告
POST /executions/{id}/report-access 签发报告免登 token → GET /report-access/view-data 取 PII-safe 报告投影。
8接收状态通知
POST /webhook-endpoints 创建订阅并保存一次性 signing_secret；按签名指南验签和事件ID幂等。
9用量与容量对账
GET /usage-records 核对逐笔结算；GET /credit-balance 监控机构供应积分容量。

§ 5

调用示例

EXAMPLES

下例展示鉴权两步（换 token → 用 token 查询能力目录）。点击右上角可复制代码：

QUICKSTART · token → capabilities

# 1. 服务端用 api_secret 换 access_token（secret 仅出现在这里）
curl -X POST "https://api.lingxiguangnian.com/api/open/v1/token" \
  -H "x-app-id: app_xxxxxxxx" \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "grant_type": "client_credentials" }'

# 响应
# {
#   "success": true,
#   "data": {
#     "access_token": "oat_xxxxxxxxxxxxxxxxxxxxxxxx",
#     "token_type": "Bearer",
#     "expires_in": 7200,
#     "scope": "capabilities:read executions:write reports:read runtime:launch:write"
#   }
# }

# 2. 用 access_token（不是 secret）查询能力目录
curl "https://api.lingxiguangnian.com/api/open/v1/capabilities" \
  -H "Authorization: Bearer oat_xxxxxxxxxxxxxxxxxxxxxxxx"

§ 6

响应信封

ENVELOPE

所有端点使用统一响应信封。失败时请按 error_code 分流，不要依赖可能调整的错误文案。

RESPONSE · JSON

// 成功
{ "success": true, "data": { /* 业务数据 */ } }

// 失败
{ "success": false, "error": "通用提示", "code": 403, "error_code": "open_api.scope_denied" }

§ 7

通用错误码

ERRORS

HTTP	error_code	触发条件
401	`open_api.unauthorized`	access_token 缺失 / 无效 / 过期 / 已撤销 / app 非 ACTIVE；或误用 api_secret 直连业务端点（不区分子原因，防探测）。
403	`open_api.scope_denied`	token 授予 scope 不含该端点所需 scope。
403	`open_api.tenant_binding_violation`	归属与 APP 绑定机构不一致（INV-0）。
429	`open_api.rate_limited`	命中限流（/token 与写端点）；按 Retry-After 重试。

§ 8

最佳实践

BEST PRACTICES

api_secret 只在服务端用于 POST /token；绝不进前端、Runtime 页面、URL、日志、版本库。
服务端缓存 access_token 并在临近过期（2h）前重新换取，避免每请求都调 /token。
所有写操作带 Idempotency-Key（16-256 字符）；同键重放返回首次结果，不重复扣额度。
命中 429 时读 Retry-After 退避重试；不要无退避狂刷。
Webhook 接收端按 X-Mbc-Webhook-Signature 验签（HMAC-SHA256 + timestamp + nonce）后再处理。
目录只返回具备当前价格且可托管运行的四类产品；所有返回项 launchable=true。