Выгрузка деталей заказа по номеру (GetSimpleReserveByIdV2)

Owned by Anna Gorovaya (Unlicensed)
Last updated: Jan 24, 2024 by Александр Исобаев
13 min read

Агенту нет необходимости получать контекст клиента для выгрузки его заказов.

Приступая к работе

Важно, чтобы служебный доступ, из-под которого делаются обращения к API, был:

  • Подписан на все типы заказов;

  • Подписан на все сервис-тимы.

В случае, если одно из условий будет нарушено, технический пользователь не увидит заказ и выгрузить его через API будет нельзя.

WSDL https://jv3.corteos.ru/XmlGate/V3/OrderManagement/OrdersAPI.asmx?WSDL

Для выгрузки заказа нам необходимо знать его номер (id_Reserve), который можно увидеть в:

  • Списке заказов: 

  • В деталях заказа:

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

 

Примеры на github:

 

Структура ответа

Ответ состоит из следующих секций:

  • Унифицированные параметры заказа;

  • Специфические данные по услуге (разные для каждого типа услуги, не имеет фиксированной xsd-схемы);

  • Информация по самому дешевому варианту (может отсутствовать);

  • Информация по самому дорогому варианту (может отсутствовать);

  • Информация о создателе;

  • Информация о сервис-тиме, в который будет передан заказ;

  • Коды заказа;

  • Пассажиры;

  • Нарушения тревел-политик;

  • Файлы вложений;

  • Плательщик;

  • Информация о командировке, в которой находится данный заказ;

  • Имя бронирующего агента.

 

Корневой элемент

В нем содержатся универсальные параметры заказа, общие для любой услуги:

 

 

  • id_Reserve - номер заказа, который мы использовали для обращения к данному методу;

  • id_ComplexReserve - номер командировки, в которой содержится данный заказ;

  • ComplexReserveName - название командировки, в которой содержится данный заказ;

  • Locator - номер брони в системе поставщика (в данном примере - номер брони в системе Amadeus).
    В некоторых заказах может быть две брони (например, перелет туда и обратно из двух one way) - в этом случае они будут написаны через "/": "N3V7NK/N3V7NY";

  • Price - стоимость заказа со всеми сборами в рублях.
    Детализацию по разбивке нужно смотреть уже внутри заказа, в OrderSpecificData;

  • Header - заголовок заказа (обычно определяет маршрут);

  • Brief - краткое описание услуги, парсить ни в коем случае нельзя;

  • OrderTypeName - тип услуги, текстовое обозначение id_ReserveType;

  • id_ReserveType - идентификатор типа услуги;

  • id_AgentGroup - уникальный код агента-исполнителя;

  • id_ClientGroup - уникальный код группы компаний клиента-заказчика;

  • id_ServiceTeam - идентификатор сервис-тима, который обслуживает;

  • id_ReserveState - состояние заказа;

  • ReserveStateName - текстовое название состояния заказа;

  • DateCreate - дата создания заказа в формате SOAP DateTime.

 

Плательщик (контейнер Payer)

Содержит информацию о компании-плательщике по заказу, которого пользователь выбрал на шаге пребукинга:

 



  • В самом заказе выбранный плательщик виден в этой секции:

 



  • В XML этот элемент выглядит таким образом.

 

 

  • id_PayerOrganization - уникальный идентификатор организации-плательщика;

  • INN - ИНН плательщика;

  • KPP - КПП плательщика.

Рекомендуется либо хранить у себя в базе данных идентификатор организации в Corteos, либо сопоставлять их по паре "ИНН+КПП". Так как эти поля заводятся администратором агентства в Кортеос, а не берутся из каких-либо реестров, то там может быть любая информация: например, можно в ИНН писать номер контрагента в 1С или что-то подобное. При необходимости можно обратиться за платной консультацией по этому вопросу.

 

Номер организации можно найти в списке организаций в административных интерфейсах:

Файлы-вложения (контейнер Files)

Это могут быть как вложения, сделанные пользователем, так и автоматически сформированные файлы электронных билетов и ваучеров.

Выглядит это так:

 

Файлов может быть 0...n

 

 

id_File - уникальный идентификатор файла;

  • Caption - название файла;

  • Url - ссылка для загрузки файла;

  • IsTravelDocument - булевый признак, является ли файл файлом электронного билета;

  • TicketNumber - номер электронного билета (только для варианта "IsTravelDocument == true");

  • id_User - идентификатор пользователя системы, в контексте которого сформировано данное вложение (например, кто выписал электронный билет).

  • id_FileType - идентификатор типа файла, указывает на тип файла в соответствии с таблицей.

