> 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/v3/dao-ru-sun-yi-ji-lu-jie-kou.md).

# 导入损益记录接口

### 接口概述

该接口用于批量导入损益记录到系统中，支持一次性导入多条损益记录数据。

* **请求方式**：`POST`
* **请求 URL**：`https://openapi.elven.com/open/v3/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="173">参数名</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>asset</td><td>String</td><td>是</td><td>标的资产名称，最大 200 字符</td></tr><tr><td>gainLossAsset</td><td>String</td><td>是</td><td>收益（损失）计量的资产币种代码，需区分大小写，可从<a href="/pages/qT2urb03RW7LSHL5onWi">币种查询接口</a>获取当前 entity 所支持的币种</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></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": "QfgBd6vH2ptevhqZjNTn06MiJOFUXGcD",
    "sourceId": "RHFjsy6UIgM1rdxvefXVsJy8L3NOhBmQ",
    "timezone": "UTC",
    "list": [
        {
            "datetime": "2024-08-01 15:59:00",
            "gainLossID": "123458",
            "type": "FUTURE_UNREALIZED",
            "asset": "ETHUSDT-PERP1",
            "positionSide": "LONG",
            "gainLossAsset": "USDT",
            "gainLossAmount": 500,
            "memo": ""
        },
        {
            "datetime": "2024-08-01 16:00:00",
            "gainLossID": "123459",
            "type": "FUTURE_REALIZED",
            "asset": "ETHUSDT-PERP1",
            "positionSide": "LONG",
            "gainLossAsset": "USDT",
            "gainLossAmount": 600,
            "memo": ""
        }
    ]
}

```

#### 响应参数

<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
}

```

### 在线调试

您可以通过 Apifox 服务进行接口的在线调试：<https://zswsuv3jhf.apifox.cn/api-253901227>

### 注意事项

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