API (Кинт)

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

Общая информация

Введение

API программного продукта позволяет делать интеграции с другим ПО. Например, реализовать личный кабинет на сайте. Для этого, разработчики могут обращаться в базу как для операций обычного чтения, так и для записи.

Требования

  1. База, к которой обращаются, должна быть опубликована на веб-сервере.
    1. При публикации базы, должна быть выполнена активация HTTP-сервиса KintAPI.
    2. Проверить правильность выполнения публикации можно путём обращения к методу GetDBInfo.
  2. Разработчик должен иметь хотя бы минимальные представления о том, что такое HTTP-протокол и JSON-сериализация
    1. Что такое тело запроса, и чем оно отличается от параметров
    2. Unified Request Location и Unified Request Identifier не должны быть пустыми определениями
    3. Виды запросов (POST, GET, OPTIONS) и чем они отличаются
    4. Базовая авторизация (если публикация выполнена без предопределения аутентификационных данных)

Вызов методов

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

До версии 21.07, единственным способом вызвать какую-либо функцию, была передача названия в предопределенном параметре Method на URI /pub/hs/KintAPI.hs/GetData или /pub/hs/KintAPI.hs/PostData, в зависимости от типа запроса.

Начиная с релиза 21.07, имя вызываемого метода стало частью URI, и вместо GetData / PostData, стало возможным прописывать имя метода (например, /pub/hs/KintAPI.hs/GetDBInfo). Старый способ вызова методов сохранился для поддержания совместимости с уже реализованными интеграциями.

Помните, что для веб-сервера регистр букв важен, и запрос вида /pub/hs/kintapi.hs/getdbinfo гарантированно приведёт к ошибке 404.

Предопределенные параметры запроса

На поведение сериализатора и API можно влиять путём передачи специальных параметров. Имена параметров можно передавать как на русском, так и на английском языке.

Имя параметра на русском Имя параметра на английском Описание Пример значения Значение по-умолчанию
Реквизиты Fields Задаёт перечень реквизитов, которые должны быть переданы вместе с ссылками на элементы Ссылка,Контрагент,КонтактноеЛицо,Договор Не задано
ДополнительныеСвойства AdditionalProperties Перечень свойств, которые должны быть добавлены в тело ответа. Ключ под свойство добавляется даже в случае отсутствия какого-либо значения. Телефон,ЭлектроннаяПочта Не задано
ПреобразоватьКлючи ConvertKeys Указывает, необходимо ли переводить ключи с русского на английский (если в встроенном словаре имеется сопоставление). true Включено
- test Предназначено более для тестов сериализации. API не будет вызывать метод, и просто вернёт JSON так, как она его получила и "пропарсила" из POST-запроса. Значение не требуется, достаточно просто передать параметр Не используется
- raw Возвращает ответ (если представляется возможным) сырым телом, без какой-либо сериализации. Не должно использоваться в нормальных ситуациях. Значение не требуется, достаточно просто передать параметр Не используется

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

API возвращает ответы всегда в формате JSON, даже если запрашивается иной через заголовок Accept. В качестве Content-Type задано значение application/json;charset=utf-8.

Структура ответа содержит два поля:

  • Success - флаг успешности выполнения, присутствует всегда
  • Result - результат выполнения

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

  • Error - описание ошибки
  • КодОшибки - код ошибки
{
    "Success": false,
    "Result": {
        "Error": "Метод конфигурации «ИмяМетода» не найден!",
        "КодОшибки": 1000
    }
}

Коды ошибок

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

Код ошибки (ErrorCode) Описание
1000 Передано некорректное или не существующее имя метода
1001 Переданы некорректные параметры запроса
1002 Передан некорректный текст POST запроса
1010 Внутренняя ошибка конфигурации, при возникновении ошибки напишите об этом на spp@kint.ru

Запрос

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

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

Авторизация

Для подключения к базе-источнику требуется передать имя и пароль пользователя базы данных: пользователь должен быть добавлен в список пользователей информационной базы. Это ограничение, накладываемое платформой 1С: Предприятие. Передача данных передаётся с помощью стандартного механизма HTTP-аутентификации, подробнее о нём прочитать можно здесь.

