API 实战：三行代码生成第一张量子凭证

准备工作

在开始之前，你需要：

一个量子财务引擎账号（免费注册）
一个有效的 API Key（在用户后台申请）
curl 或任意 HTTP 客户端

三行代码生成量子凭证

核心 API 调用就是这么简单：

curl -X POST https://openentry.top/api/v1/generate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_entity": "A公司",
    "to_entity": "B公司",
    "transaction_amount": 10000
  }'

参数说明：

| 参数 | 类型 | 说明 | |---|---|---| | from_entity | String | 资源转出主体（必填） | | to_entity | String | 资源转入主体（必填） | | transaction_amount | Number | 交易金额（权责金额），≠0 走权责路径 | | non_transaction_amount | Number | 非交易金额（非权责金额），tx=0 时生效 | | from_container | String | 转出容器（如银行账号、仓库），可选 | | to_container | String | 转入容器，可选 | | from_container_owner_entity | String | 转出容器归属主体，有值则货币态，无值则结存态 | | to_container_owner_entity | String | 转入容器归属主体 | | responsible_entity | String | 权责主体，有值则权责态 |

资源形态由引擎自动推导：你不需要指定资源形态——引擎根据容器归属和权责主体的存在性自动判定货币态/结存态/权责态/量子态。详见四态体系深度解析。

返回结果解析

成功调用后，引擎返回量子凭证的完整四态流水：

{
  "voucher_id": "qv_20260826_001",
  "status": "generated",
  "entries": [
    {
      "entry_type": "b2_monetary_outflow",
      "quantum_state": "monetary_state",
      "amount": -10000,
      "owner_entity": "A公司",
      "counterparty_entity": "B公司",
      "debit_credit": "credit",
      "rule_id": "B2.M.OUT"
    },
    {
      "entry_type": "b1_monetary_inflow",
      "quantum_state": "monetary_state",
      "amount": 10000,
      "owner_entity": "B公司",
      "counterparty_entity": "A公司",
      "debit_credit": "debit",
      "rule_id": "B1.M.IN"
    }
  ],
  "balanced": true
}

关键字段：

voucher_id：量子凭证唯一编号
entries：四态分录数组，每条记录一个资源的借贷变化
balanced：是否借贷平衡（永远为 true——这是数学保证，不是校验结果）
rule_id：适用的 B/D 规则编号（B=基本规则，D=衍生规则）

Python 示例

import requests

resp = requests.post(
    "https://openentry.top/api/v1/generate",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "from_entity": "A公司",
        "to_entity": "B公司",
        "transaction_amount": 10000,
    },
)

voucher = resp.json()
print(f"凭证编号: {voucher['voucher_id']}")
print(f"分录数量: {len(voucher['entries'])}")
print(f"借贷平衡: {voucher['balanced']}")

JavaScript 示例

const resp = await fetch('https://openentry.top/api/v1/generate', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    from_entity: 'A公司',
    to_entity: 'B公司',
    transaction_amount: 10000,
  }),
})

const voucher = await resp.json()
console.log(`凭证编号: ${voucher.voucher_id}`)
console.log(`分录数量: ${voucher.entries.length}`)

批量生成

如果需要一次处理多笔业务，可以使用批量接口：

curl -X POST https://openentry.top/api/v1/quantum/generate-batch \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "facts": [
      {"from_entity": "A公司", "to_entity": "B公司", "transaction_amount": 10000},
      {"from_entity": "B公司", "to_entity": "C公司", "transaction_amount": 5000},
      {"from_entity": "C公司", "to_entity": "A公司", "transaction_amount": 3000}
    ]
  }'

批量接口按 facts 数量计日配额，每个 fact 计 1 个单位。配额不足时整体返回 HTTP 403 且不计入配额。

错误处理

常见错误码：

| 错误码 | HTTP 状态 | 说明 | |---|---|---| | MISSING_API_KEY | 400 | 未传 API Key | | KEY_NOT_FOUND | 403 | API Key 不存在 | | KEY_EXPIRED | 403 | API Key 已过期 | | QUOTA_EXCEEDED | 403 | 当日配额用尽 | | RATE_LIMITED | 429 | 请求过于频繁 | | VALIDATION_ERROR | 400 | 参数校验失败 |

if resp.status_code == 403:
    error = resp.json()
    if error.get("error_code") == "QUOTA_EXCEEDED":
        print("当日配额已用尽，明日自动重置")
    elif error.get("error_code") == "KEY_EXPIRED":
        print("API Key 已过期，请到后台续期")

沙盒体验

注册并创建 API Key 后，可以直接在沙盒中免费体验 API 调用，实时查看四态流水结果。

下一步

阅读四态体系深度解析，理解返回结果中每个字段的含义
查看完整 API 文档，了解所有可用接口
在用户后台查看用量统计