ПОДПИСЫВАЙТЕСЬ НА НАШ ТЕЛЕГРАМ-КАНАЛ @nemo_travel_official

Интеграция со сторонними системами АПИ: различия между версиями

Материал из Центр поддержки системы бронировании
Перейти к навигации Перейти к поиску
(→‎Фиксация оплаты внешним запросом)
(→‎API универсального платежного шлюза)
Строка 695: Строка 695:
 
'''Выгрузка заказов''' — это экспорт данных заказа или заказов для различных компонентов системы Nemo. Модуль позволяет внешней системе получать данные по заказам для дальнейшей обработки.  
 
'''Выгрузка заказов''' — это экспорт данных заказа или заказов для различных компонентов системы Nemo. Модуль позволяет внешней системе получать данные по заказам для дальнейшей обработки.  
 
Подробнее о процессе выгрузки, настройках, форматах выгрузки для различных компонент можно прочитать в статье [[Выгрузка]]
 
Подробнее о процессе выгрузки, настройках, форматах выгрузки для различных компонент можно прочитать в статье [[Выгрузка]]
−
 
−
==API универсального платежного шлюза==
 
−
!!! сказано спросить у КШ, я спросил, у него нет информации !!!
 
  
 
== API Синхронизации пользователей и субагентов ==
 
== API Синхронизации пользователей и субагентов ==

Версия 18:41, 13 мая 2015

!!!СТАТЬЯ В РАЗРАБОТКЕ!!!

Содержание

API Авиабилетов

Для авторизации в системе, в запросе необходимо указать APIKey и ClientID. Эти данные можно узнать в разделе Администрирование - Веб-сервис. Авторизация. Там же можно включить/выключить нотификацию для действий сделанных через АПИ.

API Поиска авиабилетов

Это сервис внутри Nemo, который позволяет получить результаты поиска.

Для подключения к веб-службе поиска авиабилетов необходимо открыть доступ нужному пользователю. Это можно сделать в разделе «Администрирование» ⇨ «Веб-служба. Авторизация».

Подробнее можно узнать в специальной статье Веб-служба поиска авиабилетов

API Бронирования авиабилетов

Сервис позволяет забронировать/войдировать авиабилет с использованием API, описание подключения, запроса, ответов находится в этой статье Веб-служба бронирования

API Выписки авиабилетов

Агентский АПИ выписки позволяет определить валидирующего перевозчика и значение комиссии от авиакомпании для брони, а также запустить процедуру выписки билета. Веб-служба выписки

API Оплаты

Сервис внутри Nemo, который предназначен для выполнения различных операций, относящихся к оплате заказов. Агентские АПИ оплаты

API Дополнительных запросов авиабилетов

К дополнительных запросам относятся проверка на доступность, запрос на обновление заказа, чтение тарифных правил. Дополнительные запросы АПИ авиабилетов

Используемые параметры

развернуть

Параметры, используемые в запросах

развернуть

Параметры, используемые в ответах

API Отелей

Агентский API Отелей - система, которая предоставляет возможность поиска и бронирования отелей а так же получение информации о времени и размерах штрафов, уникальной информации об отеле, получение статической информации.

Подробнее можно узнать в нашей специальной статье Агентский АПИ отелей


Выгрузки статистики продаж через API (Метапоиск)

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

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

Можно получить список заказов с их статусом (забронирован, выписан, аннулирован), сделанных через метапоисковую систему.

Подробнее можно узнать в статье посвященной взаимодействию с метопоисковиками Взаимодействие с метапоисковиками

Выгрузка информации о заказах

Выгрузка заказов — это экспорт данных заказа или заказов для различных компонентов системы Nemo. Модуль позволяет внешней системе получать данные по заказам для дальнейшей обработки. Подробнее о процессе выгрузки, настройках, форматах выгрузки для различных компонент можно прочитать в статье Выгрузка

API Синхронизации пользователей и субагентов

Назначение данного модуля — обеспечение взаимодействия между сторонней программой (например, системой автоматизации туроператора "САМО-тур") и Nemo в части синхронизации списка B2B-пользователей.

Модуль является компонентом, включаемым и отключаемым из административной части.

Авторизация B2B-пользователей

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

1.Система пытается авторизовать пользователя через собственную службу авторизации. 2.В случае неудачи, но присутствия в системе введенного логина, она должна попытаться авторизовать пользователя во внешней службе авторизации («САМО-тур»), при включенном компоненте взаимодействия с «САМО-тур». 3.В случае неудачного опознавания пользователя выводится соответствующее сообщение и процедура может быть повторена путем повторного ввода логина и пароля.

Регистрация неудачных попыток входа производится только в двух случаях:

  • Компонент взаимодействия выключен.
  • Компонент взаимодействия включен и провалены обе попытки авторизации (внутренней и внешней).

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

