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

# 结算与评级 —— 逐 outcome 评级、四分之一盘与周期盘

> 在 OddsPapi 上为投注评级：基于冻结 ID 的逐 outcome 结算评级、亚洲四分之一盘的半注计算、周期盘评级，以及 UNDECIDED 与 CANCELLED 的处理方式。

结算让整条管线闭环：您用于定价与下注的那些 ID，会原样带着评级回来 —— 评级因此是对您已存键的一次查询，而不是一套需要按运动自建与维护的规则引擎。

<Note>
  OddsPapi 聚合博彩商价格，并非官方或持牌的联赛数据提供方。结算源自已解析的多源事实，且**期货结算正在推出中** —— 端点已存在，但尚未返回结果。
</Note>

***

## 一次请求，全部评级

`GET /fixtures/settlement` 接受 `fixtureId`（可选 `outcomeId` / `playerId` 缩小范围），返回赛事最终状态，以及每个 outcome 一行的评级：

```json theme={null}
"scores": {
  "result": { "period": "result", "participant1Score": 23, "participant2Score": 30 }
},
"settlements": [
  {
    "marketId": 141,
    "marketType": "1x2",
    "outcomeId": 142,
    "playerId": 0,
    "status": "WIN",
    "team1Score": 23,
    "team2Score": 30,
    "periods": ["fulltime"],
    "margin": 7.0
  },
  {
    "marketId": 141,
    "marketType": "1x2",
    "outcomeId": 141,
    "playerId": 0,
    "status": "LOSE",
    "team1Score": 23,
    "team2Score": 30,
    "periods": ["fulltime"],
    "margin": -7.0
  }
]
```

每行都自带依据：`team1Score` / `team2Score` 是评级所依据的比分，`periods` 指明使用了哪些周期行，`margin` 是适用时的净胜幅度 —— 足以审计任何一条评级，而无需重新推导。

请在赛事到达 `statusId` `2`（已结束）后调用。尚无法评级的行会以 `UNDECIDED` 返回而不是被省略 —— 见[下文](#undecided-与-cancelled-是状态而非错误)。

***

## 按选项评级，按评级派彩

投注基于与博彩商无关的**选项**键评级 —— `{fixtureId}:{outcomeId}:{playerId}` —— 因为无论谁报价，同一选项的胜负判定完全一致。把下注时存储的 `oddsId` 去掉博彩商段，关联就完成了。

以 100 注、赔率 2.00 为例，各评级的返还：

| 评级          | 含义                   |  返还 |
| ----------- | -------------------- | --: |
| `WIN`       | 全胜                   | 200 |
| `LOSE`      | 全负                   |   0 |
| `PUSH`      | 作废 / 打平线值 —— 退还本金    | 100 |
| `HALFWIN`   | 半注胜，半注退还             | 150 |
| `HALFLOSS`  | 半注负，半注退还             |  50 |
| `CANCELLED` | 盘口作废 —— 退还本金         | 100 |
| `UNDECIDED` | 尚无法评级 —— 携带 `reason` |   — |

词汇表定义见[枚举 → settlementStatus](/zh/api-reference/enumerations#settlementstatus)；新枚举值只会追加、绝不复用，因此未知评级应视为「持有」，而非错误。

***

## 四分之一盘：半注评级从何而来

亚洲四分之一盘是合二为一的两笔投注 —— 大 2.25 即半注押大 2.0、半注押大 2.5。结算端点直接对合成结果评级，无需您自行拆分：

* **大 2.25，全场共 2 球** —— 大 2.0 的半注 push，大 2.5 的半注负 → `HALFLOSS`。100 注拿回 50。
* **小 2.25，全场共 2 球** —— 小 2.0 的半注 push，小 2.5 的半注胜 → `HALFWIN`。100 注、赔率 1.90 时返还 50 + 50 × 1.90 = **145**。

与其他线值一样，每个四分之一线值都是独立的 `marketId`，因此大 2.25 与大 2.5 绝不会混入同一盘口。定价这些盘口见 [sharp 线路交易](/zh/guides/sharp-line-trading)，覆盖情况见[盘口覆盖](/zh/coverage/markets)。

***

## 周期盘基于周期行评级

周期盘 —— 上半场大小球、首盘胜负、率先达到某比分 —— 依据各周期比分行（`p1`、`p2`……）评级，而非全场 `result`。每条结算行的 `periods` 数组指明使用了哪些行。

请对照运动的结构解读周期：`p1` 在足球中是半场，在 NBA 篮球中是一节，在网球中是一盘 —— 赛事上的 `expectedPeriods` 与 `periodLength` 会告诉您是哪种。完整键词汇表（包括 `fulltime+overtime` 等组合区段与网球子周期键）见[枚举 → period](/zh/api-reference/enumerations#period)。

***

## `UNDECIDED` 与 `CANCELLED` 是状态而非错误

两者都携带人类可读的 `reason` 说明原因，且在运营上含义不同：

* **`UNDECIDED`** —— 结果数据不足或待定。请将该投注保留在结算队列中稍后复查；不要紧密循环重试 —— 按计划或在赛事更新时重新轮询。
* **`CANCELLED`** —— 盘口作废，本金退还。这是终态：完成退款并关闭该投注。赛事进入 `statusId` `3`（已取消）是常见原因，但个别盘口也可能单独作废。

请把两者作为结算队列中的显式状态处理，而不是重试直到成功，并记录 `reason` —— 它就是这笔投注为何如此派彩的审计轨迹。

***

## 期货

`GET /futures/settlement` 已存在但返回 `501` —— 期货结算正在推出中，尚未返回结果。赛事结算不受影响。在其落地之前，冠军类盘口需要您用自己的结果源评级。

***

## 您可以依赖的保证

* **评级落在冻结的 ID 上。** 您定价所用的 `marketId` / `outcomeId` 就是带着评级回来的那一个 —— 无需名称匹配、无需按博彩商翻译，博彩商改名盘口时也无需重新映射。
* **四分之一盘精确结算。** `HALFWIN` / `HALFLOSS` 是显式评级，遵循上文的半注计算 —— 绝不会四舍五入到最近的整评级。
* **不会有东西无声消失。** 无法评级的行以 `UNDECIDED` 加 `reason` 返回；作废以 `CANCELLED` 加 `reason` 返回。结算队列中的每笔投注都会到达一个有解释的终态。
* **管线在同一个键上闭环。** 同一 `oddsId` 对应实时价格、其[历史与收盘线](/zh/api-reference/concepts#历史赔率与-clv)，以及（去掉博彩商段后）它的评级。