КАБИНЕТ
API подключения
Главная  /   Туроператорам  /   API подключения
API подключения систем онлайн-бронирования компаний-участников к системе реестра туров.

Система реестра туров имеет программный шлюз для автоматического добавления туров из приложений онлайн-бронирования туроператоров. Шлюз использует HTTP-протокол и JSON-формат передачи данных с аутентификацией через переменные внутри JSON-структуры. Ниже описаны общие условия для успешной передачи данных в систему реестра туров и необходимые методы.

Подключение производится по стандартному для HTTP-протокола порту 80/tcp. В HTTP-заголовках должны присутствовать заголовки Content-Type со значением application/json и User-Agent со произвольным значением, позволяющим однозначно определить программу онлайн-бронирования и версию ПО. Используется HTTP-метод POST. Запрос производится на корень сервера. В теле запроса должна быть валидная JSON-структура запроса.

Чтобы подключиться к шлюзу, нужно сначала отладить передачу данных на тестовой платформе. Параметры подключения к тестовой платформе: адрес: http://test.fondkamkor.kz, логин test, пароль test. Затем, когда вы будете готовы отсылать реальные данные, свяжитесь с технической поддержкой для получения доступа к рабочей платформе реестра туров. В качестве примера ниже в документации используется кроссплатформенная утилита wget.

Производственные методы

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

wget -q -O - 'http://test.fondkamkor.kz' -S --post-file=create.json 
--header 'Content-Type: application/json'
При этом файл create.json содержит следующее:
{
	"input":{
		"q_touragent":"ADIYA TRAVEL"
		"q_country":"Россия",
		"q_countryen":"Russia",
		"q_airport_start":"ALA",
		"q_airlines":"DV",
		"q_airport":"AAQ",
		"q_date_from":"17.11.2018",
		"q_date_to":"24.11.2018",
		"q_days":8,
		"q_remark":"tour notes here",
		"clientcounter":0,
		"c_name_0":"Client_$CID",
		"c_borned_0":"01.01.1970",
		"c_doc_date_0":"02.11.2016",
		"c_doc_number_0":"N08462365",
		"c_doc_production_0":"MIA OF RK",
	},
	"module":"voucher",
	"section":"partner",
	"object":"queries",
	"param1":"163",
	"param2":"save",
	"formid":163,
	"agentlogin":"test",
	"agentpass":"test",
	"return":"q_number"
}
Ответ сервиса будет примерно таким:
  HTTP/1.1 200 OK
  Server: nginx/1.1.4
  Content-Type: application/json;charset=UTF-8
  Connection: close
  Cache-Control: no-store, no-cache, must-revalidate
  Pragma: no-cache
  Date: Sat, 19 Nov 2016 22:57:01 GMT
  FastCGI-PID: 17961