Для импортированных пользователей в Nemo имеется поле «Идентификатор внешней системы», который отвечает за сопоставление с ID пользователя в сторонней системе. Для менеджеров агентств оно равно номеру партнера (агента) во внешней системе, для пользователей — номеру пользователя в «САМО-туре».

Для пользователей, имеющих какое-либо значение в поле «идентификатор во внешней системе», запрещен функционал смены пароля или его восстановления по электронной почте.

Пример запросов и ответов на авторизацию:

Request 

<?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:Body>
    <getAuthorization xmlns="http://tempuri.org/">
      <login>string</login>
      <pass>string</pass>
    </getAuthorization>
  </soap12:Body>
</soap12:Envelope>

Response 

<?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:Body>
    <getAuthorizationResponse xmlns="http://tempuri.org/">
      <getAuthorizationResult>
        <session_id>string</session_id>
        <user_id>string</user_id>
        <login>string</login>
        <status>string</status>
      </getAuthorizationResult>
    </getAuthorizationResponse>
  </soap12:Body>
</soap12:Envelope>

Сервис реализует функцию «getAuthorization», на вход которой передается конструкция «getAuthorizationRequest»:

  • login (строка) - введенный пользователем логин
  • pass (строка) - введенный пользователем пароль

Функция должна отдавать системе конструкцию getAuthorizationResponse:

  • session_id (строка) - пустое значение
  • user_id (строка) - идентификатор менеджера в системе «САМО-тур»
  • login (строка) - логин пользователя (для контроля)
  • status (строка) - может иметь значения:

1. adm - администратор 2. mgr - менеджер 3. usr - пользователь (возвращается всегда это значение)

Импорт и синхронизация учетных записей

Со стороны внешней системы должно быть приложение, отправляющее в формате XML данные по учетным записям B2B-клиентов (агентств и пользователей). Со стороны Nemo имеется скрипт, который принимает XML в формате, приведенном в описании документов, передаваемых в Nemo, с ключом авторизации, определенным в Nemo в административной части модуля.

Передаваемые элементы с описанием учетных записей и партнеров имеют аккаунт (Account ID) во внешней системе и атрибут action, который может быть в состоянии update или delete, т.е. обновления/добавления и удаления, соответственно.

В административной части модуля в Nemo задается ключ авторизации для защиты от несанкционированного доступа. Значение не должно быть пустым.

Скрипт получает данные об обновлении и добавлении (проходят как одно и то же действие) или удалении информации по аккаунту. XML-данные могут содержать несколько элементов.

Описание передаваемых в Nemo XML-документов: 

<?xml version="1.0" encoding="UTF-8" ?>
<changes key="ключ_авторизации">
    <accounts> - список изменений по аккаунтам пользователей
        <item id=3 partnerId=10 action="update" admin="1">
            <login>Логин пользователя</login>
        </item>
        <item id=6 partnerId=15 action="update">
            ...
        </item>
        <item id=9 partnerId=30 action="delete" />
    </accounts>
    <partners> - список изменений по партнерам
        <item id=140 action="update">
            <name>Название агентства</name>
            <ofname>Официальное Название агентства</ofname>
            <phone>Телефон</phone>
            <tax>Форма налогообложения</tax>
            <group>123</group>
            <code>ABCD</item>
  </partners></changes></code>

При импорте информации об агентствах будут возвращаться следующие значения:

Поле во внешней системе Путь к элементу xml Тип данных Сопоставляемое поле в Nemo Примечание
Идентификатор партнера/changes/partners/item[@id]Целое число Идентификатор во внешней системе для менеджера / администратора
Название юридического лица/changes/partners/item/ofnameСтрокаПолное официальное название юридического лица Необходимо для выписки счетов юридическими лицами
Сокращенное название/changes/partners/item/nameСтрокаИмя агентства
Код агентства/changes/partners/item/codeСтрокаИспользуется при создании логина администратора
Номер группы в самотуре/changes/partners/item/groupЦелое число, либо пустоНа основании таблицы сопоставлений (см. ниже) определяется, к какой группе агентство принадлежит в Nemo
Форма налогообложения/changes/partners/item/taxЦелое число, равное идентификатору во внешней системе

Для каждого возвращенного агентства Nemo проверяет наличие его в своей базе. Если агентство не найдено, то создается новое, для него создается менеджер (админ) с логином ABCD-1234, где ABCD – буквенный идентификатор партнера во внешней системе, 1234 — id партнера во внешней системе. Пароль генерируется случайный и криптостойкий.

Если агентство найдено, то в случае необходимости производится обновление всех полей на основании данных из внешней системы. Если изменился буквенный код агентства, то Nemo переименовывает менеджера в соответствии с новым кодом. При импорте информации о пользователях агентств в Nemo будут посылаться следующие поля:

