API (Кинт)

Материал из КинтВики
Перейти к: навигация, поиск

Общее

При вызове любой операции необходимо передать имя метода - это предопределенный параметр http-запроса Method.

Ответ в формате JSON, Content-Type: application/json;charset=utf-8

Ответ содержит два поля: Success - флаг успешности выполнения и Result - результат выполнения, обычно структура.

Вызов GET запроса
http://127.0.0.1/имя_публикации/hs/KintAPI.hs/GetData?Method=ИмяМетода
Вызов POST запроса
http://127.0.0.1/имя_публикации/hs/KintAPI.hs/PostData?Method=ИмяМетода
Внимание!

Для 1С важен регистр букв при написании адреса запроса. Например, обращение по адресу /hs/kintapi.hs/ выдаст ошибку HTTP ERROR 404.


Пример ответа с ошибкой: 

{
"Success": false,
"Result": {
"Error": "Метод конфигурации <ИмяМетода> не найден!"
}
}

Для поиска любых ссылочных объектов используется одно из ключевых полей: ID или GUID.

  • ID - это навигационная ссылка на объект в базе 1С: Предприятия (e1cib/data/Справочник.НоменклатураПомещений?ref=b4585404a66e4a8911e8bb0449fde0fc),
  • GUID - это уникальный идентификатор ссылки (49fde0fc-bb04-11e8-b458-5404a66e4a89).

При передаче параметров в запросах достаточно указать одно из этих полей: 

?RoomCategory=[{"ID": "e1cib/data/Справочник.НоменклатураПомещений?ref=b4585404a66e4a8911e8bb0449fde0fc"},{"GUID": "49fde0fc-bb04-11e8-b458-5404a66e4a89"}]

Если в параметрах переданы оба поля, приоритет за полем ID. Следует учесть, что поиск по ID примерно на 50% быстрее поиска по GUID.

Файлы приложений передаются в формате base64.

Если в параметрах GET запроса передан список доп. свойств, в результат запроса результат будут добавлены значения дополнительных свойств объектов. Список свойств передается через запятую без пробелов. В 1С это поле Код доп. свойства. 

?Method=GetCatalog&CatalogName=НоменклатураПомещений&AdditionalProperties=ДопОрганизация,СуммаПредоплаты

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

&Fields=ОрганизацияПребывания,Прайс,Контрагент

Методы

GetRoomQuota

Получение данных о квоте номеров за период, обязательно передавать период, за который требуется получить данные: параметры запроса DateFrom и DateTo.

Необязательные параметры

  • RoomCategory: если требуется получить данные по определенной категории(ям) номеров;
  • Seats: будет учитываться количество свободных мест при определении доступной квоты, пример вызова: &Seats=true
  • TypeOfQuota: вид документа онлайн-квоты, по которым требуется получить квоту. Доступные значения: Travelline, Wubook, KintAPI, пример вызова: &TypeOfQuota=KintAPI
  • OrganizationOfStay: если требуется получить квоту, привязанную к определенной организации (актуально для баз в которых ведется учет по нескольким организациям), пример вызова: &OrganizationOfStay={"ID":"e1cib/data/Справочник.Организации?ref=8e8150e54935bd5411e25bc6880bb616"}
Пример вызова
http://127.0.0.1/имя_публикации/hs/KintAPI.hs/GetData?Method=GetRoomQuota&DateFrom=2018-08-01T00:00:00&DateTo=2018-08-31T00:00:00
Пример ответа
{
"Success": true,
"Result": [
{
"RoomCategory": {
"Name": "Люкс 2к",
"ID": "e1cib/data/Справочник.НоменклатураПомещений?ref=88575404a66e4a8911e340740eaeea25"
},
"DateFrom": "2018-08-06T00:00:00",
"Qty": 2,
"DateTo": "2018-08-31T23:59:59"
"QuotaID": {
"Date": "2018-10-08T12:14:10",
"Number": "demA00025",
"ID": "e1cib/data/Документ.УстановкаКвоты?ref=9a4660a44c379a5b11e8cad221b146ad",
"GUID": "21b146ad-cad2-11e8-9a46-60a44c379a5b"
}
}
]
}

