telnyx-account-python

用途

Telnyx Account - Python 是 Telnyx 官方技能包（team-telnyx/telnyx-skills）中的一个技能，提供使用 Python SDK 管理 Telnyx 账户相关功能的代码示例。它面向需要通过编程方式访问 Telnyx 账户财务、支付、发票、Webhook 与审计数据的开发者。

安装与初始化

安装命令：

pip install telnyx

初始化方式：

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
)

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

主要能力

该技能涵盖以下账户管理接口：

审计日志：GET /audit_events，列出审计日志条目。审计日志是尽力而为、最终一致的账户重要变更记录。返回字段包括 alternate_resource_id、change_made_by（枚举：telnyx、account_manager、account_owner、organization_member）、change_type、changes、created_at、id、organization_id、record_type、resource_id、user_id。
余额详情：GET /balance，获取用户余额详情。返回 available_credit、balance、credit_limit、currency、pending、record_type。
月度费用明细：GET /charges_breakdown，检索指定日期范围内电话号码的月度费用明细，日期范围不能超过 31 天。返回 currency、end_date、results、start_date、user_email、user_id。
月度费用汇总：GET /charges_summary，检索指定日期范围内的月度费用汇总，日期范围不能超过 31 天。返回 currency、end_date、start_date、summary、total、user_email、user_id。
明细记录搜索：GET /detail_records，搜索 Telnyx 平台上的任意明细记录。返回字段包括 carrier、carrier_fee、cld、cli、completed_at、cost、country_code、created_at、currency、delivery_status、direction、errors、fteu、mcc、message_type、mnc、on_net、parts、profile_id、profile_name、rate、record_type、sent_at、source_country_code、status、tags、updated_at、user_id、uuid 等。
发票列表：GET /invoices，检索分页发票列表。返回 file_id、invoice_id、paid、period_end、period_start、url。
发票详情：GET /invoices/{id}，按唯一标识符检索单张发票。返回 download_url、file_id、invoice_id、paid、period_end、period_start、url。
自动充值偏好列表：GET /payment/auto_recharge_prefs，返回支付自动充值偏好。返回 enabled、id、invoice_enabled、preference（枚举：credit_paypal、ach）、recharge_amount、record_type、threshold_amount。
更新自动充值偏好：PATCH /payment/auto_recharge_prefs，更新支付自动充值偏好。可选字段：enabled、invoice_enabled、preference、recharge_amount、threshold_amount。
用户标签列表：GET /user_tags，列出所有用户标签。返回 number_tags、outbound_profile_tags。
创建存储支付交易：POST /v2/payment/stored_payment_transactions，必填字段 amount。返回 amount_cents、amount_currency、auto_recharge、created_at、id、processor_status、record_type、transaction_processing_type。
Webhook 投递列表：GET /webhook_deliveries，列出已认证用户的 webhook_deliveries。返回 attempts、finished_at、id、record_type、started_at、status（枚举：delivered、failed）、user_id、webhook。
Webhook 投递详情：GET /webhook_deliveries/{id}，提供 webhook_delivery 调试数据，如时间戳、投递状态和尝试次数。返回字段同上。

使用方式

所有接口通过已初始化的 client 对象调用，例如：

balance = client.balance.retrieve()
print(balance.data)

列表方法返回自动分页迭代器，可使用 for item in page_result: 自动遍历所有页面。

错误处理

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

import telnyx

try:
    result = client.messages.send(to="+13125550001", from_="+13125550002", text="Hello")
except telnyx.APIConnectionError:
    print("Network error — check connectivity and retry")
except telnyx.RateLimitError:
    # 429: rate limited — wait and retry with exponential backoff
    import time
    time.sleep(1)  # Check Retry-After header for actual delay
except telnyx.APIStatusError as e:
    print(f"API error {e.status_code}: {e.message}")
    if e.status_code == 422:
        print("Validation error — check required fields and formats")

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

适用场景

该技能适用于需要以编程方式管理 Telnyx 账户财务与运营数据的场景，例如查询余额与费用、下载发票、管理自动充值、排查 Webhook 投递问题以及审计账户变更。

限制

费用明细与汇总的日期范围不能超过 31 天。审计日志为尽力而为、最终一致的记录。文档未提供其他限制、收费或价格信息。