Metadata-Version: 2.4
Name: rcs-openapi-client
Version: 0.5.0
Summary: RCS 开放 API Python SDK：AK/SK、客户读写、业务接口、PII 解密及 Webhook 验签
Author: Akimimi
License-Expression: LicenseRef-Proprietary
Project-URL: Repository, https://gitee.com/akimimi/rcs-openapi-python-client
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx<1,>=0.27
Requires-Dist: cryptography>=43
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: build>=1; extra == "dev"
Requires-Dist: twine>=6; extra == "dev"
Requires-Dist: mypy>=1.11; extra == "dev"
Requires-Dist: ruff>=0.9; extra == "dev"
Dynamic: license-file

# RCS Open API Python SDK

Python 3.11+ 的同步客户端，面向 RCS 已上线开放 API。覆盖 PHP SDK 1.11.0 的全部公开能力，并提供客户字段定义读取、类型提示、PII 解密和 Webhook 验签。

生产 API 基址为 `https://vas-api.akimimi.com`。`base_url` 只填根地址，SDK 自动追加 `/api/open/v1`。调用范围由 AK/SK 绑定的普通用户账号决定；IP 白名单由服务端管理员配置。

## 安装

包名 `rcs-openapi-client`，导入名 `rcs_openapi`，当前版本 `0.4.0`。通过私有 Gitee 发行版和构建包分发。

```bash
# 安装取得的 wheel
python -m pip install ./rcs_openapi_client-0.4.0-py3-none-any.whl

# 或安装私有仓库的固定版本（需先配置自己的 SSH 访问权限）
python -m pip install 'git+ssh://git@gitee.com/akimimi/rcs-openapi-python-client.git@v0.4.0'
```

开发分支示例可用 `@feature/python-sdk`，生产请固定审核通过的提交或发布版本，避免跟随可变分支。依赖为 HTTPX 与 cryptography，由 pip 自动安装。默认遵守 HTTPX 代理和 CA 环境设置；若使用 SOCKS 代理，另外安装 `httpx[socks]`。SDK 保持 TLS 验证开启，不提供跳过证书校验的快捷开关。

## 获取 token、创建和编辑客户

管理员发放两类不同用途的密钥：AK/SK 用来换取 72 小时 Bearer token，PII AES 密钥用来在本地解密响应中的姓名、手机号、地址和车牌。PII 密钥接受32字节的 hex64 或 base64 字符串。

```python
import os
from rcs_openapi import RcsOpenApiClient

with RcsOpenApiClient(
    base_url="https://vas-api.akimimi.com",
    access_key_id=os.environ["RCS_ACCESS_KEY_ID"],
    secret_key=os.environ["RCS_SECRET_KEY"],
    pii_aes_key=os.environ["RCS_PII_AES_KEY"],
    timeout=15,
) as client:
    client.authenticate()  # 缓存在当前实例中；不要写入日志
    customer = client.create_customer({
        "phoneNumber": "13800000000",
        "name": "张三",
        "age": 35,
        "licensePlate": "沪A12345",
        "tags": ["老客户"],
    })
    # customer 的 PII 字段仍是 enc:v1: 密文；原响应不会被解密函数修改。
    plain = client.decrypt_customer(customer)
    updated = client.update_customer(customer["id"], {
        "notes": "资料已更新",
        "licensePlate": None,
        "tags": [],
        "doNotDisturb": True,
        "dndReason": "客户要求停止联系",
    })
    detail = client.get_customer(customer["id"])
    page = client.list_customers({"q": "13800000000", "page": 1, "pageSize": 20})
```

本段示例会真实创建、编辑客户；请换成已获授权的业务数据。完整脚本见 [examples/customer_flow.py](examples/customer_flow.py)，不会打印密钥或 token。

- SDK 方法使用 snake_case；请求/响应 JSON 字段仍为服务端 camelCase。
- 创建时 `phoneNumber`、`name` 必填；客户归属由凭据决定，不能伪造 `tenantId`/`userId`。
- PATCH 仅修改提供的字段；`None` 清空可空字段，`tags=[]` 清空标签，未提供字段保持不变。客户 `age` 输入是整数或 `None`，响应按服务端历史格式为字符串或 `None`。
- 客户创建与编辑均支持 `customFields`。先用 `list_customer_fields()` 获取定义；键可用中文 label 或 fieldKey，值按定义类型传入，`None` 清空单项。日期通常输入 `YYYY-MM-DD`，返回值按服务端归一化为 ISO 字符串。
- 列表方法返回服务端分页对象；SDK 不自动遍历所有页。查询布尔值会正确编码为 `true/false`，保留 `False` 和 `0`，忽略 `None` 和空字符串。
- 可直接传 `access_token=...` 或调用 `set_access_token(...)`；token 到期后再次 `authenticate()`。SDK 不会自动重放写请求。
- 使用 `with` 管理 HTTP 连接；长期客户端在服务关闭时调用 `close()`。

