接入概述

外部系统对接事半AI平台的前置条件、认证方式、权限范围与错误码说明。

前置条件

对接前请确认以下信息：

API 地址：https://api.halfcall.cn
SIP 地址：用于 AI 呼入 SIP 转接，提交出口 IP 加入白名单后由平台单独提供（下文示例以 <SIP_HOST>:<SIP_PORT> 代替）
认证方式：所有请求在 Header 携带 Authorization: Bearer <api_key>，Key 在后台 API Key 管理页创建
数据格式：JSON，Content-Type: application/json
权限隔离：每个 API Key 只能操作自己企业下的数据
SIP 白名单：通过 SIP 转接接入 AI 呼入前，需将业务方服务器出口 IP 提交管理员加入系统白名单，否则 SIP 请求将被拒绝
话单回调：通话结束后系统主动推送话单，配置方式与签名规则见 Webhook 参考

下文示例中 sk_xxx、cmk...（项目 ID）、bot_xxx（数字员工 ID）均为占位符，请替换为所属企业的真实值。

创建 API Key 时需勾选权限范围，每个接口都要求 Key 具备对应权限，否则返回 403（见下方各接口标注的"所需权限"）：

权限	说明	覆盖接口
`READ`	查询类接口	基础查询全部；线索查询；读呼入配置；读话术/提取配置
`LEADS`	线索全生命周期管理	上传线索、推送线索、撤销线索
`CONTROL`	项目级控制	创建项目、关联数字员工、启停项目、修改拨打配置、开关呼入与设置呼入号码
`SCRIPT`	话术/音色/提取管理（风险最高，单独授权）	配置和测试来电预查、覆写线上话术提示词、配置音色、配置提取字段与意向推送

建议按最小权限原则申请 Key：仅需查询数据与结果的对接方只勾选 READ；需推送线索时增加 LEADS；需远程控制外呼节奏时增加 CONTROL；SCRIPT 权限直接影响 AI 对客户的表述，仅授予确需动态改写话术的系统。

以下接口除要求 Key 具备对应权限外，还要求企业已开通「协作项目」（由渠道在企业编辑页 → 协作权限中开启），否则返回 403（提示「企业未开启协作…」）：

企业未开通协作时，后台创建 API Key 的 CONTROL（项目控制）与 SCRIPT（话术管理）两项权限不可勾选。平台管理员或渠道管理员账号创建的 Key 不受此限制。

AI 呼入的修改类接口（开关呼入与设置号码、配置来电预查）另有要求：企业已开通**「协作呼入」，且 API Key 由企业主**创建（平台管理员、渠道管理员创建的 Key 不受此限制），否则返回 403。

模块	说明
基础查询	获取项目列表、数字员工列表、线路状态、音色列表、项目统计，以及创建项目、关联数字员工
AI 呼出	线索导入（批量/单条）、启停项目、查询通话结果、拨打配置、撤销线索
AI 呼入	开启呼入、设置呼入号码、配置来电预查（客户直接拨打平台号码）；或经 SIP 转接并通过 Header 传参
话术与配置	远程读写话术、音色、提取字段与意向推送配置
Webhook 参考	话单回调、项目结算事件推送及其配置接口
接入 AI Agent	通过 MCP 或 `mcp/tools`、`mcp/call` 接口调用平台助手的全部工具（导出、重拨、改配置等）

code	HTTP 状态码	说明
0	200/201/202	成功
-1	400	请求参数错误（如字段缺失、格式不符）
-1	401	API Key 无效、已撤销或已过期
-1	403	无权访问该资源（不属于当前企业），或 API Key 缺少该接口所需的权限范围（见上方"权限范围"表）
-1	404	资源不存在
-1	500	服务器内部错误