Инструкция по использованию API для создания заявок в системе туристического оператора «Библио Глобус»

1. Общее

API системы Библио Глобус zayavkaapi работает по модели RESTful web services. Методы сервиса zayavkaapi принимают HTTP POST запросы, в теле которых должен быть указан XML. В ответ вызывающая сторона получает XML. Если при выполнении метода сервиса возникли ошибки, то метод возвращает коды ошибок в XML.

При формировании запроса необходимо формировать XML в том регистре, в котором дано опсание запросов. Другими слоами, XML протокол API zayavkaapi чувствителен к регистру.

XML запроса должен быть в кодировке UTF-8. XML ответа отдается в кодировке UTF-8.

2. Доступ к API

Доступ к API могут получить только агентства, имеющие логин и пароль для доступа к системе туристического оператора Библио Глобус. Если у вас нет логина и пароля для доступа к системе туристического оператора Библио Глобус, вам необходимо связаться с нашими сотрудниками, отвечающими за работу с агентствами по телефону:
(495) 504-25-00
Любимов Александр — доб. 1448

Авторизация при работе с сервисами описана здесь.

3. Создание заявки через API

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

Второй этап - это запрос на получение цены на тур, с указанными параметрами. После запроса на цену заявка не создается в системе Библио Глобус. В ответ на такой запрос система вернет стоимость тура. Если клиента устраивает стоимость тура, то необходимо сделать второй запрос.

Третий этап - запрос перевода заявки в статус "Тур подобран. Просим забронировать".

Оба запроса (из второго и третьего этапов) делаются с одним и тем же телом запроса за исключением второго запроса: здесь добавляется еще один элемент (см. ниже).

Оба запроса (из второго и третьего этапов) необходимо посылать на следующий адрес:

https://www.bgoperator.ru/zayavkaapi?prx=<значение prx из XML прайса>&action=createtour

Важно: протокол https, хост www.bgoperator.ru должны быть указаны. Параметры prx и action должны быть указаны имеено в таком порядке. Значение параметра prx необходимо брать из XML прайс листа (подбронее тут). Без выполнения этих требований запрос к API не будет обработан.

Важно: в одном HTTP POST запросе к API могут быть вместе указаны запросы обоих типов. Другими словами одним запросом можно запросить цену для одного тура, а для другого изменение статуса на "Тур подобран. Просим забронировать".

3.1. Первый запрос: получение стоимости тура

Запрос на цены туров может содержать описание нескольких туров. Каждый тур - это тег <tour>. В каждом туре могут несколько групп туристов. Группа туристов определяется датой начала основого проживания и набором проживаний. Проживание в данном случае - это тип номера+питание. В группу могут входить несколько туристов. Каждая группа туристов в туре - это тег <group>. Все группы заключаются в тег <groups>.
Для каждого тура в атрибуте clientTourId тега <tour> можно указать произвольный идентификатор клиентского тура, который система вернет при ответе "как есть". Таким образом клиентская сторона сможет сопоставить запрос и ответ.

Формат запроса:

В данным запросе указан тур в Индинезию с основным проживанием на острове Бали и двуми проживаниями (before и after) в Бангкоке.

<tours>
  <tour clientTourId="
1">
    <countryId>
100410504525</countryId>
    <templateId>
121178311485</templateId>
    <groups>
      <group>
       
<startDate>01.03.2014</startDate>
       
<ins>0-100000-USD-0</ins>
              <roommeal duration="7">104623691678</roommeal>
              <roommealb duration="1">104625776787</roommealb>
              <roommeala duration="1">104625776787</roommeala>
       
<sr>43UpM9e04HAuj04HAu+04HAvK04HAvf08YLk208YLkN08YLki08YLk*0CpWZQ0CpWZl0CpWa10CpWaM0H1hOo0H1hP40H1hPP0H1hPk</sr>
              <persons>
         
<person>
           
<birthday>11.06.1982</birthday>
                     <firstName>IVAN</firstName>
                     <lastName>IVANOV</lastName>
                     <citizenship>100410000050</citizenship>
                     <passportSeries>62</passportSeries>
                     <passportNumber>12345678</passportNumber>
                     <passportTill>11.11.2016</passportTill>
                     <gender>m</gender>
                 </person>
                 
              </persons>
      </group>
     

    </groups>
  </tour>
  …
</tours>

