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

# 取消订单

支持四种取消方式。它们都使用相同的响应结构：`{ requestID, data: [ ...CancelResponsePayload ] }`。

<h2 id="cancel-response-payload">
  取消响应载荷
</h2>

每次成功取消都会返回一条或多条如下形态的记录。注意请求与响应的字段大小写不同：请求为 `orderId`/`gameId`（`d` 小写），响应为 `orderID`/`gameID`（`ID` 大写）。

<CodeGroup>
  ```json JSON theme={null}
  {
    "success": true,
    "orderID": "67f45377c18c6697c172afa4",
    "odds": -110,
    "filled": 0,
    "offered": 100,
    "remaining": 100,
    "side": "5c12bc1ce0daba000f47ba8b",
    "number": -3.5,
    "gameID": "688c0516fbc14da0c202d426",
    "userReference": "client-ref-001",
    "description": "Dallas Mavericks +3.5"
  }
  ```
</CodeGroup>

<ResponseField name="success" type="boolean">
  订单已取消时为 `true`。
</ResponseField>

<ResponseField name="orderID" type="string">
  被取消订单的 ID。
</ResponseField>

<ResponseField name="filled" type="number">
  取消到达前已经成交的数量。
</ResponseField>

<ResponseField name="offered" type="number">
  取消后始终为 `0` — 挂单侧已归零。
</ResponseField>

<ResponseField name="remaining" type="number">
  取消时尚未成交的数量。
</ResponseField>

<ResponseField name="odds" type="number">
  被取消订单的美式赔率，从 maker 视角给出。
</ResponseField>

<ResponseField name="side" type="string">
  参赛者 ID（moneyline/spread）或 `over`/`under`（大小球）。
</ResponseField>

<ResponseField name="number" type="number">
  让分或大小球盘口数值；moneyline 为 `null`。
</ResponseField>

<ResponseField name="gameID" type="string">
  被取消订单所属的赛事。
</ResponseField>

<ResponseField name="userReference" type="string">
  下单时设置的 `userReference`（如有）。
</ResponseField>

<ResponseField name="description" type="string">
  投注的人类可读描述（例如 `"Dallas Mavericks +3.5"`）。
</ResponseField>

<h2 id="cancel-by-id">
  按 ID 取消
</h2>

按订单 ID 取消单笔订单。

<h3 id="request">
  请求
</h3>

<CodeGroup>
  ```json JSON theme={null}
  [
    "cancelById",
    {
      "requestID": "YOUR_REQUEST_ID",
      "orderId": "ORDER_ID_TO_CANCEL"
    }
  ]
  ```
</CodeGroup>

<h3 id="response">
  响应
</h3>

<CodeGroup>
  ```json JSON theme={null}
  {
    "requestID": "YOUR_REQUEST_ID",
    "data": [
      {
        "success": true,
        "orderID": "67f45377c18c6697c172afa4",
        "odds": -110,
        "filled": 0,
        "offered": 0,
        "remaining": 100,
        "side": "5c12bc1ce0daba000f47ba8b",
        "number": -3.5,
        "gameID": "688c0516fbc14da0c202d426",
        "userReference": "client-ref-001",
        "description": "Dallas Mavericks +3.5"
      }
    ]
  }
  ```
</CodeGroup>

<h2 id="cancel-multiple">
  批量取消
</h2>

按 ID 取消一组指定订单。

<h3 id="request-2">
  请求
</h3>

<CodeGroup>
  ```json JSON theme={null}
  [
    "cancelMultiple",
    {
      "requestID": "YOUR_REQUEST_ID",
      "orderIDs": [
        "ORDER_ID_1",
        "ORDER_ID_2",
        "ORDER_ID_3"
      ]
    }
  ]
  ```
</CodeGroup>

<h3 id="response-2">
  响应
</h3>

`data` 中每个订单 ID 对应一条记录；请检查每条的 `success` 标志。

<CodeGroup>
  ```json JSON theme={null}
  {
    "requestID": "YOUR_REQUEST_ID",
    "data": [
      {
        "success": true,
        "orderID": "ORDER_ID_1",
        "odds": -110,
        "filled": 0,
        "offered": 0,
        "remaining": 100,
        "side": "5c12bc1ce0daba000f47ba8b",
        "number": -3.5,
        "gameID": "688c0516fbc14da0c202d426",
        "userReference": "",
        "description": "Dallas Mavericks +3.5"
      },
      {
        "success": false,
        "orderID": "ORDER_ID_2",
        "description": "order already cancelled"
      }
    ]
  }
  ```
