telnyx-account-reports-java

Telnyx Account Reports - Java 是 Telnyx 官方提供的 Java 技能示例，用于生成和获取用量报告，服务于计费、分析与对账场景。以下按用途、主要能力、使用方式、适用场景和限制分段说明。

【用途】 该技能面向使用 Java 的开发者，展示如何调用 Telnyx Java SDK 中的报表相关接口，以获取计费与用量数据，用于账务核算、使用分析和数据对账。

【主要能力】 示例覆盖以下接口类别：

1. 通话事件：GET /call_events，可按过滤参数查询通话事件（默认仅最近 24 小时，除非指定 leg_id 或 application_session_id）。返回字段含 call_leg_id、call_session_id、event_timestamp、metadata、name、record_type、type。
2. 账本计费组报告：POST /ledger_billing_group_reports 创建（可选 month、year），GET /ledger_billing_group_reports/{id} 获取。返回 created_at、id、organization_id、record_type、report_url、status、updated_at。
3. 消息详细记录（MDR）报告：GET /legacy/reporting/batch_detail_records/messaging 列出全部请求；POST 创建（必填 start_time、end_time，可选 connections、directions、filters、include_message_body、managed_accounts、profiles、record_types、report_name、select_all_managed_accounts、timezone）；GET /{id} 获取；DELETE /{id} 删除。状态枚举为 PENDING、COMPLETE、FAILED、EXPIRED。
4. 通话详细记录（CDR）报告：GET /legacy/reporting/batch_detail_records/voice 列出全部请求；POST 创建（必填 start_time、end_time，可选 call_types、connections、fields、filters、include_all_metadata、managed_accounts、record_types、report_name、select_all_managed_accounts、source、timezone）；GET /{id} 获取；DELETE /{id} 删除；GET /voice/fields 获取 CDR 可用字段，返回 Billing、Interaction Data、Number Information、Telephony Data 四组。
5. 用量报告：MDR 用量报告支持列表、创建（可选 aggregation_type）、查询、删除；号码查询用量报告支持列表 GET /legacy/reporting/usage_reports/number_lookup 与提交 POST。

【使用方式】

1. 安装依赖： Maven： <dependency> <groupId>com.telnyx.sdk</groupId> <artifactId>telnyx</artifactId> <version>6.89.0</version> </dependency> Gradle： implementation("com.telnyx.sdk:telnyx:6.89.0")
2. 初始化客户端： import com.telnyx.sdk.client.TelnyxClient; import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient; TelnyxClient client = TelnyxOkHttpClient.fromEnv();
3. 错误处理：使用 TelnyxServiceException 捕获异常，常见状态码为 401（无效 API 密钥）、403（权限不足）、404（资源不存在）、422（校验错误）、429（限流，建议指数退避重试）。
4. 分页：列表方法返回一页，可用 page.autoPager() 自动遍历，或通过 .hasNextPage() 与 .nextPage() 手动控制。

【适用场景】

• 需要以编程方式生成 Telnyx 计费或用量报表以便核算与对账的 Java 应用。
• 需要拉取通话事件、MDR、CDR 明细用于内部分析或数据导出。
• 需要自动化获取报表文件链接（report_url）并交由后续流程处理。

【限制】 资料未提供除上述接口示例之外的更多信息（如价格、配额、SLA、平台运行环境要求等）。通话事件查询在未指定 leg_id 或 application_session_id 时仅返回最近 24 小时数据。所有示例均假设 client 已按上文初始化。