Если произвести авторизацию не представляется возможным, можно произвести публикацию базы с беcпарольной аутентификацией (когда пользователь и его пароль прописаны на веб-сервере в default.vrd), но имейте в виду, что в таком случае любой, у кого будет ссылка на неё, сможет заходить в базу через режим 1С: Предприятие, если соответствующие права у пользователя имеются.

Общие методы

В данном разделе описаны методы, доступные в любой конфигурации. В скобках указано наименование кириллицей, если оно есть.

GetCatalog (СписокЭлементов)

  • Тип HTTP-запроса: GET
  • Описание: Возвращает перечень элементов справочника по заданному отбору. Можно использовать для получения списка организаций, категорий номеров и прочего.
Параметры
Наименование Обязателен? Тип данных Описание Пример
Вид / CatalogName Да Строка Имя справочника, из которого формируется выдача Организации
Отбор / Filter Нет Структура Структура, указывающая, по каким реквизитам и их значениям необходимо делать отбор {"ИНН": "1835012280"}
  • Пример вызова: 
    /GetData?Method=GetCatalog&CatalogName=Организации&Fields=Ссылка,ИНН,КПП
  • Пример вызова с отбором: 
    /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"
            },
            "ИНН": "",
            "КПП": ""
        }
    ]
}

GetDBInfo (ДанныеИБ)

Возвращает информацию о версии информационной базы. Параметров нет. Можно использовать для проверки работоспособности API.

Пример вызова
/GetData?Method=GetDBInfo
Проверка работоспособности API
https://<адрес_сервера>/<имя_публикации>/hs/KintAPI.hs/GetData?Method=GetDBInfo
Пример ответа
{
"Success": true,
"Result": {
"ВерсияAPI": "1.1",
"НомерРелиза": "20.06.03"
}
}

QRCode (КартинкаQR)

Получает картинку QR-кода по навигационной ссылке переданного объекта в формате BASE64.

GetPrintForm (ПолучитьПечатнуюФорму)

Позволяет получить сформированную печатную форму в формате BASE64.

Параметры:

  • Объект (GUID, обязательный) - для кого получаем значение параметра
  • ПечатнаяФорма (GUID, не обязательный только в случае получения значения параметра) - может использоваться для расширения списка параметров. Без печатной формы список параметров может быть ограничен.
  • ТипФайла (не обязательный только в случае получения значения параметра) - доступны значения: DOCX, HTML5, MXL, PDF, TXT, XLS
  • ИмяПараметра (Строка, не обязательный) - если передан, то вернется не печатная форма, а значение переданного параметра. По умолчанию доступны параметры на вкладках «Основные» + «Доступные» + «Дополнительные» в форме настройки печатной формы.
Пример вызова
/GetData?Method=GetPrintForm&Объект={"GUID":%20"dc7970e4-e673-11e9-b48d-5404a66e4a89"}&ПечатнаяФорма={"GUID":%20"09c83fe6-f918-4388-a2ee-b0a3276941d4"}&Формат=PDF
Пример ответа
{
"Success": true,
"Result": "JVBERi0xLjcKJeLjz9MKMSAwIG9iago8PAovRmlsdGVyIC9GbGF0ZURlY29kZQovTGVuZ3RoIDIgMCBSCi9MZW5ndGgxIDU0Nzk2Ci9MZW5ndGgyIDAKL0 ... UlRU9GCg=="
}
Пример вызова для получения значения параметра
/GetData?Method=GetPrintForm&Объект={"GUID":%20"dc7970e4-e673-11e9-b48d-5404a66e4a89"}&ПечатнаяФорма={"GUID":%20"09c83fe6-f918-4388-a2ee-b0a3276941d4"}&ИмяПараметра=ФизЛицо
Пример ответа
{
"Success": true,
"Result": {
"Наименование": "Иванов Иван Иванович",
"Код": "000000793 ",
"Идентификатор": "e1cib/data/Справочник.яъФизическиеЛица?ref=813b5404a66e4a8911e35761a7492167",
"ПометкаУдаления": false,
"ЭтоГруппа": false
}
}

Кинт: Управление санаторием

