Система гарантирования прав
граждан Республики Казахстан
в сфере выездного туризма
Администратор системы
ТУРИСТІК ҚАМҚОР
Система гарантирования прав граждан Республики Казахстан в сфере выездного туризма
Администратор системы
ТУРИСТІК ҚАМҚОР
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, formidID шаблона данныхДачислодля подключения систем туроператоров значение должно быть 163
param2Действие над туромДастрокаsave - при сохранение тура, bad - при порче тура
returnВозвращаемое поле тураНетстрокаНазвание возвращаемой переменной (при ответе). Переменная q_number содержит ТурКод.
agentloginЛогин туроператораДастрокаНа тестовой платформе - test
agentpassПароль туроператораДастрокаНа тестовой платформе - test
Хэш (объект) input:
q_touragentНазвание турфирмы-агентаДастрокаНазвание, позволяющее найти турагента при отсутствии туроператора
q_countryРусскоязычное название страны пребыванияДастрокаДолжно присутствовать в справочнике стран (см. справочные методы).
q_countryenАнглоязычное название страны пребыванияДастрокаДолжно присутствовать в справочнике стран (см. справочные методы).
q_airlinesIATA-код авиалинийДастрока, [A-Z0-9]{2}Должно присутствовать в справочнике авиалиний (см. справочные методы). Добавлено 03.10.2017
q_airport_startIATA-код аэропорта вылетаДастрока, [A-Z]{3}Должно присутствовать в справочнике аэропортов и совпадать со страной Казахстан (см. справочные методы). Добавлено 03.10.2017
q_airportIATA-код аэропорта прилетаДастрока, [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":"<h3>Вы будете перенаправлены на запрошенный адрес</h3>..."}
Подробное объяснение новых структур запроса и ответа:
Запрос
ПеременнаяНазначение поляОбяза- тельноФормат данныхОписание
param1ТурКодДачислоТурКод, по которому будет найден тур в реестре.
param2Действие над туромДастрокаsave - при сохранение тура, bad - при порче тура
Хэш (объект) input:
msgТекст описанияДастрокаОбъяснение причины отмены тура. Должно быть осмысленным, оператор турфирмы должен заполнять это поле вручную, иначе запрос будет проигнорирован.
replytoE-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 в базу. Аэропорты строятся, меняют название - все это приводит к устареванию базы данных.

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

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

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

Администратор системы «Туристік Қамқор»