telnyx-account-management-java

用途

Telnyx Account Management - Java 面向经销商（reseller）与企业（enterprise）场景，帮助开发者使用 Telnyx Java SDK 管理子账户（managed accounts）和组织用户。该技能以 Java 代码示例的形式，展示如何调用 Telnyx 账户管理相关 API。

安装与初始化

Maven 依赖：

<dependency>
    <groupId>com.telnyx.sdk</groupId>
    <artifactId>telnyx</artifactId>
    <version>6.89.0</version>
</dependency>

Gradle 依赖：

implementation("com.telnyx.sdk:telnyx:6.89.0")

客户端初始化：

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;

TelnyxClient client = TelnyxOkHttpClient.fromEnv();

文档中的示例均假设 client 已按上述方式初始化。

错误处理

所有 API 调用都可能因网络错误、速率限制（429）、校验错误（422）或认证错误（401）而失败。生产代码中应始终处理错误：

import com.telnyx.sdk.errors.TelnyxServiceException;

try {
    var result = client.messages().send(params);
} catch (TelnyxServiceException e) {
    System.err.println("API error " + e.statusCode() + ": " + e.getMessage());
    if (e.statusCode() == 422) {
        System.err.println("Validation error — check required fields and formats");
    } else if (e.statusCode() == 429) {
        // Rate limited — wait and retry with exponential backoff
        Thread.sleep(1000);
    }
}

常见错误码：401 无效 API key，403 权限不足，404 资源未找到，422 校验错误（检查字段格式），429 速率受限（使用指数退避重试）。

分页

列表方法返回一页数据。可使用 .autoPager() 自动迭代：for (var item : page.autoPager()) { ... }。如需手动控制，可使用 .hasNextPage() 与 .nextPage()。

主要能力

托管账户管理

列出当前用户管理的账户（GET /managed_accounts）。用户需经 Telnyx 明确批准才能成为管理账户。
创建新的托管账户（POST /managed_accounts），必填 business_name，可选 email、managed_account_allow_custom_pricing、password、rollup_billing。
查询当前用户可分配的全局出站通道信息（GET /managed_accounts/allocatable_global_outbound_channels），仅账户管理者可用。
检索单个托管账户详情（GET /managed_accounts/{id}）。
更新托管账户（PATCH /managed_accounts/{id}），可选 managed_account_allow_custom_pricing。
禁用托管账户（POST /managed_accounts/{id}/actions/disable），禁止其使用 Telnyx 服务（含收发电话与短信），进行中的通话不受影响，账户及其子用户将无法登录 mission control portal。
启用托管账户（POST /managed_accounts/{id}/actions/enable），可选 reenable_all_connections。
更新分配给特定托管账户的可分配全局出站通道数量（PATCH /managed_accounts/{id}/update_global_channel_limit），可选 channel_limit。

组织用户管理

列出组织中的用户（GET /organizations/users）。
获取组织用户分组报告（GET /organizations/users/users_groups_report），返回所有用户且不分页，始终包含分组信息，可通过 content-type 头以 JSON 或 CSV 格式获取。
获取组织中的单个用户（GET /organizations/users/{id}）。
删除组织中的用户（POST /organizations/users/{id}/actions/remove）。

适用场景

适用于需要以编程方式管理 Telnyx 子账户的经销商与企业开发者，例如批量创建、启用/禁用托管账户，调整全局出站通道配额，以及管理组织用户与查看用户分组报告。

限制

成为管理账户需经 Telnyx 明确批准。部分接口（如可分配全局出站通道查询）仅账户管理者可用。文档未提供收费、价格或平台支持等更多信息。