countryId — страна туризма. Идентификатор страны в системе Библио Глобуса.
templateId — значений тега <id_price> из XML прайса. В запрос к API этот параметр должен быть передан без изменений, так, как указан в XML прайсе.
comissionId — значений тега <ic> из XML прайса. В запрос к API этот параметр должен быть передан без изменений, так, как указан в XML прайсе.
Важно: для одной заявки может быть указан только один из двух тегов: либо <templateId>, либо <comissionId>. Это определяется наличием в XML прайсе тега <ic>. Если он указан, то в запросе к API необходимо указывать тег <comissionId>. В противном случае необходимо указывать тег <templateId>.
groups / group / startDate — дата начала основого проживания в формате DD.MM.YYYY. Соответствует тегу <dt> из XML прайса. В запрос к API этот параметр должен быть передан без изменений, так, как указан в XML прайсе.
groups / group / ins — страховка. Необязательный параметр. Список доступных страховок можно посмотреть в прайсе с параметром &xml=21. В секции insurance выведется список страховок. В данный тег необходимо передавать значение из тега value.
Важно: если не указывать страховку, то в создаваемую заявку будет добавлена страховка по-умолчанию.
groups / group / roommeal — основное проживание. Идентификатор названия номера-типа питания в системе Библио Глобус. Соответствует тегу <id_ns> из XML прайса. В атрибуте duration этого тега указывается длительность проживания (ночей). Соответствует тегу <o_duration> из XML прайса.
groups / group / roommealb — первое дополнительное проживание до основного. Сууффикс b значит before. Идентификатор названия номера-типа питания в системе Библио Глобус. Соответствует тегу <id_ns_b> из XML прайса. В атрибуте duration этого тега указывается длительность проживания (ночей). Соответствует тегу <b_duration> из XML прайса.
groups / group / roommealab — второе дополнительное проживание до основного. Сууффикс ab значит after before. Идентификатор названия номера-типа питания в системе Библио Глобус. Соответствует тегу <id_ns_ab> из XML прайса. В атрибуте duration этого тега указывается длительность проживания (ночей). Соответствует тегу <ab_duration> из XML прайса.
groups / group / roommealba — второе дополнительное проживание после основного. Сууффикс ba значит before after. Идентификатор названия номера-типа питания в системе Библио Глобус. Соответствует тегу <id_ns_ba> из XML прайса. В атрибуте duration этого тега указывается длительность проживания (ночей). Соответствует тегу <ba_duration> из XML прайса.
groups / group / roommeala — первое дополнительное проживание после основного. Сууффикс a значит after. Идентификатор названия номера-типа питания в системе Библио Глобус. Соответствует тегу <id_ns_a> из XML прайса. В атрибуте duration этого тега указывается длительность проживания (ночей). Соответствует тегу <a_duration> из XML прайса.
groups / group / sr — зачение тега <sr> из XML прайса. В запрос к API этот параметр должен быть передан без изменений, так, как указан в XML прайсе.
groups / group / persons / person / birthday — дата рождения туриста в формате DD.MM.YYYY.
groups / group / persons / person / firstName — имя туриста так, как указано в загран. паспорте в верхнем регистре.
groups / group / persons / person / lastName — фамилия туриста так, как указано в загран. паспорте в верхнем регистре.
groups / group / persons / person / passportSeries — серия загран. паспорта туриста.
groups / group / persons / person / passportNumber — номер загран. паспорта туриста.
groups / group / persons / person / passportTill — дата окончания действия загран. паспорта туриста в формате DD.MM.YYYY.
groups / group / persons / person / gender — пол в формате формате m (мужской) или f (женский)

Формат ответа:

<tours>
  
<tour clientTourId="1">
    <sum>
      <currency>USD</currency>
      <fullamount>1193.0</fullamount>
     
<comission>119.0</comission>
         <amount>1074.0</amount>
    </sum>
    <sum>
      <currency>RUR</currency>
      <fullamount>74563.0</fullamount>
     
<comission>7438.0</comission>
         <amount>67125.0</amount>
    </sum>
  </tour>
  …
</tours>

currency — валюта, в которой указаны полная стоимость, комиссия и сумма к оплате
fullamout — полная стоимость тура
comission — комиссия
amount — сумма к оплате

3.2. Второй запрос: подтверждение заявки

Запрос на перевод заявки в статус  "Тур подобран. Просим забронировать" оформляется точно так же, как и запрос на получение цены. Для Каждого тура, для которого необходимо поменять статус на "Тур подобран. Просим забронировать" необходимо в любое место тега <tour> вставить тег <confirm/>. После данного запроса агентство увидит созданную заявку в личном кабинете на сайте туроператора Библио Глобус в списке заявок .

Формат запроса:

<tours>
  <tour clientTourId="
2">
    <confirm/>
    <countryId>100410504525</countryId>
    <templateId>
121178311485</templateId>
    <groups>
      <group>
       