Методы

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, Смена белья"
}
]
}

GetAvailableCategories

Работает аналогично методу GetAvailableRooms, сворачивает результат по категориям номеров гостиницы.

PostBooking

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

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

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

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

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

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

Данные для создания гостей могут быть переданы двумя способами:

  • отдельным элементом строки массива гостей с именем "ФизЛицо", "Гость" или "Guest";
  • параметры для создания гостя находятся непосредственно в строке массива гостей.

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

Если в контексте создания заявки передан идентификатор заявки (навигационная ссылка или уникальный идентификатор (ID), дата и номер входящего документа (InboundDate, InboundNumber), будет выполнен поиск заявки и обновление реквизитов. Новая заявка создается в том случае, если по идентификатору ничего не найдено.

Структура поля «Guest» может содержать ключ ВидУдостоверения, в этом случае будут заполнены данные об удостоверении личности гостя. В значении этого поля должно быть значение «Паспорт» или произвольное наименование удостоверения, которое есть в базе данных (справочник Справочник «Виды удостоверений»).

Поля для заполнения данных удостоверения личности: ДокументСерия, ДокументНомер, ДокументДатаВыдачи, ДокументКемВыдан, ДокументКодПодразделения, ДатаРегистрацииПоМестуЖительства.

Передача поля Адрес регистрации: поиск адреса выполняется по ключевому полю ИдентификаторФИАС или FIAS_ID. Если идентификатор не передан, выполняется поиск по наименованию. В запросе это одно из полей: Raw, Наименование, Name.

Так же, может быть передан АдресФактический. Если его нет, но есть АдресРегистрации, то в фактический будет записан адрес регистрации.

Пример вызова
http://127.0.0.1/имя_публикации/hs/KintAPI.hs/PostData?Method=PostBooking
Тело запроса (параметры в шапке)
{
"Client": {
"Name": "Иванов Иван Иванович",
"BirthDate": "1980-11-11T00:00:00",
"Sex": "М",
"RegAddress": {},
"FactAddress": {}
},
"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": {},
"FactAddress": {}
},
"Guests": [
{
"Guest": {
"Name": "Иванов Сергей Иванович",
"BirthDate": "1995-01-11T00:00:00",
"Sex": "Мужской"
},
"DateFrom": "2018-10-01T00:00:00",
"Days": "10",
"RoomCategory": {
"ID": "e1cib/data/Справочник.НоменклатураПомещений?ref=88575404a66e4a8911e340740eaeea25"
}
}
],
"OrganizationOfStay": {
"ID": "e1cib/data/Справочник.Организации?ref=8e8150e54935bd5411e25bc6880bb616"
}
}
Пример ответа
{
"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..."
    },
    {
        "InboundDate":"2018-09-01T00:00:00",
        "InboundNumber":"RR-123124",
        "MKB10":"W25.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

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

Так же может возвращать все заявки по периоду, начиная с 21.07.01. Для этого передаётся параметры "НачалоПериода", "КонецПериода". Можно как один, так и оба сразу.

Пример вызова
/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"
},
"Результат": "Заявка подтверждена, автоматическая отмена невозможна!"
}
]
}


GetPrice

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

Параметры:

  • ВидЦен/PriceType, не обязательный. Если не задан - будет получена «Цена брони» (Проживание + Лечение + Питание). Для получения цены по варианту пребывания необходимо передать один из идентификаторов: «ЦенаПроживания», «ЦенаЛечения», «ЦенаПитания».
  • Контекст/Context (Структура) - любые параметры которые будут участвовать при расчете цены. Чем полнее контекст, тем точнее будет расчет стоимости.
  • Расшифровка - вернет таблицу расшифровки стоимости с учетом скидок по вариантам пребывания.
Пример вызова
/GetData?Method=GetPrice&Контекст={"КатегорияНомера":%20{"GUID":%20"0eaeea25-4074-11e3-8857-5404a66e4a89"}}
Пример вызова с расшифровкой
/GetData?Method=GetPrice&Контекст={"КатегорияНомера":%20{"GUID":%20"0eaeea25-4074-11e3-8857-5404a66e4a89"}}&Расшифровка=Истина
Пример ответа
{
"Success": true,
"Result": 1500
}


