文档中心
搜索
Ask AI
全部文档
文档中心开发者中心API 文档凭证三件套

凭证三件套

本节汇总 凭证模型（Journal Model，JM）、与 凭证清单（Journal List） 相关的服务端接口、以及 凭证 / 单据模板（Journal Template，JT） 在 deepfos Python SDK 中已封装的能力。网关前缀仍为 https://{host}/deepfos-server/{服务名}。

组件与后端服务对应关系

能力域

SDK / 模块类型

典型后端服务名（示例）

凭证模型

JournalModelAPI，module_type = JM

journal-model-server1-0

凭证模板与日记账跑批接口

JournalTemplateAPI，module_type = JT

journal-template-server1-0（同源提供部分「清单」查询能力，见下文）

若环境中服务名与上表不一致，请以应用管理或 elementDetail.serverName 为准。

一、凭证模型（Journal Model）

对应 deepfos.api.journal_model。子路由前缀为 **/business/model。

与 OpenAPI 对齐说明：测试环境 Swagger 地址形如 https://{host}/deepfos-server/journal-server1-0/v3/api-docs（OpenAPI 3.1），其中路径以 /business/model/... 为主。网关上 服务名 可能是 journal-model-server1-0、journal-server1-0 等，以环境 elementDetail.serverName / 应用管理为准；本文 Path 仍用 journal-model-server1-0 作占位示例。

通用约定

  • 除「配置查询」与「过账 / 取消过账」外，多数 POST 在 OpenAPI 中声明了 Query：space（空间 id）、app（应用 id）、user（用户 id）为必填，language 可选。

  • Content-Type：application/json。

  • 若响应在规范中同时列出 200 / 401 / 403 / 404，其 Body schema 与 200 相同（业务错误往往体现在 success 或 status 等字段，而非仅 HTTP 状态码）。

获取凭证模型配置

用于解析头表/行表数据表信息、凭证类型编码等。

请求

项目

值

HTTP Method

GET

Path

https://xxxx.com/deepfos-server/journal-model-server1-0/business/model/config

Query Parameters（OpenAPI 声明项）

名称

必填

类型

说明

elementName

是

String

凭证模型元素名称

folderId

是

String

模型所在目录 id

path

是

String

模型所在路径

OpenAPI 将三项均标为 required；若网关或产品在运行期按「folderId 与 path 二选一」处理，以实际环境为准。

