# Использование „длинных записей“ {#ru_gate_addendum}

статья о возможности использовать при работе через Gate расширенные наборы параметров \(«длинные записи»\) для учёта специализированной информации об оплате авиаперелётов

**На уровень выше:**[Дополнительные возможности](ru_Gate_Additional_capabilities.md)

## Общая информация {#ru_gate_addendum_overview}

Для поддержки и развития отдельных индустрий со стороны международных платёжных систем принято использовать специализированные программы, с различными льготами и преференциями для мерчантов. В частности, мерчантам, которые ведут деятельность в сфере туризма и соответствуют одной из заданных категорий \(согласно коду MCC; [Merchant Category Code, MCC](ru_glossary.md#)\), могут предоставляться определённые льготы, если при проведении оплат эти мерчанты обеспечивают передачу так называемых „длинных записей“ с детальными сведениями об оказываемых услугах.

В платёжной платформе Ecommpay поддерживается возможность работы с „длинными записями“ об услугах туристической отрасли, оплачиваемых с использованием карт платёжных систем Mastercard и Visa. Это относится к оплатам перелётов и дополнительных услуг в рамках забронированных путешествий. При этом каждая длинная запись должна передаваться в запросе на проведение соответствующего платежа в отдельном объекте `addendum` и может включать в себя сведения, соответствующие заданным структурам.

Вместе с тем, в некоторых случаях со стороны мерчантов может быть актуальным передавать расширенные сведения об оказываемых туристических услугах не через регламентированные длинные записи, а иным способом\(например, когда код категории мерчанта не подходит для получения льгот и преференций от платёжных систем, но развёрнутая информация о заказах в связке с информацией платежах по ним необходима в рабочих процессах\). Для таких ситуаций в платформе предусмотрены возможности гибко настраиваемой работы с объектом `booking_info` \([подробнее](ru_gate_additional_data.md#)\).

Применение длинных записей доступно по умолчанию в рамках любого проекта для мерчантов с допустимыми кодами категорий.Для этого предусмотрены соответствующие параметры API, описанные далее в рамках этой статьи. При использовании длинных записей вне допустимых категорий платежи отклоняются. С вопросами об актуальных программах платёжных систем и о характере и размерах льгот, доступных в конкретных случаях с учётом региональных и иных особенностей, как и с вопросами о поддержке специфических сценариев работы и отдельных видов длинных записей, можно обращаться к курирующему менеджеру Ecommpay.

## Передача сведений о бронировании авиабилетов {#ru_gate_addendum_airline}

### Ограничения {#section_g21_vhq_k1c .section}

Передавать сведения о бронировании авиабилетови рассчитывать при этом на соответствующие льготы и преференции со стороны платёжных систем могут мерчанты с кодами категорий `3000`–`3350` и `4511`. При использовании длинных записей со стороны мерчантов с другими кодами категорий платежи отклоняются с кодом состояния `310`.

Для учёта подобной информации в собственных целях \(со стороны мерчантов с любыми кодами категорий\) можно использовать объект `booking_info` \([подробнее](ru_gate_additional_data.md#)\).

### Формат данных {#section_gwf_f3q_k1c .section}

Сведения о бронировании авиабилетов в составе длинных записей должны передаваться в исходных запросах на проведение соответствующих платежей — в JSON-объекте `airlines`, вложенном в объект `addendum`. При этом для оформления каждого билета должен использоваться отдельный платёж.

Для указания общих сведений о пассажире и авиабилете в объекте `airlines` предусмотрены соответствующие параметры, а для указания сведений о полётных сегментах билета — вложенный объект `trip_legs`, в котором можно указывать от одного до четырёх полётных сегментов, используя объекты `trip_leg<legNr>`, где `<legNr>` — порядковый номер сегмента в рамках маршрута.

```language-json
{
  "addendum": {
    "airlines": {
      "ticket_number": "1055526005625",
      "passenger_name": "William Herschel",
      "customer_ref": "K7XT2A",
      "ticket_issuer_code": "KL"
      "ticket_issue_date": "2025-12-24",
      "travel_agency_code": "12345678",
      "travel_agency_name": "Deep Sky Tours",
      "restricted_ticket_indicator": true,
      "computerized_reservation_system": "SABR",
      "total_fare_amount": 15000,
      "total_tax_amount": 2000,
      "total_fees_amount": 1000,
      "trip_legs": {         \\ Объект с информацией о полётных сегментах
        "trip_leg1": {       \\ Объект с информацией о первом сегменте маршрута
          "flight_number": "3142",
          "carrier_code": "KL",
          "departure_airport": "AMS",
          "departure_at": "2026-12-25T15:30:25+01:00",
          "destination_airport": "JFK",
          "arrival_at": "2026-12-25T17:45:25-05:00",
          "stop_over_code": true,
          "service_class": "Y",
          "fare_bassis": "Y0SVR7",      
          "exchange_ticket": "3141592653589",
          "conjunct_ticket": "6626070151034",
          "coupon_number": "1",
          "endorsements_restr": "No changes allowed"
        },
        "trip_leg2": {       \\ Объект с информацией о втором сегменте маршрута
          "flight_number": "1054",
          "carrier_code": "DL",
          "departure_airport": "JFK",
          "departure_at": "2026-12-25T22:45:25-05:00",
          "destination_airport": "LHR",
          "arrival_at": "2026-12-26T10:55:25+00:00",
          "stop_over_code": false,
          "service_class": "K",
          "fare_bassis": "KHCLS7",
          "coupon_number": "2",
          "endorsements_restr": "Changes allowed"
        }
      }
    }
  }
}
```

Объект `airlines` может включаться в запросы к различным конечным точкам, при этом его структура определяется моделью, а его расположение в структуре запросов — спецификацией этих конечных точек:

-   для разовых одностадийных оплат:
    -   [/v2/payment/card/sale](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale)— с указанием платёжных данных в прямом виде или через „сетевые токены“;
    -   [/v2/payment/card/sale/saved](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale-saved)— с указанием платёжных данных через идентификаторы;
    -   [/v2/payment/card/sale/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale-token)— с указанием платёжных данных через внутренние токены платёжной платформы;
-   для разовых двухстадийных оплат:
    -   [/v2/payment/card/auth](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth)— с указанием платёжных данных в прямом виде или через „сетевые токены“;
    -   [/v2/payment/card/auth/saved](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth-saved)— с указанием платёжных данных через идентификаторы;
    -   [/v2/payment/card/auth/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth-token)— указанием платёжных данных через внутренние токены платёжной платформы.

### Используемые параметры {#section_gh5_1qf_j1c .section}

В объекте `airlines` могут передаваться следующие объекты и параметры.

|Параметр|Описание|tree|
|--------|--------|----|
|`ticket_number`  
 string, required

|Номер забронированного билета.

 Может содержать буквы базовой латиницы и цифры, при этом не должен превышать 15 символов.

 Пример: `1055526005625`

|1|
|`passenger_name`  
 string, required

|Имя и фамилия пассажира, на которого забронирован билет.

 Представляет собой строку длиной не более 20 символов.

 Пример: `William Herschel`

|2|
|`customer_ref`  
 string, required

|Идентификатор записи о пассажире в используемой системе бронирования

 Как правило, представляет собой идентификатор именной записи о пассажире \(Passenger Name Record, PNR\). Может содержать буквы базовой латиницы и цифры.

 Пример: `K7XT2A`

|3|
|`ticket_issuer_code`  
 string, required

|Двухсимвольный код авиакомпании, оформившей билет \(согласно классификации IATA\).

 Пример: `KL`

|4|
|`ticket_issue_date`  
 string, required

|Дата бронирования авиабилета в формате `ГГГГ-ММ-ДД` \(в соответствии с требованиями стандарта [ISO 8601](https://www.iso.org/ru/iso-8601-date-and-time-format.html)\).

 Пример: `2025-12-24`

|5|
|`travel_agency_code`  
 string, optional

|Код туристического агентства, оформившего билет.

 Этот код присваивается в результате аккредитации в одной из профильных ассоциаций \(IATA, ARC или другой\).

 Может содержать буквы базовой латиницы и цифры, при этом не должен превышать 8 символов.

 Пример: `12345678`

|6|
|`travel_agency_name`  
 string, optional

|Название туристического агентства, оформившего билет.

 Может содержать буквы базовой латиницы и цифры, при этом не должно превышать 25 символов.

 Пример: `Deep Sky Tours`

|7|
|`restricted_ticket_indicator`  
 boolean, optional

|Индикатор ограничений по тарифу на возврат авиабилета.

 Может принимать следующие значения:

 -   `true` — невозвратный тариф
-   `false` — возвратный тариф

 Пример: `true`

|8|
|`computerized_reservation_system`  
 string, optional

|Код компьютерной системы бронирования, который может быть актуален при оплате перелёта в Германии.

 Может принимать следующие значения:

 -   `BLAN` — Dr. Blank
-   `DALA` — Covia-Apollo
-   `DATS` — Delta
-   `DERD` — DER
-   `PARS` — TWA
-   `SABR` — Sabre
-   `STRT` — Start
-   `TUID` — TUI

 Пример: `SABR`

|9|
|`total_fare_amount`  
 integer, optional

|Сумма, взимаемая авиакомпанией за перевозку пассажира и допустимой бесплатной нормы багажа, в дробных единицах валюты.

 Пример: `15000`

|10|
|`total_tax_amount`  
 integer, optional

|Налог, включённый в сумму платежа, в дробных единицах валюты.

 Может представлять собой налог с продаж, налог на добавленную стоимость или другой вид соответствующего налога.

 Пример: `2000`

|11|
|`total_fees_amount`  
 integer, optional

|Сумма взимаемых комиссий и сборов, в дробных единицах валюты.

 Пример: `1000`

|12|
|`trip_legs`  
 object, required

|Объект, содержащий сведения о полётных сегментах. Должен содержать информацию как минимум об одном перелёте во вложенном объекте `trip_leg<legNr>` и при этом может содержать информацию не более чем о четырёх перелётах

|13|
|`trip_leg<legNr>`  
 object, required

|Объект, содержащий информацию о полётном сегменте \(или так называемом *операционном плече* — отрезке пути между двумя последовательно запланированными остановками\)|13-1 13|
|`flight_number`  
 string, required

|Номер рейса, присвоенный авиакомпанией, выполняющей перелёт, без указания кода авиакомпании.

 Может содержать буквы базовой латиницы и цифры, при этом не должен превышать 5 символов.

 Пример: `3142`

|13-1-1 13-1|
|`carrier_code`  
 string, required

|Двухсимвольный код авиакомпании, выполняющей перелёт \(согласно классификации IATA\).

 Пример: `KL`

|13-1-2 13-1|
|`departure_airport`  
 string, required

|Трёхбуквенный код пункта отправления \(согласно классификации IATA\).

 Пример: `AMS`

|13-1-3 13-1|
|`departure_at`  
 string, required

|Дата и время планового отправления в формате `ГГГГ-ММ-ДДTчч:мм:сс±чч:мм` \(в соответствии с требованиями стандарта [ISO 8601](https://www.iso.org/ru/iso-8601-date-and-time-format.html)\).

 Пример: `2026-12-25T15:30:25+01:00`

|13-1-4 13-1|
|`destination_airport`  
 string, required

|Трёхбуквенный код пункта назначения \(согласно классификации IATA\).

 Пример: `JFK`

|13-1-5 13-1|
|`arrival_at`  
 string, required

|Дата и время планового прибытия в пункт назначения в формате `ГГГГ-ММ-ДДTчч:мм:сс±чч:мм` \(в соответствии с требованиями стандарта [ISO 8601](https://www.iso.org/ru/iso-8601-date-and-time-format.html)\).

 Пример: `2026-12-25T17:45:25-05:00`

|13-1-6 13-1|
|`stop_over_code`  
 boolean, required

|Индикатор стыковки.

 Может принимать следующие значения:

 -   `true` — стыковочный рейс
-   `false` — прямой рейс

 Пример: `true`

|13-1-7 13-1|
|`service_class`  
 string, required

|Однобуквенный код класса обслуживания \(согласно классификации IATA\).

 -   R — Supersonic
-   P — First Class Premium
-   F — First Class
-   A — First Class Discounted

 -   J — Business Class Premium
-   C — Business Class
-   D — Business Class Discounted
-   I — Business Class Discounted
-   Z — Business Class Discounted

 -   W — Economy/Coach Premium
-   S — Economy/Coach
-   Y — Economy/Coach
-   B — Economy/Coach Discounted
-   H — Economy/Coach Discounted
-   K — Economy/Coach Discounted
-   L — Economy/Coach Discounted
-   M — Economy/Coach Discounted
-   N — Economy/Coach Discounted
-   Q — Economy/Coach Discounted
-   T — Economy/Coach Discounted
-   V — Economy/Coach Discounted
-   X — Economy/Coach Discounted

 Пример: `D`

|13-1-8 13-1|
|`fare_bassis`  
 string, required

|Код тарифа авиакомпании, оформившей билет.

 Может содержать буквы базовой латиницы и цифры, при этом не должен превышать 6 символов.

 Пример: `Y0SVR7`

|13-1-9 13-1|
|`exchange_ticket`  
 string, optional

|Номер билета, взамен которого был забронирован описываемый билет.

 Может содержать буквы базовой латиницы и цифры, при этом не должен превышать 15 символов.

 Пример: `3141592653589`

|13-1-10 13-1|
|`conjunct_ticket`  
 string, optional

|Номер связанного билета.

 Оформляется, когда забронированный перелёт включает в себя более четырёх полётных сегментов и билеты для этого перелёта объединяются в связанный ряд. Может содержать буквы базовой латиницы и цифры, при этом не должен превышать 15 символов.

 Пример: `6626070151034`

|13-1-11 13-1|
|`coupon_number`  
 string, optional

|Номер полётного купона, соответствующий номеру полётного сегмента.

 Пример: `1`

|13-1-12 13-1|
|`endorsements_restr`  
 string, optional

|Служебная запись, в которой могут указываться различные ограничения, дополнительная информация, а также указание возможности «передачи» \(*endorsement*\) пассажира другому перевозчику.

 Представляет собой строку длиной не более 20 символов.

 Пример: `No changes allowed`

|13-1-13 13-1S|