> ## Documentation Index > Fetch the complete documentation index at: https://docs.meoo.com/llms.txt > Use this file to discover all available pages before exploring further. # 账单 API 账单 API 使用团队 AK/SK 的 HMAC 签名，不接受 OAuth Token、用户 API Key 或成员 Bearer Token。基础路径：`/open/v1/team/billing`。 本组接口不检查当前是否拥有 ACTIVE Open 权益。只要团队凭证有效并具有所需 Scope，即可查询其所属团队的开放能力历史账单。查询不会开通权益、触发出账或执行积分扣减；没有开放能力账单时返回空列表或零汇总。 ## Scope | Scope | 能力 | | :------------------ | :------------------------ | | `team.billing.read` | 查询团队或成员账单流水、积分汇总及项目模型账单流水 | 团队 AK/SK 需显式配置该 Scope；已有 `team.member.read` 或 `team.entitlement.usage.read` 权限不包含账单查询权限。 ## 通用参数与查询口径 三个接口均为 `POST`，请求体为 JSON，使用 `Content-Type: application/json`。 | 字段 | 类型 | 必填 | 说明 | | :----------- | :----- | :- | :----------------------------- | | `start_time` | string | 是 | 开始时间，包含该时刻 | | `end_time` | string | 是 | 结束时间，不包含该时刻；必须晚于开始时间，跨度最多 31 天 | 时间格式为 `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` 筛选。 ## 查询团队或成员账单流水 ```text theme={null} POST /open/v1/team/billing/flow Content-Type: application/json { "start_time": "2026-09-01T00:00:00", "end_time": "2026-09-10T00:00:00", "member_id": "tm_Kx7Qm2pV9sRa4nBt6cWd8Y", "entitlement_code": "sandbox_runtime", "page": 0, "page_size": 20 } ``` 所需 Scope：`team.billing.read`。 除通用时间参数外，支持以下参数： | 字段 | 类型 | 必填 | 说明 | | :----------------- | :------ | :- | :---------------------------------------------------------- | | `member_id` | string | 否 | 团队成员公开 ID，格式为 `tm_...`；省略查询团队全量 | | `entitlement_code` | string | 否 | 权益类型编码，即 `entitlement_type.code`；1 至 64 字符，不能含首尾空白；省略不按权益过滤 | | `page` | integer | 否 | 页码从 0 开始，默认 0，最大 2147483647 | | `page_size` | integer | 否 | 每页条数，默认 20，范围 1 至 100 | 成员 ID 使用团队成员 API 返回的真实公开编号，不能传内部用户 ID 或阿里云 OpenID。冻结或标记删除的成员仍可查；成员不存在或属于其他团队时返回 404。`null`、空字符串不等同于省略成员筛选。非法分页值直接返回 400，不进行取整或截断。 权益筛选由 billing 读取同库 `entitlement_type`，将 `code` 转换为 `metering_item_code` 后用于账单查询；列表和 `total` 使用相同条件，可与成员筛选组合。传计量项编码不能代替权益编码，例如查询项目数量应使用 `max_projects`，不是 `project_count`。权益编码按配置读取，不局限于权益用量 API 的 7 项白名单。 `null`、空字符串、首尾空白、未知权益或未配置计量项返回 400；有效权益没有账单时返回空列表。筛选不会检查该权益当前是否已开通。 响应示例： ```text theme={null} { "items": [ { "bill_no": "B-example-001", "member_id": "tm_Kx7Qm2pV9sRa4nBt6cWd8Y", "project_id": null, "bill_type": "PERIODIC", "item_code": "sandbox_runtime", "entitlement_code": "sandbox_runtime", "entitlement_name": "构建沙箱", "metering_type": "DURATION", "source": "meooApp", "quantity": 120.5, "unit": "分钟", "total_points": 120, "actual_deducted": 0, "settle_status": "PENDING", "period_start": "2026-09-09T10:00:00", "period_end": "2026-09-09T11:00:00", "settle_time": null, "created_at": "2026-09-09T11:01:00" } ], "total": 1, "page": 0, "page_size": 20 } ``` 示例编号、用量、积分及业务类型仅作展示，以实际账单返回值为准。 **响应字段** | 字段 | 类型 | 说明 | | :---------- | :-------- | :--------------------------- | | `items` | object\[] | 本页账单，按账期开始时间倒序，同一时刻按账单内部顺序倒序 | | `total` | integer | 满足筛选条件的账单总数 | | `page` | integer | 当前页码，从 0 开始 | | `page_size` | integer | 本次每页条数 | **账单明细字段** | 字段 | 类型 | 说明 | | :---------------------------- | :---------- | :--------------------------------------------------- | | `bill_no` | string | 账单号 | | `member_id` | string/null | 成员公开编号；历史成员尚无公开编号时为 null，不返回内部用户 ID | | `project_id` | string/null | PROJECT 类型的模型账单返回项目公开 URL ID；成员聚合账单为 null，不能据此拆分项目费用 | | `bill_type` | string | 账单类型，保留计费服务取值 | | `item_code` | string | 账单计量项编码，兼容保留；用户展示使用权益字段 | | `entitlement_code` | string/null | 当前权益类型编码；计量项未配置权益映射时为 null | | `entitlement_name` | string/null | 当前权益名称；与权益编码同时有值或同时为 null | | `metering_type` | string/null | 计量类型 | | `source` | string/null | 账单来源 | | `quantity` | number/null | 明细用量，非负，可带小数；明细不存在时为 null，不补零 | | `unit` | string/null | 明细用量单位，无明细时为 null | | `total_points` | integer | 账单积分 | | `actual_deducted` | integer | 已完成扣减积分 | | `settle_status` | string | 结算状态，含 PENDING；调用方应兼容新增状态值 | | `period_start` / `period_end` | string | 账单账期开始、结束时间 | | `settle_time` | string/null | 结算时间，尚未结算时可为 null | | `created_at` | string | 账单创建时间；为本地时间字符串，不是 Unix 时间戳 | 两个流水接口均回填权益字段。权益编码和名称来自查询时的配置，不是出账时快照；配置调整可能改变历史账单的展示与筛选归类。找不到映射时保留账单，两个字段均为 null；配置重复、配置无效或字典读取失败返回 503，不随意选择权益或伪造空映射。项目模型示例展示未配置映射的情况；是否映射为某个权益以实际配置为准。 所有时间均保留计费服务返回的本地时间口径。积分使用计费服务原始整数，不进行人民币换算或倍率转换。数值须在 JavaScript 安全整数范围内；无法无损表达的积分或分页总数返回 503，不静默舍入。成员 ID 始终按精确字符串处理。 无记录时 `items` 为 `[]`；超出最后一页也返回空列表，`total` 仍表示总记录数。列表与总数不是事务快照，出账或结算并发时结果可能变化；跨页查询期间新增账单可能导致重复或位移。 ## 查询团队或成员积分汇总 ```text theme={null} POST /open/v1/team/billing/points-summary Content-Type: application/json { "start_time": "2026-09-01T00:00:00", "end_time": "2026-09-10T00:00:00", "member_id": "tm_Kx7Qm2pV9sRa4nBt6cWd8Y" } ``` 所需 Scope：`team.billing.read`。支持通用时间参数及可选 `member_id`，成员规则与流水接口一致。不支持分页或 `entitlement_code` 参数；省略 `member_id` 查询团队汇总。按权益过滤后的流水合计不能直接与未过滤的汇总比较。 ```text theme={null} { "total_points": 1000, "actual_deducted": 800, "pending_points": 200 } ``` | 字段 | 类型 | 说明 | | :---------------- | :------ | :------------------------------------------ | | `total_points` | integer | 查询范围内已出账积分合计 | | `actual_deducted` | integer | 上述账单中已完成扣减的积分合计 | | `pending_points` | integer | `total_points - actual_deducted`，表示已出账未扣减积分 | 汇总来自正式账单，不按主账号积分流水拆分成员费用。延迟结算时出现待扣减积分是正常现象；`pending_points` 可以为负数，API 不做归零处理，以保留扣减超出账单金额等异常信号。无账单时三项均为 0。本接口不返回积分余额、额度或未出账用量。 ## 查询项目模型账单流水 ```text theme={null} POST /open/v1/team/billing/project-model-flow Content-Type: application/json { "project_id": "project_public_url_id", "start_time": "2026-09-01T00:00:00", "end_time": "2026-09-10T00:00:00", "page": 0, "page_size": 20 } ``` 所需 Scope：`team.billing.read`。`project_id` 必填，使用项目 API 返回的公开 `url_id`，不是数据库主键；其余时间及分页参数与流水接口一致。不支持 `member_id`、`entitlement_code` 或计量项筛选。 只查询当前团队项目的 `llm_token` 模型账单，包含尚未扣减的账单。项目不存在或属于其他团队时返回 404；仍保留项目记录的冻结或软删除项目可查询历史账单。 响应结构及字段与账单流水接口相同。例如： ```text theme={null} { "items": [ { "bill_no": "B-example-002", "member_id": "tm_Kx7Qm2pV9sRa4nBt6cWd8Y", "project_id": "project_public_url_id", "bill_type": "REQUEST", "item_code": "llm_token", "entitlement_code": null, "entitlement_name": null, "metering_type": "TOKEN", "source": "meooApp", "quantity": 1000, "unit": "token", "total_points": 10, "actual_deducted": 0, "settle_status": "PENDING", "period_start": "2026-09-09T10:00:00", "period_end": "2026-09-09T10:01:00", "settle_time": null, "created_at": "2026-09-09T10:01:01" } ], "total": 1, "page": 0, "page_size": 20 } ``` 沙箱、应用访问、云资源等账单按成员小时聚合，无法准确归属到项目，因此本接口不代表项目全部费用。 ## 常见错误 | HTTP | Code | 说明 | | :--- | :------------------------ | :------------------------------------------------ | | 400 | `invalid_request` | 缺少参数、非法公开 ID、时间格式或范围错误、非法分页、包含额外字段，或权益编码无效/未配置计量项 | | 401 | `invalid_signature` | 团队凭证、请求摘要或签名无效 | | 401 | `signature_expired` | 签名时间戳已过期 | | 401 | `signature_replayed` | 签名 Nonce 已被使用 | | 403 | `insufficient_scope` | 凭证缺少 `team.billing.read` | | 404 | `not_found` | 成员或项目不存在，或不属于凭证团队 | | 429 | `temporarily_unavailable` | 请求频率超过限制，或限流服务暂不可用 | | 503 | `service_unavailable` | 计费服务、团队身份解析或成员映射暂不可用，权益映射重复/无效，或返回数据无效 | 错误响应使用 `application/problem+json`： ```text theme={null} { "type": "about:blank", "title": "Service Unavailable", "status": 503, "detail": "账单查询服务暂不可用", "code": "service_unavailable", "trace_id": "example_trace_id" } ``` 下游失败不返回部分账单，不降级为空列表或零汇总。排查时请提供 `trace_id`。 HMAC 方法与调用流程见[团队系统集成指南](https://app.mintlify.com/alibaba-b47c397f/alibaba-b47c397f/~/8b2e4f11-3395-4dd1-b58e-2e6935dd1392)。签名时使用实际的 `/open/v1/team/billing/...` 路径与发送的 JSON 请求体；三个接口分别签名，不能复用其他路径的签名。 ## 权益字段升级与发布顺序 先发布 billing，再发布 oneday-api。旧调用方不传新增筛选参数时仍按原口径查询；OpenAPI 对旧 billing 缺少的两个权益字段输出 null，但旧 billing 不支持权益筛选，不能在仅升级 API 的情况下启用该参数。若下游返回的非空账单不符合请求的权益编码，OpenAPI 返回 503。 回滚时先回滚 API 再回滚 billing。无数据库变更、无新增外部组件依赖；仅以只读方式访问现有 `entitlement_type`，不修改字典、索引或历史账单，不复用通用 BillingService，也不新增 ACTIVE Open 权益校验。