API 文档

概述

量子财务引擎提供 RESTful API，通过转移单生成量子凭证，实现业务与财务的无缝融合。

核心流程： 转移单 → 量子凭证（四态科目）→ 四态资源流水

接口地址

https://openentry.top/api/v1

认证方式

所有 API 请求需要在请求体中携带您的 API Key：

{
  "api_key": "YOUR_API_KEY",
  ...
}

提示： API Key 在密钥管理页面创建，请在控制台中妥善保存。密钥只会完整显示一次。

接口列表

POST/api/v1/generate

提交转移单，生成量子凭证

请求参数

参数	类型	必填	说明
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	否	交易金额（主业务金额，如销售款、采购款）
non_transaction_amount	number	否	非交易金额（辅助金额，如税费、运输费、结存调整）

类型说明：

String: 字符串类型，最大长度 255 字符
Number: 浮点数，最多支持 2 位小数，支持负数（负数表示红冲）
容器归属主体可与主体相同或不同，相同则不需要传

响应字段说明

字段	类型	说明
success	boolean	请求是否成功
request_id	string	请求唯一标识符
data.entries	array	生成的量子分录列表
data.from_state	string	转出主体状态
data.to_state	string	转入主体状态
error	object/null	错误详情，成功时为 null

量子分录 (QuantumEntry) 字段说明

字段	类型	说明
quantum_state	string	量子态类型（monetary_state / quantum_state / responsible_state / inventory_state）
amount_type	string	金额类型（transaction / non_transaction）
increase_direction	string	科目增加方向（debit=借方增加 / credit=贷方增加）
debit_credit	string	借贷方向（debit=借 / credit=贷）
amount	number	金额（正数=借方，负数=贷方）
owner_entity	string	归属主体
container	string/null	归属容器（如仓库、账户等），可空
counterparty_entity	string	对方主体
responsible_entity	string/null	权责主体，可空
cash_flow_id	integer/null	现金流标识（0=转出，1=转入，null=不适用）
rule_id	string/null	规则编号，对应SPEC文档

请求示例

curl -X POST https://openentry.top/api/v1/generate \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "qa_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "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
  }'

成功响应示例

{
  "success": true,
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "entries": [
      {
        "quantum_state": "monetary_state",
        "amount_type": "transaction",
        "increase_direction": "debit",
        "debit_credit": "credit",
        "amount": -10000.00,
        "owner_entity": "A公司",
        "container": "银行账户A",
        "counterparty_entity": "B公司",
        "responsible_entity": null,
        "cash_flow_id": 0,
        "rule_id": "1.1.1"
      }
    ],
    "from_state": "monetary_state",
    "to_state": "monetary_state"
  },
  "error": null
}

错误响应示例

{
  "success": false,
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "from_entity 不能为空"
  }
}

POST/api/v1/verify-key

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

请求示例

curl -X POST https://openentry.top/api/v1/verify-key \
  -H "Content-Type: application/json" \
  -d '{"api_key": "qa_your_api_key_here"}'

响应示例

{
  "success": true,
  "valid": true,
  "tier": "pro",
  "error": null
}

GET/api/v1/key-info

获取 API Key 的详细信息和配额

响应示例

{
  "valid": true,
  "key": {
    "userId": "user_xxx",
    "plan": "pro",
    "name": "生产环境密钥"
  },
  "quota": {
    "dailyLimit": 10000,
    "used": 1234,
    "remaining": 8766
  }
}

GET/api/v1/usage

获取 API 使用量统计

响应示例

{
  "period": "daily",
  "total_requests": 1234,
  "quota_used": 1234,
  "quota_limit": 10000,
  "usage_percent": 12.34
}

错误码

错误码	说明
MISSING_API_KEY	缺少 API 密钥
INVALID_API_KEY	API密钥无效或已过期
QUOTA_EXCEEDED	配额已用尽，请明天再试或升级套餐
VALIDATION_ERROR	请求参数校验失败

四态体系

四态科目与四态资源流水一一对应，每一步操作都是凭证级操作。

四态	四态资源	说明
💰 货币态	货币资金	资金收付、存款转移
📦 结存态	存货/库存	入库、出库、批次追踪
⚡ 量子态	过渡资源	跨主体资源转移
📋 权责态	权利义务	应收应付、权责关系

业务场景

采购入库

供应商 → 仓库：生成货币态（应付）+ 结存态（库存）

销售出库

仓库 → 客户：出库关联入库批次，成本自动传递

跨组织交易

子公司A → 子公司B：一个转移单生成各方凭证

快速开始

# Python 示例

import requests

API_KEY = "qa_your_api_key_here"
BASE_URL = "https://openentry.top/api/v1"

def generate_entry(from_entity, to_entity, transaction_amount):
    response = requests.post(
        f"{BASE_URL}/generate",
        json={
            "api_key": API_KEY,
            "from_entity": from_entity,
            "to_entity": to_entity,
            "transaction_amount": transaction_amount
        }
    )
    return response.json()

# 调用示例
result = generate_entry(
    from_entity="A公司",
    to_entity="B公司",
    transaction_amount=10000
)
print(result["data"]["entries"])

技术支持

如有问题或建议，请通过以下方式联系我们：

📧 邮箱：182234480@qq.com
💬 支持页面：联系我们