## 其它已上线接口

[完整 PHP/Python 方法对照](docs/api-parity.md) 包含主体、营销计划及轮次、场景、通话记录、设备与 SIM 配额/号码、营销线索、账号日统计、测试拨号和录音下载。返回 JSON 对象保留服务端字段，常用客户结构提供 `Customer`、`CustomerInput`、`ListResponse` 类型。

```python
from rcs_openapi import LeadIntakeRule

rule = LeadIntakeRule.rules(
    LeadIntakeRule.rule("success"),
    LeadIntakeRule.rule("pending", "or", [
        LeadIntakeRule.builtin("followup", "includes", "再联系,考虑"),
        LeadIntakeRule.extract("意向车型", "notEquals", "无"),
    ]),
)
# client.set_campaign_lead_intake_rule(campaign_id, rule)
# client.reset_campaign_lead_intake_rule(campaign_id)  # 恢复系统默认
```

`create_campaign` 创建草稿；`set_campaign_status(id, "active")` 可能开始业务执行。`test_dial` 会实际下发拨号，必须由调用方明确发起；SDK 的自动测试不会拨号。

`create_lead_from_call` 收到带 `leadId` 与 `alreadyExisted=true` 的409响应时正常返回，方便幂等处理；其它409仍抛异常。删除计划/场景/线索成功返回 `None`。`fetch_recording(recording_url)` 返回音频 `bytes`，使用录音 URL 自带的签名，不附加 API Bearer token，不跟随重定向。`decrypt_call_record`、`decrypt_marketing_lead` 提供相应 PII 解密。

## 错误与超时

```python
from rcs_openapi import RcsOpenApiError, RcsTransportError, RcsProtocolError

try:
    customer = client.get_customer(customer_id)
except RcsOpenApiError as error:
    # error.status: 401/403/404/409/422/429/500 等；error.code 为服务端错误码
    if error.status == 404:
        pass  # 不存在或不在当前账号可见范围
    else:
        raise
except RcsTransportError:
    raise  # 连接/TLS/超时；创建可能已经成功，先按手机号查询确认结果
except RcsProtocolError:
    raise  # 无效 JSON/响应结构或意外重定向
```

不自动重试创建、编辑、删除或拨号；网络异常不会把密钥、token 或签名 URL 写入 SDK 异常消息。服务端业务错误保留其原始 message，调用方应按自己的日志脱敏规则处理。

## Webhook 验签

```python
from rcs_openapi import WebhookReceiver, WebhookError

receiver = WebhookReceiver(
    webhook_secret,  # 端点独立签名密钥，不能拿 AK/SK 或 PII 密钥代替
    pii_aes_key=pii_aes_key,
    tolerance_seconds=300,
)
try:
    event = receiver.parse(raw_request_body_bytes, request_headers)
except WebhookError as error:
    # error.code: missing_header / invalid_header / bad_signature /
    # stale_timestamp / invalid_body；应拒绝处理
    raise

# 持久化检查 event.id 是否已处理；重复事件直接返回2xx。
# 时间窗口不能替代按事件ID去重。
if event.is_lead_created():
    lead = event.decrypted_lead()
elif event.is_device_alarm():
    alarm = event.alarm()
```

验签必须使用**原始请求体字节**，不要先 JSON 解析再序列化。支持请求头大小写差异、HMAC-SHA256 常量时间比较、默认 ±300 秒时间窗口；事件属性包括 `id`、`type`、`api_version`、`occurred_at`、`user_id`、`data` 和 `envelope`。四类事件的便捷方法为 `lead()`/`decrypted_lead()`、`device()`/`offline()`/`alarm()`/`sim_registered()`，未知事件仍可读取原始 data。

接收方负责持久化去重和业务任务投递，应快速返回2xx。SDK 不启动服务器，不强制绑定 Web 框架。[FastAPI 适配示例](examples/webhook_fastapi.py) 演示原始请求体验签，FastAPI 由调用方自行安装。