</CodeGroup>

<h2 id="cancel-all-by-game">
  按赛事全部取消
</h2>

取消你在单场赛事上的全部未成交订单。可选择传入 `type`、`side` 和/或 `market`，将取消范围限定到特定盘口。

<h3 id="request-3">
  请求
</h3>

<CodeGroup>
  ```json JSON theme={null}
  [
    "cancelAllByGame",
    {
      "requestID": "YOUR_REQUEST_ID",
      "gameId": "GAME_ID_TO_CANCEL",
      "type": "spread",
      "side": "5c12bc1ce0daba000f47ba8b",
      "market": "main"
    }
  ]
  ```
</CodeGroup>

<ResponseField name="gameId" type="string" required>
  要取消订单的赛事。
</ResponseField>

<ResponseField name="type" type="string">
  可选 — 过滤到单一盘口类型：`moneyline`、`spread`、`total` 或 `moneyline1x2`。
</ResponseField>

<ResponseField name="side" type="string">
  可选 — 参赛者 ID（moneyline/spread）或 `over`/`under`（大小球）。
</ResponseField>

<ResponseField name="market" type="string">
  可选 — 盘口标识符（例如 `main`）。
</ResponseField>

<h3 id="response-3">
  响应
</h3>

<CodeGroup>
  ```json JSON theme={null}
  {
    "requestID": "YOUR_REQUEST_ID",
    "data": [
      {
        "success": true,
        "orderID": "67f45377c18c6697c172afa4",
        "odds": -110,
        "filled": 0,
        "offered": 0,
        "remaining": 100,
        "side": "5c12bc1ce0daba000f47ba8b",
        "number": -3.5,
        "gameID": "688c0516fbc14da0c202d426",
        "userReference": "",
        "description": "Dallas Mavericks +3.5"
      }
    ]
  }
  ```
</CodeGroup>

<h2 id="cancel-all">
  全部取消
</h2>

取消账户上的全部未成交订单。

<h3 id="request-4">
  请求
</h3>

<CodeGroup>
  ```json JSON theme={null}
  [
    "cancelAll",
    {
      "requestID": "YOUR_REQUEST_ID"
    }
  ]
  ```
</CodeGroup>

<h3 id="response-4">
  响应
</h3>

<CodeGroup>
  ```json JSON theme={null}
  {
    "requestID": "YOUR_REQUEST_ID",
    "data": [
      {
        "success": true,
        "orderID": "67f45377c18c6697c172afa4",
        "odds": -110,
        "filled": 0,
        "offered": 0,
        "remaining": 100,
        "side": "5c12bc1ce0daba000f47ba8b",
        "number": -3.5,
        "gameID": "688c0516fbc14da0c202d426",
        "userReference": "",
        "description": "Dallas Mavericks +3.5"
      }
    ]
  }
  ```
</CodeGroup>

<h2 id="errors">
  错误
</h2>

当取消无法处理时，服务器返回标准错误结构（无 `data` 字段）：

<CodeGroup>
  ```json JSON theme={null}
  {
    "requestID": "YOUR_REQUEST_ID",
    "error": "order not found"
  }
  ```
</CodeGroup>

常见 `error` 值：

| 错误 | 何时出现 |
| - | - |
| `invalid order ID format` | `cancelById` 的 `orderId` 不是有效的 ObjectID。 |
| `order not found` | 该订单 ID 不存在。 |
| `unauthorized: order does not belong to user` | 你正在尝试取消他人的订单。 |
| `order already cancelled` | 该订单已被取消。 |
| `order is expired` | 订单在取消到达前已过期。 |
| `order already graded` | 该订单已经结算。 |
| `game not found` | 所引用的赛事不在缓存中。 |
| `Failed to process cancelMultiple` | 处理 `cancelMultiple` 批次时发生意外错误。 |
| `Failed to process cancelAll` | 处理 `cancelAll` 时发生意外错误。 |
| `Failed to process cancelAllByGame` | 处理 `cancelAllByGame` 时发生意外错误。 |

对于批量取消（`cancelMultiple`、`cancelAllByGame`、`cancelAll`），单笔失败会出现在 `data` 中，带有 `success: false` 以及解释原因的 `description` — 只有结构级的 `error` 才表示整个请求失败。


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