Нарушения тревел-политик (контейнер Violations)

Список всех нарушений политики с описаниями конкретных деталей нарушения.

В интерфейсе список нарушений можно найти в деталях заказа в блоке "Нарушена тревел-политика":

 

Нарушений может быть 0...n

 



  • id_Violation - уникальный идентификатор записи о нарушении ТП;

  • id_Policy - идентификатор нарушенной тревел-политики;

  • TravelPolicyName - название нарушенной ТП;

  • ViolationTextEnglish/Russian - описание нарушения на определенном языке.

Уникальный идентификатор тревел-политики и её название можно найти в интерфейсе в списке тревел-политик:

 

Информация о создателе заказа (узел Creator)

Здесь содержится информация о пользователе, который создал данный заказ. В интерфейсе эта информация содержится в той же секции, что и плательщик:

 



В XML этот элемент выглядит так:

 

 



  • id_Client - идентификатор клиента-инициатора;

  • id_Group - идентификатор компании инициатора. Не является идентификатором договора - по факту, это id_CustomerGroup;

  • Email - электронная почта инициатора;

  • LastName - фамилия инициатора;

  • FirstName - имя инициатора.

 

Пассажиры (контейнер Passengers)

Это список персон, которые участвуют в данном заказе.

В интерфейсе пассажиров можно найти в деталях заказа:



В XML элемент выглядит таким образом:

 



  • id_Passenger - уникальный номер пассажира (ключ, который соответствует паре "номер заказа - идентификатор персоны");

  • id_Person - уникальный идентификатор персоны;

  • FirstName - имя пассажира на русском языке;

  • LastName - фамилия пассажира на русском языке;

  • FirstNameLatin - имя пассажира на английском;

  • LastNameLatin - фамилия пассажира на английском;

  • SurName - отчество пассажира на русском;

  • DocumentType - тип документа;

  • passport - национальный паспорт;

  • foreignpassport - заграничный паспорт;

  • birthcertificate - свидетельство о рождении;

  • DocumentNumber - номер документа, по которому летит пассажир (например, серия и номер паспорта РФ);

  • id_Document - уникальный идентификатор документа;

  • id_MileCard - уникальный идентификатор мильной карты.

Мильная карта и документ требуются не для всех услуг, поэтому поля, с ними связанные, могут быть пустыми, это следует предусмотреть при разработке.



Также для командировок в статусе "Чистовик" и выше показываются структурные и структурные меняемые коды пассажиров (секция Codes) с привязкой к заказу. Данная секция совпадает по структуре с аналогичной секцией у заказа и будет расписана ниже.



Коды заказа (контейнер Codes)

Данный контейнер используется только в заказах, которые содержатся в командировках в статусе "Чистовик" и выше. Для командировок-черновиков этот контейнер пустой, так как клиент выбирает коды непосредственно перед переводом командировки в чистовик. В интерфейсе коды заказов отображаются в деталях заказа:

В данном контейнере находятся:

 



  • ризон-коды;

  • бюджетные коды с типом привязки "к заказу":

 

Элемент контейнера (StableCode) состоит из следующих полей:

  • id_MetaCode - уникальный идентификатор кода в БД;

  • id_MetaDictionary - уникальный идентификатор справочника кодов;

  • CodeValue - значение кода(обычно уникально в рамках справочника, но это не гарантируется системой);

  • DictionaryName - название справочника кодов;

  • DictionaryType - тип справочника. Возможны следующие варианты:

  • Budget - бюджетные коды;

  • StructuralPersonal - структурные коды пассажиров;

  • PolicyRulesRttached - автоматически проставленные коды нарушений ТП (привязанные к правилам);

  • ChangeableStructuralPersonal - меняемые структурные коды;

  • TravelpolicyViolationBudget - ризон-коды.



Информация о командировке (элемент ComplexReserveReference)

В Кортеос все заказы привязаны к определенной командировке.

В этом элементе содержатся данные о командировке, в которой находится данный заказ:



