开放 API 概述

开放 API 把平台里的业务数据以只读接口对外开放，供你接进自己的系统：BI 报表、内部看板、监控告警、数据归档。

能做什么

资源	能查什么	典型用途
知识库	知识库列表与详情（名称、描述、分段方式、状态）	盘点各业务线的知识库资产
客服工单	工单号、标题、状态、优先级、来源、处理人	把工单接进客服考核或工单大屏
告警	级别、来源、标题、状态、对象	汇进统一监控与值班系统
客服渠道	渠道名称、类型、启用状态	核对渠道接入情况

只读意味着只能查，不能改。需要写入的操作仍在后台进行。

不开放的部分

管理后台的内部接口一律不对外开放
客户联系方式、密钥、渠道配置里的敏感字段不出现在返回结果里
会话内容、消息明细不在开放范围内

接口按 API Key 绑定的归属范围返回数据：Key 属于哪个客户，就只能读到这个客户的数据。查别人的数据会返回「不存在」，不会提示「无权访问」。

接口长什么样

GET https://jinxino.cn/api/open/v1/meta
GET https://jinxino.cn/api/open/v1/{资源名}
GET https://jinxino.cn/api/open/v1/{资源名}/{id}

meta 返回当前 Key 的信息与全部可用资源，对接前先调它确认资源名
列表接口支持关键词、等值过滤与分页
详情接口按 id 取单条

请求与响应都是 JSON，响应统一包在 code、message、data 里。列表的 data 里有 list、total、page、page_size。

三步接入

建 Key：管理员在后台「开放 API」菜单里新建，保存后完整密钥只显示一次
调接口：请求头带 X-API-Key，先调 meta 确认能看到哪些资源
接数据：按资源分页拉取，处理 429 与 5xx 后重试

适用与不适用

适用	不适用
每天定时拉取工单、告警做报表	需要实时推送（应改用 Webhook）
把知识库清单同步进内部资产系统	需要修改平台数据
自建看板展示渠道与告警状态	大批量历史导出（应按时间分批拉取）

相关文档