响应（200，*/*，BusinessModelVO）

返回凭证模型 元数据与表结构 定义，主要字段如下（嵌套对象仅列一级含义）。

字段名

类型

说明

baseInfo

Object

模型基础信息（ModelBaseInfoVO：名称、路径、folderId 等）

logicTable

Object

逻辑表 / 头行表结构（ModelTableVO）

refTable

Object

引用表信息（ElementInfoDTO）

type

String

场景类型，如 ADD / EDIT

repairDataTable

Boolean

是否修复数据表

seqActTableName

String

流水相关物理表名

subModels

Array<Object>

子模型分区（ModelPartitionVO）

journalModelType

Array<Object>

凭证类型配置（JournalModelTypeDTO）

journalModelCommonConfig

Object

通用复制等配置（ModelCopyDTO）

customLogic

Array<Object>

执行逻辑链

seqConfig

Array<Object>

序号配置

entityValuePosition

String

枚举 HEAD / LINE

name / path / folderId

String

冗余定位字段

同步批量保存（仅新增）

请求

项目

值

HTTP Method

POST

Path

https://xxxx.com/deepfos-server/journal-model-server1-0/business/model/data/batch/save

Query Parameters

名称

必填

类型

说明

space

是

String

空间 id

app

是

String

应用 id

user

是

String

用户 id

language

否

String

语言

Request Body（ModelDataBatchDTO）

字段名

类型

说明

modelInfo

Object

元素定位（ElementDetailDTO）；OpenAPI 中该类型含必填 jmTypeCode、mapping

headOperation

String

头操作语义：EDIT / ADD；与头行组合规则见接口 summary

enableRequired / enableDefaultValue / enableEntityValue 等

Boolean

各类校验、默认值、实体值、范围、创建、重复检查、全量报错、至少一行等开关

dataMap

Object

键为 逻辑表编码，值为 ModelTableBatchDataDTO 数组

paramValueMap

Object<String>

执行参数 { key: value }

callbackInfo

Object

可选；JournalModelExecCallbackPythonDTO（elementName、serverName 必填等）

ModelTableBatchDataDTO（dataMap 中每条）主要字段：operateType、journalTypeCode、columns（ModelDataColumnDTO 列表）、headMainId、lineMainId、行数据 data（任意键值对象）。

响应（200 / 401 / 403 / 404，ModelDataReturnDTO）

字段名

类型

说明

success

Boolean

是否成功

mainKey

Object

主表业务键等

warnings / errors / infos / successInfo

Array<Object>

消息列表（MessageDTO：msg、title 等）

progressTag

Integer

进度标签

uniKeyValue

Array<Object>

唯一标识字段集合

errorRefresh

Boolean

出错时是否需刷新界面

异步批量保存（仅新增）

请求

项目

值

HTTP Method

POST

Path

https://xxxx.com/deepfos-server/journal-model-server1-0/business/model/data/sync/batch/save

Query Parameters：与「同步批量保存」相同（space、app、user 必填，language 可选）。

Request Body：与同步批量保存相同（ModelDataBatchDTO）。

响应（200 / 401 / 403 / 404，ResponseResult）

字段名

类型

说明

status

Boolean

是否受理成功等

data

Any

载荷

code

Long

业务码

message

String

描述

更新（头行编辑 / 行增删）

请求

项目

值

HTTP Method

POST

Path

https://xxxx.com/deepfos-server/journal-model-server1-0/business/model/data/update

Query Parameters：与「同步批量保存」相同。

Request Body（ModelDataBatchDTO）：与保存相同；行内通过 operateType 等区分 EDIT / ADD / DELETE / DELETE_ADD（与 SDK JournalModel.update 一致）。

响应：与「同步批量保存」相同（ModelDataReturnDTO）。

按条件查询头行数据

请求

项目

值

HTTP Method

POST

Path

https://xxxx.com/deepfos-server/journal-model-server1-0/business/model/data/query/by/where

Query Parameters：与「同步批量保存」相同。

Request Body（OpenAPI 类型名为 ModelDataQueryNewDTO）

字段名

类型

说明

elementName

String

凭证模型名称

path / folderId

String

元素定位

whereStr

String

条件字符串；字段名与头表匹配

headQueryCols

Array<String>

头表返回列

lineQueryCols

Array<String>

行表返回列

sortConfig

Array<Object>

排序；每项 QuerySortDTO：col、type（如 asc/desc）

响应（200 / 401 / 403 / 404）

规范声明为：对象，其 键为表名（或逻辑名），值为 行对象数组（array of object，additionalProperties 自由字段）。与「按表名分组的字典」叙述一致。

标准校验

请求

项目

值

HTTP Method

POST

Path

https://xxxx.com/deepfos-server/journal-model-server1-0/business/model/data/check

Query Parameters：与「同步批量保存」相同。

Request Body（CheckStandardVO）

字段名

类型

说明

elementName

String

凭证模型名称

path / folderId

String

定位

whereStr

String

与头表字段匹配的条件

dataList

Array<Object>

可选维度；CheckStandardDataVO：mainId、journalId、journalTypeCode

响应：与「同步批量保存」相同（ModelDataReturnDTO）。

借贷平衡校验

请求

项目

值

HTTP Method

POST

Path

https://xxxx.com/deepfos-server/journal-model-server1-0/business/model/data/check/dc/balance

Query Parameters：与「同步批量保存」相同。

Request Body（JmPostParamVO）

字段名

类型

说明

elementName

String

凭证模型名称

path / folderId

String

定位

whereStr

String

按头表字段匹配的条件

dataList

Array<Object>

过账 / 取消维度；JmPostParamDataVO：journalId、journalTypeCode

响应（200 / 401 / 403 / 404，JmPostResultVO）

字段名

类型

说明

success

Boolean

是否成功

msg

String

提示

postResult

Object<String>

键值型过账结果明细

fmPostMsg

Any

财务消息等（规范未细化类型）

净额计算

请求

项目

值

HTTP Method

POST

Path

https://xxxx.com/deepfos-server/journal-model-server1-0/business/model/data/calc/net/amount

Query Parameters：与「同步批量保存」相同。

Request Body：与「借贷平衡校验」相同（JmPostParamVO）。

响应：与「借贷平衡校验」相同（JmPostResultVO）。

按条件删除头行数据

请求

项目

值

HTTP Method

POST

Path

https://xxxx.com/deepfos-server/journal-model-server1-0/business/model/data/delete

Query Parameters：与「同步批量保存」相同。

Request Body（ModelDataDeleteDTO）

字段名

类型

说明

elementName

String

元素名

folderId / path

String

目录定位

partitionId

String

子模型分区 id

mainKeyList

Array<Object>

按业务主键删除；每项为键值对象（如 journal_id、_type）

whereList

Array<Object>

结构化条件；QueryWhereDTO：columnName、operationCode、value

whereStr

String

条件字符串（与头表字段匹配）

响应：与「同步批量保存」相同（ModelDataReturnDTO）。

过账

请求

项目

值

HTTP Method

POST

Path

https://xxxx.com/deepfos-server/journal-model-server1-0/business/model/deal/posting

Query Parameters：OpenAPI 未声明 space / app / user；若经网关仍要求租户类参数，以网关统一约定为准。

Request Body（JmPostParamVO）：字段同「借贷平衡校验」一节。

响应（200，ModelDataReturnDTO）：结构同「同步批量保存」的响应表。

取消过账

请求

项目

值

HTTP Method

POST

Path

https://xxxx.com/deepfos-server/journal-model-server1-0/business/model/deal/cancel-post

Query Parameters：与「过账」相同（规范未列公共 Query）。

Request Body（JmPostParamVO）：字段同「借贷平衡校验」一节。

响应（200，ModelDataReturnDTO）：结构同「同步批量保存」的响应表。

二、凭证清单（Journal List）

OpenAPI 说明：journal-server1-0 暴露的 /v3/api-docs 未包含 下文 /journal-list/... 等路径（该文档侧重 /business/model/...）。下列 请求 Body 与字段表 仍依据 SDK / 元素模型约定整理；若需与线上 完全一致 的 schema，请在对应清单或模板服务的 v3/api-docs 中核对。

产品上的「凭证清单」在不同版本可能由 独立清单服务 或与 日记账 / 模板服务 合一部署。在 deepfos 仓库的 OpenAPI 模型注解中，下列接口与 清单默认查询 相关，且与凭证模板服务 同一前缀（journal-template-server1-0）：

清单默认查询

适用于按模板元素拉取清单页默认数据或列配置（与模型 JournalTemplateQuery 的引用说明一致）。

请求

项目

值

HTTP Method

POST

Path

https://xxxx.com/deepfos-server/journal-template-server1-0/journal-list/defaultQuery

Request Body（JournalTemplateQuery，POST，application/json）

字段名

类型

必填

说明

elementName

String

是

模板或清单元素编码（以环境配置为准）

folderId

String

否

与 path 二选一

path

String

否

与 folderId 二选一

响应：规范未在本次拉取的 OpenAPI 中给出；通常为平台统一包装（列表数据 + 分页或列定义等）。实现侧请以目标服务的 api-docs 为准。

说明：若贵司将「凭证清单」拆成独立 voucher-list-server 部署，需在该服务自己的 OpenAPI 中补充路径；当前 Python SDK 未提供与 JournalModelAPI 同级的独立 JournalListAPI 类，集成可优先通过网关路由或上述同服接口确认。

三、凭证模板 / 日记账（Journal Template）

OpenAPI 说明：与第二节相同，journal-server1-0 的 /v3/api-docs 未收录 /journal-template/...、/journal/...、/posting/... 等路径。以下仍为 SDK 与后端 DTO 名称 层面的请求/响应要点；精确的 可机器读取的 Schema 请以 journal-template-server1-0（或实际部署服务名）的 v3/api-docs 为准。

对应 deepfos.api.journal_template。下列为 SDK 已显式封装 的子路径（均挂在 journal-template-server1-0 下）。

查询模板全量定义

含头/体/尾表、审批流、过账配置等（JournalTemplate.query_detail）。

请求

项目

值

HTTP Method

POST

Path

https://xxxx.com/deepfos-server/journal-template-server1-0/journal-template/query-detail

Request Body（JournalTemplateQuery）

字段名

类型

说明

elementName

String

模板元素编码

folderId

String

与 path 二选一

path

String

与 folderId 二选一

响应：未在本次 journal-server1-0 OpenAPI 中声明；一般为模板聚合定义 JSON（具体结构以服务为准）。

批量保存日记账主从数据

请求

项目

值

HTTP Method

POST

Path

https://xxxx.com/deepfos-server/journal-template-server1-0/journal/batch-save

Request Body（JournalBatchDataDTO）

字段名

类型

说明

templateCode

String

模板编码

folderId / path

String

元素定位

isNew

Boolean

是否按新增语义写入

batchData

Array<Object>

JournalData（mainData、bodyData 等嵌套字段）

响应：未在本次 OpenAPI 中声明；常为统一结果对象（成功与否 + 消息/主键等）。

按条件删除日记账数据

请求

项目

值

HTTP Method

POST

Path

https://xxxx.com/deepfos-server/journal-template-server1-0/journal/delete-by-filter

Request Body（JournalDataBatchDel）

字段名

类型

说明

templateCode

String

模板编码

folderId / path

String

定位

memberInfo

Object

头表字段到取值列表的多值过滤条件（以服务实现为准）

响应：未在本次 OpenAPI 中声明。

批量查询 / 聚合 / 汇总

请求

接口

Method

Path

批量查询

POST

.../journal/get-batch-data

聚合

POST

.../journal/get-aggregate-data

汇总

POST

.../journal/get-total-data

Request Body（三个路径均为 JournalOrderDataBatchQuery）

常用字段：

字段名

类型

说明

templateCode

String

模板编码

folderId / path

String

定位

headerParams

Array<Object>

过滤（JournalDataFilterParam）

columnParams

Array

返回列

orderColumns

Array

排序列

needDesc

Boolean

是否需要维度等描述

showDetail

Boolean

维度是否下钻明细

响应：类型在 SDK 模型中常为 DataTableCustomSqlResultDTO 等，一般含 selectResult（查询二维结果）、modifyCounts 等；确切字段以服务 api-docs 为准。

过账参数查询

请求

项目

值

HTTP Method

POST

Path

https://xxxx.com/deepfos-server/journal-template-server1-0/posting/query-posting-param

Request Body（PostingParamQueryDto）

结构与 JournalTemplateQuery 类似：elementName、folderId / path，以及服务端要求的过账参数查询扩展字段。

响应：默认过账参数 DTO（名称因版本可能为 PostingParam 等），以服务 api-docs 为准。

过账 / 取消过账

请求

接口

Method

Path

过账

POST

.../posting/get-posting

取消过账

POST

.../posting/cancel-posting

Request Body（PostingRequestDto）

组成

类型

说明

templateQuery

Object

JournalTemplateQuery

postingInfoParam

Object

PostingParam（各维度默认值，由前端或集成方组装）

响应：未在本次 journal-server1-0 OpenAPI 中声明；多为过账结果 / 任务 id / 消息体，以实现为准。

参考

  • 凭证模型元素类：deepfos.element.journal.JournalModel（源码文件名为 journal.py，与 JournalModelAPI 对应）。

  • 凭证模板元素类：deepfos.element.journal_template.JournalTemplate。

  • 模型定义：deepfos.api.models.journal_model、deepfos.api.models.journal_template。

  • 本地归档的 OpenAPI JSON（journal-server1-0，用于核对 第一节 路径与 schema）：仓库外同级目录示例为 ../../../../temp/journal-server-v3-api-docs.json（相对 doc-center/doc-center/developer/api/ 上到 doc-center/temp；若仅有工作区拷贝，可自行从 {host}/deepfos-server/{journal 服务名}/v3/api-docs 导出保存）。

上一篇：数据流
下一篇：Python SDK 文档概述
本页目录

回到顶部

咨询热线

400-821-9199

我们使用 ChatGPT，基于文档中心的内容以及对话上下文回答您的问题。

ctrl+Enter to send

© 2022 先胜云. All Rights Reserved.