Skip to main content
账单 API 使用团队 AK/SK 的 HMAC 签名,不接受 OAuth Token、用户 API Key 或成员 Bearer Token。基础路径:/open/v1/team/billing 本组接口不检查当前是否拥有 ACTIVE Open 权益。只要团队凭证有效并具有所需 Scope,即可查询其所属团队的开放能力历史账单。查询不会开通权益、触发出账或执行积分扣减;没有开放能力账单时返回空列表或零汇总。

Scope

团队 AK/SK 需显式配置该 Scope;已有 team.member.readteam.entitlement.usage.read 权限不包含账单查询权限。

通用参数与查询口径

三个接口均为 POST,请求体为 JSON,使用 Content-Type: application/json 时间格式为 YYYY-MM-DDTHH:mm:ss,允许附带 1 至 9 位小数秒,如 2026-09-01T00:00:00.123456789。使用计费服务的本地时间口径,不带 Z+08:00 等时区后缀,也不接受 Unix 时间戳。API 不重算或转换时间,不默认取当前账期。 查询以账单的 period_start 为筛选依据,即 start_time <= period_start < end_time,不是按扣款时间或账单创建时间筛选,也不会拆分横跨时间边界的账单。 主账号由服务端从 AK/SK 所属团队解析。不接受 openIdowner_id、内部用户 ID 等额外字段。三个接口均只查询 OPEN_CAPABILITY 场景的已生成账单,不含尚未出账的实时用量。所有结算状态均参与查询,包括 PENDING;不支持直接传入计量项或结算状态过滤条件;账单流水 /flow 支持使用权益编码 entitlement_code 筛选。

查询团队或成员账单流水

所需 Scope:team.billing.read 除通用时间参数外,支持以下参数: 成员 ID 使用团队成员 API 返回的真实公开编号,不能传内部用户 ID 或阿里云 OpenID。冻结或标记删除的成员仍可查;成员不存在或属于其他团队时返回 404。null、空字符串不等同于省略成员筛选。非法分页值直接返回 400,不进行取整或截断。 权益筛选由 billing 读取同库 entitlement_type,将 code 转换为 metering_item_code 后用于账单查询;列表和 total 使用相同条件,可与成员筛选组合。传计量项编码不能代替权益编码,例如查询项目数量应使用 max_projects,不是 project_count。权益编码按配置读取,不局限于权益用量 API 的 7 项白名单。 null、空字符串、首尾空白、未知权益或未配置计量项返回 400;有效权益没有账单时返回空列表。筛选不会检查该权益当前是否已开通。 响应示例:
示例编号、用量、积分及业务类型仅作展示,以实际账单返回值为准。 响应字段 账单明细字段 两个流水接口均回填权益字段。权益编码和名称来自查询时的配置,不是出账时快照;配置调整可能改变历史账单的展示与筛选归类。找不到映射时保留账单,两个字段均为 null;配置重复、配置无效或字典读取失败返回 503,不随意选择权益或伪造空映射。项目模型示例展示未配置映射的情况;是否映射为某个权益以实际配置为准。 所有时间均保留计费服务返回的本地时间口径。积分使用计费服务原始整数,不进行人民币换算或倍率转换。数值须在 JavaScript 安全整数范围内;无法无损表达的积分或分页总数返回 503,不静默舍入。成员 ID 始终按精确字符串处理。 无记录时 items[];超出最后一页也返回空列表,total 仍表示总记录数。列表与总数不是事务快照,出账或结算并发时结果可能变化;跨页查询期间新增账单可能导致重复或位移。

查询团队或成员积分汇总

所需 Scope:team.billing.read。支持通用时间参数及可选 member_id,成员规则与流水接口一致。不支持分页或 entitlement_code 参数;省略 member_id 查询团队汇总。按权益过滤后的流水合计不能直接与未过滤的汇总比较。
汇总来自正式账单,不按主账号积分流水拆分成员费用。延迟结算时出现待扣减积分是正常现象;pending_points 可以为负数,API 不做归零处理,以保留扣减超出账单金额等异常信号。无账单时三项均为 0。本接口不返回积分余额、额度或未出账用量。

查询项目模型账单流水

所需 Scope:team.billing.readproject_id 必填,使用项目 API 返回的公开 url_id,不是数据库主键;其余时间及分页参数与流水接口一致。不支持 member_identitlement_code 或计量项筛选。 只查询当前团队项目的 llm_token 模型账单,包含尚未扣减的账单。项目不存在或属于其他团队时返回 404;仍保留项目记录的冻结或软删除项目可查询历史账单。 响应结构及字段与账单流水接口相同。例如:
沙箱、应用访问、云资源等账单按成员小时聚合,无法准确归属到项目,因此本接口不代表项目全部费用。

常见错误

错误响应使用 application/problem+json
下游失败不返回部分账单,不降级为空列表或零汇总。排查时请提供 trace_id HMAC 方法与调用流程见团队系统集成指南。签名时使用实际的 /open/v1/team/billing/... 路径与发送的 JSON 请求体;三个接口分别签名,不能复用其他路径的签名。

权益字段升级与发布顺序

先发布 billing,再发布 oneday-api。旧调用方不传新增筛选参数时仍按原口径查询;OpenAPI 对旧 billing 缺少的两个权益字段输出 null,但旧 billing 不支持权益筛选,不能在仅升级 API 的情况下启用该参数。若下游返回的非空账单不符合请求的权益编码,OpenAPI 返回 503。 回滚时先回滚 API 再回滚 billing。无数据库变更、无新增外部组件依赖;仅以只读方式访问现有 entitlement_type,不修改字典、索引或历史账单,不复用通用 BillingService,也不新增 ACTIVE Open 权益校验。