Выгрузка персоны по первичному ключу (id_Person)

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

Для получения контекста клиента используется сервис OrchestratedPersonEditor.asmx

WSDL можно скачать с демо-сайта: https://demo.corteos.ru/XmlGate/V3/Orchestrated/OrchestratedPersonEditor.asmx?WSDL

Для работы в продуктовой среде необходимо заменить demo.corteos.ru на свой домен (на котором работают пользователи вашей компании)

Метод для выгрузки персоны:

https://demo.corteos.ru/XmlGate/V3/Orchestrated/OrchestratedPersonEditor.asmx?op=OrchestratedPersonGet

Данный метод позволяет по идентификатору персоны в системе Кортеос получить все её данные и параметры связанных объектов:

  • Данные персоны (ФИО, дата рождения, гражданство и так далее);

  • Документы (1 персона может иметь 0...n документов);

  • Контактная информация (1 персона может иметь 0...n контактов);

  • Мильные карты для авиаперелетов и ж/д (1 персона может иметь 0...n карт);

  • Тревел-политики (1 персона может иметь 0...n связей с политиками);

  • Структурные и структурные-меняемые коды (1 персона может иметь 0...n кодов);

  • Данные аккаунта пользователя (у персоны может быть / не быть пользовательский доступ в Кортеос. Также доступ может быть заблокирован).

В качестве параметра передается идентификатор персоны (уникальный числовой ключ):

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:cor="http://corteos.ru"> <soapenv:Header> <cor:AuthHeader> <!--Optional:--> <cor:Token>df67da97-****-****-84ce-c7c45381b310</cor:Token> </cor:AuthHeader> </soapenv:Header> <soapenv:Body> <cor:OrchestratedPersonGet> <cor:id_Person>111</cor:id_Person> </cor:OrchestratedPersonGet> </soapenv:Body> </soapenv:Envelope>


В пользовательском интерфейсе идентификатор персоны можно найти в разделе "Персоны и пользователи".

Он доступен через раздел Travel Management в редакторе договора (для агента) или из меню "Настройки" (для клиента).

В списке персон первая колонка содержит в себе этот уникальный идентификатор:

В ответе мы получаем информацию о персоне и всех связанных сущностях:

В случае ошибки будет ответ следующего вида:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <soap:Body> <OrchestratedPersonGetResponse xmlns="http://corteos.ru"> <OrchestratedPersonGetResult> <Trace ResponseDate="2019-08-27T21:03:03.9372846+03:00" SessionID="1T8G7L7K0IZQG" IP="212.233.125.182" WebSite="https://prd.corteos.ru"/> <Errors> <UniversalApiError Type="ValidationException" Text="Wrong group access id: current id = 8158 and requested id = 5872"/> </Errors> <ResponseDetails id_Group="0" BirthDate="0001-01-01T00:00:00" id_Organization="0" Male="false"> <id_Person xsi:nil="true"/> <Documents/> <MileCards/> <Contacts/> <MetaCodes/> <PersonalPolicies/> </ResponseDetails> </OrchestratedPersonGetResult> </OrchestratedPersonGetResponse> </soap:Body> </soap:Envelope>

Формат используется как для выгрузки, так и для обратной загрузки персоны. Ниже мы разберем структуру ответа (или запроса на редактирование персоны) более подробно.

Обязательность и правило использования полей относятся именно к редактированию, при выгрузке с сервера приходит информация в том виде, в котором она в настоящий момент сохранена в БД Кортеос.

Персональные данные

В пользовательском интерфейсе персональные данные можно обнаружить в редакторе персоны:


