Параметры запроса#

Детальное описание параметров для запроса /api/avia/ticket_refund_calculation.

Обязательные параметры#

ПараметрТипОписание
bookingIdguidИдентификатор бронирования (формат UUID)
ticketNumberstringНомер билета для расчёта возврата, не более 14 символов. Формат {vendor}-{number} (например, 555-6170036806)

Пример запроса#

1curl -X POST https://test.travelplatform.ru/api/avia/ticket_refund_calculation \
2  -H "Authorization: Bearer YOUR_TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "bookingId": "019a0b29-8fc8-703a-9845-50c7ce2b1322",
6    "ticketNumber": "555-6170036806"
7  }'
 1var request = new
 2{
 3    bookingId = "019a0b29-8fc8-703a-9845-50c7ce2b1322",
 4    ticketNumber = "555-6170036806"
 5};
 6
 7var response = await httpClient.PostAsJsonAsync(
 8    "https://test.travelplatform.ru/api/avia/ticket_refund_calculation",
 9    request
10);
11
12if (response.IsSuccessStatusCode)
13{
14    var result = await response.Content.ReadFromJsonAsync<TicketRefundCalculationResponse>();
15
16    if (result?.Error == null)
17    {
18        Console.WriteLine($"К возврату: {result.ForRefund.Value} {result.ForRefund.CurrencyCode}");
19        Console.WriteLine($"Штраф: {result.RefundDetails.Penalty.Value} {result.RefundDetails.Penalty.CurrencyCode}");
20    }
21}

Сценарии использования#

Сценарий 1: Расчет перед возвратом#

Действия:

  1. Выполнить запрос /api/avia/ticket_refund_calculation
  2. Получить детализацию: сумму возврата, штрафы, тарифы, сборы
  3. Выполнить фактический возврат через /api/avia/ticket_refund

Важно: Значение forRefund из ответа должно быть передано в запрос возврата без изменений.

sequenceDiagram
    participant Client
    participant API

    Client->>API: POST /api/avia/ticket_refund_calculation<br/>{bookingId, ticketNumber}
    API-->>Client: forRefund, penalty, детализация

    Client->>API: POST /api/avia/ticket_refund<br/>{bookingId, ticketNumber, forRefund}
    API-->>Client: {}

Сценарий 2: Проверка возможности возврата#

Действия:

  1. Выполнить запрос расчета возврата
  2. Если получен успешный ответ - возврат возможен
  3. Если получена ошибка — возврат запрещён. Запрет по правилам тарифа приходит от поставщика под кодом SUPPLIER_ERROR, причина — текстом в message

Особенность: Запрос также служит для проверки разрешенности возврата.

sequenceDiagram
    participant Client
    participant API

    Client->>API: POST /api/avia/ticket_refund_calculation<br/>{bookingId, ticketNumber}

    alt Возврат разрешен
        API-->>Client: HTTP 200<br/>forRefund, penalty, детализация
    else Возврат запрещен
        API-->>Client: HTTP 200<br/>{error: SUPPLIER_ERROR, message: причина}
    end

Важные моменты#

Обязательность расчета#

Всегда выполняйте расчет перед фактическим возвратом через /api/avia/ticket_refund:

  • Клиент должен знать точную сумму возврата
  • Необходимо получить согласие клиента на условия возврата
  • Значение forRefund из расчета требуется для запроса возврата

Использование forRefund#

Значение forRefund из ответа должно быть передано в запрос /api/avia/ticket_refund без изменений. Это гарантирует корректность суммы возврата.

Формула расчета#

forRefund = fare + taxes.total - penalty - невозвратные_сборы

Где:

  • fare - стоимость тарифа
  • taxes.total - возвратные сборы и таксы
  • penalty - штраф за возврат согласно правилам тарифа
  • невозвратные_сборы - сборы, которые не возвращаются

Типичные ошибки#

Код ошибкиПричинаРешение
BOOKING_NOT_FOUNDБронирование не найдено или не принадлежит клиентуПроверьте bookingId
CURRENCY_RATE_NOT_AVAILABLEНет курса для конвертации сумм в валюту отображенияПовторите запрос позже
VALIDATION_ERRORОшибка валидации запроса (HTTP 400)Проверьте обязательные поля и форматы значений
NO_TARGETSПод запрос не нашлось ни одного поставщика: ни один не настроен либо все отсеяны на этапе подготовки запросаПроверьте настройки офисов и пресетов в личном кабинете; при сохранении ошибки обратитесь в поддержку
SUPPLIER_ERRORПоставщик вернул ошибку. Причина — текстом поставщика в поле messageРазберите message; при необходимости повторите запрос позже
SYSTEM_ERRORВнутренняя ошибка Travel APIПовторите запрос позже; при повторении обратитесь в поддержку с errorId

Ошибки, пришедшие от GDS/NDC-поставщика, возвращаются под кодом SUPPLIER_ERROR: отдельного кода на каждую причину отказа Travel API не формирует, причина передаётся текстом поставщика в поле message. Не завязывайте логику на разбор message — его формат зависит от поставщика и не фиксирован.

Связанные операции#