导入记账凭证接口

接口概述

该接口用于批量导入记账凭证，一次性最多导入 1000 条数据。

请求方式：POST
请求 URL：https://openapi.elven.com/open/v4/externalJournal

导入规则：

单次最多导入 1000 条 Journal；
任意一条数据校验失败，则整批回滚并返回出错的行号与原因；
导入后，Journal 的 journalType 固定为 GENERAL_JOURNAL；
每条 Journal 的 entryList 必须借贷平衡（以 amountFC 校验）；
Journal 所属 Source 必须为 OpenAPI 类型；如名称不存在，系统自动创建同名 OpenAPI Source。

请求头参数

参数名

类型

必填

说明

elven-api-key

String

是

分配给您的API密钥

elven-api-sign

String

是

请求签名，用于验证请求合法性

elven-api-timestamp

String

是

请求时间戳，毫秒级

查看详细说明

请求参数

Body 参数（JSON 数组）

请求体是一个 JSON 数组，每个元素为一个记账凭证记录对象。

余额记录对象

参数名

类型

必填

说明

journalImportSourceName

String

是

本次导入的 Source 名称（仅支持 OpenAPI 类型）。如不存在将自动创建；最大 100 字符。若存在同名 CSV 类型 Source，则本次导入失败；若存在同名 OpenAPI Source，则导入到该 Source。

timezone

String

否

datetime 的时区；为空时默认使用 Entity 时区。参见时区信息。

mappingRuleName

String

是

科目映射规则名称。需提前在系统内配置好。

functionalCurrency

String

否

报告币种 Symbol；为空则使用当前 Entity 的报告币种。若不为空，系统将按价格源换算为报告币种，并把原币种与金额追加写入到 memo（若已有 memo，则在最前方拼接）。

journalList

Array

是

Journal 列表，单次最多 1000 条。

`journalList` 数组元素

参数名

类型

必填

说明

journalNo

String

是

Journal 编号

datetime

String

是

记账时间，格式：YYYY-MM-DD HH:mm:ss

memo

String

否

备注

referenceNo

String

否

参考编号

entryLines

Array

是

分录列表，必须借贷平衡

（以 amountFC 作为最终平衡校验基准）。

`entryList` 数组元素

参数名

类型

必填

说明

accountName

String

是

科目名称（需在映射规则中可被识别）

originalCurrency

String

是

原始币种 Symbol

amount

String

是

原始币种金额（字符串格式，保留精度）

amountFC

String

是

报告币种金额（字符串格式，保留精度）

balanceType

String

是

借贷方向，枚举：Dr / Cr

auxiliaryValueList

Array

是

辅助核算字段列表，最多 10 个

`auxiliaryValueList` 数组元素

参数名

类型

必填

说明

auxiliaryCodeName

String

否

辅助核算字段名称；需与系统已有字段一致；仅支持“自定义选项（Custom Options）类型”

value

String

否

具体值；当 auxiliaryCodeName 不为空时必填。若未匹配到已有选项，系统将自动创建。

请求示例

{
  "journalImportSourceName": "journal_import_20250812",
  "timezone": "",
  "functionalCurrency": "USDT",
  "mappingRuleName": "import_from_internal_system",
  "journalList": [
    {
      "journalNo": "JN202508130001",
      "datetime": "2025-08-17 10:30:00",
      "memo": "",
      "referenceNo": "REF-INT-001",
      "entryLines": [
        {
          "accountName": "Crypto assets",
          "originalCurrency": "BTC",
          "amount": 0.5,
          "amountFC": 100,
          "balanceType": "Dr",
          "auxiliaryValueList": [
            {
              "auxiliaryCodeName": "Entity",
              "value": "Entity01"
            },
            {
              "auxiliaryCodeName": "Project",
              "value": "Project01"
            }
          ]
        },
        {
          "accountName": "Revenue",
          "originalCurrency": "BTC",
          "amount": 0.5,
          "amountFC": 100,
          "balanceType": "Dr",
          "auxiliaryValueList": [
            {
              "auxiliaryCodeName": "Entity",
              "value": "Entity02"
            },
            {
              "auxiliaryCodeName": "Project",
              "value": "Project02"
            }
          ]
        },
        {
          "accountName": "Unrestricted Crypto assets",
          "originalCurrency": "BTC",
          "amount": 0.5,
          "amountFC": 100,
          "balanceType": "Cr",
          "auxiliaryValueList": [
            {
              "auxiliaryCodeName": "Entity",
              "value": "Entity02"
            },
            {
              "auxiliaryCodeName": "Project",
              "value": "Project02"
            }
          ]
        },
        {
          "accountName": "Revenue",
          "originalCurrency": "BTC",
          "amount": 0.5,
          "amountFC": 100,
          "balanceType": "Cr",
          "auxiliaryValueList": [
            {
              "auxiliaryCodeName": "Entity",
              "value": "Entity03"
            },
            {
              "auxiliaryCodeName": "Project",
              "value": "Project03"
            }
          ]
        }
      ]
    }
  ]
}