Персональные данные содержатся в корневом элементе OrchestratedPersonGetResponse

  • FirstName - имя на русском языке (например, "Мариночка"), обязательное поле;

  • MiddleName - отчество на русском языке (например, "Федоровична"), необязательное поле;

  • LastNameLatin - фамилия латиницей (например, "Sokolova"), обязательное поле;

  • FirstNameLatin - имя латиницей (например, "Marina"), обязательное поле;

  • MiddleNameLatin - отчество латиницей (например, "Fedorovichna"), необязательное поле;

  • Male - булевый признак пола персоны (является ли персона мужчиной), true или falseобязательное поле;

  • BirthDate - дата рождения в SOAP-формате, например,"1990-01-01T00:00:00", обязательное поле;

  • CitizenshipAlpha2Code - alpha2 код гражданства (например, "RU"), обязательное поле;

  • id_Organization - ссылка на организацию, в которой работает персона (например, "68"), обязательное поле.
    Если персона не работает ни в одной организации, то следует все равно создать в редакторе организаций некий контейнер для таких персон;

  • id_Person - уникальный номер персоны в БД (например, "216").
    Если поле заполнено, то редактируется объект с переданным идентификатором, если нет - создается новый объект.

Идентификатор организаций можно посмотреть под ТМ клиента (меню "Настройки" - "Организации"):

или агентом через редактор договоров в разделе "Тревел-менеджмент":

ID организаций указаны в первой колонке списка.

Кроме того, список организаций можно получить при помощи CRUD API списка организаций.

Документы

На пользовательском интерфейсе документы можно обнаружить в редакторе персоны:

Документы содержатся в контейнере документов, в нем может быть 0...n элементов:

Поля документа:

  • DocumentType - строка, тип документа (поле обязательно для заполнения). Может принимать значения из списка:

    • foreignpassport - загранпаспорт РФ;

    • passport - национальный паспорт любой страны (определяется CountryAlpha2Code);

    • birthcertificate - свидетельство о рождении РФ.

  • Number - номер документа (например, "113456789") (поле обязательно для заполнения).
    Если документ содержит номер и серию, то здесь их следует указать без пробелов. В частности, паспорт РФ - это просто 10 цифр подряд;

  • CountryAlpha2Code - код страны alpha2 (например, "RU") (поле обязательно для заполнения);

  • id_Document - первичный ключ документа (например, "123"). Если поле заполнено, то редактируется объект с переданным идентификатором, если нет - создается новый объект;

  • ValidityDate - срок годности документа (например, "2031-07-27T00:00:00"). Поле обязательно для заполнения для документов с известным сроком годности (например, для загранпаспорта или иностранного). Для паспорта РФ, свидетельства о рождении также лучше вычислять эти данные на основании данных о дате рождения персоны (в Кортеос автоматом этого НЕ делается).

Мильные карты

В разделе "Мильные карты" можно передавать карты авиакомпаний или карту "РЖД Бонус".

Следует учитывать, что карты альянсов (например, "Скай Тим") все равно выданы какой-то авиакомпанией, поэтому тут будет использоваться её IATA-код.

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

В ответе сервиса эти же данные содержатся в элементе MileCards:

Карта состоит из трех полей:

  • Provider - обязательный для заполнения код поставщика, тут может быть или IATA-код авиакомпании, или значение RzhdB для карт "РЖД Бонус". Пример - "SU";

  • Number - обязательный для заполнения номер карты (например, "3546845");

  • id_MileCard - уникальный идентификатор объекта. Если поле заполнено, то редактируется объект с переданным идентификатором, если нет - создается новый объект.

Контактная информация (она же "Контакты").

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

Следует учитывать, что адреса электронной почты и мобильные телефоны вносятся в некоторые системы бронирования (в частности, в системы бронирования авиабилетов), поэтому они обязательно должны содержать корректные значения в соответствии с тем, какие именно системы вы используете. Например, если вы используете Amadeus и Sirena, то следует уточнить в службе поддержки каждой GDS, в каком виде следует передавать мобильный телефон. чтобы его приняла авиакомпания (обычно это формат вида +7(916)222-33-22, но могут быть исключения - например, знак "+" может быть запрещен) и выработать нейтральный формат. На стороне Кортеос для контактной информации никакой валидации не предусмотрено, поэтому корректность форматов лежит на стороне разработчика.

