# 导入损益记录接口

### 接口概述

该接口用于批量导入损益记录到系统中，支持一次性导入多条损益记录数据。新增按照**资产代码**传递资产信息的能力。（原有 V3 版本接口，必须使用 Elven 系统的资产 id 来传递资产信息）

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

### 请求头参数

<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 格式）

<table><thead><tr><th width="207">参数名</th><th width="91">类型</th><th width="65">必填</th><th>说明</th></tr></thead><tbody><tr><td>entityAccountId</td><td>String</td><td>是</td><td>账户的主键 ID</td></tr><tr><td>sourceId</td><td>String</td><td>是</td><td>Source 的主键 ID</td></tr><tr><td>timezone</td><td>String</td><td>否</td><td>时区，为空时视为 entity 时区。<a href="/pages/aGo8tOlAb3LVWBUj7oNv">具体介绍</a></td></tr><tr><td>list</td><td>Array</td><td>是</td><td>包含多条损益记录的数组（每次最多支持 5000 条记录）</td></tr></tbody></table>

**list 数组元素**

<table><thead><tr><th width="216">参数名</th><th width="95">类型</th><th width="70">必填</th><th>说明</th></tr></thead><tbody><tr><td>datetime</td><td>String</td><td>是</td><td>交易时间，格式为 <code>YYYY-MM-DD HH:mm:ss</code></td></tr><tr><td>gainLossID</td><td>String</td><td>否</td><td>损益记录唯一标识</td></tr><tr><td>type</td><td>String</td><td>是</td><td>损益交易类型</td></tr><tr><td>positionSide</td><td>String</td><td>否</td><td>合约持仓方向（枚举值：LONG/SHORT）。仅在 type 为 <code>FUTURE_REALIZED</code> 或 <code>FUTURE_UNREALIZED</code> 时必填</td></tr><tr><td>baseAssetSymbol</td><td>String</td><td>是</td><td>标的资产名称，最大 200 字符</td></tr><tr><td>gainLossAssetID</td><td>String</td><td>否</td><td><p>收益（损失）计量的资产币种ID，需区分大小写，可从<a href="/pages/VMit0TXQj6EglCd9Ac96">资产查询接口</a>当前 entity 所支持的币种<br><code>gainLossAssetID</code> 和<code>gainLossAssetSymbol</code>至少填写一个</p><p>都填写时，只会识别<code>gainLossAssetID</code></p></td></tr><tr><td>gainLossAssetSymbol</td><td>String</td><td>否</td><td><p>收益（损失）计量的资产币种代码，需区分大小写，可从<a href="/pages/VMit0TXQj6EglCd9Ac96">资产查询接口</a>当前 entity 所支持的币种<br><code>gainLossAssetID</code> 和<code>gainLossAssetSymbol</code>至少填写一个</p><p>都填写时，只会识别<code>gainLossAssetID</code></p></td></tr><tr><td>gainLossAmount</td><td>Number</td><td>是</td><td>收益（损失）金额</td></tr><tr><td>memo</td><td>String</td><td>否</td><td>备注信息</td></tr><tr><td>originalType</td><td>String</td><td>否</td><td>原始交易类型信息</td></tr></tbody></table>

**type 参数说明**

| 类型                  | 说明          |
| ------------------- | ----------- |
| FUTURE\_REALIZED    | 合约已实现收益（损失） |
| FUTURE\_UNREALIZED  | 合约未实现收益（损失） |
| OPTIONS\_REALIZED   | 期权已实现收益（损失） |
| OPTIONS\_UNREALIZED | 期权未实现收益（损失） |

#### **PositionSide 参数说明**

| type                | positionSide 是否必填 |
| ------------------- | ----------------- |
| FUTURE\_REALIZED    | 必填（LONG/SHORT）    |
| FUTURE\_UNREALIZED  | 必填（LONG/SHORT）    |
| OPTIONS\_REALIZED   | 必须为空              |
| OPTIONS\_UNREALIZED | 必须为空              |

#### 请求示例

```json
{  "entityAccountId": "w597WQZ5SzfKegoGB8qF1XRA2D39dr0U",
    "sourceId": "mKEd2CxfIvclgwCMqOpn8m9iYZ16Bde4",
    "timezone":"UTC",
    "list": [
        {
            "datetime": "2024-08-01 15:59:00",
            "gainLossID": "123458",
            "type": "FUTURE_UNREALIZED",
            "baseAssetSymbol":"ETHSOL-PERP1",
            "positionSide":"LONG",
            "gainLossAssetID":"",
            "gainLossAssetSymbol":"USDT",
            "gainLossAmount":700,
            "memo":"",
            "originalType":"8888"
        }
    ]
}
```

#### 响应参数

<table><thead><tr><th width="149">参数名</th><th width="117">类型</th><th>说明</th></tr></thead><tbody><tr><td>status</td><td>String</td><td>请求状态（如 <code>success</code>）</td></tr><tr><td>data</td><td>Boolean</td><td>请求结果（如 <code>true</code> 表示成功）</td></tr></tbody></table>

#### 响应示例

```json
{
    "status": "success",
    "data": true,
    "requestId": "478ec893-2496-4823-8e04-0797fb06f687"
}
```

### 注意事项

1. **异步处理**：该接口调用成功后只是将数据导入到预处理数据库，系统需要一段时间来处理导入的损益记录数据，处理完成后才会显示在用户损益记录列表内。
2. **记录数量限制**：每次请求最多支持导入 **5000** 条损益记录。
3. **数据完整性**：请确保提供的交易数据完整且准确，避免因数据错误导致导入失败。
4. **时间格式**：`datetime` 参数的格式必须严格按照 `YYYY-MM-DD HH:mm:ss`，否则可能导致解析错误。
5. **交易类型**：`type` 参数必须选择正确的值，具体规则见上文。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.elven.com/v3/chinese/openapi/v4/dao-ru-sun-yi-ji-lu-jie-kou.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.