开发者文档

一、接入方式总览

IFCALL 基于腾讯云 TRTC 技术，提供以下接入方式供开发者、企业 OEM 与集成商选择：

二、对接准备

2.1 企业开户

需要在运营管理端给企业开户，指定主管姓名和电话号码，配置子账号数量，以及其他信息。

• 主管姓名和电话号码将生成企业的主卡账户，该账户默认可以直接使用，无需身份认证（默认已认证）。
• 企业主管账户用户可以登录企业端工作台查看各种数据。
• 子账号数量需要设置较大，所有通过 API 接口注册的用户都是该企业的子账户。

2.2 开通 API

企业开户后，需要开通 API 才能调用接口。开通 API 时需配置以下值：

配置项	说明
API-KEY	16 位字母数字组合的字符串，可随机生成
API-Secret	16 位字母数字组合的字符串，可随机生成
API 密码	任意位数字母数字组合的字符串，建议不小于 16 位
IP 白名单	企业业务系统的外网 IP 地址，可多个，系统只处理白名单内的请求
话单上报 URL	企业处理话单的服务 URL，系统处理该企业呼叫话单时实时上报
身份认证费率	实名认证接口额外收费，费率只对实名认证接口有效
API 权限	按运营需要设置企业可访问的接口

2.3 交付 API 配置

开通 API 时产生的 企业ID(companyId)、API-KEY、API-Secret、API 密码 需通过安全途径提供给企业，企业业务系统调用 API 时需据此进行数字签名。

2.4 重置 API 密码

如需重置 API 密码，在开通 API 时选择"重置密码"并录入新密码。重置后调用 API 需用新密码进行数字签名。

三、接口调用流程

通过 API 拨打电话有两种模式：

3.1 只拨打电话模式

1. 企业主管账户登录平台企业工作台，开通企业的子账号。
2. 子账户登录企业业务系统拨打电话，企业业务服务器调用 API 进行地理位置鉴权。
3. 平台 API 服务收到鉴权请求后，进行鉴权处理，返回位置鉴权结果。
4. 企业业务系统调用 API 进行呼叫检测。
5. 平台 API 服务检查主叫和被叫信息是否可以拨打，以及最大拨打时长，返回结果。
6. 企业业务系统调用 API 进行拨打呼叫。
7. 平台 API 服务对呼叫请求进行鉴权，通过后发起呼叫，返回呼叫 ID 以及 TRTC 的房间号和数字签名信息。
8. 企业业务系统保存呼叫 ID。
9. 企业业务系统使用呼叫 ID 查询呼叫的实时执行情况。
10. 企业业务系统使用 TRTC 房间号和数字签名发起 TRTC 通话会话。
11. 子账号用户接听电话，完成后挂断。
12. 企业业务系统调用 API 请求挂断电话。
13. 平台 API 服务挂断处理，产生话单扣费，同时上报话单给企业业务系统。
14. 企业业务系统处理收到的话单。
15. 企业业务系统下载话单的录音文件。

3.2 开通子账户拨打模式

企业业务系统开通用户账户，同时通过 API 接口请求开通子账户，然后通过子账户拨打电话。此类子账户必须进行实名认证之后才能拨打电话。

1. 企业业务系统开通用户账户。
2. 调用子账户注册 API 向平台发起开通子账户请求。
3. 平台 API 服务处理并返回用户 ID（userId）。
4. 企业业务系统记录 userId。
5. 调用实名认证接口发起账户实名认证。
6. 平台处理认证并扣费，返回认证结果。
7. 认证成功后的用户登录企业业务系统拨号，流程参考"只拨打电话模式"的 2~15 步骤。

3.3 话单产生和上报

• 直拨拨打调用顺序：startCall → alertCall → endCall
• alertCall 返回正常的呼叫就会产生话单。
• 挂断电话之后，话单会上报。

四、接口调用总则

接口调用端需要用 API-KEY、API-Secret、API 密码对请求内容进行数字签名后发起请求；受理端收到请求后先校验数字签名，校验成功才处理。

4.1 数字签名

1. 使用 API-KEY、API-Secret、API 密码和时间戳，获取加密的签名键值（signKey）：
   1. 对时间戳通过 SHA-256 算法算出 Hash 值；
   2. 拼接时间戳 Hash 值和 API 密码，得到待加密文本；
   3. 用 API-KEY（key）、API-Secret（iv）对待加密文本进行 AES 加密（PKCS5Padding 填充），得到密文；
   4. 对密文进行 Base64 编码，得到用于签名的 signKey。
