# 接入准备

> 配置账户服务请求域名、apikey、x-timestamp 和出口 IP 白名单，开始调用账户余额、账户流水、账户账单与 Global Account 接口。

账户服务 API 使用独立请求域名和特定环境的 `apikey` 请求 Header。开始调用账户余额、账户流水、账户账单或 Global Account 接口前，请先确认目标环境、接口访问权限、`apikey`、`x-timestamp` 和出口 IP 白名单已经准备完成。

## 接入步骤

<steps level="3">

### 确认接口权限

账户服务接口为受限接口，需要 Onerway 为商户开通对应能力后才能访问。

- 调用账户余额、账户流水和账户账单接口前，请确认账户服务 API 权限已开通。
- 调用 Global Account 接口前，请确认 Global Account 开户、收款或资金转出能力已开通。
- 如果平台商户需要代子商户查询，请确认父子商户关系和 `onBehalfOf` 使用权限已配置。

### 选择请求域名

请使用与 `apikey` 所属环境一致的账户服务请求域名。

| 环境 | Base URL |
| --- | --- |
| Production | `https://api.onerway.com/account-server` |
| Sandbox | `https://sandbox-api.onerway.com/account-server` |

<note>

沙盒与生产环境的凭据相互独立。接口路径以 `/api/v2/...` 或当前 Global Account 页面展示的 `/api/v1/...` 开头，Base URL、接口路径和 `apikey` 必须来自同一环境。

</note>

### 保存 apikey

账户服务通过 `apikey` 请求 Header 识别调用方权限。

| Header | 必填 | 说明 |
| --- | --- | --- |
| `apikey` | 是 | Onerway 分配的账户服务访问密钥。 |

<warning>

请将 `apikey` 保存在服务端。不要把它暴露在前端页面、移动端应用、客户端 bundle、日志或公开代码仓库中。

</warning>

### 设置 x-timestamp

账户余额、账户流水和账户账单接口需要同时提供 `apikey` 和 `x-timestamp`。网关使用 `x-timestamp` 判断请求是否在有效时间窗口内，降低请求被重放的风险。

| Header | 必填 | 说明 |
| --- | --- | --- |
| `x-timestamp` | 是 | 请求时间戳；支持 10 位秒级或 13 位毫秒级，必须与服务端时间偏差在 10分钟以内。 |
| `Content-Type` | 是（POST） | `application/json`。 |

### 提供出口 IP

调用账户服务前，请向 Onerway 提供稳定的服务端出口 IP，用于配置账户服务访问白名单。

- 仅提交稳定的服务端出口 IP。
- 如果沙盒与生产环境使用不同出口 IP，请分别提供。
- 如果出口 IP 发生变更，请在切换流量前更新白名单。

### 发起服务端请求

环境、`apikey`、`x-timestamp` 与 IP 白名单就绪后，从服务端调用接口，并在请求 Header 中传入对应字段。

```bash
curl https://sandbox-api.onerway.com/account-server/api/v2/account/balance/overview/query \
  -H 'Content-Type: application/json' \
  -H 'apikey: replace_with_account_service_apikey' \
  -H 'x-timestamp: 1776931200' \
  -d '{
    "requestId": "REQ-BAL-OV-20260423-0001",
    "displayCurrency": "USD"
  }'
```

</steps>

## 接口地址

当前对外展示的账户服务接口地址如下。请以当前环境的 Base URL 拼接接口路径发起请求。

| 类别 | 接口 | Method | Path |
| --- | --- | --- | --- |
| 账户余额 | 查询账户余额总览 | `POST` | `/api/v2/account/balance/overview/query` |
| 账户余额 | 查询账户余额 | `POST` | `/api/v2/account/balance/query` |
| 账户交易 | 查询账户流水 | `POST` | `/api/v2/account/transactions/query` |
| 账户交易 | 按交易单号查询账户流水 | `POST` | `/api/v2/account/transactions/service/query` |
| 账户账单 | 导出每日账户账单 | `POST` | `/api/v2/account/statement/daily/export` |
| Global Account（全球收付账户） | 创建 Global Account | `POST` | `/api/v1/account/global/create` |
| Global Account（全球收付账户） | 查询 Global Account 详情 | `POST` | `/api/v1/account/global/getDetail` |

完整 Sandbox 示例：

- `https://sandbox-api.onerway.com/account-server/api/v2/account/balance/overview/query`
- `https://sandbox-api.onerway.com/account-server/api/v2/account/balance/query`
- `https://sandbox-api.onerway.com/account-server/api/v2/account/transactions/query`
- `https://sandbox-api.onerway.com/account-server/api/v2/account/transactions/service/query`
- `https://sandbox-api.onerway.com/account-server/api/v2/account/statement/daily/export`
- `https://sandbox-api.onerway.com/account-server/api/v1/account/global/create`
- `https://sandbox-api.onerway.com/account-server/api/v1/account/global/getDetail`

## 幂等

账户余额、账户流水和账户账单接口支持幂等控制。在 10分钟内复用同一个 `requestId` 可以安全重试请求；命中重复时返回 `10006 DUPLICATE_REQUEST` 错误，错误类型为 `idempotency_error`。

## 下一步

- [查询账户余额总览](/zh/account/api-reference/endpoints/query-account-balance-overview) - 查询多币种账户余额汇总
- [查询账户余额](/zh/account/api-reference/endpoints/query-account-balance) - 查询指定币种的账户余额
- [查询账户流水](/zh/account/api-reference/endpoints/query-account-transactions) - 查询账户流水和余额变动记录
- [按交易单号查询账户流水](/zh/account/api-reference/endpoints/query-account-transactions-by-service-id) - 按交易单号查询关联账户流水
- [导出每日账户账单](/zh/account/api-reference/endpoints/export-daily-statement) - 导出指定日期的账户账单 CSV
- [创建 Global Account](/zh/account/api-reference/endpoints/create-global-account) - 为收单收款与资金转出场景创建 Global Account
- [查询 Global Account 详情](/zh/account/api-reference/endpoints/get-global-account-details) - 查询 Global Account 开户资料与状态
- [响应码](/zh/account/api-reference/response-codes) - 处理账户服务响应码和排查动作