Поле во внешней системеПуть к элементу xmlТип данныхСопоставляемое поле в NemoПримечание
Идентификатор пользователя/changes/accounts/item[@id]Целое числоИдентификатор внешней системыХраним как дополнительное поле
Идентификатор партнера/changes/accounts/item[@partnerId]Целое числоИдентификатор внешней системы менеджера агентства
Логин/changes/accounts/item/loginСтрокаЛогин пользователя
Администратор/changes/accounts/item[@admin]0 - нет, 1 - даЭксперт по бронированию

Для каждого возвращенного пользователя Nemo проверяет наличие его в своей базе. Если пользователь не найден, то создается новый. Пароль генерируется случайный и криптостойкий.

Если пользователь найден, то в случае необходимости производится обновление всех полей на основании данных из внешней системы. При запросе на удаление пользователя, в Nemo указанный логин удаляться не будет в целях сохранения целостности старых данных, а просто помечается как удаленный, и логин переименовывается и становится вида [логин_пользователя]_X_[числовой идентификатор_пользователя в Само]. 

<item id=[идентификатор] action="delete" />

Таблица сопоставлений групп

В административной части Nemo надо создать отдельную страницу, на которой можно сопоставить имеющиеся группы в Nemo номерам групп в САМО-тур (поле group в XML). Выводится список существующих групп для текущего (корневого) агентства.

API Кросс­авторизации

Система Nemo позволяет обращаться к ней как базе пользователей для авторизации из других систем (например форума на сайте, собственного ПО компании и т.п)

Для этого нужно подключиться к веб-службе авторизации, WSDL-описание которой располагается по адресу:

http://hostname/authorization_reol.wsdl

развернуть
Запрос


Передача параметров в форму поиска

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

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

В системе Nemo имеется возможность перенаправлять пользователей на страницу с уже заполненными параметрами поиска или сразу напрямую на результаты поиска.

Применение

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

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

Для использования заполнения формы из URL следует включить опцию: Администрирование → Настройки системы → Включить FastSearch (передачу параметров поиска)

После этого можно использовать ссылки на форму поиска вида 

http://SITEMANE/?trip_type=OW&out_iata=MOW&in_iata=BER&departure_date=21.10.2009&adults=1&children=0&input_vendors=SU,PS&param_by_get=on

Переменные FastSearch

Имена полей - такие же как имена инпутов на поисковой форме.

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

Переменные, которые предполагают в качестве значения "true" можно просто не включать в запрос, чтобы их логика не отработала.

Форма поиска

Чтобы перенаправить пользователя на страницу с заполненными параметрами поиска, необходимо указать get-параметр &param_by_get=on, иначе сработают стандартные предустановки полей формы поиска.

Процесс поиска

Если вы указываете все необходимые для поиска параметры, то для того чтобы отправить пользователя сразу на результаты поиска, нужно указать get-параметр &fast_search=on.

Маршрут «В одну сторону» и «Туда и обратно»

Элемент Переменная Допустимые значения
Тип маршрута trip_type
OW В одну сторону
RT Туда и обратно
CR Сложный маршрут
Пункт вылета out_iata
MOW Код аэропорта ИАТА
Пункт прилета in_iata
LED Код аэропорта ИАТА
Дата вылета departure_date
25.10.2013 Дата в формате ДД.ММ.ГГГГ
Дата обратного вылета back_departure_date
27.10.2013 Дата в формате ДД.ММ.ГГГГ
Время вылета prefered_departure_type
not_important Любое время
morning Утром
afternoon Днем
evening Вечером
night Ночью
Время обратного вылета prefered_back_departure_type
not_important Любое время
morning Утром
afternoon Днем
evening Вечером
night Ночью
Поиск только среди прямых рейсов ("Без пересадок") direct true
Дополнительные параметры
Элемент Переменная Допустимые значения
Нижнее ограничение по цене по умолчанию money_from
0 Целое число большее либо равное 0
Верхнее ограничение по цене по умолчанию money_to
10000 Целое число большее 0
Поиск в окружных датах district_date true
Диапазон соседних дат +(-) [дней] date_range
1 Целое число большее [1..3]
Поиск по соседним аэропортам district_airport true
Класс обслуживания class
econom Перелет эконом-классом
business Перелет бизнес-классом
first Перелет первым-классом
Фильтр по авиакомпании input_vendors
SU,PS Коды авиакомпании ИАТА через запятую без пробелов
Сортировка sort
price По стоимости
out_date По расписанию
company По авиакомпании
fltduration По длительности перелёта

Сложный маршрут

!  Данные переменные применимы только для сложного маршрута (trip_type=CR).

[X] - номера отдельных перелетов. Нумерация начинается с 0, что означает первый перелет.

Максимальное количество сегментов для сложного маршрута определяется одноименной настройкой в разделе Авиабилеты ⇨ Поиск ⇨ Ограничения поиска.