CheckGuest

Выполняет поиск карты гостя по переданным реквизитам и проверяет ее актуальность.

Пример структуры параметров
{
   "ДатаЗаезда":"2020-07-15T00:00:00",
   "Физлицо_ДатаРождения":"1949-01-23T00:00:00",
   "НаДату":"2020-07-28T00:00:00"
}

Параметры отбора карты гостя передаются в структуре с имененем "Отбор" или "Filter". Вложенные реквизиты должны быть переданы с разделителем "_", например: дата рождения физлица: "Физлицо_ДатаРождения". Служебные параметры:

  • НаДату: на какую дату проверять регистрацию гостя. Если не передан, то проверяется на текущую дату.
  • УчитыватьВремя (булево): учитывать время суток заезда и выезда гостя. По умолчанию время не учитывается.
Пример вызова
/GetData?Method=CheckGuest&Отбор={"ДатаЗаезда":"2020-07-15T00:00:00","Физлицо_ДатаРождения":"1949-01-23T00:00:00","НаДату":"2020-07-28T00:00:00"}
Пример ответа
{
"Success": true,
"Result": false
}

GetInvoices

Доступен с версии 21.07.01

Возвращает перечень счетов по контрагенту или договору (в зависимости от переданных параметров).

Пример вызова
/GetData?Method=GetInvoices&Контрагент={"ID":%20"e1cib/data/Справочник.Контрагенты?ref=9a6c5404a66e4a8911e5bb8e2aa076f5"}&Договор={"ID":%20"e1cib/data/Справочник.ДоговорыКонтрагентов?ref=bfdd7085c2c0660b11ebd27de6bcea8a"}
Пример ответа
{
    "Success": true,
    "Result": [
        {
            "Дата": "2021-06-03T10:54:11",
            "Номер": "ЧОКУС-000000120",
            "Идентификатор": "e1cib/data/Документ.СчетНаОплатуПокупателю?ref=b4bd5404a66e4a8911ebc434d07efc5a"
        },
        {
            "Дата": "2021-06-03T10:54:43",
            "Номер": "ЧОКУС-000000121",
            "Идентификатор": "e1cib/data/Документ.СчетНаОплатуПокупателю?ref=b4bd5404a66e4a8911ebc434d07efc5d"
        }
    ]
}

GetAcceptances

Доступен с версии 21.07.01

Возвращает перечень созданных приёмов платежей по контрагенту, договору и/или счету (в зависимости от переданных параметров).

Пример вызова
/GetData?Method=GetAcceptances&Контрагент={"ID":%20"e1cib/data/Справочник.Контрагенты?ref=9a6c5404a66e4a8911e5bb8e2aa076f5"}&Счет={"Идентификатор":%20"e1cib/data/Документ.СчетНаОплатуПокупателю?ref=b4bd5404a66e4a8911ebc434d07efc5d"}&Реквизиты=СуммаДокументаБезСкидки
Пример ответа
{
    "Success": true,
    "Result": [
        {
            "Дата": "2019-09-30T15:26:39",
            "Номер": "ЧО0000000000038",
            "Идентификатор": "e1cib/data/Документ.ПриемПлатежей?ref=b48b5404a66e4a8911e9e36cba1ce639",
            "СуммаДокументаБезСкидки": 1000
        },
        {
            "Дата": "2021-06-03T10:54:18",
            "Номер": "ЧО000000149    ",
            "Идентификатор": "e1cib/data/Документ.ПриемПлатежей?ref=b4bd5404a66e4a8911ebc434d07efc5b",
            "СуммаДокументаБезСкидки": 21109
        },
        {
            "Дата": "2021-06-03T11:16:05",
            "Номер": "ЧО000000150    ",
            "Идентификатор": "e1cib/data/Документ.ПриемПлатежей?ref=b4bd5404a66e4a8911ebc434d07efc61",
            "СуммаДокументаБезСкидки": 3885
        }
    ]
}

RegisterPayment

Доступен с версии 21.07.01

