用途
Telnyx Numbers - Java 是 Telnyx 官方 Java SDK 中面向电话号码管理的技能模块，用于在 Java 应用中搜索、订购和管理电话号码。它覆盖从号码搜索、下单、预留到订单状态查询的完整流程，并支持高级订单、号码块、评论、国家覆盖、客户服务记录等配套资源的管理。
主要能力
- 搜索可用电话号码：通过 client.availablePhoneNumbers().list() 调用 GET /available_phone_numbers，支持按位置、功能和覆盖范围筛选，返回 phoneNumber、recordType、quickship、reservable、bestEffort、costInformation 等字段。
- 创建号码订单：通过 client.numberOrders().create() 调用 POST /number_orders，可指定 phoneNumbers（必填）、connectionId、messagingProfileId、billingGroupId 等参数，返回订单 ID、状态、号码数量、requirementsMet 等信息。
- 查询号码订单状态：通过 client.numberOrders().retrieve() 调用 GET /number_orders/{number_order_id}，用于判断配置是否完成或是否仍有未满足的要求。
- 号码预留：通过 client.numberReservations().create() 和 retrieve() 创建与查询号码预留，返回状态、创建/更新时间、customerReference、errors 等。
- 高级订单：支持列表、创建、更新需求组、查询等操作（client.advancedOrders()），涉及 phoneNumberType、requirementGroupId、countryCode 等参数。
- 号码块：支持列出可用号码块（client.availablePhoneNumberBlocks().list()）以及号码块订单的列表、创建、查询（client.numberBlockOrders()）。
- 评论管理：支持创建、查询、标记已读、列出评论（client.comments()）。
- 覆盖与记录：支持国家覆盖查询（client.countryCoverage()）、客户服务记录（client.customerServiceRecords()）、库存覆盖请求（client.inventoryCoverage()）、移动网络运营商列表（client.mobileNetworkOperators()）、网络覆盖位置（client.networkCoverage()）等。
- 其他订单：支持 inexplicit number orders 的列表、创建、查询，以及号码订单关联电话号码的列表与查询。
使用方式
安装依赖：
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）而失败，生产代码中应始终处理错误。常见错误码：401 无效 API 密钥，403 权限不足，404 资源未找到，422 验证错误（检查字段格式），429 速率受限（使用指数退避重试）。
重要说明：电话号码必须使用 E.164 格式（例如 +13125550001），包含 + 前缀和国家代码，不能有空格、短横线或括号。分页方面，列表方法返回一页，可使用 .autoPager() 自动迭代：for (var item : page.autoPager()) { ... }；手动控制可使用 .hasNextPage() 和 .nextPage()。
参考使用规则：不要臆造 Telnyx 参数、枚举、响应字段或 webhook 字段。如果所需参数、枚举或响应字段未在本技能中内联展示，请在编写代码前阅读 references/api-details.md。在使用“Additional Operations”中的任何操作前，请先阅读可选参数部分和响应模式部分。
适用场景
适用于需要在 Java 应用中自动化电话号码采购与库存管理的场景，例如电信平台、通信服务、呼叫中心系统等，需要按位置、功能或覆盖范围搜索号码、批量下单、预留号码并跟踪订单状态。
限制
资料未提供具体的收费、价格、平台支持范围或效果数据。部分操作的可选参数、响应模式及低频 webhook 负载未在技能内联展示，需查阅 references/api-details.md。