Metadata-Version: 2.4
Name: tinet-cticloud-cli
Version: 0.1.2
Summary: Tinet CtiCloud OpenAPI CLI
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: click>=8.0
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-httpx>=0.30; extra == "dev"
Dynamic: description
Dynamic: description-content-type
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

CTICloud 命令行客户端，封装 OpenAPI 接口，与 [CTICloud Wiki](https://wiki.cticloud.cn/) 中参数与响应一致，适合脚本化集成与 Agent 调用。

**当前版本：** `0.1.2`  
**PyPI：** https://pypi.org/project/tinet-cticloud-cli/

## 功能概览

| 子命令 | 说明 |
|--------|------|
| **`config`** | 本地凭证管理 |
| **`agent`** | 座席管理与座席操作 |
| **`agent-login`** | 座席服务端登录鉴权（区别于座席上线） |
| **`agent-report`** | 座席报表查询 |
| **`agent-status`** | 座席实时状态查询 |
| **`agent-tel`** | 座席电话管理 |
| **`area-code`** | 号码归属地查询 |
| **`asr`** | ASR 转写结果查询 |
| **`cdr`** | 任务话单/来电/外呼/webcall/sip/预测外呼等通话记录查询 |
| **`data-manager`** | 缓存数据管理 |
| **`enterprise`** | 企业信息查询 |
| **`enterprise-hotline`** | 企业号码列表查询 |
| **`enterprise-setting`** | 企业配置管理 |
| **`enterprise-voice`** | 企业语音文件管理 |
| **`exten`** | 分机管理 |
| **`hybrid-group`** | 号码池管理 |
| **`investigation`** | 满意度调查记录查询 |
| **`ivr-router`** | 呼入路由设置列表查询 |
| **`monitor`** | 平台监控与实时统计：座席/队列/话机/业务/中继监控；座席/满意度/队列实时统计 |
| **`record`** | 根据录音文件名获取试听/下载地址，可落盘 |
| **`task`** | 外呼任务全生命周期管理；号码导入与查询；任务批次列表/详情；运行中任务监控总览与详情 |

所有出站 HTTP 请求自动附加 `X-CtiCloud-CLI-version: {版本号}` 请求头（不参与 sign 计算）。
## 环境要求

- Python **≥ 3.10**
- 运行时需访问 `api-{region}.cticloud.cn`
- CTICloud 部门 token（环境变量或配置文件）

## 安装

从 [PyPI](https://pypi.org/project/tinet-cticloud-cli/) 安装（推荐）：

```bash
pip install tinet-cticloud-cli
tinet-cticloud-cli --version   # 0.1.2
tinet-cticloud-cli --help
```

指定版本或升级：

```bash
pip install 'tinet-cticloud-cli==0.1.2'
pip install --upgrade tinet-cticloud-cli
```

macOS 等受限环境可使用 [pipx](https://pipx.pypa.io/)：

```bash
pipx install tinet-cticloud-cli
```

## 配置凭证

**环境变量：**

```bash
export CTICLOUD_REGION=your_enterprise_region
export CTICLOUD_VALIDATE_TYPE=2   # 1 部门编号验证 2 企业编号验证
export CTICLOUD_ENTERPRISE_ID=your_enterprise_id
export CTICLOUD_TOKEN=your_token
```

**或配置文件：**

```bash
# --validate-type：1 部门编号验证 2 企业编号验证
tinet-cticloud-cli config set \
  --region your_enterprise_region \
  --validate-type 2 \
  --enterprise-id your_enterprise_id \
  --token your_token
```

## 快速示例

顺序与上方「功能概览」一致：`config` 置顶，其余按字母序。  
枚举含义与 `--help` 一致；完整取值见各子命令 `--help` 或 [Wiki](https://wiki.cticloud.cn/)。

```bash
# config
tinet-cticloud-cli config show

# agent
tinet-cticloud-cli agent query --limit 10
tinet-cticloud-cli agent get --cno 2000
tinet-cticloud-cli agent login --cno 2000 --bind-tel 13800000001 --bind-type 1   # 1 电话 2 分机 3 webrtc
tinet-cticloud-cli agent create --cno 9001 --name 张三 --area-code 010
tinet-cticloud-cli agent update --cno 9001 --comment 备注

# agent-login / agent-report / agent-status / agent-tel
tinet-cticloud-cli agent-login authenticate --cno 9001 --pwd your_password
# --time-range-type：1 日报表 2 周报表 3 月报表 4 自定义时间
tinet-cticloud-cli agent-report agent-duration \
  --time-range-type 1 \
  --start-time 2026-07-01 --end-time 2026-07-01
tinet-cticloud-cli agent-status get --cno 9001
tinet-cticloud-cli agent-tel tel-list --cno 9001

# area-code / asr
tinet-cticloud-cli --json area-code get --tel 13800138000
# --call-type：1 呼入 2 webcall 4 预览外呼 5 预测外呼 6 主叫外呼 9 内部呼叫
tinet-cticloud-cli --json asr get --call-type 4 --main-unique-id sip-xxx

# cdr（--start-time / --end-time 等为 Unix 秒级时间戳）
tinet-cticloud-cli cdr list-auto-task --start-time 1700000000 --start-time-end 1700086400
tinet-cticloud-cli --json cdr ib-query --start-time 1700000000 --end-time 1700086400

# data-manager / enterprise*
tinet-cticloud-cli --json data-manager --method get --key your_key   # set|get|delete
tinet-cticloud-cli --json enterprise get
tinet-cticloud-cli --json enterprise-hotline list-page --limit 10
tinet-cticloud-cli --json enterprise-setting list
tinet-cticloud-cli --json exten get --exten 8001
tinet-cticloud-cli --json hybrid-group list
tinet-cticloud-cli --json investigation query --limit 10
tinet-cticloud-cli --json ivr-router list

# monitor
tinet-cticloud-cli --json monitor agent --limit 10
tinet-cticloud-cli --json monitor enterprise-call-latest
# --queue-monitor-fields：queueParams,agentStatuses,queueEntries,agentSummary
tinet-cticloud-cli --json monitor queue --queue-monitor-fields queueParams --qnos 1000
tinet-cticloud-cli --json monitor statistics-queue

# record
tinet-cticloud-cli record get-info --record-file your-record-file.mp3

# task
tinet-cticloud-cli task query --limit 10
tinet-cticloud-cli task monitor-tasks --status 2   # 1 运行中 2 暂停
```

全局 `--json` 输出 Wiki 原始 JSON；默认人类可读摘要，并对手机号、`password` / `encryptPassword` 等敏感字段脱敏。

## 帮助与 API 文档

安装后通过 `--help` 查看各子命令及参数（与 Wiki Query/Body 字段一一对应）：

```bash
tinet-cticloud-cli --help
tinet-cticloud-cli config --help
tinet-cticloud-cli agent --help
tinet-cticloud-cli agent login --help
tinet-cticloud-cli agent-login --help
tinet-cticloud-cli agent-report --help
tinet-cticloud-cli agent-status --help
tinet-cticloud-cli agent-tel --help
tinet-cticloud-cli area-code --help
tinet-cticloud-cli asr --help
tinet-cticloud-cli cdr --help
tinet-cticloud-cli cdr list-auto-task --help
tinet-cticloud-cli cdr ib-query --help
tinet-cticloud-cli data-manager --help
tinet-cticloud-cli enterprise --help
tinet-cticloud-cli enterprise-hotline --help
tinet-cticloud-cli enterprise-setting --help
tinet-cticloud-cli enterprise-voice --help
tinet-cticloud-cli exten --help
tinet-cticloud-cli hybrid-group --help
tinet-cticloud-cli investigation --help
tinet-cticloud-cli ivr-router --help
tinet-cticloud-cli monitor --help
tinet-cticloud-cli record --help
tinet-cticloud-cli task --help
```

OpenAPI 契约与字段说明见 [CTICloud Wiki](https://wiki.cticloud.cn/)。
