Telnyx Numbers Compliance - Ruby 是 Telnyx 提供的 Ruby SDK 技能示例，用于在 Ruby 应用中管理电话号码的合规事务。该技能围绕监管要求、号码套餐、支持文档和已验证号码展开，提供可直接参考的 Ruby 代码示例。
用途 该技能面向需要通过 Telnyx API 处理电话号码合规流程的开发者，帮助完成监管要求的查询与提交、号码套餐的获取与管理、合规文档的上传与关联，以及用户地址的维护等操作。
安装与初始化 安装命令：gem install telnyx 初始化方式： require "telnyx" client = Telnyx::Client.new( api_key: ENV["TELNYX_API_KEY"], ) 后续所有示例均假设 client 已按上述方式初始化。
主要能力
- 套餐定价（Bundle Pricing）：列出所有可用套餐、按 ID 获取套餐、获取用户套餐列表、批量创建用户套餐、获取未使用的用户套餐、按 ID 获取用户套餐、停用用户套餐、获取用户套餐资源。
- 文档管理（Documents）：列出所有文档链接、列出所有文档、上传文档、检索文档、更新文档、删除文档、下载文档、生成临时下载链接。上传的文档必须在 30 分钟内关联到服务，否则会被自动删除；文档只有在未关联服务时才能删除。
- 监管要求（Regulatory Requirements）：更新电话号码订单的要求组、检索电话号码列表的监管要求、检索监管要求、列出要求组、创建要求组、按 ID 获取要求组、更新要求组中的要求值、按 ID 删除要求组、提交要求组以供审批、列出所有要求类型、检索要求类型、列出所有要求、检索文档要求。
- 子号码订单（Sub Number Orders）：更新子号码订单的要求组。
- 用户地址（User Addresses）：列出所有用户地址、创建用户地址。
使用方式 所有 API 调用均通过已初始化的 client 对象进行。电话号码必须使用 E.164 格式（例如 +13125550001），包含 + 前缀和国家代码，不能包含空格、短横线或括号。分页可使用 .auto_paging_each 进行自动迭代：page.auto_paging_each { |item| puts item.id }。
错误处理 所有 API 调用都可能因网络错误、限流（429）、校验错误（422）或认证错误（401）而失败。生产代码中应始终处理错误： begin result = client.messages.send_(to: "+13125550001", from: "+13125550002", text: "Hello") rescue Telnyx::Errors::APIConnectionError puts "Network error — check connectivity and retry" rescue Telnyx::Errors::RateLimitError sleep(1) rescue Telnyx::Errors::APIStatusError => e puts "API error #{e.status}: #{e.message}" if e.status == 422 puts "Validation error — check required fields and formats" end end 常见错误码：401 无效 API Key，403 权限不足，404 资源未找到，422 校验错误，429 限流（建议使用指数退避重试）。
适用场景 适用于需要在 Ruby 项目中集成 Telnyx 电话号码合规管理能力的场景，例如批量管理号码套餐、上传并关联合规文档、创建和提交监管要求组、维护用户地址等。
限制 该技能仅提供 Ruby SDK 示例，具体 API 行为、可用性及计费信息以 Telnyx 官方为准。文档上传后需在 30 分钟内关联服务，否则自动删除；文档删除前必须先解除与服务关联。电话号码必须为 E.164 格式。