telnyx-numbers-compliance-javascript

用途

Telnyx Numbers Compliance - JavaScript 是一个面向 Telnyx 平台的 JavaScript SDK 技能，用于管理电话号码合规相关的监管要求、号码套餐、支持文档以及已验证号码。它通过 telnyx npm 包提供对 Telnyx 合规相关 API 的调用示例。

安装与初始化

安装命令：

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 已按上述方式初始化。

错误处理

所有 API 调用都可能因网络错误、速率限制（429）、验证错误（422）或认证错误（401）而失败。生产代码中应始终处理错误。文档给出的处理方式包括：

Telnyx.APIConnectionError：网络错误，检查连接并重试。
Telnyx.RateLimitError：429 速率限制，等待并使用指数退避重试，可通过 err.headers?.['retry-after'] 获取等待时间。
Telnyx.APIError：其他 API 错误，包含 status 与 message；422 表示验证错误，需检查必填字段与格式。

常见错误码：401 无效 API 密钥，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 降序排列。
列出所有文档：GET /documents，按 created_at 降序排列，返回 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 & Requirement Groups）

更新电话号码订单的要求组：POST /number_order_phone_numbers/{id}/requirement_group，必填 requirement_group_id。
检索一组电话号码的监管要求：GET /phone_numbers_regulatory_requirements。
检索监管要求：GET /regulatory_requirements。
列出要求组：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}。
按 ID 删除要求组：DELETE /requirement_groups/{id}。
提交要求组审批：POST /requirement_groups/{id}/submit_for_approval。
列出所有要求类型：GET /requirement_types，按 created_at 降序排列，返回 acceptance_criteria、created_at、description、example、id、name、record_type、type（document、address、textual）、updated_at。
检索要求类型：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}。
更新子号码订单的要求组：POST /sub_number_orders/{id}/requirement_group，必填 requirement_group_id。

使用方式

通过 npm 安装 telnyx 包，使用 API 密钥初始化客户端，然后调用 client 上对应的资源方法（如 client.bundlePricing.billingBundles.list()、client.documents.uploadJson()、client.requirementGroups.create() 等）。列表方法支持自动分页迭代。所有电话号码需使用 E.164 格式。

适用场景

适用于需要在 JavaScript/Node.js 应用中集成 Telnyx 电话号码合规管理的开发者，包括管理号码套餐、上传与关联合规文档、创建与提交监管要求组、查询监管要求等场景。

限制

电话号码必须为 E.164 格式。
上传的文档必须在 30 分钟内链接到服务，否则自动删除。
文档只有在未链接到服务时才能删除。
需处理网络错误、速率限制、验证错误和认证错误。
关于收费、价格、平台支持范围等具体信息，资料中暂未提供。