где:

  • id_ComplexReserve="757980" - уникальный идентификатор командировки;

  • Name="Санкт-Петербург" - название командировки, указанное пользователем на шаге пребукинга;

  • id_ClientCreator="113" - идентификатор пользователя-инициатора командировки;

  • CreationDate="2019-07-03T15:27:51.49" - дата и время создания командировки;

  • CurrentState="Finished" - статус командировки:

  • Draft - черновик;

  • Authorizing - сейчас идет авторизация;

  • Cleancopy - чистовик;

  • ForExecution - на исполнении у агента (это значит, что часть заказов данной командировки требуют ручной обработки);

  • Canceled - отменена (все заказы отменены);

  • Finished - выполнена (все заказы выполнены или отменены).

  • Codes - контейнер кодов с привязкой к командировке, доступно только для командировок в статусе выше черновика.

Информация о забронированной услуге, о самом дешевом и самом дорогом вариантах

Информация о забронированной услуге - OrderSpecificData;

Самый дешевый вариант - MostCheapVariant;

Самый дорогой вариант - MostExpensiveVariant.



Данные элементы не имеют фиксированной структуры и приходят в формате XML, который определяется типом услуги. В том случае, если такое XML-представление отсутствует (например, в ж/д не фиксируется дорогóй и дешевый варианты), то в элементе находится узел NotAvailable:

 



Структура авиазаказа: https://preprd.avia.corteos.ru/Home/ObjectModel#headerMultiItinerary

Структура заказа отелей: ExtendedBooking

Структура заказа трансферов:


Структура ж/д заказа описана ниже.

Элемент OrderContainer - контейнер специфичных данных по заказу ж/д билетов:

 

id_Order

атрибут

int

Идентификатор заказа в системе поставщика

id_RootTransaction

атрибут

int

Идентификатор родительской транзакции

OrderItems

элемент



Контейнер сегментов заказа (см. таблицу "Элемент OrderItems")

Элемент OrderItems - контейнер сегментов заказа:

 

id_Order

атрибут

int

Идентификатор заказа в системе поставщика

id_Transaction

атрибут

int

Идентификатор транзакции в системе поставщика

ReservationDate

атрибут

DateTime

Дата создания заказа

ReservationType

атрибут

int

Текущий тип бронированияМожет принимать одно из следующих значений 0 - 15 минут;1 - 3 часа.

IsPossibleThreeHoursReservation

атрибут

bool

Признак доступности трехчасового бронирования

SegmentType

атрибут

int

Тип сегмента Может принимать одно из следующих значений: 9 - Ж/Д сегмент, направление "Туда ";17 - Ж/Д сегмент, направление "Обратно".

TrainDepartureStationCode

атрибут

string

Код начальной станции отправления поезда

TrainDepartureStationName

атрибут

string

Название начальной станции отправления поезда

TrainArrivalStationCode

атрибут

string

Код конечной станции прибытия поезда

TrainArrivalStationName

атрибут

string

Название конечной станции прибытия поезда

PassengerDepartureStationCode

атрибут

string

Код станции отправления пассажира

PassengerDepartureStationName

атрибут

string

Название станции отправления пассажира

PassengerArrivalStationCode

атрибут

string

Код станции прибытия пассажира

PassengerArrivalStationName

атрибут

string

Название станции прибытия пассажира

Date

атрибут

DateTime

Дата и время отправления поезда

LocalDate

атрибут

DateTime

Дата и время отправления поезда по местному времени

ArrivalDate

атрибут

DateTime

Дата и время прибытия поезда

LocalArrivalDate

атрибут

DateTime

Дата и время прибытия поезда по местному времени

ConfirmTimeLimit

атрибут

DateTime

Тайм-лимит на подтверждение брони

TrainNumber

атрибут

string

Номер поезда

TrainName

атрибут

string

Название поезда

TrainCathegory

атрибут

int

Категория поездаооскоростной.

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

1 - Пассажирский;

2 - Скорый;

3 - Фирменный;

5 - Скоростной;

6 - Скорый фирменный;

7 - Скоростной фирменный (Сапсан);

8 - Скоростной (Ласточка);

9 - Скорый (Гранд Экспресс);

10 - Скоростной (Стриж)

11 - Скоростной фирменный;

12 - Высокоскоростной.









Carrier

атрибут

string

Перевозчик

CarNumber

атрибут

int

Номер вагона

FareName

атрибут

string

Название тарифа

ServiceClass

атрибут

string

Сервисный класс обслуживания

GenderType

атрибут

int

Гендерный тип купе Может принимать одно из следующих значений: 0 - Мужское;1 - Женское;2 - Смешанное;3 - Не применяется.

Places

атрибут

List<int>

Список номеров занимаемых мест

ServiceFee