<startDate>01.03.2014</startDate>
       
<ins>0-100000-USD-0</ins>
              <roommeal duration="7">104623691678</roommeal>
              <roommealb duration="1">104625776787</roommealb>
              <roommeala duration="1">104625776787</roommeala>
       
<sr>43UpM9e04HAuj04HAu+04HAvK04HAvf08YLk208YLkN08YLki08YLk*0CpWZQ0CpWZl0CpWa10CpWaM0H1hOo0H1hP40H1hPP0H1hPk</sr>
              <persons>
         
<person>
           
<birthday>11.06.1982</birthday>
                     <firstName>IVAN</firstName>
                     <lastName>IVANOV</lastName>
                     <citizenship>100410000050</citizenship>
                     <passportSeries>62</passportSeries>
                     <passportNumber>12345678</passportNumber>
                     <passportTill>11.11.2016</passportTill>
                     <gender>m</gender>
                 </person>
                 
              </persons>
      </group>
     

    </groups>
  </tour>
  …
</tours>

Формат ответа:

<tours>
  <tour clientTourId="2">
   
<id>104400000842366804</id>
       <number>214150198</number>
   </tour>
  …
</tours>

id — внутернний идентификатор заявки (тура) в системе Библио Глобус.
number — номер заявки

Обработка запроса прерывается, если найдена хотя бы одна ошибка. В этом случае в ответ посылается XML вида:

<errors clientTourId="2">
  <error>126</error>
  <info>104400000842366804</info>
</errors>

Некоторые ошибки снабжаются тегом <info>, в который записывается дополнительная информация, соответствующая ошибке.


4. Аннуляция заявки

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

4.1. Первый запрос: получение фактических затрат и ticket

Запрос посылается на следующий адрес

https://www.bgoperator.ru/zayavkaapi?idTour=<id заявки>&action=canceltour

Формат ответа:

<tours>
  
<tour>
    <sum>
      <currency>EUR</currency>
      <amount>20</amount>
          <ticket>39c1cb27c6306f0ff79ec605dc12ea8e</ticket>
    </sum>
  </tour>
</tours>

currency — валюта фактических затрат на аннуляцию
amount — сумма фактических затрат на аннуляцию
ticket — параметр, необходимый в следующем запросе на аннуляцию

4.2. Второй запрос: аннуляция

Запрос посылается на следующий адрес

https://www.bgoperator.ru/zayavkaapi?idTour=<id заявки>&action=canceltour&confirm=yes&ticket=<ticket из предыдущего ответа>

Формат ответа:

<status>OK</status>

5. Изменение контактных данных туристов в заявке

POST запрос посылается на следующий адрес

https://www.bgoperator.ru/zayavkaapi?idTour=<id заявки>&action=addContactInfo

Формат запроса:

<persons>
  
<person id="102300000815141601">
    <email>test@mail.ru</email>
    <phone>+7 916 1234567</phone>

  </person>

  <person id="...">
    ...
  </person>
</persons>

person id
— id туриста в заявке, который можно получить из запроса showtransfers (п. 6.1).

В теле запроса можно указать более одного туриста.

Формат ответа:

<status>OK</status>


6. Добавление трансферов в заявку

Добавление или изменение трансферов в заявку происходит в три этапа. На каждом этапе используются данные из предыдущего этапа. Первый этап - это получение возможных трансферов для каждого туриста в заявке. Второй этап - это получение так называемых полетных данных. Полетные данные - это id рейса и информация о рейсе в формате человекочитаемой строки. Третий этап - это непосредственно добавление трансферов на основе информации, полученной на первых двух этапах.

Изменение трансферов по запросам не отличается от добавления трансферов в заявку. Существующие трансферы будут заменены на новые, указанные в запросе.

6.1. Первый запрос: получение доступных трансферов

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

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

Формат запроса:

GET запрос посылается на следующий адрес

https://www.bgoperator.ru/zayavkaapi?idTour=<id заявки>&action=showtransfers

Формат ответа:

<tours>
  <persons tourId="
104400000817245901">
    <person id="102300000817246001">
     
<firstName>JOHN</firstName>
     
<lastName>DOE</lastName>
          <birthday>11.06.1982</birthday>
          <transferSlot dir="to" point="102640012614" ptype="h" date="14.03.2015">
              <variant id="103825996892" price="80.00" currency="USD" ttype="ind" point="103940001962" pid="103840004162" ptype="a">ШАРМ ЭЛЬ ШЕЙХ(аэропорт) - Шарм-эль-шейх(отель) / minibus 10</roommeal>
              ...
          </transferSlot>
          <transferSlot dir="from" point="102640012614" ptype="h" date="15.03.2015">
              <variant id="103825996895" price="80.00" currency="USD" ttype="ind" point="103940001962" pid="103840004167" ptype="a">Шарм-эль-шейх(отель) - ШАРМ ЭЛЬ ШЕЙХ(аэропорт) / minibus 10</roommeal>
              ...
          </transferSlot>
      </person>
     
   </persons>
