接入概述
外部系统对接事半AI平台的前置条件、认证方式、权限范围与错误码说明。
前置条件
对接前您需要确认：
- API 地址：
https://api.halfcall.cn - SIP 地址：
115.190.223.167:5080（AI 呼入接入用） - 认证方式：所有请求在 Header 携带
Authorization: Bearer <api_key>，Key 在后台 API Key 管理 页创建 - 数据格式：JSON，
Content-Type: application/json - 权限隔离：每个 API Key 只能操作自己企业下的数据
- SIP 白名单：走 AI 呼入前，业务方服务器出口IP需发送给管理员加入系统白名单，否则 SIP 请求会被拒绝
- 话单回调：通话结束后系统主动推送话单，配置方式与签名规则见 Webhook 参考
下文示例中 sk_xxx、cmk...（项目 ID）、bot_xxx（数字员工 ID）均为占位符，替换成您自己企业下的真实值。
权限范围（scopes）
创建 API Key 时需勾选权限范围，每个接口都要求 Key 具备对应权限，否则返回 403（见下方各接口标注的"所需权限"）：
| 权限 | 说明 | 覆盖接口 |
|---|---|---|
READ | 查询类接口 | 基础查询全部；线索查询；读话术/提取配置 |
LEADS | 线索全生命周期管理 | 上传线索、推送线索、撤销线索 |
CONTROL | 项目级控制 | 创建项目、关联数字员工、启停项目、修改拨打配置 |
SCRIPT | 话术/音色/提取管理（风险最高，单独授权） | 覆写线上话术提示词、配置音色、配置提取字段与意向推送 |
建议按最小权限原则申请 Key：仅需查表和查结果的对接方只勾
READ；需要推送线索的再加LEADS；需要远程控制外呼节奏的再加CONTROL；SCRIPT权限会直接影响 AI 对客户说什么，请只授予真正需要动态改写话术的系统。
接口总览
| 模块 | 说明 |
|---|---|
| 基础查询 | 获取项目列表、数字员工列表、线路状态、音色列表，以及创建项目、关联数字员工 |
| AI 外呼 | 线索导入（批量/单条）、启停项目、查询通话结果、拨打配置、撤销线索 |
| AI 呼入 | 通过 SIP Header 传参实现个性化 AI 呼入 |
| 话术与配置 | 远程读写话术、音色、提取字段与意向推送配置 |
错误码
| code | HTTP 状态码 | 说明 |
|---|---|---|
| 0 | 200/201/202 | 成功 |
| -1 | 400 | 请求参数错误（如字段缺失、格式不符） |
| -1 | 401 | API Key 无效、已撤销或已过期 |
| -1 | 403 | 无权访问该资源（不属于当前企业），或 API Key 缺少该接口所需的权限范围（见上方"权限范围"表） |
| -1 | 404 | 资源不存在 |
| -1 | 500 | 服务器内部错误 |