# 导入损益记录接口

### 接口概述

该接口用于批量导入损益记录到系统中，支持一次性导入多条损益记录数据。新增按照**资产代码**传递资产信息的能力。（原有 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="../shi-qu-xin-xi">具体介绍</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="../v3/zi-chan-cha-xun-jie-kou">资产查询接口</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="../v3/zi-chan-cha-xun-jie-kou">资产查询接口</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` 参数必须选择正确的值，具体规则见上文。