</tours>

persons tourId — id заявки в системе Библио Глобуса. В данном теге для каждого туриста - <person> - указываются возможные трансферы.
persons / person id — id туриста в заявке в системе Библио Глобуса.
persons / person / firstName — имя туриста.
persons / person / lastName — фамилия туриста.
persons / person / birthday — дата рождения туриста в формате DD.MM.YYYY.
persons / person / transferSlot — трансферный слот описывает возможность добавления трансфера. Внутри данного тега содержатся возможные варианты трансферов. Атрибуты тега <transferSlot> задают описание одной из точек трансфера.
persons / person / transferSlot dir — направление трансфера. "to" - трансфер к точке, задаваемой атрибутами тега <transferSlot>. "from" - трансфер от точки, задаваемой атрибутами тега <transferSlot>
persons / person / transferSlot point — id точки трансфера. Точка может быть отелем, аэропортом или городом.
persons / person / transferSlot ptype — тип точки трансфера, задаваемой атрибутом point. "h" - отель, "a" - аэропорт, "c" - город.
persons / person / transferSlot date — дата трансфера.
persons / person / transferSlot / variant — данный тег задает оидн из возможных вариантов трансфера и описывает вторую точку трансфера. Содержимое тега есть человекочитаемое название трансфера.
persons / person / transferSlot / variant id — id варианта трансфера.
persons / person / transferSlot / variant price — стоимость варианта трансфера.
persons / person / transferSlot / variant currency — валюта стоимости варианта трансфера.
persons / person / transferSlot / variant ttype — типа варианта трансфера. "ind" - индивидуальный трансфер, "grp" - групповой трансфер.
persons / person / transferSlot / variant point — id точки трансфера. Точка может быть отелем, аэропортом или городом.
persons / person / transferSlot / variant ptype — тип точки трансфера, задаваемой атрибутом point. "h" - отель, "a" - аэропорт, "c" - город.
persons / person / transferSlot / variant pid — содержимое данного атрибута считается системным, но обязательным для заполнения при добавлении/изменении трансферов в заявке с пакетным туром (НЕ туром без перелета).

6.2. Второй запрос: получение полетных данных

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

Формат запроса:

GET запрос посылается на следующий адрес

https://www.bgoperator.ru/zayavkaapi?action=showflightdata&idAir=<id аэропорта>&dt=<дата трансфера>&dir=<прилет/вылет в/из аэропорта>

Здесь:

id аэропорта — это id точки с ptype="a" из ответа на предыдущий запрос. Например, это id из point="103940001962".

дата трансфера — это дата date из тега <transferSlot>. Формат DD.MM.YYYY.

прилет/вылет в/из аэропорта — "a" (arrival) в случае трансфера из аэропорта (прилет). "d" (departure) в случае трансфера в аэропорт (вылет).

Формат ответа:

<tours>
  <flights
idAirport="103940001962" date="14.03.2015" dir="a">
    <flight id="103162337682">UN 651 (Y)#14.03.2015#10:45-14:25</flight>
     
   </flights>
</tours>

flights
idAirport — id аэропорта, переданного, как параметр в запросе.
flights date — дата трансфера, переданного, как параметр в запросе.
flights dir — "a" (arrival) в случае трансфера из аэропорта (прилет). "d" (departure) в случае трансфера в аэропорт (вылет).
flights / flight — содержимое тега есть человекочитаемая информация о рейсе. Эта строка и называется полетными данными.
flights / flight id — id рейса в системе Библио Глобуса.

6.3. Третий запрос: добавление трансферов в заявку

Запрос на добавление/изменение трансферов в заявку - это POST запрос, посылаемый на следующий адрес:

https://www.bgoperator.ru/zayavkaapi?idTour=<id заявки>&action=addtransfers

Формат запроса:

<persons tourId="104400000817245901">
  <person id="102300000817246001">
        <transferSlot date="14.03.2015" variantId="103840004178" pointFrom="103940001962" pointTo="102640012614" dir="to" id="1" pid="103840004162">
            <flight id="103162337682">UN 651 (Y)#14.03.2015#10:45-14:25</flight>
        </transferSlot>
        <transferSlot date="15.03.2015" variantId="103840004180" pointFrom="102640012614" pointTo="103940001962" dir="from" id="2" pid="103840004167">
            <flight id="103139177213">SU2075 (Y)#18.06.2014#19:15-00:05</flight>
        </transferSlot>
    </person>
   
