API 文档

量子财务引擎 API 参考（v1）

认证

方式：API Key（放在请求体 JSON 的 api_key 字段）

位置：所有接口均在请求体中传递，无需 Header

HTTP 状态码

状态码	说明
200	请求成功
400	参数错误（VALIDATION_ERROR）
401	未提供 API 密钥或密钥无效（MISSING_API_KEY / INVALID_API_KEY）
429	配额用尽（QUOTA_EXCEEDED）
500	服务器内部错误

额度与配额

通过 verify-key 接口返回配额信息。当 used >= limit 时，接口返回 QUOTA_EXCEEDED，需等待重置或升级。

字段	类型	说明
used	number	当日已使用次数
limit	number	当日配额上限（默认100）
reset_at	string	配额重置时间（UTC 零点）

错误码

错误码	说明
MISSING_API_KEY	缺少 API 密钥
INVALID_API_KEY	API 密钥无效
QUOTA_EXCEEDED	配额用尽
VALIDATION_ERROR	请求参数错误
KEY_NOT_FOUND	API Key 不存在

四态体系

状态	名称	典型场景
monetary_state	货币态	收款、付款
inventory_state	结存态	入库、出库
quantum_state	量子态	服务类及待转类
responsible_state	权责态	债权转移

隐私保护架构

建议开发者采用以下架构保护用户数据隐私：

架构流程

用户输入（真实数据）-> 系统生成临时映射表 -> 转换为占位符调用引擎 -> 引擎返回占位符凭证 -> 逆向映射还原真实凭证

实现步骤

用户输入真实数据：from_entity: "A公司", to_entity: "B公司", transaction_amount: 10000
系统生成临时映射表（HashMap，内存中，不持久化）：
- 主体/容器：相同真实值 -> 相同占位符（如 "A公司" -> "A"）
- 金额：根据业务类型转换为 1 或 0（不传真实金额）
转换为占位符调用引擎：from_entity: "A", to_entity: "B", transaction_amount: 1
引擎返回占位符凭证
系统逆向映射还原真实凭证返回给用户

占位符建议

字段	占位符	说明
转出主体	A	如 "A公司" -> A
转入主体	B	如 "B公司" -> B
权责主体	R	如 "C公司" -> R
转出容器	仓库A	如 "仓库1" -> 仓库A
转入容器	仓库B	如 "仓库2" -> 仓库B
容器归属主体	归属A/归属B	与主体相同则用相同占位符

金额占位符

transaction_amount	含义	说明
1	权责业务	走交易路径
0	非权责业务	走非交易路径

特点

临时映射表仅在单次请求生命周期内存在，请求结束即销毁
相同真实值自动映射到相同占位符，保证引擎相等性判定正确
用户全程只接触真实数据，零感知占位符
映射开销极小，不影响效率

正确行为矩阵

状态	交易金额	非交易金额	行为
非结存态	0	!=0	非权责业务，使用非交易金额
非结存态	!=0	0	权责业务，使用交易金额
结存态	任意	任意	正常（调拨业务）

用户端应避免的错误场景

状态	交易金额	非交易金额	错误原因
非结存态	0	0	无业务意义
非结存态	!=0	!=0	引擎会忽略非交易金额

验证 API 密钥

验证 API 密钥是否有效，并返回配额信息

POSThttps://openentry.top/api/v1/quantum/verify-key

请求参数

字段	类型	必填	说明
api_key	string	是	API 密钥

POST https://openentry.top/api/v1/quantum/verify-key
Content-Type: application/json

{
  "api_key": "qa_abc123_xxxxxxxxxxxxxxxxxxxx"
}

响应示例

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

生成量子分录（单条）

通过 API Key 生成单条量子分录

POSThttps://openentry.top/api/v1/quantum/generate

请求参数

字段	类型	必填	说明
api_key	string	是	API 密钥
from_entity	string	是	付款方
to_entity	string	是	收款方
transaction_amount	number	是	交易金额（正数）
container	string	否	归属仓库/账户（默认自动分配）

POST https://openentry.top/api/v1/quantum/generate
Content-Type: application/json

{
  "api_key": "qa_abc123_xxxxxxxxxxxxxxxxxxxx",
  "from_entity": "A公司",
  "to_entity": "B公司",
  "transaction_amount": 10000.00
}

响应示例

{
  "success": true,
  "request_id": "uuid",
  "data": {
    "entries": [{
      "quantum_state": "monetary_state",
      "amount_type": "transaction",
      "balance_direction": "debit",
      "debit_credit": "credit",
      "amount": 10000.00,
      "owner_entity": "A公司",
      "container": "仓库1",
      "counterparty_entity": "B公司",
      "responsible_entity": null,
      "cash_flow_id": 0,
      "rule_id": "T.1.M.1"
    }]
  }
}

生成量子分录（批量）

通过 API Key 批量生成量子分录，一次最多 100 条

POSThttps://openentry.top/api/v1/quantum/generate-batch

请求参数

字段	类型	必填	说明
api_key	string	是	API 密钥
facts	array	是	业务事实数组，每条包含 from_entity / to_entity / transaction_amount / container（可选）

POST https://openentry.top/api/v1/quantum/generate-batch
Content-Type: application/json

{
  "api_key": "qa_abc123_xxxxxxxxxxxxxxxxxxxx",
  "facts": [
    { "from_entity": "A公司", "to_entity": "B公司", "transaction_amount": 10000, "container": "仓库1" },
    { "from_entity": "C公司", "to_entity": "D公司", "transaction_amount": 20000, "container": "仓库2" }
  ]
}

响应示例

{
  "success": true,
  "request_id": "uuid",
  "data": {
    "entries": [
      { "quantum_state": "monetary_state", "amount": -10000, "owner_entity": "A公司", "counterparty_entity": "B公司", "container": "仓库1" },
      { "quantum_state": "monetary_state", "amount": -20000, "owner_entity": "C公司", "counterparty_entity": "D公司", "container": "仓库2" }
    ]
  }
}

准备好开始了吗？

立即体验量子财务引擎的强大能力

体验沙盒