Система реестра туров имеет программный шлюз для автоматического добавления туров из приложений онлайн-бронирования туроператоров. Шлюз использует 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'

{
	"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"}

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

wget -q -O - 'http://test.fondkamkor.kz' -S --post-file=bad.json 
--header 'Content-Type: application/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":"

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

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

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

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

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

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

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

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

wget -q -O - 'http://test.fondkamkor.kz' -S --post-file=dict_countries.json 
--header 'Content-Type: application/json'

{
	"input":{
		"what":["country","countryen","currency"],
		"output":"array"
	 },
	 "module":"voucher",
	 "section":"partner",
	 "object":"dictionaries",
	 "param1":"get",
	 "param2":"countries",
	 "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

{"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'

{
	"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'

{
	"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 в базу. Аэропорты строятся, меняют название - все это приводит к устареванию базы данных.

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

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

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

• Так как параметры заявки или туриста могут быть изменены по ходу обработки заявки или из-за корректировок тура, то, чтобы корректно обрабатывать туркоды (выписывать, подавать на порчу и тп) - имеет смысл ввести понятие туркода в программу (можно использовать логику билетов на услугу или справочника записей). Этот туркод должен быть привязан к туристу, заявке и иметь номер, статус и строку причины порчи. Так, один и тот же турист может иметь пару запорченных туркодов (менялся номер паспорта с некорректного на правильный), поданный на порчу (сменилась дата вылета или аэропорт прилета) и действующий. При этом сотрудник туроператора должен иметь возможность совершить какие-то действия с туркодом из программы - например, при смене дат вылета или номера паспорта.
• При подаче запроса на порчу имеет смысл предварительно создать новый туркод с правильными параметрами тура, получить номер и указать этот номер в причине порчи предыдущего - тогда обработка запроса на порчу будет быстрой.
• Уделите внимание обработке ошибок при создании туркода. При достаточно серьезных объемах в сезон менеджерам, обрабатывающим туры, будет некогда читать тонны приходящих писем об однообразных ошибках и может получиться так, что какая-то часть туристов не получит туркоды вообще. Частой является ситуация, когда на счету (балансе) туроператора закончились средства, но система продолжает без остановки посылать данные - как новые, так и повторно. То есть нужен переключатель состояния системы (с оповещением), который бы мог отключать регулярную посылку данных при получении каких-то ошибок или какого-то количества одинаковых ошибок.
• Если в поле названия агентства вы будете включать название города или какие-то другие параметры турагента (email, телефон), это облегчит поиск турагента в случае форс-мажоров и снизит нагрузку на сотрудников туроператора.

Обновления документации:
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 года.