</persons>

persons tourId — id заявки в системе Библио Глобуса. В данном теге для каждого туриста - <person> - указываются возможные трансферы.
persons / person id — id туриста в заявке в системе Библио Глобуса.
persons / person / transferSlot variantId — id выбранного варианта трансфера для данного трансферного слота.
persons / person / transferSlot date — дата трансфера.
persons / person / transferSlot pointFrom — id точки отправления. Берется из атрибута point из ответа за запрос из п. 6.1.
persons / person / transferSlot pointTo — id точки прибытия. Берется из атрибута point из ответа за запрос из п. 6.1.
persons / person / transferSlot dir — направление трансфера. "to" - трансфер к точке, задаваемой атрибутами тега <transferSlot>. "from" - трансфер от точки, задаваемой атрибутами тега <transferSlot>
persons / person / transferSlot pid — системный атрибут, который необходимо заполнять "как есть" при добавлении/изменении трансферов в заявке с пакетным туром (НЕ туром без перелета).
persons / person / transferSlot id — пользовательский атрибут, который можно заполнять на стороне клиента для анализа возможных ошибок в ответе.
persons / person / transferSlot / flight — данный тег со всеми атрибутами необходимо заполнять в точности так, как он приходит в ответе в п. 6.2.

Формат ответа:

В ответ на добаление/изменение трансферов приходит такая же информация, что и на запрос на создание заявки. А именно новая стоимость заявки. См. пункт 3.2.

7. Коды ошибок

При обработке запроса возможны следующие ошибки.

101 - Создание заявки невозможно, общая ошибка
102 - Отсутствует или незаполнен один из двух тегов comissionId или templateId
103 - Отказ в доступе к api из-за некорректного логина или пароля
104 - Заполнены и comissionId, и templateId. Заполнено должно быть что-то одно
105 - Указанный templateId не существует
106 - Указанный comissionId не существует
107 - Не указана страна (countryId)
108 - Указана некорректная страна (countryId)
109 - Не указана валюта (currency)
110 - Указана некорректная валюта (currency)
111 - Указана неверная дата начала тура группы (startDate)
112 - Указана неверная дата конца тура группы (endDate)
113 - Указана неверная дата рождения (birthday)
114 - Не указан тип номера с питанием (roommealId)
115 - Указан некорректный тип номера с питанием (roommealId)
116 - Не указана длительность (атрибут duration тега roommealId)
117 - Указана некорректная длительность (атрибут duration тега roommealId)
118 - Не указан параметр sr
119 - Указан некорректный параметр sr
120 - Невозможно подобрать рейсы
121 - Невозможно подобрать вариант размещения
122 - Не указано гражданство (citizenship)
123 - Указано некорректное гражданство (citizenship)
124 - Указана неверный срок действия паспорта (passportTill)
125 - Невозможно посчитать стоимость тура
126 - Обнаружен дубль бронирования. В тег <info> добавляется внутренний идентификатор тура-дубля.
127 - Не указано ни одного проживания
128 - Превышен лимит создания заявок. Создание заявки на данный момент невозможно
129 - Заявка не найдена
130 - Невозможно прочитать/создать трансферы. Общая ошибка
131 - Неверная комбинация атрибутов date, pointTo, pointFrom
132 - Неверный variantId (id трансфера)
133 - Неверный комбинация атрибутов date, pointTo, pointFrom для данного person. В тег <info> добавляется id туриста
134 - Не указан variantId (id трансфера)
135 - Не указан id заявки
136 - Не указан id туриста
137 - Турист не найден
138 - Не указан pointTo
139 - Указан несуществующий pointTo
140 - Не указан pointFrom
141 - Указан несуществующий pointFrom
142 - Не указан id рейса
143 - Рейс не найден
144 - Неверный формат даты проживания в трансферном слоте
145 - Неверный формат направления трансфера dir
146 - Неверный формат даты в полётных данных
147 - Неверный формат полётных данных
148 - Уже нельзя изменить трансфер (ограничение по времени)
149
- Не указан pid у тега variant
150 - Неверный pid у тега variant
154 - Неверный формат пола
155 - Необходимо заполнить хотя бы что-то из контактной информации
156 - Email не соответствует формату
157 - Аннуляция невозможна
158 - Заявка уже аннулирована
159 - Имя не заполнено
160 - Фамилия не заполнена
161 - Номер или серия паспорта не заполнены