> For the complete documentation index, see [llms.txt](https://resources.atriptech.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://resources.atriptech.com/api-wen-dang/product-guides/extensions-and-integrations/webhook-overview/l2b-zhuang-tai-bian-geng-tong-zhi.md).

# L2B 状态变更通知

对接 L2B 状态变更 Webhook，包括投递规则、事件字段和接收处理。

当某个“客户 + 航司 + Action”的 L2B 状态变化时，Atlas 会发送此通知。

{% hint style="warning" %}
Webhook 是辅助通知渠道，不保证每条消息送达。

请始终以每次 API 响应的 `x-l2b-*` 响应头判断实时状态。
{% endhint %}

### 触发时机

| 状态变化                | 含义            |
| ------------------- | ------------- |
| `NORMAL → WARNING`  | 使用率接近上限       |
| `WARNING → CONTROL` | 实时航司请求开始受控    |
| `CONTROL → WARNING` | 控制已解除，但使用率仍较高 |
| `WARNING → NORMAL`  | 使用率恢复正常       |

只有启用在线流量保护的规则会发送通知。

当 `action` 为 `ORDER` 时，通知仅用于用量告警。

即使进入 `CONTROL`，`order.do` 也不会被降级或拒绝。

### 接收接口要求

客户需要提供 Atlas 可访问的 HTTPS 地址。

| 项目           | 约定                                |
| ------------ | --------------------------------- |
| HTTP 方法      | `POST`                            |
| Content-Type | `application/json; charset=UTF-8` |
| 成功响应         | 精确的 HTTP `200 OK`                 |
| 响应 Body      | 不校验，可为空                           |
| 时间格式         | 含 UTC 偏移量的 ISO-8601               |

Atlas 仅根据 HTTP 状态码判断投递成功。

`201`、`202`、`204` 和其他状态码均不视为成功。

先完成幂等保存或可靠入队，再返回 `200`。

### 请求结构

事件类型固定为 `l2b.state_changed`。

```json
{
  "cid": "TAC00001",
  "notificationId": "7F34D609B1F84A43B82D238F80904E26",
  "status": -1,
  "type": "l2b.state_changed",
  "data": {
    "eventId": "7F34D609B1F84A43B82D238F80904E26",
    "clientCode": "TAC00001",
    "carrier": "MU",
    "action": "VERIFY",
    "previousState": "WARNING",
    "currentState": "CONTROL",
    "currentL2b": "83.25",
    "l2bLimit": "80",
    "usagePercent": "104.06",
    "requestCount": 333,
    "paidOrderCount": 4,
    "windowMinutes": 1440,
    "windowStart": "2026-09-08T10:00:00+08:00",
    "windowEnd": "2026-09-09T10:00:00+08:00"
  }
}
```

#### 外层字段

| 字段               | 说明                      |
| ---------------- | ----------------------- |
| `cid`            | 客户代码                    |
| `notificationId` | 通知唯一标识，也是幂等键            |
| `status`         | 当前固定为 `-1`，不表示 L2B 状态   |
| `type`           | 固定为 `l2b.state_changed` |
| `data`           | 状态变化明细                  |

#### `data` 字段

| 字段                                        | 说明                          |
| ----------------------------------------- | --------------------------- |
| `eventId`                                 | 事件 ID，与 `notificationId` 相同 |
| `clientCode`、`carrier`、`action`           | L2B 观察维度                    |
| `previousState`、`currentState`            | 原策略状态和新策略状态                 |
| `currentL2b`、`l2bLimit`、`usagePercent`    | 当前 L2B、上限和使用率，均为字符串         |
| `requestCount`、`paidOrderCount`           | 窗口内计入统计的请求数和支付订单数           |
| `windowMinutes`、`windowStart`、`windowEnd` | 滑动窗口信息和评估时间                 |
| `releaseUsagePercent`                     | 可选。`CONTROL` 释放线，数值不带 `%`   |
| `estimatedReleaseTime`                    | 可选。预计解除时间                   |
| `transitionReason`                        | 可选。状态变化原因代码                 |

可选字段可能为 `null` 或完全省略。

接收程序应忽略未知字段。

### 幂等、乱序和缺失

使用 `notificationId` 去重。

按 `clientCode + carrier + action` 保存本地状态。

使用 `windowEnd` 判断事件新旧。较早事件不得覆盖较新状态。

网络异常可能造成重复、延迟、乱序或缺失。

不要假设每个状态变化都能收到通知。

### 与 API 响应头的关系

通知反映策略状态：`NORMAL`、`WARNING` 和 `CONTROL`。

响应头反映单次请求的实际处理结果。

| `x-l2b-state` | 含义            |
| ------------- | ------------- |
| `NORMAL`      | 本次请求未受 L2B 控制 |
| `WARNING`     | 请求仍实时执行       |
| `DEGRADED`    | 返回非实时降级结果     |
| `REJECTED`    | 无可用降级结果，请求被拒绝 |

持续记录以下响应头：

```http
x-l2b-current
x-l2b-limit
x-l2b-window-minutes
x-l2b-state
```

当三个数值响应头均为 `unknown` 时，本次请求会正常放行。

这不代表该维度已经完成有效评估。

### 安全与联调

* 使用 HTTPS 接收事件。
* 当前协议没有定义签名字段或固定鉴权请求头。
* 校验必要字段和枚举值，同时兼容未知新增字段。
* 不要根据 `title`、`summary` 或 `notice` 驱动自动化逻辑。
* 将告警和流量处理放到内部异步任务中。

联调时验证重复事件、乱序事件、可选字段缺失和精确 HTTP `200` 响应。

有关 L2B 计算、控制和恢复规则，请参阅 [L2B 治理](/api-wen-dang/product-guides/booking/booking-overview/l2b-yun-xing-ji-zhi-yu-ke-hu-xiang-ying-zhi-nan.md)。