Telnyx Numbers - curl 是面向 Telnyx 电话号码管理 API 的 curl 命令行使用技能，帮助开发者通过 HTTP 请求完成电话号码的搜索、订购与管理。
用途 该技能用于在 Telnyx 平台上按位置、功能和覆盖范围搜索可用电话号码，并完成号码订购、预留、订单状态查询等号码生命周期管理操作。
安装与认证 curl 在 macOS、Linux 和 Windows 10+ 上已预装，无需额外安装。使用前需设置环境变量： export TELNYX_API_KEY="YOUR_API_KEY_HERE" 所有示例均使用 $TELNYX_API_KEY 进行认证，请求头为 Authorization: Bearer $TELNYX_API_KEY。
主要能力 核心任务包括：
- 搜索可用电话号码：GET /available_phone_numbers，支持 filter 参数（deepObject 风格），返回 items（.data）和分页信息（.meta），主要字段有 phone_number、record_type、quickship、reservable、best_effort、cost_information。
- 创建号码订单：POST /number_orders，必填 phone_numbers 数组，可选 connection_id、messaging_profile_id、billing_group_id 等，返回 .data.id、.data.status、.data.phone_numbers_count、.data.requirements_met 等。
- 查询号码订单状态：GET /number_orders/{number_order_id}，返回订单状态、需求满足情况、号码数量与列表等。
重要支持操作包括：创建与查询号码预留（POST/GET /number_reservations）、高级订单的列表、创建、更新与查询（GET/POST/PATCH /advanced_orders）、可用号码块查询（GET /available_phone_number_blocks）、评论的列表与检索（GET /comments）等。
附加操作覆盖评论创建与标记已读、国家覆盖范围查询、客户服务记录、隐式号码订单、库存覆盖请求、移动网络运营商、网络覆盖位置、号码块订单、号码订单中的电话号码管理、子号码订单及其报告、号码功能查询、号码块任务等。
Webhook 事件包括 numberOrderStatusUpdate（number.order.status.update），用于号码订单状态更新通知。
使用方式 所有请求通过 curl 发送至 https://api.telnyx.com/v2/ 下的对应端点。电话号码必须使用 E.164 格式（例如 +13125550001），包含 + 前缀和国家代码，不能包含空格、短横线或括号。列表端点返回分页结果，使用 page[number] 和 page[size] 查询参数翻页，并检查响应中的 meta.total_pages。
错误处理 所有 API 调用可能因网络错误、速率限制（429）、验证错误（422）或认证错误（401）而失败，生产代码中应始终处理错误。常见错误码：401 无效 API 密钥，403 权限不足，404 资源未找到，422 验证错误（检查字段格式），429 速率受限（使用指数退避重试）。
参考使用规则 不得臆造 Telnyx 参数、枚举、响应字段或 webhook 字段。如果所需参数、枚举或响应字段未在本技能中内联展示，在编写代码前应阅读 references/api-details.md。在使用“附加操作”中的任何操作前，需阅读可选参数部分和响应模式部分。
适用场景 适用于需要通过命令行或脚本自动化管理 Telnyx 电话号码的开发者，包括号码搜索与采购、订单状态跟踪、号码预留、覆盖范围查询、号码块管理以及子号码订单报告等场景。
限制 该技能为 curl 使用指南，不包含 SDK 封装；部分操作仅提供 HTTP 端点，未提供完整可选参数与响应模式，需查阅 references/api-details.md。未在资料中明确的功能、收费、价格、平台或效果暂未提供。