GetAvailableRooms

Получение данных о доступных (свободных) номерах за период, обязательно передавать период, за который требуется получить данные. Возвращает массив структур с описанием номеров гостиницы. Все доступные поля отображены в разделе "Пример ответа". Обязательные параметры запроса DateFrom - начало периода проживания DateTo - конец периода проживания

Необязательные параметры

  • Qty - количество мест в одном номере. Будут подобраны все номера где есть требуемое количество свободных мест. Если не передан - будут подобраны все доступные номера.
  • Vacant: если передано значение true - будут подобраны только полностью свободные номера;
  • RoomCategory: если требуется получить данные по определенной категории(ям) номеров;
  • Room: проверка доступности определенного номера гостиницы;
  • OrganizationOfStay: если требуется получить номера, привязанные к определенной организации (актуально для баз в которых ведется учет по нескольким организациям)
  • QuotaID: поиск номеров, привязанных к определенной квоте;

Время заезда и выезда берется из настроек гостиницы.

Пример вызова
http://127.0.0.1/имя_публикации/hs/KintAPI.hs/GetData?Method=GetAvailableRooms&DateFrom=2019-09-24T00:00:00&DateTo=2019-09-29T00:00:00&Vacant=true&Qty=2
Пример ответа
{
"Success": true,
"Result": [
{
"ДатаЗаезда": "2019-09-24T00:00:00",
"ДатаВыезда": "2019-09-29T23:59:59",
"Room": {
"Наименование": "Номер 201",
"Код": "ТТ00000012",
"Идентификатор": "e1cib/data/Справочник.Помещения?ref=b8f7001bfc34542111df326af0fbf7c5",
"ПометкаУдаления": false,
"ЭтоГруппа": false,
"Родитель": {
"Наименование": "Номера лаптя",
"Код": "666",
"Идентификатор": "e1cib/data/Справочник.Помещения?ref=bb9c5404a66e4a8911e7f79b39f2da3e",
"ПометкаУдаления": false,
"ЭтоГруппа": true
}
},
"Block": {
"Наименование": "Корпус 2",
"Код": "000000005",
"Идентификатор": "e1cib/data/Справочник.Здания?ref=b72f90e6baabdd1411e291efe183744d",
"ПометкаУдаления": false
},
"RoomCategory": {
"Наименование": "Люкс 2к",
"Код": "Lux",
"Идентификатор": "e1cib/data/Справочник.НоменклатураПомещений?ref=88575404a66e4a8911e340740eaeea25",
"ПометкаУдаления": false
},
"МестВНомере": 2,
"Category": {
"Наименование": "Гостиничный номер",
"Код": "",
"Идентификатор": "e1cib/data/Справочник.яъКатегории?ref=81bba100d9d99e6248a9bf544ade9963",
"ПометкаУдаления": false
},
"НачалоПериодаКвоты": null,
"КонецПериодаКвоты": null,
"ТребуетсяУборка": true,
"С": 1,
"Свободно": 1,
"До": 12.5,
"Стоимость": 0,
"ПериодПребывания": "с 24 по 29.09.2019 (5.5 суток)",
"ОтВыезда": 6,
"ДоЗаезда": 15,
"ДатаРаботы": "2018-12-19T00:00:00",
"Работа": {
"Наименование": "Смена белья",
"Код": "ТТ0000010",
"Идентификатор": "e1cib/data/Справочник.Услуги?ref=9cf55404a66e4a8911e4285c09474fc0",
"ПометкаУдаления": false,
"ЭтоГруппа": false
},
"РаботыВНомере": "19.12.2018, Смена белья"
}
]
}

PostBooking

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

Данные для создания заявки передаются в теле запроса в формате json.

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

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

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

Параметры пребывания могут быть переданы как в шапке, так и в строке массива гостей. Если параметр передан и в строке и в шапке - приоритетным считаем параметр строки. Если передан параметр Room - заявка забронирует места в переданном номере гостиницы.

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

