以下为本页可直接引用的结论要点，均来自正文对应章节的详细论证。
结论：DravenAI 对外提供一套基于 HTTPS 的 RESTful 接口，所有能力都通过「网关鉴权 → 路由到业务服务 → 返回统一结构响应」三步完成，另外以 Webhook 形式向业务系统主动推送事件。理解统一响应结构是读本文档的前提：所有接口都返回 code、message、requestId、data 四个顶层字段，业务数据一律放在 data 中。
在管理后台创建应用，拿到 API Key 与 Secret；需要代表用户操作时改用 OAuth2 授权码流程拿到访问令牌。
按接口文档拼装路径、查询参数与请求体，请求头携带凭证与签名，内容类型为 application/json。
先看 code 判断成败，成功取 data；失败按错误码分类处理，并记录 requestId 以便追溯。
{
"code": 0,
"message": "ok",
"requestId": "req-8f3c9a1b2d",
"data": { "...": "业务数据" }
}约定：code 为 0 表示成功，非 0 表示业务或系统错误；message 为中文提示，用于日志与排障，不建议直接展示给终端用户；requestId 贯穿全链路，提交工单时请一并提供。
结论：字段命名统一为小驼峰，时间统一为带时区偏移的字符串，金额与比率统一用十进制字符串传输，布尔与数值不使用字符串包装。客户端解析时应当忽略未知字段、容忍字段顺序变化，这样服务端新增字段时不会破坏既有集成。
| 约定项 | 规则 | 示例 | 说明 |
|---|---|---|---|
| 时间格式 | RFC 3339，带时区偏移 | 2026-09-30T10:12:33+08:00 | 避免使用时间戳与本地时间字符串混用，防止时区错位 |
| 标识符 | 字符串类型，带业务前缀 | asset-20260930、u-10086 | 不要用自增数字，便于跨系统定位与日志检索 |
| 空值处理 | 不返回不存在的键，或显式返回 null | tags: null | 客户端需同时兼容两种情形，不可假设字段必然存在 |
| 枚举值 | 小写英文单词，下划线分隔 | content、in_progress | 新增枚举值属于兼容变更，客户端需有默认分支 |
| 列表排序 | 由 sort 与 order 参数指定 | sort=createdAt&order=desc | 不指定时使用接口默认排序，默认排序不保证跨版本稳定 |
字符集统一为 UTF-8，请求体不做压缩；若单次请求体超过 1 MB，应改用批量接口拆分或改用直传方式，避免网关因请求体过大直接拒绝。分页相关字段在所有列表接口中保持同名同义，便于客户端封装统一的翻页逻辑。
结论：服务端对服务端的集成用 API Key；需要代表具体用户操作、且用户需感知授权范围时用 OAuth2；对安全要求更高或无法使用 TLS 双向认证的场景追加请求签名。三者可以叠加，典型组合是「OAuth2 令牌 + 签名」。
| 认证方式 | 适用场景 | 凭证有效期 | 安全要点 |
|---|---|---|---|
| API Key + Secret | 后台任务、定时同步、服务端集成 | 长期有效，支持手动吊销与轮换 | Secret 只用于生成签名，不得随请求传输；Key 需按环境隔离 |
| OAuth2 授权码 | 需要以用户身份操作、涉及用户数据权限 | 访问令牌较短（小时级），刷新令牌较长 | 回调地址需白名单；令牌按最小权限范围申请 |
| 请求签名（HMAC） | 金融、政务等高安全要求场景，或公网调用 | 每次请求生成，含时间戳与随机数防重放 | 服务端允许的时间偏差通常为 5 分钟；随机数需做短时去重 |
POST /openapi/v1/assets HTTP/1.1
Host: api.panlongshi.com
Content-Type: application/json
X-PLS-Api-Key: pls_live_xxxxxxxxxxxxxxxx
X-PLS-Timestamp: 1780000000
X-PLS-Nonce: 6f1c2e9a
X-PLS-Signature: base64(hmac_sha256(secret, method + path + timestamp + nonce + body_hash))
X-PLS-Tenant: tenant-001说明：上例中的域名 api.panlongshi.com 为示例占位，实际地址以部署环境的网关域名为准；签名串的拼接顺序、是否包含查询参数由服务端版本约定，接入前请在联调环境用官方 SDK 校对一次签名结果。
GET /openapi/v1/assets?page=1&pageSize=20 HTTP/1.1
Host: api.panlongshi.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
X-PLS-Tenant: tenant-001令牌过期时接口返回 401 与对应错误码，此时应使用刷新令牌换取新访问令牌；若刷新令牌也失效，需要重新走授权流程。禁止在前端页面或客户端代码中保存 Secret。
结论：接口遵循资源导向的 RESTful 风格——用名词复数表示资源集合，用 HTTP 方法表达动作，用路径参数定位单个资源，版本号放在路径中。违反这些约定最直接的后果是缓存、网关路由与权限校验都会失效。
结论：开放接口按业务域分为五组——资产上传与检索、知识库问答、权限与组织、看板数据、Webhook 回调。下表是每组的高频接口，参数表中「必填」列标注 M 的字段缺失将直接返回参数错误。
资产是四大资产域（内容、知识、应用、业务）的统一载体，上传走「预申请 → 直传 → 确认」三段式，避免大文件经过应用服务器造成带宽与内存压力。domain 参数决定资产归入哪个域，可选值通常为 content、knowledge、application 与 business，写入后不可直接更改，只能走资产转移流程。
上传确认后资产进入处理流程，状态依次为 uploaded、processing、indexed、published，处理失败则置为 failed 并在响应中给出原因。检索能力依赖索引完成，因此创建后立刻检索可能查不到结果：正确做法是轮询资产详情的 status 字段，或订阅 asset.indexed 事件，而不是用固定延时等待。批量导入场景建议走异步任务接口，避免同步接口因超时中断。
| 方法 | 路径 | 说明 | 关键参数 | 主要响应字段 |
|---|---|---|---|---|
| POST | /openapi/v1/assets/upload-token | 申请上传凭证与直传地址 | fileName(M)、size(M)、domain(M)、md5 | uploadUrl、objectKey、token、expireAt |
| POST | /openapi/v1/assets | 确认上传并创建资产条目 | objectKey(M)、title(M)、domain(M)、tags、ownerId | assetId、version、status、createdAt |
| GET | /openapi/v1/assets | 按条件检索资产列表 | keyword、domain、tags、page、pageSize | list、total、page、pageSize |
| GET | /openapi/v1/assets/{assetId} | 获取资产详情与版本信息 | assetId(M)（路径参数）、withVersion | assetId、title、metadata、versions、permissions |
# 示例：申请上传凭证（域名与凭证为占位）
curl -X POST "https://api.panlongshi.com/openapi/v1/assets/upload-token" \
-H "Content-Type: application/json" \
-H "X-PLS-Api-Key: pls_live_xxxxxxxxxxxxxxxx" \
-H "X-PLS-Timestamp: 1780000000" \
-H "X-PLS-Nonce: 6f1c2e9a" \
-H "X-PLS-Signature: <签名占位>" \
-d '{"fileName":"产品白皮书.pdf","size":2097152,"domain":"content","md5":"<文件MD5占位>"}'问答接口支持同步返回与流式返回两种模式：同步适合后台批处理与短答案场景；流式适合前端打字机效果，通过 SSE 或分块传输逐段返回。所有答案均带引用来源，便于人工核验。引用对象包含资产标识、片段位置与相关度分数，前端应把引用渲染为可点击的来源链接，让使用者能回溯原文，这是问答结果可被信任的前提。
confidence 字段表示答案与命中片段的相关程度，仅作排序与展示参考，不应作为是否采用的唯一判据；业务上涉及结论性输出时，仍应保留人工确认环节。多轮问答通过 sessionId 串联上下文，会话在一段时间无活动后自动过期，重要结论建议在业务系统中自行落库保存。若未指定知识库范围，系统将在调用者有权限的全部知识库中检索，响应会略慢于指定范围。
| 方法 | 路径 | 说明 | 关键参数 | 主要响应字段 |
|---|---|---|---|---|
| POST | /openapi/v1/qa/ask | 同步问答，返回完整答案与引用 | question(M)、knowledgeBaseIds、topK、withCitation | answer、citations、confidence、usedTokens |
| POST | /openapi/v1/qa/stream | 流式问答，逐段返回 | question(M)、knowledgeBaseIds、sessionId | 增量片段 event、delta、finished |
| GET | /openapi/v1/qa/sessions/{sessionId} | 查询多轮会话历史 | sessionId(M)（路径参数）、limit | turns、createdAt、lastActiveAt |
# 示例：同步问答
curl -X POST "https://api.panlongshi.com/openapi/v1/qa/ask" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <访问令牌占位>" \
-d '{"question":"防静电地板的系统电阻合格区间是多少？","topK":5,"withCitation":true}'组织与权限接口用于把客户既有的人员架构同步到 DravenAI，是 RBAC 与 ABAC 授权的前置条件。同步建议采用增量方式，用更新时间戳拉取变更，避免每次全量同步造成限流。存量组织规模在万人以上时，首次全量同步应安排在业务低峰期并分批提交，单批建议不超过 500 条。
strategy 参数决定同步语义：merge 只更新传入字段、保留未传入字段，适合日常增量同步；replace 以传入数据为准覆盖，适合以人力系统为唯一数据源的场景，误用会清空未传入的字段。权限校验接口的结果可能被短时缓存，授予权限后立即校验可能出现短暂不一致，若业务要求强一致，可在调用时附带禁用缓存参数或在授予后等待数秒。
| 方法 | 路径 | 说明 | 关键参数 | 主要响应字段 |
|---|---|---|---|---|
| POST | /openapi/v1/org/departments | 创建或更新部门 | name(M)、parentId、code、order | departmentId、path、updatedAt |
| POST | /openapi/v1/org/users/sync | 批量同步用户（幂等） | users(M)、strategy（merge 或 replace） | created、updated、skipped、failed |
| POST | /openapi/v1/permissions/grant | 授予角色或资源权限 | subjectType(M)、subjectId(M)、roleId(M)、resourceId | grantId、effectiveAt、expireAt |
| GET | /openapi/v1/permissions/check | 校验某用户对某资源的操作权限 | userId(M)、resourceId(M)、action(M) | allowed、reason、matchedPolicy |
# 示例：权限校验
curl -G "https://api.panlongshi.com/openapi/v1/permissions/check" \
-H "Authorization: Bearer <访问令牌占位>" \
--data-urlencode "userId=u-10086" \
--data-urlencode "resourceId=asset-20260930" \
--data-urlencode "action=download"看板接口返回的是聚合后的指标数据，支持按时间粒度与维度分组查询，适合对接客户自有的 BI 或大屏。指标口径与页面看板保持一致，若发现数值不一致，通常是时间粒度或过滤条件不同所致，而不是数据本身有误。
granularity 支持 hour、day、week、month 四档，跨度越大建议选越粗的粒度，避免返回行数过多导致响应变慢。聚合结果默认带缓存，实时性要求高的场景可携带刷新参数强制重算，但会增加服务端负载，不宜高频调用。需要长期留存的指标建议在业务侧定时拉取后自行存储，把本接口当作数据出口而非实时查询入口。
| 方法 | 路径 | 说明 | 关键参数 | 主要响应字段 |
|---|---|---|---|---|
| GET | /openapi/v1/metrics/overview | 获取资产总量、增长与活跃概览 | from、to、domain | totalAssets、growthRate、activeUsers、trend |
| POST | /openapi/v1/metrics/query | 自定义维度聚合查询 | metrics(M)、dimensions、filters、granularity | rows、columns、summary、generatedAt |
# 示例：按天聚合查询资产上传量
curl -X POST "https://api.panlongshi.com/openapi/v1/metrics/query" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <访问令牌占位>" \
-d '{"metrics":["upload_count"],"dimensions":["domain"],"granularity":"day","filters":{"from":"2026-09-01","to":"2026-09-30"}}'结论：Webhook 用于接收资产状态变更、任务完成、审批流转等异步事件，避免业务系统轮询。接收端必须做三件事：校验签名、按 eventId 去重、在 5 秒内返回 2xx。未返回 2xx 的事件会按指数退避重试，重试次数用尽后进入死信队列。
常见事件类型包括资产创建、索引完成、审批状态变更、同步任务结束与权限变更五类，订阅时应遵循最小订阅原则，只订阅真正需要的事件，减少无效投递。典型重试节奏为 1 分钟、5 分钟、30 分钟、2 小时，累计若干次后进入死信；死信事件可在投递记录中查询并手动重投，因此接收端故障恢复后无需重新触发业务。
| 方法 | 路径 | 说明 | 关键参数 | 主要响应字段 |
|---|---|---|---|---|
| POST | /openapi/v1/webhooks/endpoints | 注册回调地址与订阅事件 | url(M)、events(M)、secret、enabled | endpointId、createdAt、status |
| GET | /openapi/v1/webhooks/deliveries | 查询投递记录与重试状态 | endpointId、eventType、status、page | list、total、nextRetryAt |
| POST | /openapi/v1/webhooks/endpoints/{id}/retry | 手动重投失败事件 | id(M)（路径参数）、deliveryIds | accepted、scheduledAt |
# 事件体示例（由 DravenAI 推送到业务系统）
{
"eventId": "evt-7c1d93af",
"eventType": "asset.indexed",
"occurredAt": "2026-09-30T10:12:33+08:00",
"data": { "assetId": "asset-20260930", "domain": "content", "status": "indexed" },
"signature": "<HMAC 签名占位>"
}结论：列表接口统一使用页码分页，单页上限 100 条；限流按「应用 + 接口组」二维计数，超限返回 429 并携带重试等待时间。遵守这两条规则可以避免 90% 的调用失败。
结论：按错误码第一位判断责任方——4 开头多数是调用方问题（改参数、改权限、降速率），5 开头是服务端问题（重试、降级、报障）。所有错误响应都带 requestId，报障时必须提供。
| HTTP 状态 | code 示例 | 含义 | 处理建议 |
|---|---|---|---|
| 400 | 1001 | 参数缺失或格式错误 | 按 message 定位字段，修正后重试；属于调用方缺陷，重试无意义 |
| 401 | 1002 | 凭证缺失、失效或签名校验失败 | 检查时间戳偏差与签名拼接顺序；令牌过期则刷新后重试一次 |
| 403 | 1003 | 已认证但无该资源的操作权限 | 核对角色与数据范围；不要重试，应走权限申请流程 |
| 404 | 1004 | 资源不存在或已被删除 | 确认资源 ID 与租户；回收站中的资源需先恢复 |
| 409 | 1005 | 状态冲突（如重复创建、版本不一致） | 读取最新状态后决定是跳过还是更新；写入类接口带上幂等键 |
| 429 | 1006 | 触发限流 | 按响应中的等待时间退避重试，并降低调用速率或改批量接口 |
| 500 | 2001 | 服务端内部错误 | 可重试 1 至 2 次；持续出现请携带 requestId 提交工单 |
| 502 / 503 | 2002 | 依赖服务不可用或正在发布 | 指数退避重试，同时启用业务降级；检查健康检查接口状态 |
| 504 | 2003 | 处理超时（常见于大批量或复杂问答） | 缩小单次请求规模或改用异步任务接口，轮询任务结果 |
结论：优先使用官方 SDK（已封装鉴权、签名、重试与分页），只有在 SDK 未覆盖语言时才手写 HTTP 调用。无论哪种方式，都必须实现幂等、重试、批量与超时四项机制，否则在弱网与发布窗口期会出现重复数据与雪崩。
所有写接口支持 Idempotency-Key 请求头，服务端在 24 小时内对同键请求返回首次结果。键建议用「业务类型 + 业务主键 + 操作序号」生成，且必须由调用方持久化保存，不能每次随机生成。用户同步、资产创建、权限授予三类接口尤其必须启用。
只对 429、5xx 与网络超时做重试，4xx 一律不重试。重试采用指数退避（如 1 秒、2 秒、4 秒）并加随机抖动，最多 3 次；配合熔断，连续失败达到阈值后暂停调用一段时间，避免把依赖服务压垮。
优先使用批量接口，单次不超过 100 条；更大的数据集拆分为多个批次并控制并发在 2 至 5 之间。上传类场景使用直传凭证绕开应用服务器；同步类场景用增量时间戳而非全量拉取。
连接超时建议 3 至 5 秒，读超时按接口类型区分：查询类 10 秒、写入类 15 秒、问答类 30 秒以上或改用流式。超时不等于失败，对于写接口必须结合幂等键或查询接口确认最终状态，不能直接重发。
结论：接口集成按「沙箱验证 → 预发布压测 → 生产灰度 → 全量切换」四步推进，每步都有明确退出条件。跳步的最常见后果是证书、限流配额与权限模型三件事在上线当天才暴露。
上线前建议准备一份运行手册，写清凭证轮换周期、限流配额、告警联系人与降级预案。凭证应做到一环境一套、定期轮换，轮换时新旧并存一段时间以保证平滑过渡；相关管理制度可参考 私有化部署服务 中的交付与交接安排。
以下是对接过程中最常遇到的 8 个问题，答案给出可直接执行的判断与处理方式。
文档中的 api.panlongshi.com 仅为示例占位，实际地址是部署环境的网关域名，私有化部署客户以实施交接单上登记的地址为准。建议在配置文件中把地址做成环境变量，联调、预发布、生产三套环境各配一份，避免硬编码导致误调环境。
按顺序排查四点：服务器时间与接口服务器偏差是否超过 5 分钟、待签串的字段顺序与服务端是否一致、查询参数是否参与了签名、请求体是否用了压缩或重试后内容被改写。最快的办法是用官方 SDK 对同一请求打印待签串，与自实现版本的字符串做逐字符比对。
先调用权限校验接口确认该用户对该资源的实际权限结果，再检查请求头中的租户标识是否正确——跨租户是最常见的隐性原因。若权限校验接口返回 allowed 为 true 而业务接口仍 403，通常是操作类型（如导出、下载）不在角色授权范围内，需要单独申请。
使用三段式上传并开启分片：先申请上传凭证，再分片直传，最后确认创建。单片大小建议 5 至 10 MB，单文件超过 1 GB 时务必分片并支持断点续传。不要在应用服务器上做中转，也不要把文件内容放进 JSON 请求体做 Base64 传输。
服务端采用「至少一次」投递语义，网络抖动或响应超时都会触发重投，因此接收端必须按 eventId 做幂等去重（建议用唯一索引或缓存记录已处理 ID）。同时校验签名，避免伪造事件；处理逻辑要异步化，收到后先落库再返回 2xx。
先区分是检索慢还是生成慢：把 topK 降到 3 至 5、限定知识库范围、关闭不必要的重排可以显著缩短检索耗时；生成耗时则与答案长度相关，可设置最大长度或改用流式接口改善主观体验。若批量场景允许，改走异步任务接口并轮询结果。
版本号位于路径中，大版本变更才会递增，旧版本在公告的停用日期前继续可用。升级时在请求头中显式带上版本号做灰度，先在预发布环境跑通全量用例；字段废弃会提前公告并在响应中给出提示，客户端应忽略未知字段以保证前向兼容。
先在监控中统计峰值 QPS 与失败率，明确瓶颈是读接口、写接口还是问答并发，再联系服务方申请配额调整或改为批量与异步模式。临时高峰更推荐做削峰：客户端排队、错峰调度、缓存热点查询结果，而不是一味提高配额。