telnyx-numbers-ruby

用途

Telnyx Numbers - Ruby 是 Telnyx 面向 Ruby 开发者的电话号码管理技能文档，用于在 Ruby 应用中通过 Telnyx API 搜索、订购和管理电话号码。它覆盖从号码可用性查询到生产环境号码开通的完整流程。

安装与初始化

安装命令：

gem install telnyx

初始化示例：

require "telnyx"

client = Telnyx::Client.new( api_key: ENV["TELNYX_API_KEY"], # This is the default and can be omitted )

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

主要能力

核心任务

搜索可用电话号码：client.available_phone_numbers.list() — GET /available_phone_numbers。支持 filter 参数（deepObject 风格）。返回 items（available_phone_numbers.data）与 pagination（available_phone_numbers.meta）。主要字段包括 phone_number、record_type、quickship、reservable、best_effort、cost_information。
创建号码订单：client.number_orders.create() — POST /number_orders。必填参数 phone_numbers（array[object]）；可选参数包括 connection_id、messaging_profile_id、billing_group_id 等。主要响应字段包括 number_order.data.id、status、phone_numbers_count、requirements_met、messaging_profile_id、connection_id。
查询号码订单状态：client.number_orders.retrieve() — GET /number_orders/{number_order_id}。必填参数 number_order_id（UUID）。主要响应字段包括 id、status、requirements_met、phone_numbers_count、phone_numbers、connection_id。

重要支持操作

创建号码预留：client.number_reservations.create() — POST /number_reservations。必填 phone_numbers；可选 status（enum: pending, success, failure）、id、record_type 等。
查询号码预留：client.number_reservations.retrieve() — GET /number_reservations/{number_reservation_id}。
列出高级订单：client.advanced_orders.list() — GET /advanced_orders。
创建高级订单：client.advanced_orders.create() — POST /advanced_orders。可选参数包括 phone_number_type（enum: local, mobile, toll_free, shared_cost, national, ...）、requirement_group_id、country_code 等。
更新高级订单：client.advanced_orders.update_requirement_group() — PATCH /advanced_orders/{advanced-order-id}/requirement_group。
获取高级订单：client.advanced_orders.retrieve() — GET /advanced_orders/{order_id}。
列出可用号码块：client.available_phone_number_blocks.list() — GET /available_phone_number_blocks。
检索所有评论：client.comments.list() — GET /comments。

附加操作

文档还列出了更多操作，包括：创建/检索评论、标记评论已读、获取国家覆盖范围、获取特定国家覆盖、客户服务记录（CSR）的列表/创建/验证/检索、非显式号码订单、库存覆盖请求、移动网络运营商、网络覆盖位置、号码块订单、号码订单电话号码、子号码订单及其报告等。每个操作均给出 SDK 方法、端点、使用场景与必填参数。

使用方式

电话号码必须为 E.164 格式（例如 +13125550001），包含 + 前缀和国家代码，不能有空格、短横线或括号。
分页：使用 .auto_paging_each 自动迭代，例如 page.auto_paging_each { |item| puts item.id }。
错误处理：所有 API 调用可能因网络错误、速率限制（429）、验证错误（422）或认证错误（401）而失败。常见错误码：401 无效 API 密钥，403 权限不足，404 资源未找到，422 验证错误（检查字段格式），429 速率受限（使用指数退避重试）。
参考使用规则：不要臆造 Telnyx 参数、枚举、响应字段或 webhook 字段。若所需参数、枚举或响应字段未在技能中内联展示，请在编写代码前阅读 references/api-details.md。使用 ## Additional Operations 中的任何操作前，请阅读可选参数部分和响应模式部分。

适用场景

适用于需要在 Ruby 应用中集成 Telnyx 电话号码管理能力的开发者，例如：按位置、功能和覆盖范围搜索号码，创建号码订单并跟踪开通状态，管理号码预留与高级订单，查询国家覆盖范围与客户服务记录等。

限制

文档未提供关于收费、价格、平台支持范围或具体效果的信息。部分操作的可选参数与响应模式需查阅 references/api-details.md 获取完整内容。