Пример вызова
http://127.0.0.1/имя_публикации/hs/KintAPI.hs/PostData?Method=PostBooking
Тело запроса (параметры в шапке)
{
"Client": {
"Name": "Иванов Иван Иванович",
"BirthDate": "1980-11-11T00:00:00",
"Sex": "М",
"RegAddress": {}
},
"Guests": [
{
"Name": "Иванов Сергей Иванович",
"BirthDate": "1995-01-11T00:00:00",
"Sex": "Мужской",
"Relation": {
"Name": "Сын",
"ID": "e1cib/data/Справочник.яъСтепениРодстваФЛ?ref=95965404a66e4a8911e3c1440ad6102b"
}
}
],
"OrganizationOfStay": {
"ID": "e1cib/data/Справочник.Организации?ref=8e8150e54935bd5411e25bc6880bb616"
},
"DateFrom": "2018-10-01T00:00:00",
"Days": 10,
"RoomCategory": {
"ID": "e1cib/data/Справочник.НоменклатураПомещений?ref=88575404a66e4a8911e340740eaeea25"
},
"File": "iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAQAAADZc7J/AAAABGdBTUEAALGPC/xh..."
}
Тело запроса (параметры в строке)
{
"Client": {
"Name": "Иванов Иван Иванович",
"BirthDate": "1980-11-11T00:00:00",
"Sex": "М",
"RegAddress": {}
},
"Guests": [
{
"Name": "Иванов Сергей Иванович",
"BirthDate": "1995-01-11T00:00:00",
"Sex": "Мужской",
"Relation": {
"Name": "Сын",
"ID": "e1cib/data/Справочник.яъСтепениРодстваФЛ?ref=95965404a66e4a8911e3c1440ad6102b"
}
}
],
"OrganizationOfStay": {
"ID": "e1cib/data/Справочник.Организации?ref=8e8150e54935bd5411e25bc6880bb616"
},
"DateFrom": "2018-10-01T00:00:00",
"Days": 10,
"RoomCategory": {
"ID": "e1cib/data/Справочник.НоменклатураПомещений?ref=88575404a66e4a8911e340740eaeea25"
},
"File": "iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAQAAADZc7J/AAAABGdBTUEAALGPC/xh..."
}
Пример ответа
{
"Success": true,
"Result": {
"Date": "2018-08-21T11:07:37",
"Number": "ТТ0000000173",
"ID": "e1cib/data/Документ.ЗаявкаПокупателя?ref=b4535404a66e4a8911e8a510e223144c"
}
}

Есть возможность передачи данных для создания медицинской справки для каждого из гостей по заявке.

Пример заполнения полей справки
"MedicalCertificate": {
"InboundDate":"2018-02-04T00:00:00",
"InboundNumber":"RR-123123",
"MKB10":"W26.6",
"MedicalInstitution":"СПб ГБУЗ Городская Мариинская больница",
"File":"DFHHFGFM<JGKFYJBDVBDGdBTUEAALGPC/xh..."
}

Дополнительные свойства

Есть возможность установки дополнительных свойств при создании объектов. Для этого в контексте объекта должно быть установлено поле AdditionalProperties. Значение массива - структура описания свойства: поле Property содержит ссылку на свойство (поля ID или GUID) или строковый код свойства, поле Value - его значение.

Пример заполнения поля
[
{
"Property": "Цвет",
"Value": "Красный"
},
{
"Property": {
"GUID": "e2634e5a-13e4-22g7-bded-1206a89t4e19"
},
"Value": {
"GUID": "a56e244a-19e5-11e3-bded-5404a66e4a89"
}
}
]

Для передачи контактных данных в поле Property можно передать идентификатор вида контактной информации: ЭлектроннаяПочта или Телефон. 

[
{
"Property": "ЭлектроннаяПочта",
"Value": "example@example.com"
},
{
"Property": "Телефон",
"Value": "1-234-567-890"
}
]

GetBookingStatus

