> For the complete documentation index, see [llms.txt](https://docs.elven.com/v3/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.elven.com/v3/chinese/openapi/v4/dao-ru-ji-zhang-ping-zheng-jie-kou.md).

# 导入记账凭证接口

### 接口概述

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

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

**导入规则**：

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

### 请求头参数

<table><thead><tr><th width="202">参数名</th><th width="90">类型</th><th width="64">必填</th><th>说明</th></tr></thead><tbody><tr><td>elven-api-key</td><td>String</td><td>是</td><td>分配给您的API密钥</td></tr><tr><td>elven-api-sign</td><td>String</td><td>是</td><td>请求签名，用于验证请求合法性</td></tr><tr><td>elven-api-timestamp</td><td>String</td><td>是</td><td>请求时间戳，毫秒级</td></tr></tbody></table>

[查看详细说明](https://docs.elven.com/v3/openapi/jie-kou-shou-quan#elven-api-sign)

### 请求参数

#### Body 参数（JSON 数组）

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

**余额记录对象**

<table><thead><tr><th width="223.74609375">参数名</th><th width="88.2265625">类型</th><th width="78.81640625">必填</th><th>说明</th></tr></thead><tbody><tr><td>journalImportSourceName</td><td>String</td><td>是</td><td><strong>本次导入的 Source 名称（仅支持 OpenAPI 类型）</strong>。如不存在将自动创建；最大 100 字符。若存在<strong>同名 CSV 类型 Source</strong>，则本次导入失败；若存在<strong>同名 OpenAPI Source</strong>，则导入到该 Source。</td></tr><tr><td>timezone</td><td>String</td><td>否</td><td><code>datetime</code> 的时区；为空时默认使用 Entity 时区。参见<a href="https://docs.elven.com/v3/~/revisions/y0ldstKm87X4xSBoZRzJ/openapi/shi-qu-xin-xi"><strong>时区信息</strong></a>。</td></tr><tr><td>useAccountID</td><td>Boolean</td><td>否</td><td><p>是否使用 AccountID 来导入科目信息。不填写视为 False。<br><br>设置为 False 时：</p><p><code>mappingRuleName</code>  必填。</p><p>entryList 中的 <code>accountName</code> 必填。</p><p>entryList 中的 <code>AccountID</code>必须为空。<br><br>设置为 True 时：</p><p><code>mappingRuleName</code>  必须为空。</p><p>entryList 中的 <code>accountName</code> 必须为空。</p><p>entryList 中的 <code>AccountID</code>必填，且必须可以匹配到系统已有的科目。</p></td></tr><tr><td>mappingRuleName</td><td>String</td><td>否</td><td>科目映射规则名称。需提前在系统内配置好。</td></tr><tr><td>functionalCurrency</td><td>String</td><td>否</td><td>报告币种 Symbol；为空则使用当前 Entity 的报告币种。若不为空，系统将按价格源<strong>换算为报告币种</strong>，并把<strong>原币种与金额</strong>追加写入到 <code>memo</code>（若已有 <code>memo</code>，则在最前方拼接）。</td></tr><tr><td>journalList</td><td>Array</td><td>是</td><td><strong>Journal 列表</strong>，单次最多 <strong>1000 条</strong>。</td></tr><tr><td>autoCreateCustomAssets</td><td>Boolean</td><td>否</td><td>是否自动将无法匹配到已有资产的originalCurrency 创建为自定义资产。不填写视为 False</td></tr></tbody></table>

#### **`journalList` 数组元素**

<table><thead><tr><th width="133.28125">参数名</th><th width="78.89453125">类型</th><th width="68.60546875">必填</th><th>说明</th></tr></thead><tbody><tr><td>journalNo</td><td>String</td><td>是</td><td>Journal 编号</td></tr><tr><td>datetime</td><td>String</td><td>是</td><td>记账时间，格式：<code>YYYY-MM-DD HH:mm:ss</code></td></tr><tr><td>memo</td><td>String</td><td>否</td><td>备注</td></tr><tr><td>referenceNo</td><td>String</td><td>否</td><td>参考编号</td></tr><tr><td>entryLines</td><td>Array</td><td>是</td><td><p><strong>分录列表</strong>，<strong>必须借贷平衡</strong></p><p>（以 <code>amountFC</code> 作为最终平衡校验基准）。</p></td></tr></tbody></table>

#### `entryList` 数组元素

<table><thead><tr><th width="182.8125">参数名</th><th width="99.3984375">类型</th><th width="109.59375">必填</th><th>说明</th></tr></thead><tbody><tr><td>accountName</td><td>String</td><td>否</td><td><p>科目名称<br><code>useAccountID</code> 设置为 True 时必须为空。</p><p><code>useAccountID</code> 设置为 False 时必填，且可以通过映射关系匹配到已有的科目。</p></td></tr><tr><td>accountID</td><td>String</td><td>否</td><td>科目ID<br><code>useAccountID</code> 设置为 True 时必填，且可以匹配到已有的科目。<br><code>useAccountID</code> 设置为 False 时必须为空。</td></tr><tr><td>originalCurrency</td><td>String</td><td>是</td><td>原始币种 Symbol</td></tr><tr><td>amount</td><td>String</td><td>是</td><td>原始币种金额（字符串格式，保留精度）</td></tr><tr><td>amountFC</td><td>String</td><td>是</td><td>报告币种金额（字符串格式，保留精度）</td></tr><tr><td>balanceType</td><td>String</td><td>是</td><td>借贷方向，枚举：<code>Dr</code> / <code>Cr</code></td></tr><tr><td>auxiliaryValueList</td><td>Array</td><td>是</td><td>辅助核算字段列表，<strong>最多 10 个</strong></td></tr></tbody></table>

#### `auxiliaryValueList` 数组元素

<table><thead><tr><th width="204.328125">参数名</th><th width="96.9296875">类型</th><th width="93.7734375">必填</th><th>说明</th></tr></thead><tbody><tr><td>auxiliaryCodeName</td><td>String</td><td>否</td><td>辅助核算字段名称；需与系统已有字段一致；<strong>仅支持“自定义选项（Custom Options）类型”</strong></td></tr><tr><td>value</td><td>String</td><td>否</td><td>具体值；当 <code>auxiliaryCodeName</code> 不为空时<strong>必填</strong>。若未匹配到已有选项，系统将自动创建。</td></tr></tbody></table>

#### 请求示例

```json
{
  "journalImportSourceName": "journal_import_20250812",
  "timezone": "",
  "functionalCurrency": "USDT",
  "useAccountID": false,
  "mappingRuleName": "import_from_internal_system",
  "autoCreateCustomAssets": false,
  "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"
            }
          ]
        }
      ]
    }
  ]
}
  
```

### 响应参数

<table><thead><tr><th width="148">参数名</th><th width="137">类型</th><th>说明</th></tr></thead><tbody><tr><td>success</td><td>Boolean</td><td>数据已通过校验，系统将异步进行数据创建。</td></tr></tbody></table>

#### 响应示例

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

#### **注意事项**

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