/open/v1/team/billing。
本组接口不检查当前是否拥有 ACTIVE Open 权益。只要团队凭证有效并具有所需 Scope,即可查询其所属团队的开放能力历史账单。查询不会开通权益、触发出账或执行积分扣减;没有开放能力账单时返回空列表或零汇总。
Scope
团队 AK/SK 需显式配置该 Scope;已有
team.member.read 或 team.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 所属团队解析。不接受 openId、owner_id、内部用户 ID 等额外字段。三个接口均只查询 OPEN_CAPABILITY 场景的已生成账单,不含尚未出账的实时用量。所有结算状态均参与查询,包括 PENDING;不支持直接传入计量项或结算状态过滤条件;账单流水 /flow 支持使用权益编码 entitlement_code 筛选。
查询团队或成员账单流水
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 仍表示总记录数。列表与总数不是事务快照,出账或结算并发时结果可能变化;跨页查询期间新增账单可能导致重复或位移。
查询团队或成员积分汇总
team.billing.read。支持通用时间参数及可选 member_id,成员规则与流水接口一致。不支持分页或 entitlement_code 参数;省略 member_id 查询团队汇总。按权益过滤后的流水合计不能直接与未过滤的汇总比较。
汇总来自正式账单,不按主账号积分流水拆分成员费用。延迟结算时出现待扣减积分是正常现象;
pending_points 可以为负数,API 不做归零处理,以保留扣减超出账单金额等异常信号。无账单时三项均为 0。本接口不返回积分余额、额度或未出账用量。
查询项目模型账单流水
team.billing.read。project_id 必填,使用项目 API 返回的公开 url_id,不是数据库主键;其余时间及分页参数与流水接口一致。不支持 member_id、entitlement_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 权益校验。
