> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apexiumbet.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 预览与下单 - 发送订单

> Apexium 订单需要提供什么：投注选项、投注额、价格下限、部分成交与到期；预览与下单有何不同，以及两者各自返回什么。

`POST /v1/orders` 既用于预览，也用于下单。`mode` 为必填且没有默认值，因此请求绝不会意外下单。

| `mode` | 发生什么 | 响应 |
| - | - | - |
| `"preview"` | 应用所有规则和限额，并以测试订单的方式向博彩公司试单。不会下单，也不会存储任何内容。 | `200`，带 `status: "PREVIEW"` |
| `"place"` | 订单被下达。 | `201` 并返回新订单；若重发相同请求，则返回 `200` 和已有订单（参见[幂等性](https://docs.apexiumbet.com/zh/guides/idempotency.md)） |

## 请求

```json theme={null}
{
  "mode": "place",
  "clientOrderId": "my-order-0002",
  "fixtureId": "id1000001761300868",
  "outcomeId": 101,
  "playerId": 0,
  "side": "back",
  "bookmakers": ["sharpbet", "betfair-ex"],
  "stake": { "amount": "200.00", "currency": "USD" },
  "minPrice": "1.90",
  "acceptBetterOdds": true,
  "acceptPartialStake": true,
  "expiresAt": "2026-10-05T15:00:00.000Z"
}
```

| 字段 | 含义 |
| - | - |
| `clientOrderId` | 您为订单设定的标识符，在您的账户内唯一。它使重试变得安全。 |
| `fixtureId`、`outcomeId`、`playerId` | 投注选项，使用行情数据的标识符。`playerId` 默认为 `0`（无球员）。 |
| `side` | `"back"`。v1 不支持 lay。 |
| `bookmakers` | 投注额可以分配到的博彩公司。省略时，使用您账户的所有博彩公司。 |
| `stake` | 总投注额，以账户币种计。参见[金额格式](https://docs.apexiumbet.com/zh/guides/money.md)。 |
| `minPrice` | 您接受的最低价格，至少为 `1.001`。 |
| `acceptBetterOdds` | `true` 允许注单以优于报价的价格成交。 |
| `acceptPartialStake` | `true` 接受只成交部分投注额。`false` 为全部成交否则撤销（fill or kill）。 |
| `expiresAt` | 可选。在该时间之前持续处理未成交的剩余部分，最晚为一小时之后。 |

### 投注额如何拆分

投注额会在所请求的博彩公司之间拆分，只选取报价不低于 `minPrice` 的那些，并遵守各自的限额。每一部分成为一笔**注单**。因此一个订单可以包含多笔不同价格的注单；`averageFilledPrice` 是它们按投注额加权的平均值。

### 部分成交与到期

| `acceptPartialStake` | `expiresAt` | 行为 |
| - | - | - |
| `false` | — | 全部成交否则撤销（fill or kill）：要么成交全部投注额，要么都不成交。 |
| `true` | 未设置 | 立即成交否则撤销（immediate or cancel）：当前能成交的部分保留，其余丢弃。 |
| `true` | 已设置 | 当前能成交的部分保留，剩余部分在 `expiresAt` 之前持续处理。 |

带 `expiresAt` 的订单会一直保持进行中，直到成交或到期。可通过 [`POST /v1/orders/{id}/cancel`](https://docs.apexiumbet.com/zh/guides/cancellation) 提前撤单。部分环境尚未提供到期功能：它们会返回 `503 EXPIRY_NOT_AVAILABLE`，而去掉 `expiresAt` 的同一订单可以正常下单。

### 博彩公司

* **您的博彩公司。** `GET /v1/me` 列出您账户的博彩公司。请求其他博彩公司会返回 `403 BOOKMAKER_NOT_AVAILABLE`。
* **对 API 关闭的博彩公司。** 某个博彩公司即使已在您的账户上启用，也可能对 API 关闭，`GET /v1/me` 不会列出它。请求它会返回 `400 BOOKMAKER_NOT_AVAILABLE_VIA_API`，且省略 `bookmakers` 时也绝不会使用它。

## 先预览

预览返回当前会下达的内容：`bets` 中每个博彩公司对应一项，包含其状态、投注额和价格。

```json theme={null}
{
  "clientOrderId": "my-order-0002",
  "status": "PREVIEW",
  "requestedStake": { "amount": "200.00", "amountCents": 20000, "currency": "USD" },
  "filledStake": { "amount": "200.00", "amountCents": 20000, "currency": "USD" },
  "averageFilledPrice": "1.93",
  "bets": [
    { "bookmaker": "sharpbet", "status": "PLACED", "requestedStake": { "amount": "120.00", "amountCents": 12000, "currency": "USD" }, "filledPrice": "1.95" },
    { "bookmaker": "betfair-ex", "status": "PLACED", "requestedStake": { "amount": "80.00", "amountCents": 8000, "currency": "USD" }, "filledPrice": "1.90" }
  ]
}
```

示例已缩短。价格会变动：预览是一个较好的估计，而不是预留。当无法下达任何内容时，预览返回的错误与下单时相同。如果只想读取价格和限额，请用 `GET /v1/betslip` 读取投注单：参见[行情赔率与投注单](https://docs.apexiumbet.com/zh/guides/feed-odds-and-betslip.md)。

## 拒绝

在向博彩公司发送任何内容之前，会先检查订单：您的余额、每场赛事的限额、账户规则、价格和流动性。检查失败时，请求返回错误，不记录任何内容；参见[错误](https://docs.apexiumbet.com/zh/api-reference/errors.md#订单拒绝)。

订单记录之后，博彩公司仍可能拒绝其负责的那一部分。这不是错误：订单照常返回，被拒绝的注单带有 `status: "REJECTED"` 和 `declineReason`。参见[订单与注单生命周期](https://docs.apexiumbet.com/zh/guides/order-lifecycle.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.