атрибут

double

Сервисный сбор

SpecialTravelTermsNotification

атрибут

string

Уведомление пассажира об особых условиях поездки

Conditions

атрибут

string

Информация о времени отправления и прочих условиях

TStatus

атрибут

int

Текущий статус транзакции Может принимать одно из следующих значений: 0 - Успешная;1 - Неуспешная;2 - В процессе подтверждения.

AllowEReg

атрибут

bool

Признак возможности установки электронной регистрации

IsTwoStorey

атрибут

bool

Признак двухэтажного вагона

IsSuburbanTrain

атрибут

bool

Признак пригородного поезда

IsDoubleSeatsPrice

атрибут

bool

Признак выкупа целого купе с двумя местами

IsQuadroSeatsPrice

атрибут

bool

Признак выкупа целого купе с четырьмя местами

Blanks

элемент

string

Контейнер бланков заказа, см. таблицу "Элемент Blanks"

Элемент Blanks - контейнер бланков заказа

 

id_Transaction

атрибут

int

Идентификатор транзакции в системе поставщика

id_Blank

атрибут

int

Идентификатор бланка в системе поставщика

TicketNumber

атрибут

string

Номер билета

Amount

атрибут

double

Стоимость билетов по данному бланку без сборов

PriceCathegory

атрибут

string

Строковое представление категории билета

PlaceString

атрибут

string

Занимаемые места в формате поставщика

EReg

атрибут

int

Признак установки электронной регистрации Может принимать одно из следующих значений: 0 - электронная регистрация недоступна;1 - электронная регистрация;2 - без электронной регистрации.

Passengers

элемент



Контейнер данных о пассажирах из данного бланка(см. таблицу "Элемент Passengers")

RzhdStatus

атрибут

int

Cтатус бланкаМожет принимать одно из следующих значений 0 - без электронной регистрации;1 - электронная регистрация;2 - оплата не подтверждена;3 - аннулирован;4 - возвращен;5 - возвращены места;6 - выдан посадочный купон (проездной документ) на бланке строгой отчетности;7 - отложенная оплата;20 - произошла ошибка и актуальный статус заказа (билета) неизвестен.

PlaceTier

атрибут

string

Тип места (ярус)

PlaceTierDescription

атрибут

string

Описание места

Storey

атрибут

int

Требование к этажности Может принимать одно из следующих значений: 0 - требования к этажу не заданы 1 - первый этаж вагона 2 - второй этаж вагона

RefundInfo

элемент



Контейнер с данными о возврате билетов(см. таблицу "Элемент RefundInfo")

Элемент Passengers - контейнер данных о пассажирах

FirstName

атрибут

string

Имя

LastName

атрибут

string

Фамилия

MiddleName

атрибут

string

Отчество

UfsDocumentType

атрибут

string

Тип документа пассажира в системе поставщика

DocumentNumber

атрибут

string

Номер документа пассажира в системе поставщика

Birthday

атрибут

DateTime

Дата рождения пассажира

Элемент RefundInfo - контейнер с данными о возврате билетов

Stan

атрибут

string

Уникальный идентификатор операции возврата

id_RefundTransaction

атрибут

string

Идентификатор транзакции возврата

id_RefundBlank

атрибут

int?

Идентификатор бланка возврата

RefundDate

атрибут

DateTime

Дата проведения возврата

Amount

атрибут

double

Сумма к возврату

Информация о дополнительных расходах

Блок доступен в ответе, если на договоре активирован МОД ModBtripAdvanceReportsExtendedAdditionalExpenses

Добавляется раздел SelectedAdditionalExpenses, где AdvanceReportAdditionalExpenceDetails - блок, содержащий информацию об одном доп. расходе и его атрибутах:

SelectedAdditionalExpenseID

элемент

string

Уникальный идентификатор расхода

SelectedAdditionalExpense

элемент

double

Величина расхода

SelectedAdditionalExpenseComment

элемент

string

Наименование расхода

SelectedAdditionalExpenseDate

элемент

Date

Дата расхода (проставляется в МОДе ModBtripAdvanceReportsExpensesEditor)

SelectedAdditionalExpenseLocatorOrTicketNumber

элемент

string

Номер отчетного документа (проставляется в МОДе ModBtripAdvanceReportsExpensesEditor)

Имя бронирующего агента

В том случае, если заказ для клиента создавал агент, в ответе API по заказу появится блок:

AgentName

