Collapsar
开发者文档

API 参考

完整的接口说明、参数定义与代码示例——三行代码即可完成首次调用

Collapsar Engine - API Reference

引擎版本：0.1.0

本文档为 Collapsar 的完整 API 参考，随引擎源码同步更新。

快速开始：本引擎是一个 会计 API 开放平台（SMR 架构：感知 / 记忆 / 推理）。只需：

  1. 在 collapsarai.com 注册账号
  2. 创建 API Key
  3. 用 API Key 调用下方接口

所有接口均使用 API Key 鉴权（X-API-Key Header 或 body 字段）。

目录

🔓 Collapsar 入口

Entry（主入口，同步 JSON）

POST /api/v1/collapsar/entry
Content-Type: application/json

API Key 传入方式（任选其一）：

  1. 请求体字段：{ "api_key": "qa_xxx_yyy", ... }
  2. HTTP Header：X-API-Key: qa_xxx_yyy（适用于不想把 Key 放入 body 的场景）

两者都提供时，请求体优先。

请求参数

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | api_key | string | 是 | API 密钥 | | from_entity | string | 是 | 转出主体名称 | | to_entity | string | 是 | 转入主体名称 | | responsible_entity | string | 否 | 权责主体 | | from_container | string | 否 | 转出容器（如仓库、银行账户） | | to_container | string | 否 | 转入容器 | | from_container_owner_entity | string | 否 | 转出容器归属主体 | | to_container_owner_entity | string | 否 | 转入容器归属主体 | | transaction_amount | number | 否 | 交易金额（默认 0；≠0 走交易路径） | | non_transaction_amount | number | 否 | 非交易金额（默认 0） | | reversal | boolean | 否 | 红冲标记：true 时借贷方向翻转（金额恒为正，不用负数表达红冲） | | business_context | object | 否 | 业务上下文（记忆指纹 + 科目推理），见下方说明 | | account_ranges | array | 否 | 候选科目的核算范围（P0-P3） |

Business Context 参数

| 参数 | 类型 | 说明 | |------|------|------| | business_type | string | 业务类型（如"采购"、"销售"） | | resource_name | string | 资源名称 | | business_purpose | string | 业务目的 | | from_department | string | 转出部门 | | to_department | string | 转入部门 | | date | string | 业务日期 |

请求示例

{
  "api_key": "qa_abc123_xxxxxxxxxxxxxxxxxxxx",
  "from_entity": "A公司",
  "to_entity": "B公司",
  "responsible_entity": "C公司",
  "from_container": "仓库1",
  "to_container": "仓库2",
  "from_container_owner_entity": "A公司",
  "to_container_owner_entity": "B公司",
  "transaction_amount": 10000.00,
  "non_transaction_amount": 500.00,
  "business_context": {
    "business_type": "材料采购",
    "resource_name": "网布",
    "business_purpose": "网布采购"
  }
}

响应

| 字段 | 类型 | 说明 | |------|------|------| | success | boolean | 请求是否成功 | | request_id | string | 请求唯一标识 | | data.voucher | object | 对外凭证：voucher_id / balanced / entries | | data.voucher.voucher_id | string | 凭证编号（qv_日期_短码） | | data.voucher.balanced | boolean | 借贷平衡校验结果 | | data.voucher.entries[] | array | 分录列表（含 entry_index、account_name 科目、debit_credit、amount 等） | | data.fingerprint | string | 凭证检索指纹（记忆复用） | | data.collapse_results | array | 塌缩推理明细（含置信度分级） | | error | object | 错误信息（失败时） | | quota | object | 配额信息（used / limit / remaining） |

响应示例

{
  "success": true,
  "request_id": "uuid",
  "data": {
    "voucher": {
      "voucher_id": "qv_20261016_a1b2c3d4",
      "balanced": true,
      "entries": [
        {
          "entry_index": 1,
          "group_label": "转出",
          "debit_credit": "credit",
          "account_name": "主营业务收入",
          "amount": -10000.00,
          "balance_direction": "debit",
          "counterparty": "B公司",
          "owner": "A公司"
        }
      ]
    },
    "fingerprint": "a3f5c9e2f8b1d4a6",
    "collapse_results": []
  },
  "error": null,
  "quota": {
    "used": 28,
    "limit": 100,
    "remaining": 72
  }
}

计费口径：参数校验通过后才计配额；校验失败（VALIDATION_ERROR）不消耗次数。

错误响应

{
  "success": false,
  "request_id": "uuid",
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "from_entity 不能为空"
  }
}

Entry Stream（流式入口，SSE）

POST /api/v1/collapsar/entry-stream
Content-Type: application/json
Response: text/event-stream