{"status":200,"string":"4Ru61117-33"}
Здесь черным цветом указаны стандартные HTTP-заголовки ответа, красным - тело ответа (формат JSON).
Подробное объяснение структур запроса и ответа:
Запрос
Переменная Назначение поля Обяза- тельно Формат данных Описание
module Название модуля системы Да строка для работы с турами и справочниками значение должно быть "voucher"
section Режим аутентификации Да строка для подключения систем туроператоров значение должно быть "partner"
object Название метода Да строка Меняется в зависимости от типа запроса. Может быть "queries" или "dictionaries"
param1, formid ID шаблона данных Да число для подключения систем туроператоров значение должно быть 163
param2 Действие над туром Да строка save - при сохранение тура, bad - при порче тура
return Возвращаемое поле тура Нет строка Название возвращаемой переменной (при ответе). Переменная q_number содержит ТурКод.
agentlogin Логин туроператора Да строка На тестовой платформе - test
agentpass Пароль туроператора Да строка На тестовой платформе - test
Хэш (объект) input:
q_touragent Название турфирмы-агента Да строка Название, позволяющее найти турагента при отсутствии туроператора
q_country Русскоязычное название страны пребывания Да строка Должно присутствовать в справочнике стран (см. справочные методы).
q_countryen Англоязычное название страны пребывания Да строка Должно присутствовать в справочнике стран (см. справочные методы).
q_airlines IATA-код авиалиний Да строка, [A-Z0-9]{2} Должно присутствовать в справочнике авиалиний (см. справочные методы). Добавлено 03.10.2017
q_airport_start IATA-код аэропорта вылета Да строка, [A-Z]{3} Должно присутствовать в справочнике аэропортов и совпадать со страной Казахстан (см. справочные методы). Добавлено 03.10.2017
q_airport IATA-код аэропорта прилета Да строка, [A-Z]{3} Должно присутствовать в справочнике аэропортов и совпадать со страной (см. справочные методы)
q_date_from Дата начала тура (вылет) Да строка, ДД.ММ.ГГГГ или ГГГГ-ММ-ДД Дата должна быть в будущем
q_date_to Дата конца тура (прилет) Да строка, ДД.ММ.ГГГГ или ГГГГ-ММ-ДД Дата должна быть больше даты начала
q_days Число дней тура Нет число Не должно быть меньше единицы
q_remark Заметки по туру Нет строка  
clientcounter Счетчик туристов Да число Число меньше на единицу, чем число туристов в туре (для 1 туриста = 0)
c_name_0 Имя туриста 1 Да строка ФИО туриста. Если компания туроператора решит не передавать ФИО, должно быть значение Client_$CID
c_borned_0 Дата рождения туриста 1 Да строка, ДД.ММ.ГГГГ или ГГГГ-ММ-ДД Должна быть в прошлом, и больше 2х лет от даты прилета обратно (не infant). Если компания туроператора решит не сообщать дату рождения, должно быть значение 01.01.1970
c_doc_date_0 Дата выдачи паспорта туриста 1 Нет строка, ДД.ММ.ГГГГ или ГГГГ-ММ-ДД Дата должна быть в прошлом. Необязательна.
c_doc_number_0 Номер паспорта туриста 1 Да строка Допустимы цифры и буквы, до 15 символов.
c_doc_production_0 Госорган, выдавший паспорт туристу 1 Нет строка Аббревиатура органа государства, необязательна.
Ответ
Название поля Назначение поля Формат данных Описание
status Код ответа число 200 - успешно, другое значение - ошибка.
string Текст ответа строка Если ошибка - ее текст, если успешно - ТурКод

Только один турист допустим в присланном туре, иначе сервис вернет ошибку. ПО туроператора должно присвоить возвращенный туркод каждому туристу и отобразить в соответствующих печатаемых документах для туриста.

wget -q -O - 'http://test.fondkamkor.kz' -S --post-file=bad.json 
--header 'Content-Type: application/json'
При этом файл bad.json содержит следующее:
{
	"input":{
		"msg":"Аннулируйте туркод - в нем неправильно указан город прилета. Верный туркод - 123456-7890",
		"replyto":"manager@touroperator.kz"
	},
	"module":"voucher",
	"section":"partner",
	"object":"queries",
	"param1":"4Ru61117-32",
	"param2":"bad",
	"agentlogin":"test",
	"agentpass":"test"
}
Ответ сервиса будет примерно таким:
  HTTP/1.1 200 OK
  Server: nginx/1.1.4
  Content-Type: application/json;charset=UTF-8
  Connection: close
  Cache-Control: no-store, no-cache, must-revalidate
  Pragma: no-cache
  Date: Sat, 19 Nov 2016 22:57:01 GMT
  FastCGI-PID: 17961

