> 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/api-can-kao/yu-ding-hou-api/fei-piao.md). # 废票 {% hint style="info" %} 遇到 API 接入问题时，可登录 [Eva](https://www.atriptech.com/) 寻求帮助。 {% endhint %} 用这一页处理独立废票流程。 Void 已从退款流程中拆分出来。 它只处理废票场景。 ### 适用范围 * 仅支持 Void 类型 * 仅支持按订单维度处理 * 不支持部分乘客废票 * 不支持先拆单或拆 PNR 后再通过 Atlas 提交部分废票 * 严格受航司窗口期限制 {% hint style="warning" %} `voidQuotation.do` 只接受 Void 请求。 如果已超出废票窗口期，接口会返回不可废票。 {% endhint %} ### 典型流程 {% stepper %} {% step %} ### 获取废票报价 调用 `voidQuotation.do`。 用 `orderNo` 获取最新可废票金额和条件。 重点读取 `isVoidable` 和 `voidOfferId`。 {% endstep %} {% step %} ### 提交废票 调用 `void.do`。 使用最新的 `orderNo` 和 `voidOfferId` 提交申请。 成功后保存 `voidCode`。 {% endstep %} {% step %} ### 查询废票状态 调用 `queryVoidOrders.do`。 使用 `voidCode` 持续跟踪处理结果。 {% endstep %} {% endstepper %} ### 关键标识符 * `orderNo` — 原始订单号 * `voidOfferId` — 废票报价 ID * `voidCode` — 废票单号 ### 通用请求头 所有废票接口都需要以下请求头： * `Accept: application/json` * `Content-Type: application/json` * `Accept-Encoding: gzip` * `x-atlas-client-id: ` * `x-atlas-client-secret: ` ### Void Quotation 请求最新废票报价。 入参只需要 `orderNo`。 即使废票服务费是固定值，也必须先调用 `voidQuotation.do`。 不要跳过这一步。 请以报价返回的 `isVoidable`、`voidOfferId` 和 `voidDeadline` 为准。 ```json { "orderNo": "TESTA20250512100600259" } ``` 重点关注这些字段： * `isVoidable` — 当前是否还能废票 * `voidOfferId` — 后续提交废票必填 * `voidMethod` — 退款方式 * `voidFareAmount` — 原票面金额和预计废票金额 * `serviceFee` — Void Service Fee * `voidRules` — 航司废票规则 ## POST /voidQuotation.do > Void Quotation ```json {"openapi":"3.0.1","info":{"title":"Default module","version":"1.0.0"},"security":[],"paths":{"/voidQuotation.do":{"post":{"summary":"Void Quotation","deprecated":false,"description":"","tags":[],"parameters":[{"name":"Accept","in":"header","description":"","required":true,"schema":{"type":"string"}},{"name":"Content-Type","in":"header","description":"","required":true,"schema":{"type":"string"}},{"name":"Accept-Encoding","in":"header","description":"","required":true,"schema":{"type":"string","default":"gzip"}},{"name":"x-atlas-client-id","in":"header","description":"","required":true,"schema":{"type":"string","default":""}},{"name":"x-atlas-client-secret","in":"header","description":"","required":true,"schema":{"type":"string","default":""}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"orderNo":{"type":"string","description":"Atlas original order number. You can choose to request either orderNo or both airlinePNR and carrier."}},"required":["orderNo"]}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"integer","description":"Status code\n0 : Success\n801：Order not found for void. Check the original main ticket order number.\n803：Void already submitted for this passenger or segment. Query void status instead.\n805：voidOfferId expired. Call refundQuotation.do again for a fresh ID, then resubmit.\n808：This ticket is non-voidable per airline policy.\n810：Invalid request parameters\n814：Void submission already in progress. Wait before retrying.\n815：Ticket not found. Verify ticket number and order number.\n816：Void already submitted for this order. Query void status instead of resubmitting.\n817：Void already submitted for this order. Query void status instead of resubmitting.\n818：Void already submitted for this order. Query void status instead of resubmitting.\n820：Ticket already used — cannot void a flown segment.\n822：Void deadline exceeded. This ticket can no longer be voided.\n824：Wrong orderNumber: use the main ticket order, not the ancillary order number.\n841：Void not support the payment method. Please contact the airline directly for resolution.\n843：Atlas does not currently support VOID service for the airline or route of this booking."},"msg":{"type":"string","description":"Error message\nThe ‘msg’ element is for description of the results. Please do not use this field to check the success or failure of the request. Only use the ‘status’ code to check the result.","nullable":true},"fastConfirmation":{"type":"integer","enum":[0,1],"description":"Fast confirmation depends on whether the airline supports auto fulfillment.\n0 for False, 1 for True."},"expectedConfirmationDate":{"type":"string","description":"Expected date of getting airline void confirmation. The format is yyyyMMdd."},"expectedRefundDate":{"type":"string","description":"Expected date of getting refund. The format is yyyyMMdd."},"voidOfferId":{"type":"string","description":"Void offer id for this quotation which can be used for the coming Void call."},"voidMethod":{"type":"string","enum":["CashBackToOriginalPayment","Voucher"],"description":"Void method: CashBackToOriginalPayment or Voucher.\nCashBackToOriginalPayment: Refund cash back to the original form of payment.\nVoucher: Refund in the form of a voucher."},"voidTickets":{"type":"array","items":{"type":"object","properties":{"lastName":{"type":"string","description":"Last name of the passenger who wants to void."},"firstName":{"type":"string","description":"First name of the passenger who wants to void."},"ticketNo":{"type":"string","description":"The PNR received from the airline in the retrieve PNR response."}}},"description":"The void calculation for each of the passengers whose void quote has been requested"},"voidFareAmount":{"type":"object","properties":{"currency":{"type":"string","description":"The refund calculation for flight fare and inflow ancillaries.\n3-letter ISO currency code."},"originalFareAmount":{"type":"number","description":"Original fare of the flight."},"estimatedRefundAmount":{"type":"number","description":"Estimated amount which can be got back for this refund of flight."}},"required":["currency","originalFareAmount","estimatedRefundAmount"],"description":"If voidMethod is CashBackToOriginalPayment, the voidFareAmount field is not null."},"voidPostTicketingServiceAmounts":{"type":"array","items":{"type":"object","properties":{"postTicketingOrderNo":{"type":"string","description":"Unique order number for the post-ticketing service."},"currency":{"type":"string","description":"Currency used for post-ticketing service calculations.\n3-letter ISO currency code."},"originalPostTicketingServiceAmount":{"type":"number","description":"The original amount charged for the post-ticketing service."},"estimatedRefundAmount":{"type":"number","description":"Estimated amount which can be got back for this refund of Ancillaries."}},"required":["postTicketingOrderNo","currency","originalPostTicketingServiceAmount","estimatedRefundAmount"]},"description":"The void calculation for Post-ticketing Servrice, including baggage etc. Each post-ticketing order will be present as an object."},"serviceFee":{"type":"object","properties":{"currency":{"type":"string","description":"Currency used for the service fee.\n3-letter ISO currency code."},"transactionFee":{"type":"integer","description":"Transaction Fee of void."}},"required":["currency","transactionFee"],"description":"Service fee of void."},"voidWindow":{"type":"object","properties":{"supportVoid":{"type":"boolean"},"allowVoid":{"type":"boolean"},"voidTimeAfterIssure":{"type":"string"},"voidTimeBeforeDepature":{"type":"string"},"sameDayDeadlineTime":{"type":"string"},"sameDayTimezone":{"type":"string"}},"required":["supportVoid","allowVoid","voidTimeAfterIssure","voidTimeBeforeDepature","sameDayDeadlineTime","sameDayTimezone"],"description":"Void Window"},"orderNo":{"type":"string","description":"Original order number"},"isVoidable":{"type":"boolean","description":"True : Voidable False: Non-Voidable \ntrue or false"}},"required":["fastConfirmation","expectedConfirmationDate","expectedRefundDate","voidOfferId","voidMethod","isVoidable","voidTickets","voidFareAmount","serviceFee","voidWindow","orderNo","status","msg"]}}},"headers":{}}}}}}} ``` ### Submit Void 提交废票申请。 这一调用依赖最新的 `voidOfferId`。 ```json { "orderNo": "TESTA20250512100600259", "voidOfferId": "v_b893711fcfae4e9d949e9965576bfd3a" } ``` #### 提交前校验与限制 提交前请先确认这些规则： * `voidOfferId` 必须来自最新一次 `voidQuotation.do` * Atlas 只接受整单废票 * 不支持部分乘客废票 * 不支持通过拆单或拆 PNR 转成部分废票后再提交 * `voidDeadline` 通常是当日截止时间，例如 `23:59` 前。具体以报价返回值为准 如果已过 `voidDeadline`，`void.do` 会实时拒绝请求。 {% hint style="warning" %} 常见错误信息：`Void deadline exceeded. This ticket can no longer be voided` {% endhint %} 提交后保存返回的 `voidCode`。 后续查询状态时只用这个标识符。 ### 提交后的状态跟踪 提交成功后，不要重复调用 `void.do`。 请先保存 `voidCode`。 后续用它跟踪整个废票生命周期。 推荐同时接入两条链路： * `order.void` webhook — 接收状态变化通知 * `queryVoidOrders.do` — 做补偿查询和人工复核 如果提交响应里的 `voidStatus` 还不是最终状态，请等待后续通知或继续查单。 ## Make a Void > Void quotation function should be called in prior of this call ```json {"openapi":"3.0.1","info":{"title":"Default module","version":"1.0.0"},"security":[],"paths":{"/void.do":{"post":{"summary":"Make a Void","deprecated":false,"description":"Void quotation function should be called in prior of this call","tags":[],"parameters":[{"name":"Accept","in":"header","description":"","required":true,"schema":{"type":"string"}},{"name":"Content-Type","in":"header","description":"","required":true,"schema":{"type":"string"}},{"name":"Accept-Encoding","in":"header","description":"","required":true,"schema":{"type":"string","default":"gzip"}},{"name":"x-atlas-client-id","in":"header","description":"","required":true,"schema":{"type":"string","default":""}},{"name":"x-atlas-client-secret","in":"header","description":"","required":true,"schema":{"type":"string","default":""}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"orderNo":{"type":"string","description":"Atlas original order number. You can choose to request either orderNo or both airlinePNR and carrier."},"voidOfferId":{"type":"string","description":"Get this from the void quotation response. "}},"required":["orderNo","voidOfferId"]}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"integer","description":"Status code\n0 : Success,\n801：Order not found for void. Check the original main ticket order number.\n803：Void already submitted for this passenger or segment. Query void status instead.\n805：voidOfferId expired. Call refundQuotation.do again for a fresh ID, then resubmit.\n808：This ticket is non-voidable per airline policy.\n810：Invalid request parameters\n814：Void submission already in progress. Wait before retrying.\n815：Ticket not found. Verify ticket number and order number.\n816：Void already submitted for this order. Query void status instead of resubmitting.\n817：Void already submitted for this order. Query void status instead of resubmitting.\n818：Void already submitted for this order. Query void status instead of resubmitting.\n820：Ticket already used — cannot void a flown segment.\n822：Void deadline exceeded. This ticket can no longer be voided.\n824：Wrong orderNumber: use the main ticket order, not the ancillary order number.\n841：Void not support the payment method. Please contact the airline directly for resolution.\n843：Atlas does not currently support VOID service for the airline or route of this booking."},"msg":{"type":"string","description":"Error message\nThe ‘msg’ element is for description of the results. Please do not use this field to check the success or failure of the request. Only use the ‘status’ code to check the result.","nullable":true},"fastConfirmation":{"type":"integer","description":"Fast confirmation depends on whether the airline supports auto fulfillment.\n0 for False, 1 for True."},"expectedConfirmationDate":{"type":"string","description":"Expected date of getting airline void confirmation. The format is yyyyMMdd."},"expectedRefundDate":{"type":"string","description":"Expected date of getting refund. The format is yyyyMMdd."},"voidOfferId":{"type":"string","description":"Void offer id for this quotation which can be used for the coming void call."},"voidMethod":{"type":"string","description":"Voidmethod: CashBackToOriginalPayment or Voucher.\nCashBackToOriginalPayment: Refund cash back to the original form of payment.\nVoucher: Refund in the form of a voucher."},"voidTickets":{"type":"array","items":{"type":"object","properties":{"lastName":{"type":"string","description":"Last name of the passenger who wants to void."},"firstName":{"type":"string","description":"First name of the passenger who wants to void."},"ticketNo":{"type":"string","description":"The PNR received from the airline in the retrieve PNR response."}},"required":["lastName","firstName","ticketNo"]},"description":"The void calculation for each of the passengers whose void quote has been requested"},"voidFareAmount":{"type":"object","properties":{"currency":{"type":"string","description":"The void calculation for flight fare and inflow ancillaries.\n3-letter ISO currency code."},"originalFareAmount":{"type":"number","description":"Original fare of the flight."},"estimatedRefundAmount":{"type":"number","description":"Estimated amount which can be got back for this refund of flight."}},"required":["currency","originalFareAmount","estimatedRefundAmount"],"description":"If voidMethod is CashBackToOriginalPayment, the voidFareAmount field is not null."},"voidPostTicketingServiceAmounts":{"type":"array","items":{"type":"object","properties":{"postTicketingOrderNo":{"type":"string","description":"Unique order number for the post-ticketing service."},"currency":{"type":"string","description":"Currency used for post-ticketing service calculations.\n3-letter ISO currency code."},"originalPostTicketingServiceAmount":{"type":"number","description":"The original amount charged for the post-ticketing service."},"estimatedRefundAmount":{"type":"number","description":"Estimated amount which can be got back for this refund of Ancillaries."}},"required":["postTicketingOrderNo","currency","originalPostTicketingServiceAmount","estimatedRefundAmount"]}},"serviceFee":{"type":"object","properties":{"currency":{"type":"string","description":"Currency used for the service fee.\n3-letter ISO currency code."},"transactionFee":{"type":"number","description":"Transaction Fee of void."}},"required":["currency","transactionFee"],"description":"Service fee of void."},"orderNo":{"type":"string","description":"Original order number"},"isVoidable":{"type":"boolean","description":"True : Voidable False: Non-Voidable\ntrue or false"},"voidStatus":{"type":"integer","description":"The present status of the void.\nThe options are:\n0: Atlas Processing\n1: Airline Processing (Submitted to airline by Atlas)\n2: Refunded\n3: Airline Refunding\n4: Rejected\n5: Fullfillment Done\n6: Withdrew\nIf the ticket is paid by deposit: the status can be 0,1,2,3,4\nIf the ticket is paid by VCC pass through: the status can be 0,1,4,5,6\nWithdrew is only in the refund claim"},"voidCode":{"type":"string","description":"Void order number generated for this void request"},"cancelReason":{"type":"string","description":"The reason why the void was cancelled."}},"required":["status","msg","fastConfirmation","expectedConfirmationDate","expectedRefundDate","voidOfferId","voidMethod","voidTickets","voidFareAmount","serviceFee","orderNo","isVoidable","voidStatus","voidCode","cancelReason"]}}},"headers":{}}}}}}} ``` ### Query Void Status 查询废票处理进度和结果。 ```json { "voidCode": "202505-0012" } ``` 重点关注这些字段： * `voidStatus` — 当前废票状态 * `actualRefundAmount` — 航司确认后的实际退款金额 * `cancelReason` — 废票被拒绝或关闭时的原因 * `orderNo` — 原始订单号回显 #### 查询时效建议 提交后，通常可在 `5` 分钟内看到废票申请是否已成功受理并进入处理流程。 这不代表废票已经最终成功。 最终成功、失败或关闭状态，仍需继续通过 `queryVoidOrders.do` 跟踪。 更推荐同时接入 `order.void` webhook。 ### 与 webhook 配合使用 `queryVoidOrders.do` 适合这些场景： * webhook 首次接入后的对账 * webhook 投递失败后的补偿查询 * 人工复核某个 `voidCode` 的最终结果 推荐做法： 1. 提交废票后保存 `voidCode` 2. 优先消费 `order.void` 通知 3. 收到通知后，按需用 `queryVoidOrders.do` 对账 4. 如果长时间未收到通知，再主动查询 业务状态判断以 `voidStatus` 为准。 不要用顶层 `status` 判断废票处理进度。 ## Query Void Status > No preceding function needs to be carried out. ```json {"openapi":"3.0.1","info":{"title":"Default module","version":"1.0.0"},"security":[],"paths":{"/queryVoidOrders.do":{"post":{"summary":"Query Void Status","deprecated":false,"description":"No preceding function needs to be carried out.","tags":[],"parameters":[{"name":"Accept","in":"header","description":"","required":true,"schema":{"type":"string"}},{"name":"Content-Type","in":"header","description":"","required":true,"schema":{"type":"string"}},{"name":"Accept-Encoding","in":"header","description":"","required":true,"schema":{"type":"string","default":"gzip"}},{"name":"x-atlas-client-id","in":"header","description":"","required":true,"schema":{"type":"string","default":""}},{"name":"x-atlas-client-secret","in":"header","description":"","required":true,"schema":{"type":"string","default":""}}],"requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{}}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"voidOrders":{"type":"array","items":{"type":"object","properties":{"orderNo":{"type":"string","description":"The original order number"},"voidCode":{"type":"string","description":"The void order number generated for this void request"},"expectedConfirmationDate":{"type":"string","description":"Expected date to receive airline void confirmation. Format: yyyyMMdd."},"expectedRefundDate":{"type":"string","description":"Expected date to receive the refund. Format: yyyyMMdd.","nullable":true},"voidTickets":{"type":"array","items":{"type":"object","properties":{"lastName":{"type":"string","description":"Last name of the passenger for whom the void is requested"},"firstName":{"type":"string","description":"First name of the passenger for whom the void is requested"},"ticketNo":{"type":"string","description":"The PNR received from the airline retrieve PNR response."}},"required":["lastName","firstName","ticketNo"]},"description":"Void calculation for each passenger requesting a void quotation"},"voidFareAmount":{"type":"object","properties":{"currency":{"type":"string","description":"Currency used for flight fare and onboard ancillary service void calculations.\n3-letter ISO currency code."},"originalFareAmount":{"type":"number","description":"The original fare amount of the flight."},"estimatedRefundAmount":{"type":"number","description":"Estimated amount recoverable from this flight refund."}},"required":["currency","originalFareAmount","estimatedRefundAmount"],"description":"If voidMethod is CashBackToOriginalPayment, the voidFareAmount field is not empty."},"voidPostTicketingServiceAmounts":{"type":"array","items":{"type":"object","properties":{"postTicketingOrderNo":{"type":"string","description":"The unique order number for the post-ticketing service."},"currency":{"type":"string","description":"Currency used for post-ticketing service calculations.\n3-letter ISO currency code."},"originalPostTicketingServiceAmount":{"type":"number","description":"The original charged amount for the post-ticketing service."},"estimatedRefundAmount":{"type":"number","description":"Estimated amount recoverable from this ancillary service refund."}},"required":["postTicketingOrderNo","currency","originalPostTicketingServiceAmount","estimatedRefundAmount"]},"description":"List of void amounts for post-ticketing services"},"serviceFee":{"type":"object","properties":{"currency":{"type":"string","description":"Currency used for the service fee.\n3-letter ISO currency code."},"transactionFee":{"type":"integer","description":"Transaction fee for the void."}},"required":["currency","transactionFee"],"description":"Service fee for the void."},"voidStatus":{"type":"integer","description":"Current status of the void.\nOptions:\n0: Atlas processing\n1: Airline processing (submitted to airline by Atlas)\n2: Refunded\n3: Airline refunding\n4: Rejected\n5: Fulfillment completed\n6: Cancelled\nIf ticket is paid via deposit: status may be 0,1,2,3,4\nIf ticket is paid via VCC direct payment: status may be 0,1,4,5,6\nCancelled status only exists in refund applications"},"cancelReason":{"type":"string","description":"Reason why the void was cancelled."},"voidOfferId":{"type":"string","description":"The void offer ID for this quotation, which can be used for subsequent void calls."},"voidMethod":{"type":"string","description":"Void method: CashBackToOriginalPayment or Voucher","enum":["CashBackToOriginalPayment","Voucher"]}},"required":["orderNo","voidCode","expectedConfirmationDate","voidStatus","voidMethod"]},"description":"List of void orders"},"status":{"type":"integer","description":"API status code.\n0 : Success\n801: No voidable orders found. Please check the original main ticket order number.\n803: Passenger or segment has already submitted a void request. Please check the void status.\n805: voidOfferId has expired. Please call refundQuotation.do again to get a new ID and resubmit.\n808: This ticket cannot be voided according to airline policy.\n810: Invalid request parameters.\n814: Void submission is already in process, please try again later.\n815: Ticket not found. Please verify the ticket number and order number.\n816: This order has already submitted a void request. Please check the void status, do not resubmit.\n817: This order has already submitted a void request. Please check the void status, do not resubmit.\n818: This order has already submitted a void request. Please check the void status, do not resubmit.\n820: Ticket already used - cannot void flown segments.\n822: Void deadline has passed. This ticket can no longer be voided.\n824: Wrong order number: Please use the main ticket order number, not the ancillary service order number.\n841: Void is not supported for this payment method. Please contact the airline directly for processing.\n843: Atlas currently does not support void service for this airline or route."},"msg":{"type":"string","description":"Error message","nullable":true}},"required":["voidOrders","status","msg"],"description":"Void order query response"}}},"headers":{}}}}}}} ``` ### 集成要点 * 废票报价只支持 `orderNo` * 即使服务费固定，也必须先调用 `voidQuotation.do` * 提交废票使用 `orderNo + voidOfferId` * 超过 `voidDeadline` 后，`void.do` 会实时返回错误 * 查询状态使用 `voidCode` * 可通过 `order.void` webhook 接收异步状态通知 * 服务费类型为 **Void Service Fee** * 推荐用独立废票接口处理 Void ### 与退款 API 的区别 * 废票报价接口是 `voidQuotation.do` * 废票提交接口是 `void.do` * 废票查询接口是 `queryVoidOrders.do` * Void 不区分自愿或非自愿原因 * Void 入参更简单 * Void 不支持部分乘客处理 * Void 自动化更高 * Void 窗口期限制更严格 ### 相关页面 * [预订后 API](/api-wen-dang/api-can-kao/yu-ding-hou-api.md) * [退款](/api-wen-dang/api-can-kao/yu-ding-hou-api/tui-kuan.md) * [废票通知](/api-wen-dang/readme/webhook-gai-lan/fei-piao-tong-zhi.md) * [预订后概览](/api-wen-dang/readme/yu-ding-hou-gai-lan.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, and the optional `goal` query parameter: ``` GET https://resources.atriptech.com/api-wen-dang/api-can-kao/yu-ding-hou-api/fei-piao.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.