Внутри блока размещается информация (ФИО) агента, создавшего заказ, которое соответствует тому, как агент заведен в системе.

Пример ответа API:

Пример заведения агента в системе:

Тест

Форма для тестирования доступна только для запросов от локальных компьютеров.

SOAP 1.1

В следующем примере показаны запрос и ответ SOAP 1.1. Вместо элементов-заполнителей следует подставить фактические значения.

HTML/XML

POST /XmlGate/V3/OrderManagement/OrdersAPI.asmx HTTP/1.1 Host: demo.corteos.ru Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "http://corteos.ru/GetSimpleReserveByIdV2" <?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Header> <AuthHeader xmlns="http://corteos.ru"> <Token>string</Token> </AuthHeader> </soap:Header> <soap:Body> <GetSimpleReserveByIdV2 xmlns="http://corteos.ru"> <id_Reserve>int</id_Reserve> </GetSimpleReserveByIdV2> </soap:Body> </soap:Envelope>

HTML/XML

HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <GetSimpleReserveByIdV2Response xmlns="http://corteos.ru"> <GetSimpleReserveByIdV2Result> <Trace ResponseDate="dateTime" SessionID="string" IP="string" WebSite="string" /> <Errors> <UniversalApiError Type="string" Text="string" /> <UniversalApiError Type="string" Text="string" /> </Errors> <ResponseDetails id_Reserve="int" id_ComplexReserve="int" ComplexReserveName="string" Locator="string" Price="double" Header="string" Brief="string" OrderTypeName="string" id_ReserveType="int" id_AgentGroup="int" id_ClientGroup="int" id_ServiceTeam="int" id_ReserveState="int" ReserveStateName="string" DateCreate="dateTime" id_Agent="int"> <id_PayerOrganization>int</id_PayerOrganization> <OrderSpecificData>xml</OrderSpecificData> <MostCheapVariant>xml</MostCheapVariant> <MostExpensiveVariant>xml</MostExpensiveVariant> <Creator id_Client="int" id_Group="int" Email="string" LastName="string" FirstName="string" /> <ServiceTeam> <id_ServiceTeam>int</id_ServiceTeam> <Name>string</Name> <Code>string</Code> </ServiceTeam> <Codes> <StableCode xsi:nil="true" /> <StableCode xsi:nil="true" /> </Codes> <Passengers> <StablePassenger xsi:nil="true" /> <StablePassenger xsi:nil="true" /> </Passengers> <Violations> <StablePolicyViolation xsi:nil="true" /> <StablePolicyViolation xsi:nil="true" /> </Violations> <Files> <StableFile xsi:nil="true" /> <StableFile xsi:nil="true" /> </Files> <Payer> <id_PayerOrganization>int</id_PayerOrganization> <INN>string</INN> <KPP>string</KPP> </Payer> <ComplexReserveReference id_ComplexReserve="int" Name="string" id_ClientCreator="int" CreationDate="dateTime" CurrentState="string"> <Codes xsi:nil="true" /> </ComplexReserveReference> <AgentName>string</AgentName> </ResponseDetails> </GetSimpleReserveByIdV2Result> </GetSimpleReserveByIdV2Response> </soap:Body> </soap:Envelope>

SOAP 1.2

В следующем примере показаны запрос и ответ SOAP 1,2. Вместо элементов-заполнителей следует подставить фактические значения.

HTML/XML

POST /XmlGate/V3/OrderManagement/OrdersAPI.asmx HTTP/1.1 Host: demo.corteos.ru Content-Type: application/soap+xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8"?> <soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope"> <soap12:Header> <AuthHeader xmlns="http://corteos.ru"> <Token>string</Token> </AuthHeader> </soap12:Header> <soap12:Body> <GetSimpleReserveByIdV2 xmlns="http://corteos.ru"> <id_Reserve>int</id_Reserve> </GetSimpleReserveByIdV2> </soap12:Body> </soap12:Envelope>

HTML/XML

В ноябре 2023 года добавлена GetSimpleReserveByIdV3

Её отличием от GetSimpleReserveByIdV2 является новый блок ExtraData в ответе:

В этом блоке перечисляется:

  • ФИО сотрудника который финализировал заказ

  • ID сотрудника который финализировал заказ

  • e-mail сотрудника который финализировал заказ

Обратите внимание! что блок ExtraData в ответе по этому методу будет показан только когда данный заказ будет в нужном статусе “Выполнен”

Так же блок ExtraData может быть расширен в будущем новыми параметрами