{"target":"/Voucher/partner/queries/33/view","status":200,
"string":"

Вы будете перенаправлены на запрошенный адрес

..."}Подробное объяснение новых структур запроса и ответа:
Запрос
Переменная Назначение поля Обяза- тельно Формат данных Описание
param1 ТурКод Да число ТурКод, по которому будет найден тур в реестре.
param2 Действие над туром Да строка save - при сохранение тура, bad - при порче тура
Хэш (объект) input:
msg Текст описания Да строка Объяснение причины отмены тура. Должно быть осмысленным, оператор турфирмы должен заполнять это поле вручную, иначе запрос будет проигнорирован.
replyto E-mail оператора Да строка Обратный адрес для связи с туроператором, пославшим запрос на отмену заявки
Ответ
Название поля Назначение поля Формат данных Описание
target Ссылка на отмененный тур строка URL-адрес для просмотра в браузере.

Если тур видоизменился (изменились его параметры, перечисленные в запросе создания тура), необходимо отменить старый тур, создать новый и получить новый ТурКод. Если не отменить старый, взнос за тур будет списан с баланса туроператора дважды.

Функция повтора создания туркода

При недоступности сервиса, возврате ошибок или иных причинах неполучения туркода для туриста ПО туроператора должно либо попытаться позже (спустя какое-то время, не мгновенно) еще раз получить туркод, либо оповестить сотрудников туроператора об ошибке. В случае повторяющейся проблемы неполучения туркода ПО должно прекратить попытки создания туркода и оповестить сотрудников туроператора. Если в Фонд обратится сам турист и сообщит об отсутствии ТурКода, это может грозить туроператору лишением лицензии.

Если ПО туроператора многократно (бесконечно) пытается создать тур и получить ТурКод, необходимо ограничить попытки сутками с момента начала попыток, либо лимитировать количество попыток создания тура. Причины, по которым система не выдает туркод могут быть самыми разными: аккаунт туроператора может быть заблокирован в системе Фонда, деньги на счету туроператора могут закончиться, в поле запроса создания тура могут быть найдены ошибки, распознаваемые системой Фонда, но не распознаваемые со стороны ПО туроператора и тому подобное. Бесконечность попыток при условии увеличивающегося количества туров, которые требуется сохранить - может привести к перегрузке одной или обеих систем.

Справочные методы

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

Получение массива данных по странам:

wget -q -O - 'http://test.fondkamkor.kz' -S --post-file=dict_countries.json 
--header 'Content-Type: application/json'
При этом файл dict_countries.json содержит следующее:
{
	"input":{
		"what":["country","countryen","currency"],
		"output":"array"
	 },
	 "module":"voucher",
	 "section":"partner",
	 "object":"dictionaries",
	 "param1":"get",
	 "param2":"countries",
	 "agentlogin":"test",
	 "agentpass":"test"
}
Запрос
Переменная Назначение поля Обяза- тельно Формат данных Описание
object Название метода Да строка Меняется в зависимости от типа запроса. Может быть "queries" или "dictionaries"
param1 Действие над справочником Да строка Единственное допустимое для уровня туроператора действие над справочником - получение информации (get)
param2 Название справочника Да строка Доступные справочники: countries, airports, airlines, agents
Хэш (объект) input:
what Массив запрашиваемых полей Нет список строк Если не указать эту переменную, будут выведены все столбцы, что увеличит объем ответа.
output Структура ответа Нет строка Если не указать эту переменную, массив variants будет содержать объекты, а не списки.
Ответ
Название поля Назначение поля Формат данных Описание
target Ссылка на отмененный тур строка URL-адрес для просмотра в браузере.
Ответ сервиса будет примерно таким:
  HTTP/1.1 200 OK
  Server: nginx/1.1.4
  Content-Type: application/json;charset=UTF-8
  Connection: close
  Cache-Control: no-store, no-cache, must-revalidate
  Pragma: no-cache
  Date: Sat, 19 Nov 2016 22:57:01 GMT
  FastCGI-PID: 17961

{"variants":[["Австралия","Australia","USD"],["Австрия","Austria","EUR"],["Азербайджан","Azerbaijan","USD"],
...
,["Ямайка","Jamaica","USD"],["Япония","Japan","USD"]],"dictname":"countries"}

 

Получение массива данных по аэропортам:

wget -q -O - 'http://test.fondkamkor.kz' -S --post-file=dict_airports.json 
--header 'Content-Type: application/json'
При этом файл dict_airports.json содержит следующее:
{
	"input":{
		"what":["iata","icao","country","countryen"],
		"output":"array"
	 },
	 "module":"voucher",
	 "section":"partner",
	 "object":"dictionaries",
	 "param1":"get",
	 "param2":"airports",
	 "agentlogin":"test",
	 "agentpass":"test"
}
Ответ будет аналогичным по структуре.

Получение массива данных по авиалиниям:

wget -q -O - 'http://test.fondkamkor.kz' -S --post-file=dict_airlines.json 
--header 'Content-Type: application/json'
При этом файл dict_airlines.json содержит следующее:
{
	"input":{
		"what":["iata","icao","country","airline","companyname","address","airline_url"],
		"output":"array"
	 },
	 "module":"voucher",
	 "section":"partner",
	 "object":"dictionaries",
	 "param1":"get",
	 "param2":"airlines",
	 "agentlogin":"test",
	 "agentpass":"test"
}
Ответ будет аналогичным по структуре.

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

Также вы можете скачать в формате XLS для ручной сверки со справочниками в своей программе списки названий стран (27кб, 260 стран) и кодов аэропортов IATA с привязкой к странам (1.6мб, 9432 кода).

Если вы встретили ошибку вида "Invalid Country/IATA combination. Check dictionaries synchronisation, please", но уверены в том, что вы подали правильное название страны и код аэропорта, возможно, он отсутствует в наших справочниках, обратитесь в таком случае в техническую поддержку фонда, чтобы справочники были обновлены.

Может возникнуть ситуация, когда код IATA признается несуществующим, хотя он есть на самом деле (вы получаете ошибку вида "Invalid Country/IATA code..."). В этом случае нужно обратиться в техническую поддержку с просьбой добавить код IATA в базу. Аэропорты строятся, меняют название - все это приводит к устареванию базы данных.

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

На правах рекомендации

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

 

Обновления документации:
13.12.2016
Удален абзац:
"На сегодня (20.11.2016) остается открытым вопрос о количестве туристов в туре. Если их количество все же будет равным количеству в реальном туре, то переменная clientcounter должна будет равна N-1, где N - количество туристов в туре, а переменные c_name_0 ... c_doc_production_0 должны быть продублированы с соответствующими суффиксами _1, _2 и т.д. - под каждого туриста. Если же их количество будет фиксировано одним туристом в туре, встанет задача хранить туркод для каждого туриста в программе туроператора (и распечатывать в ваучерах или иных документах для туриста массив туркодов)."
Вместо него добавлена фраза:
"Только один турист допустим в присланном туре, иначе сервис вернет ошибку. ПО туроператора должно присвоить возвращенный туркод каждому туристу и отобразить в соответствующих печатаемых документах для туриста."
03.10.2017
Добавлена информация по двум обязательным полям ввода при передачи данных для получения туркода: q_airlines и q_airport_start. Добавлено описание запроса справочника airlines. Обязательность начнет действовать с 1го января 2018 года.

Преимущества для всех
Система гарантирования прав граждан Республики Казахстан была введена в действие Постановлением Правительства РК от 21 октября 2016 года №607. Корпоративный Фонд "Туристік Қамқор" определен Администратором системы согласно Постановления Правительства РК от 21 октября 2016 года №608
Оперативная регистрация в Системе
Автоматическая генерация туркода
Обработка Туркода на сервере
Безопасность хранения и использования данных
Ежегодные отчеты о деятельности Системы
Эффективное взаимодействие всех участников туристической отрасли
Ежедневная статистика вылетов
+
Сообщение сайта
+
+
Хотите разместить заказ или узнать больше о наших продуктах?
Пожалуйста, заполните форму ниже.
Ваше сообщение будет обработано в кратчайшие сроки!
ОТПРАВИТЬ