Описание API (Кинт)

Введение

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

Требования

1. База, к которой обращаются, должна быть опубликована на веб-сервере.
   1. При публикации базы, должна быть выполнена активация HTTP-сервиса KintAPI.
   2. Проверить правильность выполнения публикации можно путём обращения к методу GetDBInfo. Пример: https://demo.kint.ru/kus_demo/hs/KintAPI.hs/GetData?Method=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	Задаёт перечень реквизитов, которые должны быть переданы вместе с ссылками на элементы. Поддерживается получение нестандартных реквизитов: ПредставлениеОбъекта, Идентификатор, GUID.	Ссылка,Контрагент,КонтактноеЛицо,Договор	Не задано
ДополнительныеСвойства	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
1032	При отмене заявки оказалось что она уже отменена, необходимо со стороны сайта написать обработчик такой ситуации
1100	Не передан параметр с видом справочника
1101	Переданный вид справочника отсутствует в конфигурации
1102	Элемент справочника не найден по полям поиска
1103	По полям поиска найдено несколько подходящих элементов
1104	Ошибка записи элемента справочника, возможно переданы не все обязательные реквизиты

Запрос

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

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

Авторизация

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

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

Пагинация

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

Имя параметра на русском	Имя параметра на английском	Описание	Пример значения	Значение по умолчанию
КоличествоЭлементов	CountOnPage	Количество элементов в результате запроса.	100	0
НомерСтраницы	PageNumber	Номер требуемой части результата запроса.	10	1

Методы с поддержкой пагинации:

• GetCatalog (СписокЭлементов). Пагинация доступна только для объектов, у которых есть свойство «Ссылка».
• ПолучитьИзмененияПоУзлу.
• GetAvailableRooms.

Пример вызова

/hs/KintAPI.hs/GetData?Method=GetCatalog&CatalogName=яъФизическиеЛица&PageNumber=6&CountOnPage=10