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

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

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

• Документы (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 (тревел-менеджер).

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

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

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

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

В ответе метода 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".

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

Примеры:

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

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

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

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

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

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

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

____