Возвращает статус заявки, в параметрах можно передать массив идентификаторов заявок.

Запрос содержит один обязательный параметр Booking.

Дополнительные параметры:

  • AdditionalProperties. В результат будут добавлены значения дополнительных свойств заявки, заданных для нее в базе. Список свойств передается через запятую без пробелов. В 1С это поле КОД доп. свойства.
  • PrintForm. Вывод файла печатной формы в формате PDF. Необходимо передавать ИД печатной формы в базе КУС: PrintForm={"GUID":"c357203b-c09c-11e8-b45b-5404a66e4a89"}
Пример вызова
/GetData?Method=GetBookingStatus&Booking=[{"ID": "e1cib/data/Документ.ЗаявкаПокупателя?ref=b4535404a66e4a8911e89ae406700121"}, {"GUID": "78fd6678-86d4-11e5-a33f-60a44c379a5b"}]
Пример ответа
{
"Success": true,
"Result": [
{
"Date": "2018-08-08T12:21:19",
"Number": "ТТ0000000165",
"Sanatorium": {
"Name": "ОАО санаторий \"Родные просторы\"",
"ID": "e1cib/data/Справочник.Организации?ref=8e8150e54935bd5411e25bc6880bb616"
},
"Status": "Исполнена (закрыта)",
"Booked": 4,
"Denied": 0,
"ToProcess": 0,
"ID": "e1cib/data/Документ.ЗаявкаПокупателя?ref=b4535404a66e4a8911e89ae406700121"
},
{
"Date": "2018-08-13T20:15:22",
"Number": "ТТ0000000170",
"Sanatorium": {
"Name": "ОАО санаторий \"Родные просторы\"",
"ID": "e1cib/data/Справочник.Организации?ref=8e8150e54935bd5411e25bc6880bb616"
},
"Status": "На исполнении (1)",
"Booked": 0,
"Denied": 0,
"ToProcess": 1,
"ID": "e1cib/data/Документ.ЗаявкаПокупателя?ref=b4535404a66e4a8911e89f1413f618ad"
}
]
}

GetBookingList

Список заявок заявителя.

Пример вызова
/GetData?Method=GetBookingList&Client={"ID":"e1cib/data/Справочник.Контрагенты?ref=aab56c626dc53d6911e8a44b45d09480"}
Пример ответа
Аналогично методу GetBookingStatus.

CancelBooking

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

В зависимости от текущего состояния заявки выполняются следующие действия:

  • Черновик (документ не проведен): устанавливается пометка на удаление документа, в реквизит "Комментарий" документа записывается причина отмены.
  • На исполнении (документ проведен): создается общий отказ по всем строкам заявки с указанием причины.
  • Забронирована (создан документ "Путевка"): для каждой путевки, созданной на основании заявки выполняется операция "Снятие брони" с указанием причины.

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

Пример вызова
/PostData?Method=CancelBooking&DenyReason={"GUID": "21b146ad-cad2-11e8-9a46-60a44c379a5b"}
Тело запроса
[
{
"Booking": {
"GUID": "78fd6678-86d4-11e5-a33f-60a44c379a5b"
},
"DenyReason": {
"GUID": "49fde0fc-bb04-11e8-b458-5404a66e4a89"
}
},
{
"Booking": {
"GUID": "49fde0fc-bb04-11e8-b458-5404a66e4a89"
}
}
]
Пример ответа
{
"Success": true,
"Result": [
{
"Booking": {
"Date": "2018-08-08T12:21:19",
"Number": "ТТ0000000165",
"ID": "e1cib/data/Документ.ЗаявкаПокупателя?ref=b4535404a66e4a8911e89ae406700121"
},
"Результат": "Заявка подтверждена, автоматическая отмена невозможна!"
}
]
}

GetCatalog

Метод позволяет получить перечень элементов справочника, можно использовать для получения списка организаций, категорий номеров и т.п.

Обязательный параметр - CatalogName (имя справочника в конфигураторе). Опциональные параметры: Fields (список реквизитов через запятую), Filter (отбор в виде json с идентификаторами объектов)

