telnyx-numbers-compliance-javascript

用途

本技能面向使用 Telnyx 平台进行电话号码合规管理的开发者，提供基于 JavaScript SDK 的接口调用示例。它覆盖监管要求（regulatory requirements）、号码套餐（billing bundles / user bundles）、支持文档（documents）以及已验证号码等合规相关资源的操作。

安装与初始化

安装指定版本 SDK：

npm install telnyx@6.74.2

初始化客户端：

import Telnyx from 'telnyx';

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

后续所有示例均假设 client 已按上述方式初始化。

错误处理

所有 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 速率限制（使用指数退避重试）。

重要说明

电话号码必须使用 E.164 格式（例如 +13125550001），包含 + 前缀和国家代码，不能有空格、短横线或括号。
分页：列表方法返回自动分页迭代器，使用 for await (const item of result) { ... } 自动遍历所有页面。

主要能力

套餐定价（Bundle Pricing）

获取所有允许的套餐：GET /bundle_pricing/billing_bundles，返回 cost_code、created_at、currency、id、is_public、mrc_price、name、slug、specs 等字段。
按 ID 获取单个套餐：GET /bundle_pricing/billing_bundles/{bundle_id}，返回 active、bundle_limits、cost_code、created_at、id、is_public、name、slug 等字段。
获取用户套餐列表：GET /bundle_pricing/user_bundles，返回 active、billing_bundle、created_at、id、resources、updated_at、user_id 等字段。
批量创建用户套餐：POST /bundle_pricing/user_bundles/bulk，可选参数 idempotency_key、items。
获取未使用的用户套餐：GET /bundle_pricing/user_bundles/unused，返回 billing_bundle、user_bundle_ids。
按 ID 获取用户套餐：GET /bundle_pricing/user_bundles/{user_bundle_id}。
停用用户套餐：DELETE /bundle_pricing/user_bundles/{user_bundle_id}。
获取用户套餐资源：GET /bundle_pricing/user_bundles/{user_bundle_id}/resources，返回 created_at、id、resource、resource_type、updated_at。

文档（Documents）

列出所有文档链接：GET /document_links，返回 created_at、document_id、id、linked_record_type、linked_resource_id、record_type、updated_at。
列出所有文档：GET /documents，返回 av_scan_status、content_type、created_at、customer_reference、filename、id、record_type、sha256、size、status、updated_at。
上传文档：POST /documents，可选参数 customer_reference、file、filename、url。上传的文件必须在 30 分钟内关联到某个服务，否则会被自动删除。
检索文档：GET /documents/{id}。
更新文档：PATCH /documents/{id}。
删除文档：DELETE /documents/{id}。文档只有在未关联服务时才能删除；若已关联，必须先解除关联。
下载文档：GET /documents/{id}/download。
生成临时下载链接：GET /documents/{id}/download_link，返回预签名 URL，可直接从存储后端下载而无需认证。

监管要求（Regulatory Requirements）

更新电话号码订单的要求组：POST /number_order_phone_numbers/{id}/requirement_group，必填 requirement_group_id。
检索一组电话号码的监管要求：GET /phone_numbers_regulatory_requirements，返回 phone_number、phone_number_type、record_type、region_information、regulatory_requirements。
检索监管要求：GET /regulatory_requirements，返回 action、country_code、phone_number_type、regulatory_requirements。

要求组（Requirement Groups）

列出要求组：GET /requirement_groups。
创建要求组：POST /requirement_groups，必填 country_code、phone_number_type、action，可选 customer_reference、regulatory_requirements。返回 action、country_code、created_at、customer_reference、id、phone_number_type、record_type、regulatory_requirements、status（approved、unapproved、pending-approval、declined、expired）、updated_at。
按 ID 获取要求组：GET /requirement_groups/{id}。
更新要求组中的要求值：PATCH /requirement_groups/{id}，可选 customer_reference、regulatory_requirements。
按 ID 删除要求组：DELETE /requirement_groups/{id}。
提交要求组审批：POST /requirement_groups/{id}/submit_for_approval。

要求类型与要求（Requirement Types / Requirements）

列出所有要求类型：GET /requirement_types，返回 acceptance_criteria、created_at、description、example、id、name、record_type、type（document、address、textual）、updated_at。
按 ID 检索要求类型：GET /requirement_types/{id}。
列出所有要求（支持过滤、排序、分页）：GET /requirements，返回 action（both、branded_calling、ordering、porting）、country_code、created_at、id、locality、phone_number_type（local、national、toll_free）、record_type、requirements_types、updated_at。
检索文档要求记录：GET /requirements/{id}。

子号码订单（Sub Number Orders）

更新子号码订单的要求组：POST /sub_number_orders/{id}/requirement_group，必填 requirement_group_id。返回 country_code、created_at、customer_reference、id、is_block_sub_number_order、order_request_id、phone_number_type、phone_numbers、phone_numbers_count、record_type、regulatory_requirements、requirements_met、status、updated_at 等字段。

使用方式

开发者需先安装 telnyx@6.74.2 并初始化客户端，然后按上述接口调用对应方法。列表接口返回自动分页迭代器，可直接用 for await 遍历。所有电话号码参数须为 E.164 格式。生产环境应实现错误处理，特别是对 429 速率限制使用指数退避重试。

适用场景

适用于需要在 Telnyx 平台上管理电话号码合规流程的 JavaScript/Node.js 应用，例如：查询和创建号码套餐、上传和管理合规支持文档、创建和提交监管要求组、查询特定号码或地区的监管要求、更新订单或子订单的要求组等。

限制

文档上传后必须在 30 分钟内关联到服务，否则自动删除。
文档只有在未关联服务时才能删除，已关联的必须先解除关联。
电话号码必须使用 E.164 格式。
本技能仅提供 JavaScript SDK 示例，其他语言或平台的支持情况暂未提供。
关于收费、价格、具体平台支持范围等信息，资料中暂未提供。