请求体同 Entry。返回 SSE 流，帧类型依次为： initial（分录骨架，毫秒级）→ progress → llm_chunk（推理增量）→ collapse（科目塌缩）→ review（全局复核）→ done。

Entry Batch（批量入口）

POST /api/v1/collapsar/entry-batch
Content-Type: application/json

请求参数

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | api_key | string | 是 | API 密钥 | | facts | array | 是 | 业务事实列表（≤100 条），每个元素同 Entry 参数 |

请求示例

{
  "api_key": "qa_abc123_xxxxxxxxxxxxxxxxxxxx",
  "facts": [
    {
      "from_entity": "A公司",
      "to_entity": "B公司",
      "transaction_amount": 10000.00
    },
    {
      "from_entity": "C公司",
      "to_entity": "D公司",
      "transaction_amount": 20000.00
    }
  ]
}

响应

{
  "success": true,
  "total_count": 2,
  "success_count": 2,
  "failed_count": 0,
  "results": [...]
}

批量仅做感知层（分录骨架），不做 LLM 推理；仅按通过校验的 fact 数量计日配额。

Legacy 路径（向后兼容）

以下旧路径与对应新入口完全等效（同 handler），保留以兼容存量调用方：

| Legacy 路径 | 推荐路径 | |------------|---------| | POST /api/v1/generate | POST /api/v1/collapsar/entry | | POST /api/v1/generate-batch | POST /api/v1/collapsar/entry-batch | | POST /api/v1/generate-stream | POST /api/v1/collapsar/entry-stream | | POST /api/v1/quantum/generate | POST /api/v1/collapsar/entry | | POST /api/v1/quantum/generate-batch | POST /api/v1/collapsar/entry-batch | | POST /api/v1/quantum/generate-stream | POST /api/v1/collapsar/entry-stream | | POST /api/v1/quantum/generate-stream-multi | 多转移单合并流式（暂无 collapsar 别名） |

验证密钥

POST /api/v1/quantum/verify-key
Content-Type: application/json

请求参数

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | api_key | string | 是 | API 密钥 |

响应

{
  "success": true,
  "valid": true,
  "user_id": "uuid",
  "plan": "free",
  "quota": {
    "used": 27,
    "limit": 100,
    "remaining": 73
  }
}

🔓 公开 API · 用量统计

获取指定 API Key 的当日用量

GET /api/v1/usage/daily
X-API-Key: qa_abc123_xxxxxxxxxxxxxxxxxxxx

响应

{
  "success": true,
  "error": null,
  "quota": {
    "used": 27,
    "limit": 100,
    "remaining": 73,
    "period": "daily"
  }
}

查询当前用户用量统计（需登录）

GET /api/v1/usage/stats
Cookie: session_token=<登录会话令牌>

响应

{
  "stats": {
    "totalCalls": 128,
    "apiKeysCount": 3,
    "currentPlan": "free",
    "todayCalls": 12,
    "weekCalls": 56,
    "dailyTrend": [ { "date": "2026-07-26", "count": 12 } ],
    "topEndpoints": [ { "endpoint": "/api/v1/collapsar/entry", "count": 80 } ]
  }
}

错误码

| 错误码 | HTTP 状态码 | 说明 | |--------|-------------|------| | MISSING_API_KEY | 400 Bad Request | 缺少 API 密钥 | | VALIDATION_ERROR | 400 Bad Request | 请求参数校验失败（不消耗配额） | | KEY_NOT_ACTIVATED | 403 Forbidden | API 密钥未激活 | | KEY_EXPIRED | 403 Forbidden | API 密钥已过期 | | KEY_NOT_FOUND | 403 Forbidden | API 密钥不存在 | | INVALID_API_KEY | 403 Forbidden | API 密钥无效 | | QUOTA_EXCEEDED | 403 Forbidden | 当日配额用尽 | | UNAUTHORIZED | 401 Unauthorized | 未登录或登录已过期 | | FORBIDDEN | 403 Forbidden | 无权限访问 | | INTERNAL_ERROR | 500 Internal Server Error | 服务器内部错误 | | RATE_LIMITED | 429 Too Many Requests | 请求过于频繁（不消耗日配额） |

限流与配置

引擎提供两层防护：

  1. 日配额（daily quota）：每个 API Key 每日总调用量上限
  2. 令牌桶（token bucket）：按 API Key 维度的瞬时速率/突发限制

配置项：

| 配置项 | 环境变量 | 默认值 | 说明 | |---|---|---|---| | 稳态速率 | RATE_LIMIT_RPS | 5 | 每 Key 每秒平均可请求数 | | 突发容量 | RATE_LIMIT_BURST | 10 | 令牌桶容量 |

准备好开始了吗？

在沙盒中免费体验，或注册创建你的第一个 API Key

免费试用创建账户