响应参数

参数名

类型

说明

success

Boolean

数据已通过校验，系统将异步进行数据创建。

响应示例

{
    "status": "success",
    "data": true,
    "requestId": "3f785786-a5a4-4907-8674-e6784bcc92ea"
}

注意事项

异步处理：本接口调用成功仅表示数据被系统接收并进入预处理数据库；系统会在后台完成解析、映射与校验，处理完成后结果才会反映在 Journal 列表中。
整批回滚：任意一条数据不合法将导致整批回滚；请根据失败响应中的 errorRowIndex / errorMessage 修复后再提交。
数量限制：单次请求最多导入 1000 条 Journal；单个 Journal 的 entryList 建议不超过 5000 条。
时间格式：datetime 必须严格使用 YYYY-MM-DD HH:mm:ss；请结合 timezone 确保时间语义正确。
时区说明：若未提供 timezone，系统默认采用当前 Entity 的时区。
映射要求：mappingRuleName 必须存在且可用；accountName 必须能被映射规则识别，否则报错。
币种换算：若提供 functionalCurrency，系统将按价格源换算并在 memo 前部追加“原币种与金额”信息（若已有 memo 则拼接在最前）。
借贷平衡：以 amountFC 为最终平衡校验基准；

错误信息（示例）

sourceName 匹配到已有的 CSV 数据源

sourceName matches an existing CSV data source. Please use a different name.

timezone 内容无法匹配到枚举值

timezone value does not match any valid enum. Please follow the API specification.

functionalCurrency 匹配到 0 个/多个资产

functionalCurrency '未识别到的原始数据的文本' matched zero or multiple assets. Please add it as a custom asset in the Asset list, or create a mapping rule of type "Custom Data" in Asset Mapping.

mappingRlueName 未匹配到已有科目映射规则

mappingRuleName does not match any existing account mapping rule. Please manage mapping rules in Ledger → Chart of Account → Account Mapping → Import to Eleven.

journalList 格式不符合要求

journalList format is invalid.

datetime 无法识别

datetime is invalid. Please use the format YYYY-MM-DD HH:mm:ss.

entryList 格式不符合要求

entryList format is invalid.

accountName 没有提前配置映射规则

accountName '未识别到的原始数据的文本' has no configured mapping rule. Please manage mapping rules in Ledger → Chart of Account → Account Mapping → Import to Eleven.

originalCurrency 匹配到 0 个/多个资产

originalCurrency '未识别到的原始数据的文本' matched zero or multiple assets. Please add it as a custom asset in the Asset list, or create a mapping rule of type "Custom Data" in Asset Mapping.

amount 无法识别为数字

amount is not a valid number.

amountFC 无法识别为数字

amountFC is not a valid number.

balanceType 未匹配到枚举值

balanceType does not match any valid enum. Please use Dr or Cr.

auxiliaryValueList 格式不符合要求

auxiliaryValueList format is invalid.

auxiliaryCodeName 未匹配到系统中已有的自定义类型的辅助核算字段

auxiliaryCodeName '未识别到的原始数据的文本' does not match any existing auxiliary code of type "Custom Options".

auxiliaryValueList name 不为空时、 value 为空

auxiliaryValueList.value is required when name is not empty. If the current entry has no value for the auxiliary code, do not include the name in auxiliaryValueList.

单条 entry 的辅助核算数量超过 10 个

The number of auxiliary values in a single entry exceeds the maximum limit of 10.

journal 借贷不平衡

Debit and credit amountFC values do not balance in the journal.

Previous导入账户余额接口 Next删除记账凭证接口

Last updated 4 days ago

Was this helpful?

接口概述

请求头参数

请求参数

Body 参数（JSON 数组）

journalList 数组元素

entryList 数组元素

auxiliaryValueList 数组元素

请求示例

响应参数

响应示例

注意事项

错误信息（示例）

`journalList` 数组元素

`entryList` 数组元素

`auxiliaryValueList` 数组元素