Создаёт приём платежей. Должен быть строго POST-запросом. В теле должны содержаться данные для добавления в документ. Основными считаются ссылка на счёт-основание, вид документа и сумма. Все остальные должны передаваться внутри объекта "Контекст".

Пример запроса
{
    "Счет": {"Идентификатор": "e1cib/data/Документ.СчетНаОплатуПокупателю?ref=b4bd5404a66e4a8911ebc42b9401edbb"},
    "ВидДокумента": "ПриемПлатежей",
    "Сумма": 100,
    "Контекст": {
        "ЧекПробитВоВнешнейПрограмме": true,
        "НомерВходящегоДокумента": "000002",
        "ДатаВходящегоДокумента": "2021-07-13T13:33:59"
    }
}
Пример ответа
{
    "Success": true,
    "Result": {
        "Дата": "2021-07-14T10:07:23",
        "Номер": "ЧО000000162    ",
        "Идентификатор": "e1cib/data/Документ.ПриемПлатежей?ref=967f708bcda2156111ebe469c0d8a16b"
    }
}

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

Внутренний Внешний
Наименование 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.

Учет. Анализ. Управление

Методы

PostDocument

Создание документов переданного вида. Обязательный параметр: Вид - имя документа в дереве метаданных или имя предопределенного элемента справочника яъВидыДокументов (для документов, которые делятся на несколько видов, например документ яъЗаказ).

Поддерживаются следующие виды:

  • яъЗаказПокупателя
  • яъЗаказПоставщику
  • яъЗаказНаПроизводство
  • ОплатаПлатежнойКартой
  • ПриходныйКассовыйОрдер
  • ПоступлениеНаРасчетныйСчет
  • _ПеремещениеРастений
  • ПеремещениеРезервов
  • ИзменениеХарактеристик

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

Пример создания заказа покупателя
/PostData?Method=PostDocument&Вид=яъЗаказПокупателя

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

Если передан параметр СкладРезервирования, товары заказа будут автоматически зарезервированы на переданном складе. Параметр может быть передан в реквизитах шапки или в табличной части:

  • Если склад указан в табличной части - используется склад из табличной части
  • Если склад не указан в табличной части - используется склад шапки
  • Если склад не указан ни в шапке ни в табличной части - товар не резервируется
Тело запроса
{
"Организация": {
"GUID": "8a276db6-ce58-11e5-982d-14dae9b19a48"
},
"идИнтернетЗаказа": "0001",
"Дата": "2020-01-01T00:00:00",
"ОплатаПлатежнойКартой": {
"СуммаДокумента": 500,
"ВидОплаты": {
"ID": "e1cib/data/Справочник.ВидыОплатОрганизаций?ref=98165404a66e4a8111e879fee15001c2"
}
},
"СкладРезервирования": {
"ID": "e1cib/data/Справочник.Склады?ref=8b25a0661889f40541be854e00d95269"
},
"Контрагент": {
"Наименование": "Иванов Иван Иванович",
"ИНН": ""111111111111"",
"GUID": "3cc7dcfa-930d-11df-b942-001bfc345421"
},
"Товары": [
{
"Номенклатура": {
"Наименование": "Красная герань 30 мм",
"Артикул": "000112",
"GUID": "2b82b757-366b-11e9-982b-5404a66e4a81"
},
"Количество": 10,
"Цена": 150,
}
],
"ДополнительныеСвойства": [
{
"Свойство": "СуммаДоставки",
"Значение": 100
}
]
}
Пример ответа
{
"Success": true,
"Result": {
"Дата": "2020-01-01T00:00:00",
"Номер": "0000--000000045",
"Идентификатор": "e1cib/data/Документ.яъЗаказ?ref=98485404a66e4a8111eaa099a5a5b36d"
}
}

Коды ошибок

Код ошибки (ErrorCode) Описание
3000 В параметрах не передан вид создаваемого документа.
3001 В параметрах передан вид документа, не поддерживаемый методом.
3002 Не удалось записать созданный документ.
3003 Передан вид документа, отсутствующий в конфигурации.
3004 Не удалось зарезервировать товары заказа покупателя.
Источник — «http://wiki.kint.ru/index.php?title=API_(Кинт)&oldid=61892»