Элемент Переменная Допустимые значения
Пункты вылета cr_iata[0]

cr_iata[1]
...
cr_iata[8]

MOW Код аэропорта ИАТА
Пункты прилета cr_back_iata[0]

cr_back_iata[1]
...
cr_back_iata[8]

LED Код аэропорта ИАТА
Дата вылета cr_date[0]

cr_date[1]
...
cr_date[8]

25.10.2013 Дата в формате ДД.ММ.ГГГГ
Время вылета cr_pref_departure[0]

cr_pref_departure[1]
...
cr_pref_departure[8]

not_important Любое время
morning Утром
afternoon Днем
evening Вечером
night Ночью
Класс обслуживания cr_class[0]

cr_class[1]
...
cr_class[8]

econom Перелет эконом-классом
business Перелет бизнес-классом
first Перелет первым классом
Окружные аэропорты (±XX км) cr_district_airport[0]

cr_district_airport[1]
...
cr_district_airport[8]

true

Пассажиры

Элемент Переменная Допустимые значения
Взрослых от 12 лет adults
1 Целое число большее либо равное 0
Детей от 2 до 12 лет children
1 Целое число большее либо равное 0
Младенцев до 2 лет infants
1 Целое число большее либо равное 0
Младенцев с местом до 2 лет infants_seat
1 Целое число большее либо равное 0
Молодых от 12 до 24 лет
youths
1 Целое число большее либо равное 0

!  Данный параметр доступен только в новой базовой теме.

Пожилых от 65 лет seniors
1 Целое число большее либо равное 0

!  Данный параметр доступен только в новой базовой теме.

Примеры FastSearch запросов

развернуть

В одну сторону (простой)

развернуть

В одну сторону (с фильтрами по авиакомпаниям)

развернуть

Туда-обратно

развернуть

Сложный маршрут

Взаимодействие FastSearch и Метрики

Для того, чтобы переход был зарегистрирован системой как переход с определенного источника, необходимо передать в запросе дополнительный параметр utm_source (Metrics Session ID). Например: 

http://SITEMANE/?(some_parameters=vals&)utm_source=source_alias

где source_alias - алиас источника переходов. Дополнительная информация по использованию модуля Метрики.

Пример FastSearch запроса с параметром для модуля Метрики

развернуть

FastSearch (с учетом источника перехода для модуля Метрики)

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

При выписки билета через стороннюю систему 1С, отправляется запрос "GetDebtCounterparty", который спрашивает, можно ли с счета в 1С списать средства для оплаты. В ответе содержится заключение от 1С, в случае если ошибок нет, в ответе будет 

<m:Opportunity>Да</m:Opportunity>

Пример запроса "GetDebtCounterparty" 

<?xml version="1.0" encoding="UTF-8"?>

  <SOAP-ENV:Body>
    <ns1:GetDebtCounterparty>
      <ns1:ExternalUserId>00000001</ns1:ExternalUserId>
      <ns1:ExternalPaymentId>00000001</ns1:ExternalPaymentId>
      <ns1:BaseFare>2490</ns1:BaseFare>
      <ns1:Tax>643</ns1:Tax>
      <ns1:ValVendorCommission>49.8</ns1:ValVendorCommission>
      <ns1:Locator>0X97T6</ns1:Locator>
      <ns1:Discount>0</ns1:Discount>
      <ns1:Charge>0</ns1:Charge>
      <ns1:Sum>3133</ns1:Sum>
      <ns1:TotalPrice>3658.1</ns1:TotalPrice>
      <ns1:GDSCurrency>RUB</ns1:GDSCurrency>
      <ns1:OrderCurrency>RUB</ns1:OrderCurrency>
      <ns1:OrderCurrencyRate>1</ns1:OrderCurrencyRate>
      <ns1:beginDate>2014-08-30T11:05:00</ns1:beginDate>
    </ns1:GetDebtCounterparty>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Пример ответа "GetDebtCounterparty" 

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header/>
  <soap:Body>
    <m:GetDebtCounterpartyResponse xmlns:m="http://DOMEN_NAME/avia">
      <m:return xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="m:AnswerDebt">
        <m:Opportunity>Да</m:Opportunity>
        <m:Message1/>
      </m:return>
    </m:GetDebtCounterpartyResponse>
  </soap:Body>
</soap:Envelope>

Загрузка счетов из сторонней системы

При взаимодействии с веб-сервисом 1С, на этапе бронирования отправляется запрос, на создание аккаунта 1С, содержащий в себе данные счета. В системе логирования этот запрос можно найти под именем «[GDS] Запрос "NewAccount"» и ответ «[GDS] Ответ "NewAccount"»

развернуть

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

развернуть

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

Источник — https://support.nemo.travel/index.php?title=Интеграция_со_сторонними_системами_АПИ&oldid=7113