SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场telnyx-porting-in-javascript

telnyx-porting-in-javascript

编程与开发

查看项目

更新于 10-16 05:25

技能介绍

用途

Telnyx Porting In - JavaScript 是 Telnyx 提供的 JavaScript SDK 技能，用于在 JavaScript/Node.js 应用中集成电话号码携入（Port In）Telnyx 平台的完整流程。它封装了 Telnyx 携号转网相关 API，使开发者能够以编程方式检查号码可携性、创建和管理携入订单、处理 LOA 文档、跟踪携入状态并生成报告。

安装与初始化

安装命令：

npm install telnyx

初始化客户端：

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});

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

主要能力

可携性检查

运行可携性检查并立即返回结果（POST /portability_checks）。可传入 phone_numbers 数组，返回 fast_portable、not_portable_reason、phone_number、portable、record_type 等字段。

携入事件

  • 列出所有携入事件（GET /porting/events），返回 available_notification_methods、event_type、id、payload、payload_status、porting_order_id 等。
  • 查看指定携入事件（GET /porting/events/{id}）。
  • 重发指定携入事件（POST /porting/events/{id}/republish）。

LOA 配置

  • 列出 LOA 配置（GET /porting/loa_configurations）。
  • 创建 LOA 配置（POST /porting/loa_configurations），需提供 address、company_name、contact、logo、name 等。
  • 预览 LOA 配置参数（POST /porting/loa_configurations/preview），无需创建配置即可预览将生成的 LOA 模板。
  • 检索指定 LOA 配置（GET /porting/loa_configurations/{id}）。
  • 更新指定 LOA 配置（PATCH /porting/loa_configurations/{id}）。
  • 删除指定 LOA 配置（DELETE /porting/loa_configurations/{id}）。
  • 预览指定 LOA 配置（GET /porting/loa_configurations/{id}/preview）。

携入报告

  • 列出携入相关报告（GET /porting/reports），返回 created_at、document_id、id、params、record_type、report_type、status、updated_at。
  • 创建携入相关报告（POST /porting/reports），report_type 为 export_porting_orders_csv。
  • 检索指定报告（GET /porting/reports/{id}）。

英国运营商

列出英国可用运营商（GET /porting/uk_carriers），返回 alternative_cupids、created_at、cupid、id、name、record_type、updated_at。

携入订单

  • 列出所有携入订单（GET /porting_orders），返回 activation_settings、additional_steps、created_at、customer_group_reference、customer_reference、description、documents、end_user、id、messaging、misc、old_service_provider_ocn、parent_support_key、phone_number_configuration、phone_number_type、phone_numbers、porting_phone_numbers_count、record_type、requirements、requirements_met、status、support_key、updated_at、user_feedback、user_id、webhook_url 等字段。
  • 创建携入订单（POST /porting_orders），必填 phone_numbers，可选 customer_group_reference、customer_reference。
  • 列出所有异常类型（GET /porting_orders/exception_types），返回 code 与 description，code 枚举包括 ACCOUNT_NUMBER_MISMATCH、AUTH_PERSON_MISMATCH、BTN_ATN_MISMATCH、ENTITY_NAME_MISMATCH、FOC_EXPIRED、FOC_REJECTED、LOCATION_MISMATCH、LSR_PENDING、MAIN_BTN_PORTING、OSP_IRRESPONSIVE、OTHER、PASSCODE_PIN_INVALID、PHONE_NUMBER_HAS_SPECIAL_FEATURE、PHONE_NUMBER_MISMATCH、PHONE_NUMBER_NOT_PORTABLE、PORT_TYPE_INCORRECT、PORTING_ORDER_SPLIT_REQUIRED、POSTAL_CODE_MISMATCH、RATE_CENTER_NOT_PORTABLE、SV_CONFLICT、SV_UNKNOWN_FAILURE。
  • 列出所有电话号码配置（GET /porting_orders/phone_number_configurations）。
  • 创建电话号码配置列表（POST /porting_orders/phone_number_configurations）。
  • 检索指定携入订单（GET /porting_orders/{id}）。
  • 编辑指定携入订单（PATCH /porting_orders/{id}），可选字段包括 activation_settings、customer_group_reference、customer_reference、documents、end_user、messaging、misc、phone_number_configuration、requirement_group_id、requirements、user_feedback、webhook_url。
  • 删除指定携入订单（DELETE /porting_orders/{id}），仅限 draft 状态的订单。
  • 异步激活携入订单中的每个号码（POST /porting_orders/{id}/actions/activate），仅限美国 FastPort 订单。
  • 取消携入订单（POST /porting_orders/{id}/actions/cancel）。

使用方式

所有 API 调用均通过已初始化的 client 对象进行。电话号码必须使用 E.164 格式（例如 +13125550001），包含 + 前缀和国家代码，不能包含空格、短横线或括号。列表方法返回自动分页迭代器，可使用 for await (const item of result) { ... } 自动遍历所有页面。

错误处理

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

try {
  const result = await client.messages.send({ to: '+13125550001', from: '+13125550002', text: 'Hello' });
} catch (err) {
  if (err instanceof Telnyx.APIConnectionError) {
    console.error('Network error — check connectivity and retry');
  } else if (err instanceof Telnyx.RateLimitError) {
    // 429: rate limited — wait and retry with exponential backoff
    const retryAfter = err.headers?.['retry-after'] || 1;
    await new Promise(r => setTimeout(r, retryAfter * 1000));
  } else if (err instanceof Telnyx.APIError) {
    console.error(`API error ${err.status}: ${err.message}`);
    if (err.status === 422) {
      console.error('Validation error — check required fields and formats');
    }
  }
}

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

适用场景

适用于需要在 JavaScript/Node.js 应用中自动化电话号码携入流程的场景，例如批量提交携入订单、自动生成与预览 LOA 文档、跟踪携入事件与状态、导出携入订单报告，以及查询英国运营商信息等。

限制

  • 电话号码必须为 E.164 格式。
  • 删除携入订单仅限 draft 状态。
  • 异步激活操作仅限美国 FastPort 订单。
  • 关于收费、价格、平台支持范围等更多信息，资料中暂未提供。