Пример вызова
/GetData?Method=GetCatalog&CatalogName=Организации&Fields=Ссылка,ИНН,КПП&Filter={"ГоловнаяОрганизация": {"ID": "e1cib/data/Справочник.Организации?ref=b72f90e6baabdd1411e271b038722897"}}
Пример вызова с отбором
/GetData?Method=GetCatalog&CatalogName=Организации&Fields=Ссылка,ИНН,КПП&Filter={"ГоловнаяОрганизация":%20{"ID":"e1cib/data/Справочник.Организации?ref=ad5c5404a66e4a8911e37e83f3ef6892"}}
Пример ответа
{
"Success": true,
"Result": [
{
"Ссылка": {
"Name": "ОАО санаторий \"Родные просторы\"",
"ID": "e1cib/data/Справочник.Организации?ref=8e8150e54935bd5411e25bc6880bb616"
},
"ИНН": "1835012280",
"КПП": "184101001"
},
{
"Ссылка": {
"Name": "ООО \"Италмас\"",
"ID": "e1cib/data/Справочник.Организации?ref=b72f90e6baabdd1411e271b038722897"
},
"ИНН": "",
"КПП": ""
}
]
}

Соответствие имен реквизитов

Внутренний Внешний
Наименование Name
Код Code
Идентификатор ID
Контрагент Client
ОписаниеОшибки Error
НомерГостиницы Room
КатегорияНомера RoomCategory
Дата Date
Номер Number
НачалоПериода DateFrom
КонецПериода DateTo
Количество Qty
ОрганизацияПребывания Sanatorium
Состояние Status
ПредварительноЗабронировано Booked
Подтверждено Processed
Отказано Denied
ОсталосьОбработать ToProcess
ПричинаОтказа DenyReason
Заявка Booking
Файл File
КоличествоДней Days
ОрганизацияПребывания OrganizationOfStay
Семья Family
Гости Guests
Пол Sex
СтепеньРодства Relation
АдресРегистрации RegAddress
ДатаРождения BirthDate
НомерСНИЛС SNILS
Категория Category
МестоРождения Birthplace
Гражданство Citizenship
стрМестоРаботы PlaceOfWork
стрДолжность Position
ИдентификаторФИАС FIAS_ID
Дом House
Корпус Block
Квартира Flat
ПочтовыйИндекс ZipCode
стрДопСвойства AdditionalProperties
ПечатнаяФорма PrintForm
Квота QuotaID
Продавец Agent
Прайс Price
КатегорияПутевки VoucherCategory
Справка MedicalCertificate
ЛечебноеУчреждение MedicalInstitution
ДиагнозНаправившегоУчреждения MKB10
ДатаВходящегоДокумента InboundDate
НомерВходящегоДокумента InboundNumber

Коды ошибок

Если при выполнении метода сервиса возникли ошибки, в ответ сервера, помимо расшифровки ошибки, будет добавлен код ошибки. Пример ответа: 

{
"Success": false,
"Result": {
"Error": "Метод конфигурации <ИмяМетода> не найден!",
"ErrorCode": "1000"
}
}
Код ошибки (ErrorCode) Описание
1000 Передано некорректное или не существующее имя метода
1001 Переданы некорректные параметры запроса
1002 Передан некорректный текст POST запроса
1010 Внутренняя ошибка конфигурации, при возникновении ошибки напишите об этом на spp@kint.ru
1020 Ошибка создания документа «Заявка» методом PostBooking
1021 Ошибка обработки файлов, приложенных к заявке или справке.
1025 Не найдена заявка по ссылке при запросе статуса методом GetBookingStatus.
1030 Не найдена заявка по ссылке при отказе методом CancelBooking.
1031 Ошибка установки пометки заявки на удаление методом CancelBooking.
1032 Ошибка выполнения отказа по заявке методом CancelBooking.
1033 Ошибка снятия брони по подтвержденной заявке методом CancelBooking.
Источник — «http://wiki.kint.ru/index.php?title=API_(Кинт)&oldid=48242»