Skip to main content
API Reference

账单 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_timestring是开始时间，包含该时刻
end_timestring是结束时间，不包含该时刻；必须晚于开始时间，跨度最多 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 筛选。

查询团队或成员账单流水

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_idstring否团队成员公开 ID，格式为 tm_...；省略查询团队全量
entitlement_codestring否权益类型编码，即 entitlement_type.code；1 至 64 字符，不能含首尾空白；省略不按权益过滤
pageinteger否页码从 0 开始，默认 0，最大 2147483647
page_sizeinteger否每页条数，默认 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；有效权益没有账单时返回空列表。筛选不会检查该权益当前是否已开通。 响应示例： 
{
  "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
}
示例编号、用量、积分及业务类型仅作展示，以实际账单返回值为准。 响应字段
字段类型说明
itemsobject[]本页账单，按账期开始时间倒序，同一时刻按账单内部顺序倒序
totalinteger满足筛选条件的账单总数
pageinteger当前页码，从 0 开始
page_sizeinteger本次每页条数
账单明细字段
字段类型说明
bill_nostring账单号
member_idstring/null成员公开编号；历史成员尚无公开编号时为 null，不返回内部用户 ID
project_idstring/nullPROJECT 类型的模型账单返回项目公开 URL ID；成员聚合账单为 null，不能据此拆分项目费用
bill_typestring账单类型，保留计费服务取值
item_codestring账单计量项编码，兼容保留；用户展示使用权益字段
entitlement_codestring/null当前权益类型编码；计量项未配置权益映射时为 null
entitlement_namestring/null当前权益名称；与权益编码同时有值或同时为 null
metering_typestring/null计量类型
sourcestring/null账单来源
quantitynumber/null明细用量，非负，可带小数；明细不存在时为 null，不补零
unitstring/null明细用量单位，无明细时为 null
total_pointsinteger账单积分
actual_deductedinteger已完成扣减积分
settle_statusstring结算状态，含 PENDING；调用方应兼容新增状态值
period_start / period_endstring账单账期开始、结束时间
settle_timestring/null结算时间，尚未结算时可为 null
created_atstring账单创建时间；为本地时间字符串，不是 Unix 时间戳
两个流水接口均回填权益字段。权益编码和名称来自查询时的配置，不是出账时快照；配置调整可能改变历史账单的展示与筛选归类。找不到映射时保留账单，两个字段均为 null；配置重复、配置无效或字典读取失败返回 503，不随意选择权益或伪造空映射。项目模型示例展示未配置映射的情况；是否映射为某个权益以实际配置为准。 所有时间均保留计费服务返回的本地时间口径。积分使用计费服务原始整数，不进行人民币换算或倍率转换。数值须在 JavaScript 安全整数范围内；无法无损表达的积分或分页总数返回 503，不静默舍入。成员 ID 始终按精确字符串处理。 无记录时 items 为 []；超出最后一页也返回空列表，total 仍表示总记录数。列表与总数不是事务快照，出账或结算并发时结果可能变化；跨页查询期间新增账单可能导致重复或位移。

查询团队或成员积分汇总

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 查询团队汇总。按权益过滤后的流水合计不能直接与未过滤的汇总比较。 
{
  "total_points": 1000,
  "actual_deducted": 800,
  "pending_points": 200
}
字段类型说明
total_pointsinteger查询范围内已出账积分合计
actual_deductedinteger上述账单中已完成扣减的积分合计
pending_pointsintegertotal_points - actual_deducted，表示已出账未扣减积分
汇总来自正式账单，不按主账号积分流水拆分成员费用。延迟结算时出现待扣减积分是正常现象；pending_points 可以为负数，API 不做归零处理，以保留扣减超出账单金额等异常信号。无账单时三项均为 0。本接口不返回积分余额、额度或未出账用量。

查询项目模型账单流水

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；仍保留项目记录的冻结或软删除项目可查询历史账单。 响应结构及字段与账单流水接口相同。例如： 
{
  "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
}
沙箱、应用访问、云资源等账单按成员小时聚合，无法准确归属到项目，因此本接口不代表项目全部费用。

常见错误

HTTPCode说明
400invalid_request缺少参数、非法公开 ID、时间格式或范围错误、非法分页、包含额外字段，或权益编码无效/未配置计量项
401invalid_signature团队凭证、请求摘要或签名无效
401signature_expired签名时间戳已过期
401signature_replayed签名 Nonce 已被使用
403insufficient_scope凭证缺少 team.billing.read
404not_found成员或项目不存在，或不属于凭证团队
429temporarily_unavailable请求频率超过限制，或限流服务暂不可用
503service_unavailable计费服务、团队身份解析或成员映射暂不可用，权益映射重复/无效，或返回数据无效
错误响应使用 application/problem+json： 
{
  "type": "about:blank",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "账单查询服务暂不可用",
  "code": "service_unavailable",
  "trace_id": "example_trace_id"
}
下游失败不返回部分账单，不降级为空列表或零汇总。排查时请提供 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 权益校验。
  • Meoo 开放平台
  • 团队系统集成
  • 快速接入
  • 认证与授权
  • 通用协议
  • API 文档
  • 运行与安全
    • 接入流程
    Agent 专题
    API Reference
    账单 API - Meoo