## 开发与验证

```bash
python3.11 -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev]'
pytest -q
ruff check src tests scripts examples
ruff format --check src tests scripts examples
mypy src
python -m build
python -m twine check dist/*
```

[验收记录](docs/validation.md) 区分协议单测、跨语言字节向量、真实 HTTP/PostgreSQL 和 wheel 安装结果。隔离验收脚本只接受 `127.0.0.1/localhost/::1:3033`，通过标准输入传入本轮凭据，禁止把生产凭据写进测试文件。SDK 本身仍可正常连接上述生产 HTTPS 域名。

本软件为专有软件，使用与分发需获得授权。

## 场景日汇总

需已部署 `GET /stats/scenario-summary` 的服务端；测试基址为 `https://rcs-api.mimixiche.cn`，SDK 更新不代表生产接口已发布。

```python
totals = client.get_scenario_summary(
    '2026-10-01', '2026-10-31', scenario_alias='insurance',
)
```

必填日期包含首尾，相同日期统计一天；可选 `scenario_id` / `scenario_alias` 同时提供时取交集。返回 outboundCount、connectedCount、totalDurationSeconds（秒）、successCount、leadCount、outboundCustomerCount 六项累加值。仅查询已落库日统计，无匹配返回六项零，不补算当天/缺失日，客户数不跨日期/场景再次去重。服务端错误沿用 RcsOpenApiError，例如422不会转换成零。


## 接口外呼任务（0.2.0 私有分发）

```python
request = {"campaignId": "cmp_xxx", "scenarioId": "scn_xxx", "phone": "13800138000", "externalRef": "order-001", "customer": {"name": "张三"}}
task = client.create_outbound_call(request)
current = client.get_outbound_call_task(task["taskId"])
page = client.list_outbound_calls({"externalRef": request["externalRef"], "status": "queued"})
```

沿用后台预建并发布的接口计划，202是可靠受理，不表示已拨号。externalRef必传、用户内唯一；相同归一化请求重放200、内容变化409 external_ref_conflict，只有成功接单占号。SDK不自动重试写入、不生成或替换业务单号、不自动重拨。超时结果未知时由调用方沿用原单号和原请求重试，task_in_flight应查询已存在taskId，不能换号绕过。

RcsOpenApiError保留code/message/status，并新增request_id、details；旧三参构造兼容。完整39项业务码由服务接入文档定义，典型包括external_ref_conflict、task_in_flight、missing_required_field、feature_disabled、no_available_window和payload_too_large。服务端可能带字段校验和已有taskId详情，调用方可按编码分支处理。

WebhookEvent新增is_outbound_call_finished()/outbound_call_task()，沿用WebhookReceiver的真实原始体验签。事件ID是outbound_call.finished:<taskId>，接收方负责持久化去重；任务快照保持密文PII及当前权限，不触发自动解密或重拨。0.2.0只提供私有wheel/sdist，不发布公共PyPI；包发布不代表目标API已部署。

### 合作方 API 登录（0.3.0）

平台管理员先开通 API 登录，登记 HTTPS 回调及出口 IP 白名单。合作方后端通过
`RcsOpenApiClient(base_url, partner_id=..., partner_client_id=..., partner_client_secret=...)` 配置凭证。
调用 `send_partner_login_sms(phone)` 获取挑战，再以 `submit_partner_login(input, idempotency_key)`
提交短信字段或 `method=password` 的密码字段。回调处理器使用
`WebhookReceiver(signing_key).parse_partner_login(raw_body, headers)`，核对合作方和请求 ID，
按事件 ID 去重。成功时将兑换码传给 `exchange_partner_login_code(code)`，按用户保存返回的访问令牌。
同一提交重试复用幂等键，兑换不自动重试。密码方式需单独启用。

### 主体管理与营销结果日统计

使用 create_agent(input) 创建主体，必填 aliasName、storeAddress、entityType 和 name，可选 openTime、closeTime、storePhone。delete_agent(id) 归档主体，未结束计划仍引用时抛出 409 conflict。get_outbound_daily_stats(date) 的 marketingOutcomeCounts 返回 success、failure、no_effective_communication。

### 当前用户资料

使用已认证的客户端调用 `get_current_user()`，返回当前账号资料及适用的合作方绑定。
