> 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/readme/webhook-gai-lan/fei-piao-tong-zhi.md).

# 废票通知

{% hint style="info" %}
遇到 API 接入问题时，可登录 [Eva](https://www.atriptech.com/) 寻求帮助。
{% endhint %}

当你需要异步跟踪废票处理时，使用这个 webhook。

### 触发时机

Atlas 会在这些场景发送 `order.void`：

* 废票提交成功
* 废票状态发生变化
* 自动执行连续重试 10 次仍失败

### 收到后建议处理

* 按 `type` 路由到废票处理器
* 用 `orderNo` 和 `voidCode` 关联本地记录
* 用 `voidStatus` 更新废票状态
* 保留 `message` 作为展示或排障信息

### 推送方式

Atlas 会向你已注册的 webhook 地址发起 `POST` 请求。

请求头 `Content-Type` 固定为 `application/json`。

你使用 `updateWebhookURL.do` 注册的地址即可接收这个事件。

无需单独为废票事件再次注册。

### 建议优先读取的字段

* `type`
* `data.orderNo`
* `data.voidCode`
* `data.voidStatus`
* `data.message`

### 典型载荷

```json
{
  "cid": "TAC00001",
  "type": "order.void",
  "status": -1,
  "data": {
    "orderNo": "TESTA20250512100600259",
    "voidCode": "202505-0012",
    "voidStatus": 2,
    "message": "废票成功，航司已确认"
  }
}
```

### 说明

* `type` 固定为 `order.void`
* `status` 是内部字段。正常值为 `-1`
* `message` 可能为空
* `voidStatus = 4` 时，通常表示废票被拒绝或自动执行失败

{% tabs %}
{% tab title="字段说明" %}
**cid**

* **类型：** String
* **是否必填：** 是
* **说明：** 客户唯一标识。
* **示例：** `"TAC00001"`

**type**

* **类型：** String
* **是否必填：** 是
* **说明：** 事件类型。
* **固定值：** `order.void`

**status**

* **类型：** Integer
* **是否必填：** 是
* **说明：** 内部字段。
* **正常值：** `-1`

**data**

* **类型：** Object
* **是否必填：** 是
* **说明：** 废票事件数据体。

**data.orderNo**

* **类型：** String
* **是否必填：** 是
* **说明：** Atlas 订单号。

**data.voidCode**

* **类型：** String
* **是否必填：** 是
* **说明：** 废票单号。

**data.voidStatus**

* **类型：** Integer
* **是否必填：** 是
* **说明：** 当前废票状态码。

**data.message**

* **类型：** String
* **是否必填：** 否
* **说明：** 状态描述或失败原因。
  {% endtab %}

{% tab title="voidStatus 枚举" %}

* `0` = `Atlas Processing` — Atlas 已接收请求，处理中
* `1` = `Airline Processing` — 已提交航司，等待处理
* `2` = `Voided / Refunded` — 废票成功或已退款
* `3` = `Airline Voiding` — 航司废票处理中
* `4` = `Rejected` — 废票被拒绝
* `5` = `Completed` — 全流程完成
* `6` = `Withdrew` — 废票申请已撤回
  {% endtab %}

{% tab title="message 示例" %}

* `0`：`废票申请已受理，正在提交航司`
* `1`：`废票已提交至航司处理`
* `2`：`废票成功，航司已确认`
* `3`：`航司废票处理中，请等待`
* `4`：`废票失败：不在废票窗口期内`
* `4`：`废票失败：该航司暂不支持废票服务`
* `4`：`废票失败：系统重试 10 次仍未成功`
* `5`：`废票已完成，退款预计 X 个工作日内到账`
* `6`：`废票申请已撤回`
  {% endtab %}
  {% endtabs %}

### 自动失败重试

系统自动执行废票失败时，会按固定策略重试：

* 每次间隔 `30s`
* 最多重试 `10` 次
* 仍失败时，状态转为 `Rejected`
* 同时推送 `order.void` webhook

常见触发原因：

* 前置校验失败
* 提交航司失败
* 查询处理结果失败

{% hint style="warning" %}
当自动重试耗尽时，通常会收到 `voidStatus = 4`，且 `message` 会说明失败原因。
{% endhint %}

### 相关页面

* [Webhook 概览](/api-wen-dang/readme/webhook-gai-lan.md)
* [Webhook 注册与事件](/api-wen-dang/api-can-kao/webhook-yu-shi-jian-api/webhook-zhu-ce-yu-shi-jian.md)
* [废票概览](/api-wen-dang/readme/yu-ding-hou-gai-lan/yu-ding-hou-cao-zuo/fei-piao.md)
* [废票 API 参考](/api-wen-dang/api-can-kao/yu-ding-hou-api/fei-piao.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://resources.atriptech.com/api-wen-dang/readme/webhook-gai-lan/fei-piao-tong-zhi.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.