2. 对请求参数按照 ASCII 码排序（不包括 sign 参数）。
3. 将排序后的参数用 & 拼接成待处理字符串，每个参数格式为 key=value。
4. 把 signKey 附加到待处理字符串中：[待处理字符串]&key=[signKey]。
5. 使用 MD5 算法对拼接后的字符串处理，得到的 MD5 值转为大写，得到数字签名值 signValue。

4.2 接口调用

• 调用 API 时，计算出签名值 signValue 后加入请求参数中（字段名：sign）。
• 无特殊说明时，接口一律采用 POST 模式调用，Content-Type: application/json;charset=UTF-8。
• 服务端收到请求后对参数进行签名计算，与请求中的签名一致才处理。
• 接口返回信息总体结构：

{
  "status": 0,    // 接口处理结果，Integer，0 成功，其他异常，参见状态定义
  "message": "",  // 异常描述，String
  "data": {       // 接口处理结果返回对象
     ...
  }
}

五、接口说明

以下接口均需携带 companyId、timestamp、sign 公共参数。

5.1 用户管理接口

5.2 呼叫记录接口

5.3 拨打处理接口

5.4 话单上报接口

平台处理企业呼叫话单后，向企业的话单上报 URL 实时上报话单通知（调用方向：平台 → 企业业务系统）。

• URL：企业的话单上报 URL
• 调用模式：POST，Content-Type: application/json;charset=UTF-8
• 参数包含 cdrId、caller、outCaller、called、callTime、answerTime、releaseTime、talkSeconds、billSeconds、billMoney、billRate、statusCode、statusName、causeCodeName、areaName 等。
• 返回：{ "status": 0, "message": "", "data": "" }

六、状态定义

6.1 接口处理结果状态（status）

状态码	说明
0	处理成功
5700103	用户 ID 不能是空值
5700166	已经存在这个电话号码的用户
5700341	企业 ID 不能是空值
5700343	主叫号码不能是空值
5700344	被叫号码不能是空值
5700345	没有找到企业信息，请确认企业 ID 是正确的
5700346	对接端 IP 地址不在白名单内
5700348	接口调用密码不正确
5700350	没有找到主叫对应的用户，请确认主叫号码已在系统中注册
5700355	数字签名不正确
5700357	您的企业没有使用这个接口的权限
5700361	开始日期和结束日期间隔不能超过 30 天
5700367	需要进行用户身份实名验证
5700368	用户不存在或者用户和企业不匹配

6.2 呼叫认证结果状态（authStatus）

状态码	说明
0	通过认证
900002	鉴权失败
900004	需要电话号码授权
900101	主叫号码非法
900102	没有电话卡
900103	电话卡被锁定
900105	电话卡过期
900106	电话卡没有余额
900107	被叫号码非法
900108	被叫号码格式错误
900110	不支持的地区
900111	没有该地区的费率
900112	受限的地区
900117	账上余额小于最小余额
900201	外显号码不存在

七、调用实例

7.1 数字签名核心逻辑

// 1. 生成签名键值 signKey
String signKey = generateKey(key, iv, pwd, timestamp);
//    key=API-KEY, iv=API-Secret, pwd=API密码, timestamp=时间戳

// 2. 生成数字签名 sign
String sign = generateSign(signKey, map);
//    map 为请求参数（不含 sign），按 ASCII 排序拼接，
//    末尾附加 &key=signKey，再整体 MD5 转大写

// 3. 将 sign 加入请求参数后发起 POST 请求
map.put("sign", sign);

完整 Java 参考实现（SignTool.java、HttpTool.java、ApiResult.java）请查看 线上文档 或联系我们的商务技术支持获取。

八、接入流程

1. 通过 商务合作 开通企业账户并申请 API 权限。
2. 获取 API-KEY、API-Secret、API 密码、企业 ID 及话单上报 URL 等配置。
3. 在服务端实现数字签名算法（参考上文）并完成接口联调。
4. 按接入方式选择对应的 SDK（小程序 / Web / uni-app）集成前端通话能力。
5. 完成实名认证、位置授权等合规流程后即可上线拨打国际长途。