В интерфейсе контактная информация выглядит так:

А вот ее представление в ответе API:

Контакт содержит в себе следующие поля:

  • ContactContent - содержимое контакта (например, "+7(916)222-33-22"), обязательно к заполнению.
    Также следует валидировать на стороне клиента адрес электронной почты, например, при помощи регулярного выражения. Для контакта с типом "email" поле содержит адрес электронной почты персоны;

  • ContactType - тип контакта:

    • mobile;

    • email;

    • other;

  • id_Contact - уникальный идентификатор объекта. Если поле заполнено, то редактируется объект с переданным идентификатором, если нет - создается новый объект.

Аккаунт

Предоставляет персоне права на доступ к системе. В списке персон в пользовательском интерфейсе у персон без аккаунта в системе роль пуста:

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

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

Если персона не является пользователем, то узел Account будет пустым.

Рассмотрим структуру этого элемента:

  • Email - адрес электронной почты, должен быть корректный email (обязательно для заполнения);

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

  • id_Client - уникальный идентификатор объекта. Если поле заполнено, то редактируется объект с переданным идентификатором, если нет - создается новый объект;

  • id_Role - пользовательская роль, может принимать значения из списка:

    • 1 (селф-букер);

    • 2 (тревел-координатор);

    • 3 (тревел-менеджер).

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

Первая колонка в списке содержит идентификатор:

Тревел-политики

В редакторе персоны тревел-политики, привязанные к конкретной персоне, отображаются в списке:

В ответе метода API за это отвечает элемент-контейнер PersonalPolicies:

Поля элемента:

  • PolicyName - название политики, строка, не пустое;

  • ServiceType - тип услуги, не пустое:

    • avia;

    • rail;

    • hotel.

Другие типы услуг в настоящее время недоступны, на них нет тревел-политик.

  • CorteosVersions - массив значений типа int, в какой версии Кортеос надо создать привязку (может быть "2" или "3"). Несмотря на то, что сами идентификаторы политик одинаковы в старой и новой версиях, привязки создаются отдельно, так как там реализуется связь "многие-ко-многим";

  • id_TravelPolicy - идентификатор политики, его можно увидеть в списке тревел-политик по соответствующей услуге:

Данный идентификатор одинаков для v. 2 и v. 3.


Структурные и меняемые структурные коды персон

На интерфейсе они отображаются в списке кодов:

В ответе метода API они содержатся в ноде MetaCodes:

 
Код состоит из следующих элементов:

  • DictionaryName - название справочника кодов (обязательно для заполнения, не может быть пустым, строка);

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

  • V3Id - ID персоны в конкретном справочнике версии 3;

  • CorteosVersions - массив значений типа int, в какую версию Кортеос отправить код. Может быть "2" или "3".

В отличие от других сущностей код не содержит уникального идентификатора, так как он разный в разных версиях системы и вместо него используется составной ключ (DictionaryNameCodeValue).

Примеры:

Код, который будет добавлен только во вторую версию, в справочник с названием "Финальный авторизатор" со значением кода "Y".

Код, который будет добавлен и во вторую, и в третью версию одновременно:

Логика работает следующим образом: система ищет в БД справочник с названием, точно совпадающим со значением из поля DictionaryName в таблице соответствующей версии. Если такого справочника нет - выдается ошибка; если он есть, то система ищет в нем код со значением CodeValue. Если такого кода нет, то в справочнике создается новый код и происходит привязка кода к персоне, а если код уже есть, то просто создается привязка.

Название справочников кодов в интерфейсе доступно в разделе "Справочники кодов":


В колонке "Название" мы видим текст, который должен соответствовать полю DictionaryName из ответа API:

Если перейти в справочник и зайти в раздел "Коды справочника":

то в полученном списке нас интересует поле "Значение кода", соответствующее полю CodeValue в API.

____